Difference between revisions of "Common-utils-encryption"

From Gcube Wiki
Jump to: navigation, search
(String Decryption)
(XML Document Decryption)
 
(16 intermediate revisions by the same user not shown)
Line 3: Line 3:
  
 
=== Design and implementation notes ===  
 
=== Design and implementation notes ===  
The library uses a symmetric key based on the [http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf AES] standard algorithm for cryptography. It does expect that such a key is available on the local classpath.  
+
The library uses a symmetric key based on the [http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf AES] standard algorithm for cryptography. It does expect that such a key is available on the local classpath. Optionally, the key can be programmatically passed to the methods exposed by the Encrypters.
 +
 
 
In addition, the resulting encrypted data are encoded in the BASE 64 schema in order to represent them in the ASCII string format.
 
In addition, the resulting encrypted data are encoded in the BASE 64 schema in order to represent them in the ASCII string format.
  
 
The library builds on top of the [http://santuario.apache.org Apache XML Security for Java] library and the [http://www.w3.org/TR/xmlenc-core/ XML Encryption] standard.
 
The library builds on top of the [http://santuario.apache.org Apache XML Security for Java] library and the [http://www.w3.org/TR/xmlenc-core/ XML Encryption] standard.
  
The library exposes two main classes:
+
It exposes two main classes:
 
* <code>StringEncrypter</code> for encrypting/decrypting String objects
 
* <code>StringEncrypter</code> for encrypting/decrypting String objects
 
* <code>XMLDocumentEncrypter</code> for encrypting/decrypting XML Documents or Elements
 
* <code>XMLDocumentEncrypter</code> for encrypting/decrypting XML Documents or Elements
  
 
=== Sample Usage ===
 
=== Sample Usage ===
 
These samples are taken from the exploitation the resource library does of the encryption library for protecting the AccessData content of the RuntimeResource class.
 
  
 
==== String Encryption ====
 
==== String Encryption ====
 +
 +
This and the following sample are taken from the exploitation the resource library does of the encryption library for protecting the AccessData content of the RuntimeResource class.
  
 
The following snippet shows how to encrypt a string:
 
The following snippet shows how to encrypt a string:
Line 25: Line 26:
  
 
//...
 
//...
resource.setAccessData(new StringEncrypter("my sensible data").encrypt());
+
resource.setAccessData(StringEncrypter.getEncrypter().encrypt("my sensible data"));
  
 
</source>
 
</source>
Line 53: Line 54:
 
<Endpoint EntryName="ap">http://myaccesspoint.eu</Endpoint>
 
<Endpoint EntryName="ap">http://myaccesspoint.eu</Endpoint>
 
</Interface>
 
</Interface>
<AccessData>dtvKM4JImPLQvboHwBvKEur1tbvdnKXYB82AICLq5/c=</AccessData>
+
<AccessData>dtvKM4JImPLQvboHwBvKEur1tbvdnKXYB82AICLq5/c=</AccessData> <!-- here's the encrypted data -->
 
</AccessPoint>
 
</AccessPoint>
 
</Profile>
 
</Profile>
Line 68: Line 69:
 
//...
 
//...
 
AccessPoint ap = new AccessPoint();
 
AccessPoint ap = new AccessPoint();
ap.setAccessData(new StringEncrypter(this.load("AccessData")).decrypt());
+
ap.setAccessData(StringEncrypter.getEncrypter().decrypt(this.load("AccessData")));
 
System.out.println("Access data's content: " + ap.getAccessData());
 
System.out.println("Access data's content: " + ap.getAccessData());
  
Line 79: Line 80:
  
 
==== XML Document Encryption ====
 
==== XML Document Encryption ====
TBP
+
The following snippet shows how to encrypt the content of the root element of an XML document:
 +
 
 +
<source lang="java">
 +
 
 +
import org.gcube.common.utils.encryption.XMLDocumentEncrypter;
 +
import org.w3c.dom.Document;
 +
import org.w3c.dom.Element;
 +
 
 +
//...
 +
Document doc = createSampleDocument();
 +
XMLDocumentEncrypter edoc = new XMLDocumentEncrypter(doc);
 +
XMLDocumentEncrypter.getEncrypter().encrypt(doc.getDocumentElement());
 +
</source>
 +
 
 +
Here it is the XML document before the encryption:
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
  <myns:RootElement xmlns:myns="http://www.myns.org/ns/#app1">
 +
    <myns:foo>Some simple text</myns:foo>
 +
  </myns:RootElement>
 +
</source>
 +
 
 +
 
 +
...and here it is the same document after the encryption:
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<myns:RootElement xmlns:myns="http://www.myns.org/ns/#app1">
 +
  <xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" Type="http://www.w3.org/2001/04/xmlenc#Content"> 
 +
    <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
 +
    <xenc:CipherData>
 +
      <xenc:CipherValue>HcfOBbYyR8lUZBTcd47XfBYRMQoAToQyymmq/eG0tjtk8vFzSRBL1UKIADEHkHQjy+1pQrNNZndP
 +
dW9wkBLxgImz0fIQlLx7AEtcFzkWQHsS4QcX0ssnyzMd86fAFGZHMjIEMGI9Dv31eJNoHGF2SQ==</xenc:CipherValue>
 +
    </xenc:CipherData>
 +
    </xenc:EncryptedData>
 +
</myns:RootElement>
 +
 
 +
</source>
  
 
==== XML Document Decryption ====
 
==== XML Document Decryption ====
TBP
+
The following code shows how to decrypt the root Element of the Document encrypted in the previous example:
 +
<source lang="java">
 +
import org.gcube.common.utils.encryption.XMLDocumentEncrypter;
 +
 
 +
//...
 +
Document doc = XMLDocumentUtils.deserialize(encDoc);
 +
XMLDocumentEncrypter.getEncrypter().decrypt(doc.getDocumentElement());
 +
System.out.println("The document after the decryption:");
 +
System.out.println(XMLDocumentUtils.serialize(doc));
 +
</source>
 +
 
 +
This will print out:
 +
 
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
  <myns:RootElement xmlns:myns="http://www.myns.org/ns/#app1">
 +
    <myns:foo>Some simple text</myns:foo>
 +
  </myns:RootElement>
 +
</source>

Latest revision as of 21:33, 27 January 2012

Scope

This library offers an easy way to encrypt and decrypt XML documents and String objects.

Design and implementation notes

The library uses a symmetric key based on the AES standard algorithm for cryptography. It does expect that such a key is available on the local classpath. Optionally, the key can be programmatically passed to the methods exposed by the Encrypters.

In addition, the resulting encrypted data are encoded in the BASE 64 schema in order to represent them in the ASCII string format.

The library builds on top of the Apache XML Security for Java library and the XML Encryption standard.

It exposes two main classes:

  • StringEncrypter for encrypting/decrypting String objects
  • XMLDocumentEncrypter for encrypting/decrypting XML Documents or Elements

Sample Usage

String Encryption

This and the following sample are taken from the exploitation the resource library does of the encryption library for protecting the AccessData content of the RuntimeResource class.

The following snippet shows how to encrypt a string:

import org.gcube.common.utils.encryption.StringEncrypter;
 
//...
resource.setAccessData(StringEncrypter.getEncrypter().encrypt("my sensible data"));

After its serialization, the resource appears as follows:

<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>
<Resource version="0.4.x">
	<ID>ac41d0d0-4791-11e1-b442-a3a8a4cd06fd</ID>
	<Type>RuntimeResource</Type>
	<Profile>
		<Category>test category</Category>
		<Name>resource name</Name>
		<Description>a description</Description>
		<Platform>
			<Name>Test platform</Name>
			<Version>1</Version>
			<MinorVersion>1</MinorVersion>
		</Platform>
		<RunTime>
			<HostedOn>macos-manuele</HostedOn>
			<GHN UniqueID="123456789"/>
			<Status>READY</Status>
		</RunTime>
		<AccessPoint>
			<Interface>
				<Endpoint EntryName="ap">http://myaccesspoint.eu</Endpoint>
			</Interface>
			<AccessData>dtvKM4JImPLQvboHwBvKEur1tbvdnKXYB82AICLq5/c=</AccessData> <!-- here's the encrypted data -->
		</AccessPoint>
	</Profile>
</Resource>

String Decryption

The following snippet shows how to decrypt a string:

import org.gcube.common.utils.encryption.StringEncrypter;
 
//...
AccessPoint ap = new AccessPoint();
ap.setAccessData(StringEncrypter.getEncrypter().decrypt(this.load("AccessData")));
System.out.println("Access data's content: " + ap.getAccessData());

This will print the following line:

Access data's content: my sensible data

XML Document Encryption

The following snippet shows how to encrypt the content of the root element of an XML document:

import org.gcube.common.utils.encryption.XMLDocumentEncrypter;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
 
//...
Document doc = createSampleDocument();
XMLDocumentEncrypter edoc = new XMLDocumentEncrypter(doc);
XMLDocumentEncrypter.getEncrypter().encrypt(doc.getDocumentElement());

Here it is the XML document before the encryption:

<?xml version="1.0" encoding="UTF-8"?>
  <myns:RootElement xmlns:myns="http://www.myns.org/ns/#app1">
     <myns:foo>Some simple text</myns:foo>
  </myns:RootElement>


...and here it is the same document after the encryption:

<?xml version="1.0" encoding="UTF-8"?>
 <myns:RootElement xmlns:myns="http://www.myns.org/ns/#app1">
   <xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" Type="http://www.w3.org/2001/04/xmlenc#Content">  
     <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
     <xenc:CipherData>
       <xenc:CipherValue>HcfOBbYyR8lUZBTcd47XfBYRMQoAToQyymmq/eG0tjtk8vFzSRBL1UKIADEHkHQjy+1pQrNNZndP
dW9wkBLxgImz0fIQlLx7AEtcFzkWQHsS4QcX0ssnyzMd86fAFGZHMjIEMGI9Dv31eJNoHGF2SQ==</xenc:CipherValue>
     </xenc:CipherData>
    </xenc:EncryptedData>
 </myns:RootElement>

XML Document Decryption

The following code shows how to decrypt the root Element of the Document encrypted in the previous example:

import org.gcube.common.utils.encryption.XMLDocumentEncrypter;
 
//...
Document doc = XMLDocumentUtils.deserialize(encDoc);
XMLDocumentEncrypter.getEncrypter().decrypt(doc.getDocumentElement());
System.out.println("The document after the decryption:");
System.out.println(XMLDocumentUtils.serialize(doc));

This will print out:

<?xml version="1.0" encoding="UTF-8"?>
  <myns:RootElement xmlns:myns="http://www.myns.org/ns/#app1">
    <myns:foo>Some simple text</myns:foo>
  </myns:RootElement>