This documentation use unreleased features! See the Roadmap page.
During the QiPki development a comprehensive Crypto API was build and is still enhanced.
This library does not try to reinvent the wheel where good wheels are found. It leverages the
JCA
and BouncyCastle.
The main goal of the Crypto API is to ease the developer pain by wrapping underlying tools
with nice, strongly typed APIs and being easily testable, mockable, usable with dependency
injection tools like Guice, CDI or Qi4j.
Getting started
You will need java and
maven plus a source editor of your choice.
Create a new maven project
Start by creating a new maven project with the following command:
mvn -B archetype:generate -DarchetypeArtifactId=maven-archetype-quickstart -DgroupId=com.mycompany.app -DartifactId=my-app -Dversion=2.0-SNAPSHOT
Replace com.mycompany.app and my-app by the groupId and artifactId you want to use.
This should have created a my-app directory containing an empty java maven project.
Now, open the pom.xml file and add this before the <dependencies> section:
<build>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.5</source>
<target>1.5</target>
</configuration>
</plugin>
</plugins>
</build>
<repositories>
<repository>
<id>qipki-snapshots-repository</id>
<url>http://repository-qipki.forge.cloudbees.com/snapshot/</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
Depends on the qipki-crypto module
Add org.codeartisans.qipki:qipki-crypto as dependency to your project inside the
<dependencies> section:
<dependency>
<groupId>org.codeartisans.qipki</groupId>
<artifactId>qipki-crypto</artifactId>
<version>2.0-SNAPSHOT</version>
</dependency>
Ensure that everything works by issueing a mvn clean install command.
You can now start using the QiPki Crypto API.
Note that the examples below are automaticaly extracted from actual code, often from unit tests.
When applicable, theses examples show two ways to do things: with and without Qi4j.
You'll se that the plumbing code provided for integration with Qi4j ease things a lot.
Using another DI tool like Guice, CDI or Spring would help in quite the same way.
Digests aka. Hashes
A cryptographic hash function is a deterministic procedure that takes an arbitrary block of data
and returns a fixed-size bit string, the (cryptographic) hash value, such that an accidental or
intentional change to the data will change the hash value. The data to be encoded is often
called the "message," and the hash value is sometimes called the message digest or simply digest.
Cryptographic hash function
From Wikipedia, the free encyclopedia
The following code generate hexadecimal encoded hashes of a single string using several algorithms.
// Snippet extracted from DigesterTest.java starting on line 62
private void testDigester( Digester digester )
throws UnsupportedEncodingException
{
// Digest messages
String hexMd5 = digester.hexDigest( MESSAGE, DigestParameters.MD5 );
String hexSha1 = digester.hexDigest( MESSAGE, DigestParameters.SHA_1 );
String hexSha256 = digester.hexDigest( MESSAGE, DigestParameters.SHA_256 );
String hexSha384 = digester.hexDigest( MESSAGE, DigestParameters.SHA_384 );
String hexSha512 = digester.hexDigest( MESSAGE, DigestParameters.SHA_512 );
// Test
assertEquals( EXPECTED_MD5, hexMd5 );
assertEquals( EXPECTED_SHA_1, hexSha1 );
assertEquals( EXPECTED_SHA_256, hexSha256 );
assertEquals( EXPECTED_SHA_384, hexSha384 );
assertEquals( EXPECTED_SHA_512, hexSha512 );
}
The DigestParameters accept the following options:
DigestAlgorithm algorithm: the hashing algorithm to usebyte[] salt: the salt to useint iterations: the number of times the hashing algorithm will be run
Theses options let you make proper password hashing. Here is an example using a random 64 bits salt
and 1024 iterations:
// Snippet extracted from DigesterTest.java starting on line 83
public void saltedHashExample()
{
// A Base64 encoded SHA-256 digest using a 64bit random salt and 1024 iterations
String base64 = digester.base64Digest( MESSAGE, new DigestParameters( SHA_256, digester.generateSalt( 64 ), 1024 ) );
// A Hex encoded SHA-256 digest using a 64bit random salt and 1024 iterations
String hex = digester.hexDigest( MESSAGE, digester.newParamsBuilder().using( SHA_256 ).salted( 64 ).iterations( 1024 ).build() );
}
Symetric cryptography AES for example
Symmetric-key algorithms are a class of algorithms for cryptography that use trivially related,
often identical, cryptographic keys for both encryption of plaintext and decryption of
ciphertext. The encryption key is trivially related to the decryption key, in that they may be
identical or there is a simple transformation to go between the two keys. The keys, in practice,
represent a shared secret between two or more parties that can be used to maintain a private
information link.
Symmetric-key algorithm
From Wikipedia, the free encyclopedia
The following code generates a 128 bits AES key and then use it to cipher a string then to decipher it using CBC mode of operation and PKCS5 padding.
// Snippet extracted from CipherTest.java starting on line 77
private void testAES128( SymetricGenerator symGenerator, CipherFactory cipherFactory )
throws UnsupportedEncodingException
{
// AES-128 key generation
SecretKey key = symGenerator.generateCipheringKey( AES_128 );
String plainText = "CipherMe";
// Cipher creation
SymetricCipher cipher = cipherFactory.newSymetricCipher( AES_CBC_PKCS5 );
// Cipher and decipher
byte[] ciphered = cipher.cipher( plainText.getBytes( UTF_8 ), key );
byte[] deciphered = cipher.decipher( ciphered, key );
// Test
assertEquals( plainText, new String( deciphered, UTF_8 ) );
}
The very same operation applied on a data stream:
// Snippet extracted from CipherTest.java starting on line 98
public void testOnStreams()
throws UnsupportedEncodingException
{
// AES-128 key generation
SecretKey key = symGenerator.generateCipheringKey( AES_128 );
String plainText = "CipherMe in a stream";
// Cipher creation
SymetricCipher cipher = cipherFactory.newSymetricCipher( AES_CBC_PKCS5 );
// Ciphering…
InputStream inputStream = new ByteArrayInputStream( plainText.getBytes( UTF_8 ) );
ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
cipher.cipher( inputStream, outputStream, key );
byte[] ciphered = outputStream.toByteArray();
// Deciphering…
inputStream = new ByteArrayInputStream( ciphered );
outputStream = new ByteArrayOutputStream();
cipher.decipher( inputStream, outputStream, key );
byte[] deciphered = outputStream.toByteArray();
// Test
assertEquals( plainText, new String( deciphered, UTF_8 ) );
}
Message Authentication Codes
In cryptography, a message authentication code (often MAC) is a short piece of information used
to authenticate a message.
A MAC algorithm, sometimes called a keyed (cryptographic) hash function, accepts as input a
secret key and an arbitrary-length message to be authenticated, and outputs a MAC (sometimes
known as a tag). The MAC value protects both a message's data integrity as well as its
authenticity, by allowing verifiers (who also possess the secret key) to detect any changes to
the message content.
Message authentication code
From Wikipedia, the free encyclopedia
// Snippet extracted from MacTest.java starting on line 44
@Test
public void testMac()
{
// Alice & Bob
SecretKey signingKey = symGenerator.generateSigningKey( HmacSHA256_256 );
// Alice
String message = "Oh Bob, MAC me!";
String aliceMAC = mac.hexMac( message, new HMACParameters( HmacSHA256, signingKey ) );
System.out.println( "Alice: " + message + " [ " + aliceMAC + " ]" );
// Bob
String bobMAC = mac.hexMac( message, new HMACParameters( HmacSHA256, signingKey ) );
assertEquals( aliceMAC, bobMAC );
System.out.println( "Bob: Alright Alice!" + " [ " + bobMAC + " ]" );
}
Asymetric-key cryptography
Public-key cryptography refers to a cryptographic system requiring two separate keys, one to
lock or encrypt the plaintext, and one to unlock or decrypt the cyphertext. Neither key will do
both functions. One of these keys is published or public and the other is kept private. If the
lock/encryption key is the one published then the system enables private communication from the
public to the unlocking key's owner. If the unlock/decryption key is the one published then the
system serves as a signature verifier of documents locked by the owner of the private key.
Asymmetric-key cryptography
From Wikipedia, the free encyclopedia
TODO Add examples from the unit tests.
X.509
In cryptography, X.509 is an ITU-T standard for a public key infrastructure (PKI) and Privilege
Management Infrastructure (PMI). X.509 specifies, amongst other things, standard formats for
public key certificates, certificate revocation lists, attribute certificates, and a
certification path validation algorithm.
X.509
From Wikipedia, the free encyclopedia
Distinguished names
The DistinguishedName class hide api complexity needed to handle X.509 distinguished
names in the X.500
tradition, especially regarding encoding and special characters escape.
The DistinguishdNameTemplate class build on this to provide a convenient way to
generate DNs from templates:
// Snippet extracted from DistinguishedNameTemplateTest.java starting on line 39
@Test
public void testDistinguishedNameTemplate()
{
// Create a template
String template = "CN=${U_FIRSTNAME} ${U_LASTNAME}, E=${U_EMAIL}, O=${U_ORGANISATION}, "
+ "OU=Github, 0.9.2342.19200300.100.1.5=${D_SERIALNUMBER}";
// Prepare context properties
Map<String, String> context = new HashMap<String, String>();
context.put( "U_FIRSTNAME", "Paul" );
context.put( "U_LASTNAME", "Merl,=\"+<>#;\\in" );
context.put( "U_ORGANISATION", "Codearti€ans" );
context.put( "U_EMAIL", "paul+zog@nosphere.org" );
// Build the DistinguishedName instance
DistinguishedName dn = new DistinguishedNameTemplate( template ).buildDN( context );
systemOutput( dn );
// Assert formats
assertEquals( EXPECTED_RFC1779, dn.toString( RFC1779 ) );
assertEquals( EXPECTED_RFC1779_and_RFC3383, dn.toString( RFC1779_and_RFC3383 ) );
assertEquals( EXPECTED_RFC2253, dn.toString( RFC2253 ) );
assertEquals( EXPECTED_RFC2253_and_RFC3383, dn.toString( RFC2253_and_RFC3383 ) );
assertEquals( EXPECTED_RFC2253_CANONICAL, dn.toString( RFC2253_CANONICAL ) );
// Assert formats through BouncyCastle X509Name (does not support RFC1779 formatted Directory Strings)
assertEquals( EXPECTED_BC_RFC2253, new X509Name( dn.toString( RFC2253 ) ).toString() );
assertEquals( EXPECTED_BC_RFC2253_and_RFC3383, new X509Name( dn.toString( RFC2253_and_RFC3383 ) ).toString() );
assertEquals( EXPECTED_BC_RFC2253_CANONICAL, new X509Name( dn.toString( RFC2253_CANONICAL ) ).toString() );
}
I/O
TODO Add examples from the unit tests.
Logging
TODO Explain SLF4J usage and loggers hierarchy
Git (with the help of Github) empower you to fork a module, hack on the source and share those changes
with others. You only have to involve the project team when you are ready to contribute those changes
back into the project's master (upstream) branch by sending a pull request. This is the preferred
contribution workflow.