•  Print this page
    Print this page

Bouncy Castle Crypto package
 
 
The Bouncy Castle Crypto package is a Java implementation of cryptographic algorithms. The package is organised so that it contains a light-weight API suitable for use in any environment (including J2ME) with the additional infrastructure to conform the algorithms to the JCE framework. The package is distributed under a license based on the MIT X Consortium license, which means it is distributed at no charge for commercial or non-commercial use.

The Bouncy Castle Crypto package can be downloaded from: http://www.bouncycastle.org

The Bouncy Castle package can be downloaded in one go which includes JCE, provider, light weight API, J2ME, JDK1.2, JDK1.1, and JDK1.0 compatibility classes, signed jars, etc. or can be downloaded separately.

An overview of the Bouncy Castle libraries and their purpose can be found here below.
The jar files depends on the JVM version you have installed.

Bouncy Castle libraries
Jar/zipDescription
jce-jdkNN-MMM.jar Java Cryptography Extension (JCE) library

This package support the generation of certificates and PKCS10 signing requests.
bctsp-jdkNN-MMM.jar Bouncy Castle TSP (Time Stamp Protocol) library
bctest-jdkNN-MMM.jar Bouncy Castle test classes library
bcprov-jdkNN-MMM.jar Bouncy Castle provider library
bcpg-jdkNN-MMM.jar Bouncy Castle OpenPGP/BCPG library

A package dealing with OpenPGP objects.
bcmail-jdkNN-MMM.jar Bouncy Castle SMIME/CMS library

A package for processing RFC 3852 Cryptographic Message Syntax (CMS) objects - also referred to as PKCS#7 (formerly RFC 2630, 3369), and also dealing with S/MIME objects (RFC 3851).
cldc_classes.zip Bouncy Castle J2ME library
cldc_crypto.zip Bouncy Castle J2ME library
Note: NN=J2SE version, MMM=Bouncy Castle release

Quick guides







Cryptography basics



Information

The Security API is a core API of the Java programming language, built around the java.security package (and its subpackages).

The first release of the Security API in JDK 1.1 has introduced the "Java Cryptography Architecture" (JCA), a framework for accessing and developing cryptographic functionality for the Java platform. In JDK 1.1, the JCA included APIs for digital signatures and message digests.

The Java Cryptography Extension (JCE) extends the JCA API to include APIs for encryption, key exchange, and Message Authentication Code (MAC). Together, the JCE and the cryptography aspects of the SDK provide a complete, platform-independent cryptography API. JCE was previously an optional package (extension) to the Java 2 SDK, Standard Edition, versions 1.2.x and 1.3.x. JCE has now been integrated into the Java 2 SDK, v 1.4.

More information about the abbreviations, see quick guide "Cryptography abbreviations".



Message digest
J2SE 1.4.x supporting algorithms: MD5, SHA-1, SHA-256, SHA-384, SHA-512
A message digest is a number which is created algorithmically from a file/message and represents that file/message uniquely. If the file/message changes, the message digest will change.
In short message digests ensures the integrity of a file/message. Message digests are also known as one-way hash functions.

Note 1: If you want to use MD2 you must install a provider package, for example Bouncy Castle.
Note 2: MD2 and MD5 are 128-bit algorithms.
Note 3: MD5 is most used.
Note 4: SHA-1, SHA-256, SHA-384, SHA-512 are respectively 160, 256, 384, and 512-bits
              algorithms.
Note 5: SHA-1 is most used.

Code example 1: MessageDigestExample.java



Message authentication code
J2SE 1.4.x supporting algorithms: HmacMD5, HmacSHA1
If a key is used to create a message digest, the algorithm is known as a message authentication code. Due to key generation it takes a longer time before the message digest is created.

Code example 1: MessageAuthenticationCodeExample.java



Private key cryptography (a.k.a. symmetric key cryptography or shared key cryptography)
J2SE 1.4.x supporting algorithms: AES, Blowfish, DES, DESede
Using private key cryptography, Alice and Bob can communicate securely using the following simple protocol:
  • Alice and Bob each have the same private key that only they know and they agree to use a common cryptographic algorithm, or cipher.
  • Alice encrypts her message (=plaintext) with with the private key and sends the encrypted message (=ciphertext) to Bob.
  • Bob receives the encrypted message and decryptes it with the private key to re-create the original message.
The strength of the private key encryption is determined by the cryptography algorithm (=cipher) and the length of the key.
The message can be encrypted bit by bit or chunks of bits, called blocks. The blocks, called cipher blocks are typically 64 bits in size. If the message is not a multiple of 64 bits, then the short block must be padded. Single-bit ciphers are called stream ciphers. A well known cipher is the DES algorithm which uses 56-bit keys.
Note: Do not use DES, the key size is to weak.

Code example 1: PrivateExample.java
Code example 2: DESCipherGenerator.java
Code example 3: DESCryptoTest.java
Code example 4: DESKeyGenerator.java



Public key cryptography (also known as asymmetric key cryptography)
J2SE 1.4.x supporting algorithms: RSA, DH
Using public key cryptography, Alice wants to send an encrypted message to Bob using the following simple protocol:
  • Alice and Bob both have their own key pairs. A key pair consists of a public key and a private key. If the public key is used to encrypt something, then it can only be decrypted using the private key. And similarly, if the private key is used to encrypt something, then it can be decrypted only using the public key. It is not possible to figure out what the private key is given only the public key, or vice versa.
  • Alice wants to send an encrypted message to Bob. She encrypts the message (=plaintext) using Bob's public key and sends the encrypted message (=ciphertext) to Bob.
  • Bob receives the encrypted message and decryptes if it with his private key to to re-create the original message.
RSA is supported by J2SE 1.4. However to make this work you need a third-party library like BouncyCastle.

The Diffie-Hellman (DH)algorithm, also known as key-agreement algorithm is used to allow two parties to derive a secret key by sharing information over a public channel. This key can then be used for private key encryption.

Code example 1: PublicExample.java



Padding
J2SE 1.4.x supporting algorithms: No padding, PKCS5Padding, OAEPWith<digest>And<mgf>Padding, SSL3Padding
If the message is not a multiple of 64 bits, then the short block must be padded (see Symmetric key encryption). There are several ways to pad a block, such as using all zeroes or ones or by repeating a byte whose value represents the number of remaining bytes.

Code example 1: PrivateExample.java



Mode
The way we use a block cipher is called its mode of use. Modes allow you to specify how encryption will work. For example, you can allow the encryption of one block to be dependent on the encryption of the previous block, or you can make the encryption of one block independent of any other blocks. The Java platform supports the following modes:
  • NONE - No mode
  • Block modes - Messages are split in blocks.
    • ECB (Electronic Code Book)
      The message is broken into independent 64-bit blocks which are encrypted.

    • CBC (Cipher Block Chaining)
      The message is broken into 64-bit blocks, but they are linked together in the encryption operation.

    • PCBC (Propagating Cipher Block Chaining)
      Is a variation on the CBC mode of operation and is designed to extend or propagate a single bit error in the ciphertext. This allows errors in transmission to be captured and the resultant plaintext to be rejected.

  • Stream modes - On bit stream messages.
    • CFB (Cipher Feedback Mode)
      There message is treated as a stream of bits, added to the output of the DES, with the result being feed back for the next stage.

    • OFB (Output Feedback Mode)
      The message is treated as a stream of bits, added to the message, but with the feedback being independent of the message.

Code example 1: PrivateExample.java



Cryptographic Service Providers
Each SDK installation has one or more provider packages installed. J2SE can be enhanced by adding additional security algorithms libraries (statically or dynamically) from third-party vendors (a.k.a. cryptographic service providers or providers). A few of them are: Clients may configure their runtime with different providers, and specify a preference order for each of them. The preference order is the order in which providers are searched for requested services when no specific provider is requested. This is done by modifying the "java.security" file. This file is located at:
  • C:\Tools\java\j2sdk1.4.2_01\jre\lib\security (J2SE SDK location)
  • C:\Program Files\Java\j2re1.4.2_01\lib\security (J2SE runtime location)
When creating an instance of a service, you specify the algorithm but you can specify the provider by its name. For example:

Signature sign = Siganture.getInstance("SHA1WithDSA", "BC");



If you do not specify a provider, the first "SHA1WithDSA" is taken from the provider list (see file java.security).

The provider name can be found below:

ProviderProvider name
sun.security.provider.Sun SUN
com.sun.net.ssl.internal.ssl.Provider SunJSSE
com.sun.rsajca.Provider SunRsaSign
com.sun.crypto.provider.SunJCE SunJCE
sun.security.jgss.SunProvider SunJGSS
org.bouncycastle.jce.provider.BouncyCastleProvider BC

Code example 1: ProviderInformation.java
Code example 2: DynamicProvider.java
Code example 3: DESCipherGenerator.java
Code example 4: DESCryptoTest.java



Digital Signatures
J2SE 1.4.x supporting algorithms: MD2withRSA, MD5withRSA, SHA1withDSA, SHA1withRSA
A digital signature is an electronic signature that can be used to authenticate the identity of the sender of a message or the signer of a document.
Using digital signatures, Alice wants to send a message to Bob using the following simple protocol:
  • Alice creates a digest of the message, a sort of digital fingerprint.
  • Alice then encrypts the digest with her private key. The encrypted digest is the digital signature.
  • The encrypted digest is sent to Bob along with the message.
    Usually the message in not encrypted.
  • When Bob receives the message, he decrypts the digest using Alice's public key.
  • Bob then creates a digest of the message using the same function that Alice used.
  • Bob compares the digest that he created with the one that Alice encrypted. If the digests match, then Bob can be confident that the signed message is indeed from Alice. If they don't match, then the message has been tampered with or isn't from Alice at all.
Digital signatures do not provide encryption of the message, so encryption techniques must be used in conjunction with signatures if you also need confidentiality.

Code example 1: DigitalSignature1Example.java
Code example 2: DigitalSignature2Example.java



Digital Certificates
J2SE 1.4.x supporting algorithms: X.509 Digital Certificate Standard
A Digital Certificate is the electronic equivalent of a business license. Digital Certificates are issued by trusted third parties (a Certification Authority (CA)). Prior to issuing a Digital Certificate, a CA reviews an applicant's credentials, such as the Dun & Bradstreet number, Articles of Incorporation, and takes several other steps to ensure the organisation is not claiming a false identity. A Digital Certificate is signed with the CA's private key.

A Digital Certificate typically contains the following:
  • Owner's public key
  • Owner's name
  • Expiration date of the public key
  • Name of the issuer (the CA that issued the Digital Certificate)
  • Serial number of the Digital Certificate
  • Digital signature of the issuer
Using digital certificates, Alice wants to send an encrypted message to Bob using the following simple protocol:
  • Alice wants to have Bob's public key, she will go to a CA usually called Trent to ask for a copy.
  • Trent will then send her a message containing details of Bob's identity and Bob's public key. This message, called the certificate for Bob's public key, is signed by Trent.
  • Alice now verifies that the digital signature is correct using Trent's public key. If this is the case, she knows that she has Bob's real public key and she now also knows that Bob is called Bob.
  • Alice wants to send a secret message to Bob. She encrypts the message (=plaintext) using Bob's public key and sends the encrypted message (=ciphertext) to Bob.
  • Bob receives the encrypted message and decryptes if it with his private key to to re-create the original message.
There are many Certification Authorities issuing digital certificates, a few of them are: Now, thanks to CAcert, everyone can get a free digital certificate signed by a global player.
CAcert is a non-profit volunteer organization.



Java Cryptographic Services

Java Cryptographic Services
Cryptographic ServiceAlgorithms/TypesDescription
SecureRandom SHA1PRNG Generates random numbers appropriate for use in cryptography. SHA1PRNG is an implementation of the Pseudo Random Number Generator (PRNG) algorithm.

Class: java.security.SecureRandom

KeyGenerator AES, Blowfish, DES, DESede, HmacMD5, HmacSHA1 Generates secret keys to be used by other services with the same algorithms.

Class: javax.crypto.KeyGenerator

KeyPairGenerator DSA, RSA, DH Generates a pair of public and private keys to be used by other services with the same algorithms.
MessageDigest SHA1, MD5 Computes the digest of a message.
Mac HmacMD5, HmacSHA1 Computes the message authentication code of a message.
Signature SHA1WithDSA, SHA1WithRSA Creates and verifies the digital signature of a message
KeyStore JKS, JCEKS, PKCS12 Stores keys and certificates.
CertificateFactory X509 Creates certificates.
Cipher DES, TripleDES, Blowfish Encrypts and decrypts messages.
KeyAgreement DH Lets two parties agree on a secret key without exchanging it over an insecure medium.




Secure programming techniques
  • Store passwords as char arrays (NOT as Strings) and zero them out after use, due to memory snooping or disk block snooping (when memory is low, information is stored on disk swap space).
  • When objects are serialized, use the transient keyword on sensitive data fields which you do not want to be streamed. This will minimize snooping.


More information about cryptography, see: