View source for Document Encryption - Implementation Notes and Examples

== Introduction ==
This page intends to support the implementation of the [http://wiki.ihe.net/index.php?title=Document_Encryption 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.

{| class="wikitable"
|-
! 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:

#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 (keywords 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

=== OpenSSL example ===
The following example demonstrates encryption of a file according to the CMS profile using the OpenSSL command line application:
<blockquote>
openssl cms -binary -digest_create -md sha256 -in doc.mime -outform der -out doc.digested
<br>
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
</blockquote>
<blockquote>
notes:
*assumption: doc.mime contains mime-wrapped document
*the OpenSSL command line application has a small limitation, which requires a small [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/econtent_type.patch patch] for the econtent_type option (see files section)
*example uses PKI key management method, AES-256 CBC encryption, SHA-256 digest
</blockquote>
The created files can be decrypted with the following commands:
<blockquote>
openssl cms -decrypt -inform der -in doc.digested.encrypted_cert -keyform pem -inkey recipientprivk.pem -outform der -out doc.digested.encrypted_cert.decrypted
<br>
openssl cms -digest_verify -inform der -in doc.digested.encrypted_cert.decrypted -outform der -out doc.digested.encrypted_cert.decrypted.verified
</blockquote>
<blockquote>
notes:
* doc.digested.encrypted_cert.decrypted.verified should equal doc.mime
</blockquote>
The structure of the encrypted files can be inspected using an ASN1 viewer, e.g. the one provided by OpenSSL:
<blockquote>
openssl asn1parse -inform der -in doc.digested.encrypted_cert
</blockquote>


A [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/cmstest.sh 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:
<blockquote>
MIME-Version: 1.0<br>
Content-Type: application/octet-stream<br>
Content-Transfer-Encoding: binary<br>
Content-Disposition: attachment; filename=doc.bin
</blockquote>

The [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/mime.txt example] can also be downloaded (see files section)

== Files (examples, scripts, patches) ==
The following files are available to facillitate development and testing:
{| class="wikitable"
|-
! File
! Description
|-
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/cmstest.sh cmstest.sh]
| script illustrating CMS functionality used by DEN profile
|-
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/output.txt output.txt]
| example cmstest.sh script output
|-
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.digested.encrypted_cert doc.digested.encrypted_cert]
| encrypted document example
|-
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.digested.encrypted_pass doc.digested.encrypted_pass]
| encrypted document example
|-
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.digested.encrypted_symm doc.digested.encrypted_symm]
| encrypted document example
|-
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.signed.encrypted_cert doc.signed.encrypted_cert]
| encrypted document example
|-
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.signed.encrypted_pass doc.signed.encrypted_pass]
| encrypted document example
|-
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.signed.encrypted_symm doc.signed.encrypted_symm]
| encrypted document example
|-
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/mime.txt mime.txt] 
| MIME header example
|-
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/econtent_type.patch 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: [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/packages/DEN.Support.Materials.v1.zip DEN.Support.Materials.v1.zip]

[[Category:Profile Implementations]]


== Guidance on using both DEN and DSG ==

Please refer to this blog post on [http://healthcaresecprivacy.blogspot.com/2011/10/using-both-document-encryption-and.html Using both Document Encryption (DEN) and Document Digital Signature (DSG)]