Document Encryption - Implementation Notes and Examples

From IHE Wiki
Jump to: navigation, search

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)