Document Encryption - Implementation Notes and Examples

Introduction

This page intends to support the implementation of the Document Encryption (DEN) profile by providing examples and information on tooling support.

CMS software

The table below presents an (incomplete) list of software that supports the CMS encryption functionality for the DEN profile.

Software	version	encryption (AES)	password	PKI (certificate)	shared (symmetric) key	digest (SHA-256)	signature (RSA)	remarks
openssl (note 1.)	1.0.0-d	+	-	+	+	+	+
openssl	HEAD branch / SNAPSHOT	+	+	+	+	+	+
Bouncy Castle Crypto API (Java)	1.46	+	+	+	+ (note 2.)	+ (note 2.)	+
Microsoft CryptoAPI (note 3.)
Microsoft .NET Framework (note 3.)
Bouncy Castle Crypto API (.NET) (note 4.)
...

notes:

1. OpenSSL in addition to its cryptographic library also offers a command line application with support for most functionality (see example section below)
2. supported, but untested
3. TBD (keywords CMS/PKCS7)
4. TBD

Interoperability

The following have been verified as being interoperable:

• OpenSSL with Bouncycastle. Tested features: PKI and password key management methods, AES encryption, signature

TBD: interoperability matrix

Advanced functionality

TBD

OpenSSL example

The following example demonstrates encryption of a file according to the CMS profile using the OpenSSL command line application:

openssl cms -binary -digest_create -md sha256 -in doc.mime -outform der -out doc.digested
openssl cms -encrypt -binary -econtent_type pkcs7-digestData -aes256 -in doc.digested -keyform pem -inkey privatekey.pem -outform der -out doc.digested.encrypted_cert certificate.pem

notes:

• assumption: doc.mime contains mime-wrapped document
• the OpenSSL command line application has a small limitation, which requires a small patch for the econtent_type option (see files section)
• example uses PKI key management method, AES-256 CBC encryption, SHA-256 digest

The created files can be decrypted with the following commands:

openssl cms -decrypt -inform der -in doc.digested.encrypted_cert -keyform pem -inkey recipientprivk.pem -outform der -out doc.digested.encrypted_cert.decrypted
openssl cms -digest_verify -inform der -in doc.digested.encrypted_cert.decrypted -outform der -out doc.digested.encrypted_cert.decrypted.verified

notes:

• doc.digested.encrypted_cert.decrypted.verified should equal doc.mime

The structure of the encrypted files can be inspected using an ASN1 viewer, e.g. the one provided by OpenSSL:

openssl asn1parse -inform der -in doc.digested.encrypted_cert

A script demonstrating all key management methods (PKI, password, symmetric key), algorithms, signature, digest is available in the files section.

MIME header

Example MIME header for DEN:

MIME-Version: 1.0
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary
Content-Disposition: attachment; filename=doc.bin

The example can also be downloaded (see files section)

Files (examples, scripts, patches)

The following files are available to facillitate development and testing:

File	Description
cmstest.sh	script illustrating CMS functionality used by DEN profile
output.txt	example cmstest.sh script output
doc.digested.encrypted_cert	encrypted document example
doc.digested.encrypted_pass	encrypted document example
doc.digested.encrypted_symm	encrypted document example
doc.signed.encrypted_cert	encrypted document example
doc.signed.encrypted_pass	encrypted document example
doc.signed.encrypted_symm	encrypted document example
mime.txt	MIME header example
econtent_type.patch	patch for econtent_type option for OpenSSL command line application

The above files plus supporting files (sample files, certificates and keys) are also available in a ZIP archive which can be downloaded from the IHE FTP site: DEN.Support.Materials.v1.zip

Guidance on using both DEN and DSG

Please refer to this blog post on Using both Document Encryption (DEN) and Document Digital Signature (DSG)