CWA2: Proof of concept TOOLS

TOOLS: Encryption and decryption

The objective of this document is to explain in short how to use the tools included in the Java Open Source packet cryptTools to encrypt and decrypt a file using XML encryption. Note these tools are part of a proof of concept, and still are in alpha state. These tools are therefore provided “AS IS”, without warranty of any kind.

Note all source codes (batch files, xml, command line, java, etc) end with two lines with three whitespaces an a dot (” .”). This is just only for compatibility with older navigators, and these two lines shouldn’t be considered part of the source code.

Download from here: cryptTools. Uncompress by example at c:\DEMOS

Prerequisites:

Before using these tools, you need:

1. Java: If Java SE (Standard Edition) is not installed on your computer, download from Oracle and install it. This packet has been tested with java version 1.6.0_45, so this version or a newer one should be fine. If Java SE is installed on your computer, verify version (by using “java –version”), and if needed download and install a newer one.
2. Packet crypTools. File cryptools_0_3_1.jar is the file, developed into the CEN WS XBRL project, where the classes have been packed. These classes are now under development, and are oriented just only as a proof of concept and didactic example, but not to be part of a production system. Source code will be available under an open-source license (EUPL and other FLOSS licenses are being considered).
3. File “allJKS.jks”. This file is a Java KeyStore. This Java KeyStore holds public/private RSA keys. Public keys are in the form of X509 certificates. You can use the sample java KeyStore file “allJKS.jks” (uncompress this zip file and extract allJKS.jks). These keys are self-generated (issuer=subject), and must be used just only for testing. These are not trusted certificates.
4. Apache Santuario (java edition), v. 1.5.4. Download from http://santuario.apache.org/download.html.
5. The Bouncy Castle Java Crypto APIs v. 1.49. Download from http://www.bouncycastle.org/latest_releases.html.
6. Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. This is a add-on on java installation to allow cryptographic extensions. Download and install from (take care on your java version):

• http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html or
• http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html

Encryption of a file: cypher.Encrypt

To Encrypt a file, use the command:

java.exe -classpath cryptTools_0_3_1.jar;commons-logging-1.1.1.jar;serializer-2.7.1.jar;xalan-2.7.1.jar;xercesImpl-2.9.1.jar;xml-apis-1.3.04.jar;xmlsec-1.5.4.jar;bcprov-jdk15on-149.jar cypher.LaunchEncryptFile -k keystoreFile -p keystorePassword -os keystoreAlias -fte FileNameToEncrypt -f OutputFileName
   .
   .

Where:

Implementation dependent parameters

• keystoreFile: Is the Java Keystore file (file “allJKS.jks”).
• keystorePassword: Is the password of the Java Keystore File. In the Java KeyStore “allJKS.jks” the password is “XBRL2013” (without “).

Functional parameters

• Receiver. The public key of the only one that decrypt the file (by using its private key), others do not have access to receiver’s private key. In this implementation, it is a keystoreAlias (Java Keystores identify key pairs by an alias). Current example file “allJKS.jks” store public/private keys for the next aliases

• declarer1
• declarer2
• declarer3
• nsa
• esa
• bankingunion

• FileNameToEncrypt: The file to be embedded and encrypted into the XML output file (OutputFileName).
• OutputFileName: The XML file to be generated, with XML encryption and the embedded encrypted file.

This tool uses XML encryption. The file is embedded into a XML document, and encrypted using symmetric algorithm AES-256. A key transport algorithm (RSA-OAEP) is used to encrypt the generated AES-256 secret key. Key transport algorithms are public key encryption algorithms especially specified for encrypting and decrypting keys (See http://www.w3.org/TR/2013/REC-xmlenc-core1-20130411/#sec-Alg-KeyTransport).

RSA-OAEP use RSA public key to encrypt AES secret key, and the AES secret key is used to encrypt the file. When de-ciphering, the RSA private key will be used to recover the AES secret key. This is SP800-56B complaint, using KTS-OAEP-basic, without key confirmation.

The use of AES256 is acceptable for encryption and decryption (the algorithm and key length is safe to use; no security risk is currently know). See NIST Special Publication 800-131A). Also, RSA is acceptable, with |n|=2048, for SP800-56B key agreement schemas. |n| is the length in bits of the RSA modulus (n=pq), and |n|=2048 means |n| is at least 2048.

AES256 is a block cipher, able to encrypt/decrypt messages of a fixed length (called block, in AES256 block size is 128 and key size is 256). To be able to encrypt/decrypt larger messages (larger than one block size), it’s needed a mode of operation, an algorithm that describe how to apply the block cipher many times to be able to work with larger messages.

Selected mode of operation is Galois Counter Model, as recommended in “XML Encryption Syntax and Processing Version 1.1 W3C Recommendation 11 April 2013”. For details on GCM, see NIST Special Publication 800-38D.

The certificate used to encrypt is also included in the XML file, to be able to identify the private key corresponding to this certificate later, when decrypting.

Basically the steps of this tool are:

• Create XML document with the embedded file
• Generate AES-256 key.
• Get RSA public key (and certificate) from Java Key Store.
• Cipher AES key with RSA, using RSA-OAEP.
• Cipher XML document (with the embedded file) with AES-256.
• Store all in a file using W3C Encryption format.

Sample file (cryptographic computed values not shown):

<xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" Type="http://www.w3.org/2001/04/xmlenc#Element">
    <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
    <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <xenc:EncryptedKey xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
            <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p">
                <xenc:OAEPparams>ZHVtbXkxMjM=</xenc:OAEPparams>
                <xenc11:MGF xmlns:xenc11="http://www.w3.org/2009/xmlenc11#" Algorithm="http://www.w3.org/2009/xmlenc11#mgf1sha1"/>
            </xenc:EncryptionMethod>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>. . .</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
            <xenc:CipherData>
                <xenc:CipherValue>. . .</xenc:CipherValue>
            </xenc:CipherData>
        </xenc:EncryptedKey>
    </ds:KeyInfo>
    <xenc:CipherData>
        <xenc:CipherValue>. . .</xenc:CipherValue>
    </xenc:CipherData>
</xenc:EncryptedData>
   .
   .

Sample command.

Note: remember to add the appropiate path to every jar file, by example, add c:\demos\cryptools\jars to cryptTools_0_3_1.jar, to commons-logging-1.1.1.jar, etc. Or run the command from the cryptoolsjars directory:

java.exe -classpath cryptTools_0_3_1.jar;commons-logging-1.1.1.jar;serializer-2.7.1.jar;xalan-2.7.1.jar;xercesImpl-2.9.1.jar;xml-apis-1.3.04.jar;xmlsec-1.5.4.jar;bcprov-jdk15on-149.jar cypher.LaunchEncryptFile -k c:\DEMOS\allJKS.jks -p XBRL2013 -os nsa -fte c:\DEMOS\helloworld.txt -f c:\DEMOS\helloworld.encrypted.xml
   .
   .

Sample output text on the screen:

oct 21, 2013 7:33:03 PM cypher.EncryptFile outputDocToFile
INFO: Wrote document containing encrypted data to file:/c:/DEMOS/helloworld.encrypted.xml
   .
   .

Decryption: cypher.Decrypt

To decrypt an xml file ciphered using the previous command, use the command:

java -classpath cryptTools_0_3_1.jar;commons-logging-1.1.1.jar;serializer-2.7.1.jar;xalan-27.1.jar;xercesImpl-2.9.1.jar;xml-apis-1.3.04.jar;xmlsec-1.5.4.jar;bcprov-jdk15on-149.jar cypher.LaunchDecryptFile  -k keystoreFile -p keystorePassword -f FileToUnEncrypt -o OutputPath
   .
   .

Where:

Functional parameters

• EncryptedFile: XML file with the embedded encrypted content. Output from previous tool cipher.Encrypt.
• OutputPath: Is the path where the embedded file (inside EncryptedFile) will be extracted after decrypting.

Implementation dependent parameters

• keystoreFile: Is the Java Keystore file (file “allJKS.jks”).
• keystorePassword: Is the password of the Java Keystore File. In the Java KeyStore “allJKS.jks” the password is “XBRL2013” (without “).

This tool search for the certificate included in the XML file “EncryptedFile”, looking for a a private key corresponding to this certificate in the specified Java Keystore File. Then this private key is used to decrypt the embedded ciphered content and output it inside OutputPath, using the original filename. This file name was stored as ID attribute before encrypting.

Sample command:

java.exe -classpath cryptTools_0_3_1.jar;commons-logging-1.1.1.jar;serializer-2.7.1.jar;xalan-2.7.1.jar;xercesImpl-2.9.1.jar;xml-apis-1.3.04.jar;xmlsec-1.5.4.jar;bcprov-jdk15on-149.jar cypher.LaunchDecryptFile -k c:\demos\allJKS.jks -p XBRL2013 -f c:\demos\helloworld.encrypted.xml -o c:\demos
   .
   .

Sample output text on the screen:

oct 21, 2013 7:48:13 PM cypher.DecryptFile loadEncryptionDocument
INFO: Encrypted document loaded from file:/c:/demos/helloworld.encrypted.xml
oct 21, 2013 7:48:13 PM cypher.DecryptFile loadDecryptionKey
INFO: Encrypted with X509 CERTIFICATE:
oct 21, 2013 7:48:13 PM cypher.DecryptFile loadDecryptionKey
INFO: Issuer: CN=NSA, OU=KeysDept, O=NSA, L=Luxemburg, ST=Luxemburg, C=LU
oct 21, 2013 7:48:13 PM cypher.DecryptFile loadDecryptionKey
INFO: Subject: CN=NSA, OU=KeysDept, O=NSA, L=Luxemburg, ST=Luxemburg, C=LU
oct 21, 2013 7:48:13 PM cypher.DecryptFile loadDecryptionKey
INFO: Found alias nsa for X509 Certificate.
oct 21, 2013 7:48:13 PM cypher.DecryptFile outputDocToFile
INFO: Wrote document containing decrypted data to c:\demos/helloworld.txt
   .
   .

Use from another program

Two utility classes to easy the call from another program (this is, as a library instead as a command line application) have been prepared: EncryptFileUtil and DecryptFileUtil.

Sample use of EncryptFileUtil inside a java code:

String fileToEncrypt="c:\DEMOS\fileshelloword.txt";
String ouputFile="c:\DEMOS\mytests\files\helloword.txt.xml";
String keyStoreFile="c:\DEMOS\allJKS.jks";
String alias="nsa";
String password="XBRL2013";
EncryptFileUtil encryptionUtility=new EncryptFileUtil();
encryptionUtility.doFileEncryption(fileToEncrypt, ouputFile, keyStoreFile, alias, password);
System.out.println("Encryption error flag: "+encryptionUtility.isErrorFlag());
System.out.println("Done.");
   .
   .

Sample use of DecryptFileUtil inside a java code:

String inputFile="c:\DEMOS\mytestsfileshelloword.txt.xml";
String outputPath="c:\DEMOS\mytestsfiles";
String keyStoreFile="c:\DEMOS\allJKS.jks";
String keyStorePassword="XBRL2013";
DecryptFileUtil decryptionUtility=new DecryptFileUtil();
decryptionUtility.doFileDecryption(inputFile, outputPath, keyStoreFile, keyStorePassword);
System.out.println("Error en descifrado: "+decryptionUtility.isErrorFlag());
System.out.println("Ruta fichero descifrado: "+decryptionUtility.getOutputPath());
System.out.println("Fichero descifrado: "+decryptionUtility.getEmbeddedFileName());
System.out.println("Done.");
   .
   .

Question? Please feel free to contact us: cenwsxbrl at gmail.com