I/O drivers

The mmssl module publishes two drivers for converting binary documents to textual representation and a driver dedicated to symmetric encryption. These drivers have the same behaviour: encryption or encoding is performed when the driver is used for writing while decryption/decoding is done on a stream that is open for reading.

Driver base64

base64:[nonl,]filename

This driver can be used to handle documents encoded using the base64 standard. When used in an output stream, it generates the base64 encoded version of its binary input and in an input stream it expects a base64 encoded document that it decodes.

For instance the following statement encodes "mydata.bin":

fcopy("mydata.bin",F_BINARY,"mmssl.base64:mydata.b64",F_TEXT)

By default the generated text is split into lines of 76 characters but with the option nonl the entire document is output on a single line.

Driver hex

hex:filename

This driver produces a textual representation of a binary document by replacing each byte by its hexadecimal representation (e.g. the value 13 is converted to the string "0d").

The following code extract displays the hexadecimal representation of the binary input file "mem:md5":

fcopy("mem:md5",F_BINARY,"mmssl.hex:",F_TEXT)
writeln

Driver crypt

crypt:[[nosalt,][md=a,][cipher=c,][key=kf,][iv=if,]pwd=p|pf]filename

The crypt driver performs encryption (when writing) or decryption (when reading) of its stream using a symmetric cipher (that is, the same key is used for encryption and decryption). Options are provided enclosed in square brackets, at the least a password has to be provided. For instance, the following statement encrypts the file "mydata" using the password stored in the file "passfile":

fcopy("mydata","mmssl.crypt:[passfile]mydata.enc")

The password is read from the first line of the password file (that is opened as a text document). Alternatively, the password may be directly passed through the file name using the pwd= option:

fcopy("mydata","mmssl.crypt:[pwd=mysecret]mydata.enc")

Encryption (or decryption) is performed using the default cipher as defined by the control parameter ssl_cipher. Another cipher can be selected using the cipher option.

The encryption (or decryption) process requires a key as well as an initialisation vector. The size of these components depends of the selected cipher and the appropriate data is generated by a key derivation routine using the provided password as input. This procedure employs a message digest algorithm and may use some initial value (or salt). Without any specific option the driver relies on the default message digest algorithm defined by the control parameter ssl_digest and generates a random salt of 8 bytes. These bytes are then saved at the beginning of the encrypted document such that the decryption process can retrieve them and regenerate the encryption key and initialisation vector from the provided password. This default behaviour can be changed using the nosalt option to avoid using a salt and the option md to select some other message digest algorithm. It is also possible to provide the encryption key and the initialisation vector via dedicated files using options key and iv. In this case no password has to be provided.

Driver hmac

hmac:[[md=a,]key=kf|key]filename

The hmac driver computes a HMAC ( keyed-hash message authentication code) of its input stream using the provided key and hash function (the driver does not support reading). Options are provided enclosed in square brackets, at the least a key has to be provided. For instance, the following statement generates the HMAC of the file "mydata" using the key stored in the file "keyfile":

fcopy("mydata","mmssl.hmac:[keyfile]mydata.hmac")

The key is read from the key file that is opened as a binary document. Alternatively, the key may be directly passed through the file name using the key= option:

fcopy("mydata","mmssl.hmac:[key=mykey]mydata.hmac")

Computation of a HMAC is based on a message digest algorithm, without any specific option the driver relies on the default message digest algorithm defined by the control parameter ssl_digest otherwise, the option md can be used to select some other algorithm.