General Usage

This section will teach you about the tools jasypt offers you when the easy utilities found in the easy usage page are not enough for your needs.

Digesters

Digesters are classes specialised in creating message digests (also called hashes) from input.

Message digests are the results of digest (or hash) functions, and they are unidirectional, this is, starting from a message digest, the original message cannot be reconstructed.

Because of this, message digests are very adequate for password encryption. In fact, in some countries, it is illegal to store a user's password in an unencrypted way, and even encrypted in a reversible (bi-directional) way.

Digesters in jasypt live in the org.jasypt.digest package, which is composed of the following interfaces:

  • ByteDigester for creating digests from byte array input.
  • StringDigester for creating digests from String input.

And the following standard implementations:

  • StandardByteDigester: very configurable and extremely secure implementation of ByteDigester, implemented following the directives given in PKCS #5: Password-Based Cryptography Standard.
  • StandardStringDigester: String counterpart to StandardByteDigester, receiving String input and returning charset-safe, BASE64 (or hexadecimal) encoded String output.

...with their corresponding pool-based implementations for high performance in multi-processor/multi-core systems:

  • PooledByteDigester: same API as StandardByteDigester, but in fact contains a pool of these objects that are used to serve digest/check requests in round-robin.
  • PooledStringDigester: same API as StandardStringDigester, but in fact contains a pool of these objects that are used to serve digest/check requests in round-robin.

Using them can be very simple:

...
StandardStringDigester digester = new StandardStringDigester();
digester.setAlgorithm("SHA-1");   // optionally set the algorithm
digester.setIterations(50000);  // increase security by performing 50000 hashing iterations
...
String digest = digester.digest(myMessage);
...

These digesters, both standard and pooled, implement a coherent and secure set of default configuration values, but they can be additionally configured in two ways:

  • By calling to its setX(...) methods (algorithm, provider, salt size, etc.)
  • By setting a DigesterConfig object which configures the digester. A default bean implementation of this interface is supplied (SimpleDigesterConfig), but the user can create his/her own one to be able to retrieve configuration parameters in whichever ways he/she needs.

Improving performance in multi-processor/multi-core systems

Pooled digesters have exactly the same API as their non-pooled Standard relatives --so they can be used interchangeably-- but add a new required configuration method called setPoolSize() which establishes the amount of standard digesters they will internally hold.

...
PooledStringDigester digester = new PooledStringDigester();
digester.setPoolSize(4);          // This would be a good value for a 4-core system 
digester.setAlgorithm("SHA-1");
digester.setIterations(50000);
...
String digest = digester.digest(myMessage);
...

These pooled objects will use their internal Standard* digesters to serve the requests in round-robin, so the amount of thread blocking caused by the synchronised code in the standard artifacts is reduced to a minimum.

These implementations do not create new threads, so they can be safely used in container-controlled environments which do not allow the creation of new threads.

The pool size recommended for a specific application and machine depends on many factors, but will be approximately equal to the number of processors/cores in the machine.

More info

Please refer to the JavaDoc for more information about usage and functionality.

Encryptors

Encryptors are classes specialised in performing bi-directional encryption operations. This is, they can both encrypt plain data and decrypt encrypted data.

The relevant interfaces for encryption in jasypt live in the org.jasypt.encryption package, and are:

  • ByteEncryptor for encryption and decryption of byte arrays.
  • StringEncryptor for encryption and decryption of Strings.
  • BigIntegerEncryptor for encryption and decryption of BigIntegers.
  • BigDecimalEncryptor for encryption and decryption of BigDecimals.

Jasypt provides implementations for one type of encryption: Password-Based Encryption (PBE).

Password-Based Encryption (PBE)

Password-Based encryption is performed by means of generating an encryption key from a user-supplied password, and feeding an encryption algorithm with both the input and the generated key. Keys are usually obtained by applying some hash function to the password.

So, all PBE encryptors in jasypt will need to be set a password before being used for encryption or decryption operations.

The relevant interfaces for PBE in jasypt live in the org.jasypt.encryption.pbe package, and are:

  • PBEByteEncryptor for password-based encryption and decryption of byte arrays.
  • PBEStringEncryptor for password-based encryption and decryption of Strings.
  • PBEBigIntegerEncryptor for password-based encryption and decryption of BigIntegers.
  • PBEBigDecimalEncryptor for password-based encryption and decryption of BigDecimals.

And the following standard implementations:

  • StandardPBEByteEncryptor: very configurable and extremely secure implementation of PBEByteEncryptor, implemented following the directives given in PKCS #5: Password-Based Cryptography Standard.
  • StandardPBEStringEncryptor: String counterpart to StandardPBEByteEncryptor, receiving String input and returning charset-safe, BASE64 (or hexadecimal) encoded String output as encryption results.
  • StandardPBEBigIntegerEncryptor: Equivalent to StandardPBEByteEncryptor, receiving BigInteger input and returning BigInteger output.
  • StandardPBEBigDecimalEncryptor: Equivalent to StandardPBEByteEncryptor, receiving BigDecimal input and returning BigDecimal output.

...with their corresponding pool-based implementations for high performance in multi-processor/multi-core systems:

  • PooledPBEByteEncryptor: same API as StandardPBEByteEncryptor, but in fact contains a pool of these objects that are used to serve encrypt/decrypt requests in round-robin.
  • PooledPBEStringEncryptor: same API as StandardPBEStringEncryptor, but in fact contains a pool of these objects that are used to serve encrypt/decrypt requests in round-robin.
  • PooledPBEBigIntegerEncryptor: same API as StandardPBEBigIntegerEncryptor, but in fact contains a pool of these objects that are used to serve encrypt/decrypt requests in round-robin.
  • PooledPBEBigDecimalEncryptor: same API as StandardPBEBigDecimalEncryptor, but in fact contains a pool of these objects that are used to serve encrypt/decrypt requests in round-robin.

It's basic usage can be very simple:

...
StandardPBEStringEncryptor encryptor = new StandardPBEStringEncryptor();
encryptor.setPassword("jasypt");                         // we HAVE TO set a password
encryptor.setAlgorithm("PBEWithHMACSHA512AndAES_256");   // optionally set the algorithm
encryptor.setIvGenerator(new RandomIvGenerator());       // for PBE-AES-based algorithms, the IV generator is MANDATORY
...
String encryptedText = encryptor.encrypt(myText);
...
String plainText = encryptor.decrypt(encryptedText);  // myText.equals(plainText)
...

As with digesters, Standard*Encryptors implement a coherent and secure set of default configuration values (except for the password), but they can also be additionally configured in two ways:

  • By calling to its setX(...) methods (algorithm, provider, password, salt, IV, etc...)
  • By setting a PBEConfig object which configures the digester. A default bean implementation of this interface is supplied (SimplePBEConfig), but the user can create his/her own one to be able to retrieve configuration parameters in whichever ways he/she needs (for instance, retrieve the password from a remote server).

Improving performance in multi-processor/multi-core systems

Pooled encryptors have exactly the same API as their non-pooled Standard relatives --so they can be used interchangeably-- but add a new required configuration method called setPoolSize() which establishes the amount of standard encryptors they will internally hold.

...
PooledPBEStringEncryptor encryptor = new PooledPBEStringEncryptor();
encryptor.setPoolSize(4);          // This would be a good value for a 4-core system
encryptor.setPassword("jasypt");
encryptor.setAlgorithm("PBEWithMD5AndTripleDES");
...
String encryptedText = encryptor.encrypt(myText);
...

These pooled objects will use their internal Standard* encryptors to serve the requests in round-robin, so the amount of thread blocking caused by the synchronised code in the standard artifacts is reduced to a minimum.

These implementations do not create new threads, so they can be safely used in container-controlled environments which do not allow the creation of new threads.

The pool size recommended for a specific application and machine depends on many factors, but will be approximately equal to the number of processors/cores in the machine.

More info

Please refer to the JavaDoc for more information about usage and functionality.