mmssl

Topics covered in this chapter:

The Mosel module mmssl is an interface to the OpenSSL cryptographic library (http://www.openssl.org). It brings most of the functionality of this library to the Mosel language and serves as the cryptographic component in other parts of Mosel. In particular, it provides support for the HTTPS protocol in mmhttp and implements the encryption and signing mechanisms used by the Mosel core libraries when secure BIM files are used.

Overview

Document encryption in Mosel

Encryption and decryption of documents are achieved by cipher algorithms. Ciphers can be of two kinds: symmetric ciphers use the same encryption key to perform the encryption and decryption tasks while asymmetric ciphers require one key to execute the encryption and another one for the decryption. In mmssl, symmetric ciphers are made available through the crypt I/O driver (Section Driver crypt): the encryption key (the size of which depends on the cipher) is automatically generated based on some given passphrase (either input from an external file or directly in the file name specification). The implementation of the crypt driver allows the user to select which specific cipher algorithm it should use (for instance AES, DES or IDEA).

For asymmetric encryption, mmssl relies on the RSA cryptographic system. For the RSA algorithm, a key (RSAgenkey) consists of two components: a public part that is usually distributed to the individuals with whom documents are to be exchanged and a private part that must be kept secret by the owner of the key (this private key also includes the public key). In this framework, a document encrypted using a public key (RSApubencrypt) can only be decrypted with the corresponding private key (RSAprivdecrypt). Moreover, the key pair can also be used for signing documents: the electronic signature of a document is created with a private key (msgsign) and the corresponding public key is used to verify this signature (msgverify). Since only the owner of the private key can create the signature, the recipient has a guarantee on the origin of the document.

RSA keys are commonly stored as text files in the OpenSSL PEM standard format, this is also the most convenient representation for exchanging key information (RSAsavekey). In addition to this file format, mmssl can store a key in the form of a Mosel array of integers (RSAloadkey). By using this encoding a model may embbed keys or retrieve them from any of the usual model data sources.

The mmssl command

The module mmssl is distributed together with a command line tool of the same name as the module: mmssl. This program helps setting up an initial working environment and performs basic key and certificate operations directly from a shell (Unix) or command window (Windows). Running the mmssl program without any arguments will display a short help message, otherwise the following commands can be used:

setup

Check the configuration directory of mmssl and create it if necessary (see parameter ssl_dir)

genkey keyfile [size]

Generate a new RSA key pair of the specified size (default: 1024) and save it into keyfile.

getpub keyfile keyfilepub

Extract the public key of the private RSA key file keyfile and save it into keyfilepub

chkkey keyfile [keyfile...]

Check the validity of the provided key file(s)

gencert certfile [prod=value...]

Generate an X509 certificate using the provided properties (see x509newcrt for further detail)

chkcert certfile [keyfile]

Check the validity of the provided X509 certificate. If an additional private key file is provided, its compatibility with the certificate is also checked.

list [digest|cipher]

Display the list of supported message digests ( digest) or cipher algorithms ( cipher). Both lists are reported with the short form of the command.

Many procedures of the mmssl module require the availability of a configuration directory. To create and populate an initial setup it is recommended to run the following command before starting to use the module:

> mmssl setup

Note that the setup procedure is not destructive: if the configuration directory has already been created the command will only check its validity, add any missing components and suggest how to proceed in case of incorrect settings.

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 a base64 document is split into lines of 76 characters but with the option nonl the entire document is output as (or read from) 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.