Difference between revisions of "Document Encryption - Implementation Notes and Examples"

From IHE Wiki
Jump to navigation Jump to search
 
(7 intermediate revisions by one other user not shown)
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 [http://wiki.ihe.net/index.php?title=Document_Encryption Document Encryption (DEN)] profile by providing examples and information on tooling support.
  
 
== CMS software ==
 
== CMS software ==
Line 18: Line 18:
 
! signature  
 
! signature  
 
(RSA)
 
(RSA)
−
! note
+
! remarks
 
|-
 
|-
 
| '''openssl'''  
 
| '''openssl'''  
Line 67: Line 67:
 
#OpenSSL in addition to its cryptographic library also offers a command line application with support for most functionality (see example section below)
 
#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
 
#supported, but untested
−
#TBD; look for CMS/PKCS7
+
#TBD (keywords CMS/PKCS7)
 
#TBD
 
#TBD
  
Line 79: Line 79:
  
 
=== Advanced functionality ===
 
=== Advanced functionality ===
−
TBD: e.g. multiple recipients
+
TBD
  
 
=== OpenSSL example ===
 
=== OpenSSL example ===
Line 91: Line 91:
 
notes:
 
notes:
 
*assumption: doc.mime contains mime-wrapped document
 
*assumption: doc.mime contains mime-wrapped document
−
*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)
+
*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
 
*example uses PKI key management method, AES-256 CBC encryption, SHA-256 digest
 
</blockquote>
 
</blockquote>
Line 110: Line 110:
  
  
−
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.
+
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 ==
 
== MIME header ==
Line 121: Line 121:
 
</blockquote>
 
</blockquote>
  
−
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)
+
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) ==
 
== Files (examples, scripts, patches) ==
Line 130: Line 130:
 
! Description
 
! Description
 
|-
 
|-
−
| [ftp://ftp.ihe.net/IT_Infrastructure/iheitiyr9-2011-2012/Technical_Cmte/Profile_Work/DocumentEncryption/implementation_support/den_cms_20110731/cmstest.sh cmstest.sh]
+
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/cmstest.sh cmstest.sh]
 
| script illustrating CMS functionality used by DEN profile
 
| 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]
+
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/output.txt output.txt]
 
| example cmstest.sh script output
 
| 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]
+
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.digested.encrypted_cert doc.digested.encrypted_cert]
 
| encrypted document example
 
| 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]
+
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.digested.encrypted_pass doc.digested.encrypted_pass]
 
| encrypted document example
 
| 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]
+
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.digested.encrypted_symm doc.digested.encrypted_symm]
 
| encrypted document example
 
| 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]
+
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.signed.encrypted_cert doc.signed.encrypted_cert]
 
| encrypted document example
 
| 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]
+
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.signed.encrypted_pass doc.signed.encrypted_pass]
 
| encrypted document example
 
| 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]
+
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/doc.signed.encrypted_symm doc.signed.encrypted_symm]
 
| encrypted document example
 
| 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]  
+
| [ftp://ftp.ihe.net/TF_Implementation_Material/ITI/examples/DEN/mime.txt mime.txt]  
 
| MIME header example
 
| 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]
+
| [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
 
| 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]
+
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]]
 
[[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)]

Latest revision as of 10:12, 24 October 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

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)

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