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
Software | version | encryption
(AES) |
password | PKI (certificate) | shared (symmetric) key | digest
(SHA-256) |
signature
(RSA) |
note |
---|---|---|---|---|---|---|---|---|
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.) | ||||||||
Bouncy Castle Crypto API (.NET)
(note 4.) | ||||||||
... |
notes:
- OpenSSL in addition to its cryptographic library also offers a command line application with support for most functionality (see example section below)
- supported, but untested
- TBD; look for CMS/PKCS7
- 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: e.g. multiple recipients
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
And decryption:
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_cms_20110731.zip