The ehealth platform

Transcription

1 Cookbook End-to-end Encryption Known recipient Version 2.3 This document is provided to you free of charge by The ehealth platform Willebroekkaai 38 Quai de Willebroeck 1000 BRUSSELS All are free to circulate this document with reference to the URL source.

2 Table of Contents Table of Contents Document management Document references Versioning Goal of the document Global Overview of the ETEE service Schema implicating both getetk webservice and Crypto Library Concepts and technologies Quick starting guide Prerequisites The Crypto Library ehealth Authentication Certificate ETK The ETK Depot Accessibility The getetk request The getetk response The Crypto Library Seal Unseal Error and Failure messages Verify ETK The RevocationStatusChecker Implementation aspects Development and test procedures Request for release into production Maintenance, support and monitoring of the service Risks Working environment Passphrases Keystores Storage of sealed messages Questions, problems and solutions ehealth helpdesk Typical set-up problems Licenses Apache Bouncy Castle Annex Service specification ehealth ETEE Unknown recipients v.1.2 2/34

3 1 Document management 1.1 Document references this chapter will not be published ID Title Version Date Author 1 Requesting ehealth Certificates v.2.0 May 2010 ehealth 2 Cookbook Cookbook v.2.0: End to end Encryption for a known recipient (addressed messages) v.2.1 April 2010 ehealth 3 Cookbook STS ehealth 4 Glossary 1.0 ehealth 1.2 Versioning The versions of the related components and documentation of this writing are Reference Version Date Crypto Library for addressed messages v getetk webservice v Obtaining an ehealth authentication certificate v Goal of the document This document is intended as an integration reference for the ehealth ETEE 1 base service. The target audience is defined as software integrators implementing the ETEE services in their own custom application. This is not a software manual for end users with instructions and screenshots of an application. Instead it explains the concepts, principles and the interface to the ETK 2 Depot and the Crypto Library. This document will provide all the necessary elements to get you started developing. It explains in that context: - the main concepts and principles - the usage of ETK Depot webservice - the usage of the Java Crypto Library This cookbook only deals with the first phase of the ETEE project: encryption of messages for a known recipient (also known as addressed messages ). 1 End to End Encryption 2 ehealth Token Key Service specification ehealth ETEE Unknown recipients v.1.2 3/34

4 2 Global Overview of the ETEE service 2.1 Schema implicating both getetk webservice and Crypto Library The ETEE service consists of two main parts: - The first part provides a webservice that will allow you to fetch the ETK of a recipient. You need the ETK of the recipient to send a message. - The second part is the Crypto Library that will seamlessly interact with the ETK. The crypto library will seal and unseal a secure message in one easy step. It can also verify the validity of an ETK and the ehealth authentication certificate. Sequence of events for: The sender: 1. Searching the ETK in the ETK Depot using the getetk webservice 2. Verifying the validity of the ETK using the VerifyEtk method of the Crypto Library Service specification ehealth ETEE Unknown recipients v.1.2 4/34

5 3. Securing a plaintext message using the Seal method of the Crypto Library. I.e. Signing and encrypting and signing (aka Triple Wrapping ) and conversion of the message to the specific CMS 3 format. Transfer message: 4. Please note that the ETEE base service (the ETK Depot nor the Crypto Library) does not provide tools for passing the CMS message from the sender to the receiver. A message can be passed by any possible means ( , webservices, cd rom, tape, internet, intranet, disks,...) and this process is not within the scope of the ETEE project. The receiver: 5. Decrypting the message using the Unseal method of the Crypto Library. This includes a thorough verification (certificatechecker) of the authentication certificates being used to sign the message. Message authenticity and integrity is confirmed. The authentication certificate of the sender is included in each message. All steps are performed through the Crypto Library, except the first step: the getetk webservice that fetches the ETK from the ETK Depot via webservices technology. 2.2 Concepts and technologies This section provides you with a brief introduction and some references to important concepts and technologies Asymmetric and Symmetric Encryption The ehealth Encryption service is based on Public Key cryptography. This means that both asymmetric and symmetric encryption algorithms are used to secure information. Asymmetric encryption algorithms use, as the name somewhat suggests, different keys for encryption and decryption. Symmetric algorithms use the same key for encrypting and decrypting information. Asymmetric encryption involves the usage of a public encryption key that is used to encrypt information and a private encryption key that is used to decrypt information. The private key file and its corresponding password must be protected to the maximum possible extent Bouncy Castle The reference implementation of the ETEE basic service is based on the standard library of the Legion of the Bouncy Castle 4. It is used for encryption, decryption and signing. Bouncy Castle is a collection of API 5 s used in cryptography. It includes APIs for both the Java and the C# programming languages Triple Wrapping Since message security relies on integrity, authenticity and confidentiality simply signing and encrypting a message does not suffice. Signing and Encrypting does not guarantee message authenticity because is vulnerable to surreptitious forwarding. A triple wrapped message is a message that has been signed, then encrypted, then signed again. Further details about these principles and the reasons behind why triple wrapping is required can be found in the paper Defective Sign & Encrypt in S/MIME,PKCS#7, MOSS, PEM, PGP, and XML Donald T. Davis (MIT) 3 Cryptographic Message Syntax Application Programming Interface Service specification ehealth ETEE Unknown recipients v.1.2 5/34

6 2.2.4 Certificates A certificate binds a public key to an identity with the signature of the Certification Authority. It holds no confidential information. The private key of the corresponding public key is usually password protected and must be kept private. End To End encryption uses two different key pairs for the signing and encryption to enhance security. An ehealth CA issued authentication keypair corresponds to exactly one ehealth issued encryption keypair. Each certificate has its public and private key. The public keys are available in the authentication and encryption certificate and both are available in the same ETK The ETK An ETK holds multiple certificates (an authentication and an encryption certificate) and has all the necessary elements to verify the integrity and identity of the holder of the private decryption key associated with the ETK. An ETK essentially contains two certificates that are linked together: a specific certificate for encryption and your authentication certificate for signing. This encryption certificate is signed with your CA issued authentication certificate. Additionally the ETK is signed by the ehealth RA. When sending a secured message the ETK of the recipient must be obtained. This will give the assurance that the message is sent to someone who was properly identified by the ehealth platform. You may not cache ETKs locally, always use a fresh ETK. The ehealth platform will only guarantee the validity of the ETK at the moment of downloading Encrypted message format The encrypted data messages are CMS messages as specified in RFC Any content can be encrypted by the Crypto Library regardless of their original format. A successful decryption will return the same that was originally encrypted. 6 Service specification ehealth ETEE Unknown recipients v.1.2 6/34

7 3 Quick starting guide 3.1 Prerequisites Java The ETEE Crypto Library can be used with any operating system that supports Java version Developers require the JDK. Clients that only use the ETEE service need to have the JRE installed. Java can be downloaded from Sun Microsystems Java Cryptography Extention (JCE) You are required to Download and Install the Java(TM) Cryptography Extension Unlimited Strength Jurisdiction Policy Files Error messages referring to an illegal keysize could indicate that this prerequisite was not satisfied. Please refer to the Problems and Solutions section in this case for further instructions Bouncy Castle The library has been tested with Bouncy Castle 1.39 for Java version The required Bouncy Castle libraries are delivered with the ETEE package you downloaded. The required JARs can also be downloaded from the Legion of the Bouncy Castle Get Log 4j Apache log4j is a Java based logging utility. You can download version 1.2 from the Apache Software Foundation. logging.apache.org 3.2 The Crypto Library The Crypto Library can be found in the technical library of the ehealth portal 8. Please check on a regular basis to confirm that you have the latest Crypto Library available. You can find all the necessary java documentation, examples, tests, test sources and additional libraries that are required and useful to test and integrate the Crypto Library. File: etee crypto [version].jar Java Documentation File: etee crypto [version] javadoc.jar The Java code has been thoroughly documented. A compilation of all this documentation can be found here. 7 Only Java version is supported 8 Service specification ehealth ETEE Unknown recipients v.1.2 7/34

8 3.2.2 Examples and tests File: etee crypto [version] tests.jar The examples within the packages demonstrate error and exception handling. These examples are detailed further in this document. The tests contain a number of JUnit Tests that can be used to check your configuration. All JUnit tests should pass successfully to confirm you have a good working environment. All JUnit files can be identified by their TEST prefix Test sources File: etee crypto [version] test sources.jar The test sources contain all necessary files and passwords to run the tests. These files can be key stores, test messages and ETKs. Private key stores containing Alice s and Bob s private authentication key and private encryption key including their corresponding certificates. As documented in the test resources, the passwords are always test Additional libraries These additional libraries can be identified as Bouncy Castle libraries, that are required at runtime. These are essential libraries that implement the base functionalities of cryptography. The additional libraries for Log4j Bouncy Castle are to be copied to the Java CLASSPATH. Files: bcmail jdk jar bcprov jdk jar The other libraries are testing dependencies that are useful if you want to run the JUnit tests or debug. Files: log4j jar junit 4.7.jar 3.3 ehealth Authentication Certificate The usage of the ETEE service requires you to have an ehealth authentication certificate. You can find a reference to the procedure as well to get an ETK in this document 9. Please note that ETEE requires you to have an ehealth Certificate as it is issued from February You can determine if you have a compatible certificate if the RDN in the certificate contains OrganizationUnit= ehealth platform Belgium More information and an up to date procedure is available on the ehealth website, section base services ehealth Certificates. 3.4 ETK You need to have an ehealth Authentication Certificate to create and publish your ETK. More information can be found on the ehealth website, section base services, End to End Encryption. 9 Procedure to obtain an ehealth platform Belgium Authentication Certificate respectively getting an ETK for the End To End Encryption base service is to be found on the ehealth portal technical library. Service specification ehealth ETEE Unknown recipients v.1.2 8/34

9 4 The ETK Depot 4.1 Accessibility The ETK Depot is accessible via webservices. The webservice URL for the ETEE getetk webservice can be obtained by contacting the ehealth platform. You will require an ehealth authentication certificate to access it. 4.2 The getetk request This part describes the structure of a getetk request message Structure of the request The getetkrequest contains solely an Identifier part: Field name Descriptions The Identifier block contains the search criteria for the ETK. The search criteria are of the identifiertype. Usually one identifier suffices to uniquely identify an ETK. An optional second identifier that must match also can be added. (these identifiers can be seen as conditions where the AND operator will be applied) Service specification ehealth ETEE Unknown recipients v.1.2 9/34

10 An identifiertype is composed as follows: Field name Type Descriptions The Type field identifies the type of identification number based on its origin. - For RIZIV INAMI number, use type NIHII - For RIZIV INAMI type hospital, use type NIHII HOSPITAL - For company number use type CBE - For pharmacy numbers recognized by the FAGG AFMPS use type NIHII PHARMACY - For Social Security numbers use type SSIN Value ApplicationID (Optional) The Value field needs to contain the number of the type you specified earlier. The value is of type string and can only contain numbers. Mind to keep the leading zeroes in e.g. the CBE number. The ApplicationID field specifies a particular entity, group, section, division, software application, within the organization identified using the Type and Value fields Example of a getetk Request <soapenv:envelope xmlns:soapenv=" xmlns:urn="urn:be:fgov:ehealth:etkdepot:1_0:protocol"> <soapenv:header/> <soapenv:body> <urn:getetkrequest> <urn:searchcriteria> <urn:identifier> <urn:type>nihii</urn:type> <urn:value> </urn:value> <urn:applicationid>xrays</urn:applicationid> </urn:identifier> </urn:searchcriteria> </urn:getetkrequest> </soapenv:body> </soapenv:envelope> 4.3 The getetk response This part describes the structure of a getetk response message. Service specification ehealth ETEE Unknown recipients v /34

11 4.3.1 Structure of the response Field name Id Descriptions The first part of the response will give internal information and a general status for your request. The number attributed to the request/reply by the ehealth platform. The Status block will contain a code and a message language reference. Status Code If no error has occurred during the transaction, the Code will be 200 The ETK for the given identifier has been found in the ETK Depot and is included in this response. Otherwise the statuscode will be: 200 The getetkrequest was correctly processed. Service specification ehealth ETEE Unknown recipients v /34

12 400 The getetkrequest SOAP message is not correct. 500 The ETK could not be retrieved due to an internal server error Message Returns the message language of the message, if any. The second part of this request will return the search criteria you submitted in your request. GivenSearchCriteria This branch if of the SearchCriteriaType in the form of one or two Identifiers that were used in the getetk request. The branch is optional since it will not be displayed in case of an internal server error. The following branch will return the ETK or other information when applicable. The 3 following elements are a choice. MatchingETK This means that multiple ETKs have been found matching your searchcriteria. No ETK is actually sent when this occurs. Instead, all Identifiers of all the ETKs matching your request are returned. This will enable you to further refine your searchcriteria to the ETK you are required to obtain. ETK Your search yielded a unique result. The ETK itself is returned in Base64 format. Error A semantic error occurred. One ore more error messages are included in the response. Service specification ehealth ETEE Unknown recipients v /34

13 4.3.2 Example of a getetk Response Remark: Showing the complete contents of the <ETK> tag has no additional value. Therefore a portion has been cut out in the middle of the string to reduce the size of this document. The original requests yields about 2 additional pages of output. <S:Envelope xmlns:s=" <S:Body> <ns2:getetkresponse xmlns:ns3="urn:be:fgov:ehealth:commons:1_0:core" xmlns:ns2="urn:be:fgov:ehealth:etkdepot:1_0:protocol" > <ns3:status> <Code>200</Code> <Message Lang="EN">The getetkrequest was correctly processed.</message> </ns3:status> <ns2:givensearchcriteria> <ns2:identifier> <ns2:type>nihii</ns2:type> <ns2:value>123</ns2:value> <ns2:applicationid>xrays</ns2:applicationid> </ns2:identifier> </ns2:givensearchcriteria> <ns2:etk>tulbr0ntcudtswizrfffsefxq0fnsufdqvffeen6qupcz1vyrgdnq0dnvufn SUFHQ1NxR1NJYjNEUUVIQWFDQUpJQUVnZ1BvTUlJRUNEQ0NBdkNnQXdJQkFnSVJBTlVtc mn0v2d5mecrc1bwbhjicgc2a3deuvlks29aswh2y05buuvgqlfbd2da.. </ns2:etk> </ns2:getetkresponse> </S:Body> </S:Envelope> Service specification ehealth ETEE Unknown recipients v /34

14 5 The Crypto Library Encrypting and Decrypting are the main functionalities of the crypto library. However, the encryption and decryption process includes additional operations. Therefore we can use Seal to reference to what is generally known as the Encrypt process and Unseal to reference what is generally known as the Decrypt process. The package contains examples that you can use to study and test the Seal and Unseal operation. The package references and includes all necessary resources (ExampleProperties). The Seal, Unseal and VerifyETK operations are discussed in detail in this section. These examples will give you a thorough understanding of the Crypto Library. In the following examples the Crypto library is used to Seal a message from Alice To Bob. The message is This is a secret message from Alice for Bob. Bob will successfully Unseal this message from Alice. 5.1 Seal General As explained before, simple signing and encrypting is not secure since it allows surreptitious forwarding and thus cannot guarantee message authenticity. Therefore each message is triple wrapped. This means that the data to be encrypted is signed by the author, encrypted for the recipient, and signed again by the author. This modus operandi assures message security in its broadest sense. Sequence of events 1. The inner signature is created: the message is signed and the signature is attached to the message 2. The actual encryption. The data from the previous step (the message and its signature) is encrypted with the public key of the ETK. 3. The outer signature is created. The data from the previous step is signed. This signature and the authentication certificate are appended to the message. The input arguments are: The passphrase of your private authentication key The ETK of the recipient The data to be encrypted The out put arguments is: The triple wrapped message to be sent to the recipient Service specification ehealth ETEE Unknown recipients v /34

15 5.1.2 Seal code sample / CVS file status: $Id: Seal.java,v /01/27 16:35:10 alde Exp $ Copyright (c) Smals / package be.smals.ehealth.etee.crypto.examples; import java.io.file; import java.io.filenotfoundexception; import java.io.fileoutputstream; import java.io.ioexception; import java.security.keystore; import java.security.keystoreexception; import java.security.nosuchalgorithmexception; import java.security.privatekey; import java.security.security; import java.security.unrecoverablekeyexception; import java.security.cert.x509certificate; import org.bouncy Castle.cms.CMSException; import org.bouncy Castle.jce.provider.Bouncy CastleProvider; import be.smals.ehealth.etee.crypto.encryptiontoken; import be.smals.ehealth.etee.crypto.testfiles; import be.smals.ehealth.etee.crypto.encrypt.datasealer; import be.smals.ehealth.etee.crypto.encrypt.datasealerfactory; import be.smals.ehealth.etee.crypto.utils.keymanager; / An example that illustrates the actions at Alice's (sender) side in order to protect an authenticated message, encrypted for Bob's (recipient) eyes / public class Seal implements TestFiles { args / public static void main(string[] args) { try { // 0. During initialisation, Alice creates her DataSealer that she can use to seal data. DataSealer alicesdatasealer = init(); // 1. Here Alice has a message for Bob that must be // sealed to secure its confidentiality, integrity and authenticity. byte[] messagefromalicetobob = "This is a secret message from Alice for Bob.".getBytes(); Service specification ehealth ETEE Unknown recipients v /34

16 // 2. Get the public encryption key of the addressee, Bob, from the ETK-DEPOT web service. EncryptionToken bobsetk = getbobsetkfrometkdepot(); // 3. Seal the datatobesealed byte[] sealeddata = alicesdatasealer.seal(bobsetk, messagefromalicetobob); File cmsfile = writetotransportmedium(sealeddata); System.out.println("The sealed data is written in file: " + cmsfile.getabsolutepath()); catch (IOException e) { System.err.println("The I/O operations during sealing the data failed or was interrupted."); e.printstacktrace(); catch (CMSException e) { System.err.println("The data sealing failed. Check the log and root cause of the exception for details."); e.printstacktrace(); catch (RuntimeException e) { // RuntimeException must not be catched, this is just to document that // RuntimeExceptions are due to : // - improper setup of the runtime environment (consult the FAQ section in the Cookbook) // - not related to the Crypto library of ehealth End-To-End Encrypton (check out the root cause). System.err.println("Your runtime environment is not properly set up regarding dependencies " + "(Consult the FAQ), or there are other issues not related to " + "the Crypto library of ehealth End-To-End Encrypton " + "(check out the root cause of the exception)"); e.printstacktrace(); catch (KeyStoreException e) { System.err.println("Alice's private authentication key could not be retrieved from her Keystore."); e.printstacktrace(); / During initialization, Alice creates a DataSealer that she can use later to protect her messages Alice's DataSealer, ready to sign and encrypt KeyStoreException - if Alice's private authentication key could not be retrieved from her keystore / private static DataSealer init() throws KeyStoreException { PrivateKey aliceauthenticationkey; X509Certificate aliceauthcertificate; DataSealer datasealer = null; // 0. Bouncy Castle must be added as a security provider // because the ehealth.etee.crypto library depends on it. Security.addProvider(new Bouncy CastleProvider()); // 1.0. Get the DataSealerFactory Service specification ehealth ETEE Unknown recipients v /34

17 DataSealerFactory datasealerfactory = DataSealerFactory.getInstance(); try { // 1.1. Get the sender's private authentication key for signature creation aliceauthenticationkey = KeyManager.getKey(getAliceKeyStore(), ExampleProperties.ALICES_AUTHENTICATION_KEY_ALIAS, ExampleProperties.ALICES_AUTHENTICATION_KEY_PASSWORD); // 1.2. Get the sender's authentication certificate that matches the authentication key aliceauthcertificate = KeyManager.getCertificate(getAliceKeyStore( ), ExampleProperties.ALICES_AUTHENTICATION_KEY_ALIAS); // 1.3 Get the DataSealer for Alice datasealer = datasealerfactory.getdatasealer(aliceauthenticationkey, aliceauthcertificate); catch (UnrecoverableKeyException e) { // TODO should be avoided e.printstacktrace(); catch (NoSuchAlgorithmException e) { // TODO should not be throwed, is not possible if BC is configured e.printstacktrace(); return datasealer; Alice's Keystore / private static KeyStore getalicekeystore() { return ExampleProperties.getAliceKeyStore(); / This method abstracts how the encryption token of the recipient is retrieved from the ETK-DEPOT web service. I.e. the implementation of this method is not representative for real world application. See the cookbook how to do Bob's encryption token. / private static EncryptionToken getbobsetkfrometkdepot() { return ExampleProperties.getBobEtk(); / This method abstracts how Alice's message after data sealing is transported to Bob. (This is application a File containing the sealed message of Alice. / private static File writetotransportmedium(byte[] sealeddata) { File cmsfile = new File("/message_from_alice_for_bob.msg"); Service specification ehealth ETEE Unknown recipients v /34

18 FileOutputStream fos; try { fos = new FileOutputStream(cmsFile); fos.write(sealeddata); fos.close(); catch (FileNotFoundException e) { System.err.println("This exceptions are not related to the crypto library of ehealth End-To-End Encrypton"); e.printstacktrace(); catch (IOException e) { System.err.println("This exceptions are not related to the crypto library of ehealth End-To-End Encrypton"); e.printstacktrace(); return cmsfile; Seal console ouput The expected output for this sealing example is: The sealed data is written in file: C:\message_from_alice_for_bob.msg Note that depending on your Log4j settings you can generate additional debugging output. 5.2 Unseal General Decrypting a message basically consists out of three steps that can be described as un wrapping the triple wrapped message. Sequence of events 1. Verifying the outer signature. This is done by verifying if the signed message digest matches the message digest as calculated by the recipient. The attached authentication certificate of the sender is checked (expiration date, chain of trust, revocation status, ) If these two checks are successful the signature is valid and data integrity can be assured. 2. Decrypting the encrypted message: an attempt is made to find and retrieve the relevant private key from the local keystore of the recipient. If the attempt is successful and the private key was found, the message is decrypted and the inner envelope is returned. 3. Verifying the inner signature: This is done by verifying if the signed message digest matches the message digest as calculated by the recipient. (see step 1) If this check is successful the signature is valid and data integrity can be assured. The input arguments are: - The certificate chain of the authentication certificate that was used to sign the message - The passphrase of the recipient s private decryption key - The chosen revocationstatuschecker - The ciphertext message that was received The output argument is: - The plaintext message Service specification ehealth ETEE Unknown recipients v /34

19 5.2.2 Unseal code sample / CVS file status: $Id: Unseal.java,v /01/27 16:35:50 alde Exp $ Copyright (c) Smals / package be.smals.ehealth.etee.crypto.examples; import java.io.file; import java.io.fileinputstream; import java.io.filenotfoundexception; import java.io.ioexception; import java.io.inputstream; import java.security.keystore; import java.security.keystoreexception; import java.security.nosuchalgorithmexception; import java.security.privatekey; import java.security.security; import java.security.cert.certificateexception; import java.util.map; import org.bouncy Castle.jce.provider.Bouncy CastleProvider; import be.smals.ehealth.etee.crypto.testfiles; import be.smals.ehealth.etee.crypto.cert.mockrevocationstatuschecker; import be.smals.ehealth.etee.crypto.cert.revocationstatuschecker; import be.smals.ehealth.etee.crypto.decrypt.dataauthenticationerror; import be.smals.ehealth.etee.crypto.decrypt.dataauthenticationfailure; import be.smals.ehealth.etee.crypto.decrypt.dataunsealer; import be.smals.ehealth.etee.crypto.decrypt.dataunsealerfactory; import be.smals.ehealth.etee.crypto.decrypt.unsealresult; import be.smals.ehealth.etee.crypto.utils.keymanager; / An example that illustrates the actions at Bob's (recipient) side in order to read and verify a sealed data message from Alice / public class Unseal implements TestFiles { args / public static void main(string[] args) { try { // 0. During initialisation, Bob creates his DataUnsealer that he can use to // decrypt and verify incomming sealed data. DataUnsealer bobsdataunsealer = init(); // 1. Now Bob receives some 'sealed data' Service specification ehealth ETEE Unknown recipients v /34

20 byte[] sealeddata = getsealeddata(); // 2. Unseal the received message UnsealResult rslt = bobsdataunsealer.unseal(sealeddata); // 3. Process the result of the unseal operation if (rslt.hasunsealeddata()) { // 3.A. The decryption operation succeeded if (rslt.isvalid()) { // 3.A.A. There are no errors or failures // 3.A.A.1. Get the author System.out.println("from author: " + rslt.getauthenticationcertificate().getsubjectdn()); // 3.A.A.2. Get the unsealed data System.out.println("unsealed data: " + new String(rslt.getUnsealedData())); else { // 3.A.B. The data authenticity is not OK // 3.A.B.1. Get the DataAuthenticationErrors or DataAuthenticationFailures // and do your specific security failure or error processing // BEFORE reading the unsealed data (otherwise you will have an RuntimeException for (DataAuthenticationError error : rslt.getdataauthenticationerrors()) { // e.g. System.err.println("error: " + error); for (DataAuthenticationFailure failure : rslt.getdataauthenticationfailures()) { // e.g. System.err.println("failure: " + failure); // 3.A.B.2. After checking the errors and failures you can get the unsealed data System.out.println("unsealed data: " + new String(rslt.getUnsealedData())); // 3.A.B.3. and in most cases also the author if (!rslt.getdataauthenticationfailures().contains(dataauthenticationfailure.a UTHENTICATION_CERTIFICATE_EXPECTED_BUT_NOT_PRESENT)) { System.out.println("author certificate: " + rslt.getauthenticationcertificate()); else { // 3.B the decryption failed, there is no decrypted data System.out.println("the msg could not be unsealed, because:" + rslt.getdecryptionfailure()); catch (CertificateException e) { System.err.println("creation of Bobs DataUnsealer failed:" + e.getstacktrace()); catch (KeyStoreException e) { System.err.println("creation of Bobs DataUnsealer failed:" + e.getstacktrace()); Service specification ehealth ETEE Unknown recipients v /34

21 catch (NoSuchAlgorithmException e) { System.err.println("creation of Bobs DataUnsealer failed:" + e.getstacktrace()); catch (IOException e) { System.err.println("creation of Bobs DataUnsealer failed:" + e.getstacktrace()); / During initialisation, Bob creates his DataUnsealer that he can use to decrypt and verify incomming sealed Bob's DataUnsealer, ready to decrypt and verify data sealed for NoSuchAlgorithmException / private static DataUnsealer init() throws CertificateException, IOException, KeyStoreException, NoSuchAlgorithmException { CertificateException - if any of the certificates in the keystore could not be IOException - if there is an I/O or format problem with the keystore data, if a password is required but not given, or if the given password was incorrect. If the error is due to a wrong password, the cause of the IOException should be an UnrecoverableKeyException. / DataUnsealerFactory dataunsealerfactory; DataUnsealer bobsdataunsealer = null; KeyStore cacertificateskeystore = null; KeyStore bobskeystore = null; Map<String, PrivateKey> bobsdecryptionkeys = null; RevocationStatusChecker revocationstatuschecker; // 1. Create Bob's DataUnsealer // 1.0. Bouncy Castle must be added as a security provider because // the ehealth.etee.crypto library depends on it. Security.addProvider(new Bouncy CastleProvider()); // 1.1 Get a DataUnsealerFactory dataunsealerfactory = DataUnsealerFactory.getInstance(); // 1.2 Get the keystore containing the CA certificates cacertificateskeystore = KeyManager.getKeyStore(getCaCertificateKeystoreIs(), ExampleProperties.LOCAL_CA_CERTIFICATES_STORE_TYPE, ExampleProperties.LOCAL_CA_CERTIFICATES_STORE_PASSWORD) ; // 1.3 Get Bob's decryption keys bobskeystore = KeyManager.getKeyStore(getBobsKeystoreIs(), ExampleProperties.BOBS_PRIVATE_KEYSTORE_TYPE, ExampleProperties.BOBS_PRIVATE_KEYSTORE_PASSWORD) ;

22 Service specification ehealth ETEE Unknown recipients v /34

23 bobsdecryptionkeys = KeyManager.getDecryptionKeys(bobsKeystore, ExampleProperties.BOBS_PRIVATE_DECRYPTION_KEY_PASSWORD); // 1.4 Choose your RevocationStatusChecker revocationstatuschecker = new MockRevocationStatusChecker(); // TODO should be the OCSP checker // 1.5 Now you have all what is necessary to create Bob's DataUnsealer bobsdataunsealer = dataunsealerfactory.getdataunsealer(cacertificateskeystore, bobsdecryptionkeys, revocationstatuschecker); return bobsdataunsealer; / Method to abstract how Bob received the sealed data from Alice comes. (This is application the sealed data from IOException / private static byte[] getsealeddata() { byte[] sealeddata = null; File encryptedmsg = new File("/message_from_alice_for_bob.msg"); FileInputStream fis; try { fis = new FileInputStream(encryptedMsg); sealeddata = new byte[fis.available()]; fis.read(sealeddata); catch (FileNotFoundException e) { e.printstacktrace(); new RuntimeException("The sealed data could not be retrieved."); catch (IOException e) { e.printstacktrace(); new RuntimeException("The sealed data could not be retrieved."); return sealeddata; InputStream to Bob's keystore / private static InputStream getbobskeystoreis() { return KeyStore.class.getResourceAsStream(ExampleProperties.BOBS_PRIVATE_KEYSTORE_ FILE); InputStream to the CA certificates keystore / private static InputStream getcacertificatekeystoreis() { Service specification ehealth ETEE Unknown recipients v /34

24 return Unseal.class.getResourceAsStream(ExampleProperties.LOCAL_CA_CERTIFICATES_S T ORE_FILE); Unseal console output Note: depending on your Log4j settings you can generate additional debugging output. from author: CN=NIHII\= ,OU=NIHII\= ,OU=Alice,OU=eHealthplatform Belgium,O=Federal Government,C=BE unsealed data: This is a secret message from Alice for Bob. 5.3 Error and Failure messages Possible errors and failures that can occur on the sealing or unsealing process can be catalogued into three different categories Data Authentication Error A DataAuthenticationError indicates that the decryption of an encrypted message was successfully completed, BUT that the integrity or author authentication of the message is NOT CORRECT according to the ehealth specifications. The source of the incorrectness is described by the DataAuthenticationError. Although it is not certain that the data authentication is broken, it is questionable. The receiver of such an encrypted message should not trust the origin of the message, nor the content Data Authentication Failure A DataAuthenticationFailure indicates that the decryption of an encrypted message was successfully completed, BUT that the integrity or author authentication of the message is violated. The source of the failure is described by the DataAuthenticationFailure. The receiver of such an encrypted message should not trust the origin of the message, nor the content Decryption Failure A DecryptionFailure indicates that the decryption process of an encrypted message could not be completed. The source of the failure is described by the DecryptionFailure. 5.4 Verify ETK General To ensure security, the ETK of a recipient needs to be fetched and validated by the sender of the message for each message being sent. This ETK validity verification is not automatically done by the Seal process. Normally, when an ETK has been fetched from ehealth, it is considered valid only at that point in time. The ETK must be validated before sending a message using the verify method that is available in the Crypto Library. Reminder: This is a reference for developers and not for end users. If and how this validation is done by the end user depends completely on how you implement the library. We suggest that ETK validation is done automatically in the background and that appropriate feedback is given to the end user. Sequence of events The ETK is verified. The following items of the ETK are checked: Service specification ehealth ETEE Unknown recipients v /34

25 1. whether the encryption token was signed by the private key that corresponds with the included authentication certificate 2. whether the ETKs validity period is respected 3. whether the encryption key algorithm is valid 4. whether the key usage of the encryption key is valid 5. whether the validity period is respected of the certificate with which the ETK is signed 6. whether the ETK is signed by a valid authentication certificate 7. whether the Subject of the ETK equals the Subject of the authentication certificate with which the ETK is signed The input arguments are: - The ETK to validate - The certificate chain of the authentication certificate that was used to sign the message - An implementation of a certificatechecker The output argument is: - An acknowledgement message ETK Validation Example / CVS file status: $Id: VerifyEtk.java,v /01/18 13:17:13 jeh Exp $ Copyright (c) Smals / package be.smals.ehealth.etee.crypto.examples; import java.security.keystore; import java.security.keystoreexception; import java.security.security; import java.security.cert.certificateexception; import org.bouncy Castle.jce.provider.Bouncy CastleProvider; import be.smals.ehealth.etee.crypto.encryptiontoken; import be.smals.ehealth.etee.crypto.cert.certificatechecker; import be.smals.ehealth.etee.crypto.cert.mockrevocationstatuschecker; import be.smals.ehealth.etee.crypto.cert.revocationstatuschecker; / Example to show how to verify a cached / public class VerifyEtk { public static void main(string[] args) { Service specification ehealth ETEE Unknown recipients v /34

26 // 0. Bouncy Castle must be added as a security provider // because the ehealth.etee.crypto library depends on it. Security.addProvider(new Bouncy CastleProvider()); // 1. Get the public encryption key of the addressee, Bob, from your cache. EncryptionToken bobsetk = getbobsetkfromcache(); // 2. Get a CertificateChecker CertificateChecker certificatechecker = new CertificateChecker(getRevocationStatusChecker()); // 3. Verify the ETK before using it to seal data try { bobsetk.verify(getcacertkeystore(), certificatechecker); System.out.println("The ETK of Bob is valid"); catch (CertificateException e) { e.printstacktrace(); throw new RuntimeException("the ETK of Bob is not valid"); catch (KeyStoreException e) { e.printstacktrace(); throw new RuntimeException("the certificate of the CA could not be retrieved"); / This method abstracts the retrieval of the Keystore containing the / private static KeyStore getcacertkeystore() { return ExampleProperties.getCaCertificatesStore(); / This method abstracts the retrieval or creation fo a RevocationStatusChecker. <p> This implementation returns a MockRevocationStatusChecker to make it work with the test certificates of Alice and Bob <b>but THIS IS NOT HOW TO DO IT IN REAL LIFE APPLICATION.</b> </p> <p> In real application you must use the OcspRevocationStatusChecker or your own implementation of the RevocationStatusChecker interface. RevocationStatusChecker / private static RevocationStatusChecker getrevocationstatuschecker() { RevocationStatusChecker revocationstatuschecker; //!!! don't use this in real life!!! revocationstatuschecker = new MockRevocationStatusChecker(); Service specification ehealth ETEE Unknown recipients v /34

27 // TODO include the real DN and cacert //!!! in real life USE the OcspRevocationStatusChecker!!! or your own implementation // X509Certificate cacert = ExampleProperties.getCaCertificates(); // get this from the ehealth site // String dn = ""; //get this from the ehealth site // revocationstatuschecker = new OcspRevocationStatusChecker(dn, cacert); return revocationstatuschecker; / This method abstracts how the encryption token of the recipient is retrieved from the ETK-DEPOT web service. So, the implementation of this method is not representative for real world application. See the cookbook how to do Bob's encryption token. / private static EncryptionToken getbobsetkfromcache() { return ExampleProperties.getBobEtk(); This assures the ETK validation. It returns nothing when the ETK is OK and throws and exception if there is a failure ETK Validation console output Note: depending on your Log4j settings you can generate additional debugging output. The ETK of Bob is valid 5.5 The RevocationStatusChecker A certificate that has been revoked has been invalidated by means of an explicit action of its holder. This can happen at any time, therefore it is required to go check if such a revocation occurred. This is done using information provided by the CA using different technologies. The RevocationStatusChecker calls the isrevoked method that returns the value True or False. If there is a problem (an Exception) the status will be considered as Unknown. Typically there are two technologies of checking if a certificate has been revoked. An integrator of the ehealth End To End Encryption Crypto Library can choose between different out of the box implementations, or provide a custom made implementation. The two out of the box implementations of the revocationstatuschecker are the CrlRevocationStatusChecker based on CRL (a periodically published list that contains the revoked serial numbers) and the OcspRevocationStatusChecker based on OCSP (a real time checker that returns true or false for a given input certificate serial number). Both are discussed further. In order to achieve the freshest certificate validity information, it is recommended to use the included OCSP method The CrlRevocationStatusChecker - the CrlRevocationStatusChecker tries to determine the CRL Distribution Point in the certificate. - next, it tries to fetch the CRL via the URL indicated in the CRL Distribution Point. Service specification ehealth ETEE Unknown recipients v /34

28 - the serial number of the authentication certificate being checked is matched against the serial numbers in the CRL. If a match is found, the certificate is identified as Revoked. Possible error messages are: - No CRLs found in the extensions of the certificate (the certificate has no details concerning the CRL Distribution points included.) - CRL not correct. (the CRL could be retrieved but its contents are not correct) - CRL could not be fetched. (the CRL is not available: this could be a server error or connection problem) - CRL URI 10 not correct. (the URI is not correct so an attempt to fetch the CRL will not be made) - If no CRL distribution points are found, you will get the message No CRLs found in the extensions of the certificate The OcspRevocationStatusChecker The OcspRevocationStatusChecker gathers all information needed for checking the certificate's revocation status through OCSP. Then it creates an OCSP request and sends it to an OCSP service and processes the response of the service. This response to the isrevoked method is a boolean. Performance remark: For high volumes of revocation status checks via OCSP, this implementation should be adapted to become a thread that accepts several requests, and bundles them into one OCSP request. Possible exceptions are: - The OCSP request is malformed and not accepted by the OCSP service. - The OCSP request is not authorized by the OCSP service. - The OCSP service is busy and could not process the OCSP request now. - An internal error occurred in the OCSP service. - The OCSP request is declined by the OCSP service because it must be signed. - The OCSP response contains an invalid Status code. 10 Uniform Resource Locator Service specification ehealth ETEE Unknown recipients v /34

29 6 Implementation aspects 6.1 Development and test procedures Once an ETK Depot client has been developed that can connect to our web service in acceptance environment integration and acceptance tests can begin. We ask to test during minimum one month. The reason behind this is to maximize the protection for production environment from any incidents. when you are developing an application that will use the ETEE infrastructure you are required to notify ehealth via a written document at least 3 months in advance before the scheduled production date. This is required for efficient capacity planning and will help the ehealth platform to assure the ehealth SLAs. If everything is fine, ehealth and the partner agree on a release date. ehealth should prepare the connection to the production environment and provides the URL of the production environment. During the release day, the partner in the Healthcare sector provides feed back to the designeated ehealth contact(s) on the release test results. A contract has to be signed where you as a partner confirm that the integrator will uphold to the ehealth rules also in case of new releases of his software. Please bear in mind that proof must be delivered that the following is implemented: Before encryption: always use a fresh ETK, this means caching of an earlier downloaded ETK for a while is not allowed one is obliged to immediately decrypt the received cipher text. It is not desirable to store received cipher text in order to decrypt later. Every time a user s private key is required the user has to enter the appropriate passphrase 6.2 Request for release into production If acceptance tests are successful, the partner in the Healthcare sector sends its test results, test performance results, with sample of request and ehealth answer to the ehealth point of contact by . Items to check before you can get access to the production environment: 1. Retrieve the ETK 2. Search for an ETK with criteria that should not give a result. This response should be correctly identified as No ETK found. 3. Search for an ETK with search criteria that yield multiple ETKs Service specification ehealth ETEE Unknown recipients v /34

30 6.3 Maintenance, support and monitoring of the service Once in production, the partner in the Healthcare sector who is using the web service for one of its applications will always test first in the acceptance environment before releasing any adaptation to its own application. In addition, the partner will inform ehealth on the changes and their test period. In case of the development of an additional use case based on an existing integration, ehealth must be informed at least one month in advance with a detailed estimate of the expected load. This will ensure an effective capacity management. In case of technical issues on the web service, the technician of the partner in the Healthcare sector may obtain support from ehealth. In case e Health finds a bug or vulnerability in its software, the partner is obliged to update its application with the latest version of the software within 10 business days. In case the partner finds a bug or vulnerability in the software that e health delivered, he is obliged to contact and inform e Health immediately and is forbidden to publish this bug or vulnerability by any means. Service specification ehealth ETEE Unknown recipients v /34

31 7 Risks 7.1 Working environment Your PC needs to be properly secured. This means that your computer has a quality and up to date antivirus software running and a network firewall. 7.2 Passphrases All of your passphrases need to be kept secured and they need to comply with the ehealth security policy. 7.3 Keystores Taking a backup of your keystore is a good practice. However, keep in mind that both the keystore as its backup contain your private key and need to be kept in a safe place. 7.4 Storage of sealed messages Users are required to immediately unseal the received cipher text. It is not advised to store received cipher text in order to unseal it later. The ETEE basic service is an encryption service for a message that is in transit. This means that the encryption is intended only to provide a secure passage of the message. It is not intended to provide secure storage of information. Secure storage of unencrypted information is the responsibility of the recipient of the message. If you keep your messages in an encrypted form the recipient will loose access to his data permanently if he loses his private key or the passphrase protecting it. Furthermore, at some point in time the ETK of the sender will be invalid. In that case, the recipient will have access to the message but it will result in an error pointing out that authentication failed. Service specification ehealth ETEE Unknown recipients v /34