PostScript Calling Convention

PostScript Calling Convention

User Interface for the PostScript Resource

BWIPP encoders are invoked as named PostScript resources. The caller provides three arguments on the operand stack, then locates and executes the resource:

0 0 moveto <data> <options> /<encoder> /uk.co.terryburton.bwipp findresource exec

Argument	Type	Description
data	string	Content to be encoded by the symbology. Valid contents vary per encoder -- see the Symbologies Reference.
options	string or dict	Properties of the symbol as space-separated key=value pairs, or a PostScript dictionary. Common options are listed in the Options Reference; some encoders accept additional options documented on their own pages.
encoder	name	The symbology type, e.g. /qrcode, /ean13, /code128.

The resource renders the barcode at the current point on the page.

For a hands-on introduction see the Quick Guide.

Use Cases

Trusted user writing a PostScript document

A user composing or editing a PostScript file directly controls the data and options as string literals within the document:

100 300 moveto (01234565) (includetext) /ean8 /uk.co.terryburton.bwipp findresource exec

Standard PostScript escaping rules apply (e.g. \(, \) for literal parentheses). Malformed PostScript is the user's own responsibility.

See the Quick Guide for getting started.

Untrusted input from an external service

When data or options originate from untrusted user input, a database, or an external service, the host application that is processing the data and driving the PostScript VM is responsible for ensuring that the supplied values cannot break out of the string arguments to inject and execute arbitrary PostScript.

The recommended technique is to hexify all arguments so that the PostScript interpreter receives hex-encoded string literals since these cannot contain injection sequences:

0 0 moveto
<3032333435363733>        % hex-encoded data
<696e636c75646574657874>  % hex-encoded options
<65616e38> cvn            % hex-encoded encoder name
/uk.co.terryburton.bwipp findresource exec

Errors should be caught using a PostScript stopped context so that invalid input results in a handled exception rather than an interpreter error.

See Developing a Frontend to BWIPP for complete guidance on safe argument passing, error handling, and image generation.

Security

BWIPP's security policy defines vulnerabilities in terms of this calling convention: A security issue is one where data and options passed through the interface described above cause unintended behaviour such as code execution, information disclosure, or denial of service.