Document Encryption - Implementation Notes and Examples: Difference between revisions

From IHE Wiki
Jump to navigation Jump to search
← Older editNewer edit →
Pkoster (talk | contribs)
37 edits
No edit summary
Pkoster (talk | contribs)
37 edits
No edit summary
Line 1: Line 1:
== Introduction ===
== Introduction ==
This page intends to support the implementation of the Document Encryption (DEN) profile by providing examples and information on tooling support.
This page intends to support the implementation of the Document Encryption (DEN) profile by providing examples and information on tooling support.


== Tooling ==
== CMS software ==
=== CMS ===


{| class="wikitable"
{| class="wikitable"
Line 9: Line 8:
! Software
! Software
! version
! version
! encryption (AES)
! encryption  
(AES)
! password
! password
! PKI
! PKI (certificate)
! shared key
! shared (symmetric) key
! digest (SHA-256)
! digest  
! signature (RSA)
(SHA-256)
! signature  
(RSA)
! note
! note
|-
|-
| openssl
| '''openssl'''
(note 1.)
| 1.0.0-d
| 1.0.0-d
| +
| +
| -
| -
| + (note 1)
| +
| +
| +
| +
| +
| +
| +
| +
|
|-
|-
| BouncyCastle
| '''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 ====
 
=== Interoperability ===


The following have been verified as being interoperable:
The following have been verified as being interoperable:
Line 45: Line 74:
TBD: interoperability matrix
TBD: interoperability matrix


==== Special cases ===
=== Advanced functionality ===
TBD: special cases, e.g. multiple recipients
TBD: e.g. multiple recipients


==== OpenSSL example ===
=== OpenSSL example ===
The following example demonstrates encryption of a file according to the CMS profile:
The following example demonstrates encryption of a file according to the CMS profile using the OpenSSL command line application:
<blockquote>
<blockquote>
openssl cms -binary -digest_create -md sha256 -in doc.mime -outform der -out doc.digested
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
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:
notes:
*assumption: doc.mime contains mime-wrapped document
*assumption: doc.mime contains mime-wrapped document
*proper handling of the econtent_type option requires a small patch
*the OpenSSL command line application has a small limitation, which requires a small [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/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
*example uses PKI key management method, AES-256 CBC encryption, SHA-256 digest


And decryption:
And decryption:
<blockquote>
<blockquote>
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 -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
openssl cms -digest_verify -inform der -in doc.digested.encrypted_cert.decrypted -outform der -out doc.digested.encrypted_cert.decrypted.verified
</blockquote>
</blockquote>
Line 69: Line 99:
* doc.digested.encrypted_cert.decrypted.verified should equal doc.mime
* doc.digested.encrypted_cert.decrypted.verified should equal doc.mime


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


== Document Encryption (DEN) ==
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>


=== MIME ===
 
A [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/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:
Example MIME header for DEN:
<blockquote>
<blockquote>
Line 82: Line 117:
</blockquote>
</blockquote>


== XDM Media Encryption option ==
The [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/mime.txt example] can also be downloaded (see files section)
TBD: provide example on CMS encapsulation of ZIP-ed XDM media content (without MIME wrapper).


== Example files, scripts, patches ==
== Files (examples, scripts, patches) ==
A ZIP archive with example files and scripts demonstrating the application of CMS can be downloaded from the IHE FTP site:
The following files are available to facillitate development and testing:
<< url >>
{| class="wikitable"
|-
! File
! Description
|-
| [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/cmstest.sh cmstest.sh]
| script illustrating CMS functionality used by DEN profile
|-
| [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/output.txt output.txt]
| example cmstest.sh script output
|-
| [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/doc.digested.encrypted_cert doc.digested.encrypted_cert]
| encrypted document example
|-
| [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/doc.digested.encrypted_pass doc.digested.encrypted_pass]
| encrypted document example
|-
| [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/doc.digested.encrypted_symm doc.digested.encrypted_symm]
| encrypted document example
|-
| [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/doc.signed.encrypted_cert doc.signed.encrypted_cert]
| encrypted document example
|-
| [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/doc.signed.encrypted_pass doc.signed.encrypted_pass]
| encrypted document example
|-
| [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/doc.signed.encrypted_symm doc.signed.encrypted_symm]
| encrypted document example
|-
| [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/mime.txt mime.txt]
| MIME header example
|-
| [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/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/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731.zip den_cms_20110731.zip]

Revision as of 13:53, 31 July 2011

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:

  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; look for 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: 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

Retrieved from "http://wiki.ihe.net/index.php?title=Document_Encryption_-_Implementation_Notes_and_Examples&oldid=52526"