This guide contains low-level technical information. Maybe you should start first with the Easy Usage or General Usage guides?

Encrypting texts

Jasypt offers support for performing PBE (Password Based Encryption) operations on texts. This is offered through the org.jasypt.encryption.pbe.PBEStringEncryptor interface and its default implementation, org.jasypt.encryption.pbe.StandardPBEStringEncryptor.

Basics

Jasypt uses the byte (binary) encryption mechanisms as a basis for text encryption, with the following specificity:

  • All the String results (of encryption) are encoded in BASE64 (or hexadecimal, if you prefer), and thus can be safely stored as US-ASCII characters. This output encoding can be chosen with the setStringOutputType method.

Usage

Assuming that you will be using the default implementation, once the StandardPBEStringEncryptor instance has been created, this is how it will work:

Configuration

The algorithm, password and key-obtention iterations can take values in any of these ways:

  • Using its default values (except for password).
  • Setting an org.jasypt.encryption.pbe.config.PBEConfig object which provides new configuration values. Learn More.
  • Calling the corresponding setAlgorithm(...), setProvider(...), setProviderName(...), setPassword(...), setKeyObtentionIterations(...), setSaltGenerator(...) or setIvGenerator(...) methods.

And the actual values to be used for initialization will be established by applying the following priorities:

  • First, the default values are considered (except for password).
  • Then, if a link org.jasypt.encryption.pbe.config.PBEConfig object has been set with setConfig(...), the non-null values returned by its getX() methods override the default values.
  • Finally, if the corresponding setX(...) method has been called on the encryptor itself for any of the configuration parameters, the values set by these calls override all of the above.

Initialization

Before it is ready to encrypt, an object of this class has to be initialised. Initialisation happens:

  • When initialize() is called.
  • When encrypt(...) or decrypt(...) are called for the first time, if initialize() has not been called before
  • Once an encryptor has been initialised, trying to change its configuration willresult in an AlreadyInitializedException being thrown.

Usage

An encryptor may be used for:

  • Encrypting messages, by calling the encrypt(..) method.
  • Decrypting messages, by calling the decrypt(...) method.

When using a random salt generator, two encryption results for the same message will always be different (except in the case of random salt coincidence). This enforces security by difficulting brute force attacks on sets of data at a time and forcing attackers to perform a brute force attack on each separate piece of encrypted data.

The same applies when a random IV generator is used: the IV should be random and only used one time, so org.jasypt.RandomIvGenerator is the recommended one.

Learn more

To learn more about the mechanisms involved in encryption, read PKCS #5: Password-Based Cryptography Standard.

Code examples

Easiest use: the BasicTextEncryptor util class:

...
BasicTextEncryptor textEncryptor = new BasicTextEncryptor();
textEncryptor.setPassword(myEncryptionPassword);
...
String myEncryptedText = textEncryptor.encrypt(myText);
...
String plainText = textEncryptor.decrypt(myEncryptedText);
...

More security: the StrongTextEncryptor util class with a much more secure (but slower!) algorithm (you may need to download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files to use it):

...
StrongTextEncryptor textEncryptor = new StrongTextEncryptor();
textEncryptor.setPassword(myEncryptionPassword);
...
String myEncryptedText = textEncryptor.encrypt(myText);
...
String plainText = textEncryptor.decrypt(myEncryptedText);
...

More security: the AES256TextEncryptor util class with a much more secure algorithm: PBEWithHMACSHA512AndAES_256, (you need Java 8 at least to use it):

...
AES256TextEncryptor textEncryptor = new AES256TextEncryptor();
textEncryptor.setPassword(myEncryptionPassword);
...
String myEncryptedText = textEncryptor.encrypt(myText);
...
String plainText = textEncryptor.decrypt(myEncryptedText);
...

All these util classes are in fact pre-configured, easy-to-use versions of StandardPBEStringEncryptor, so let's use the original class for total control:

...
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)
...

And we can even use a pooled version for higher performance in multi-processor/multi-core systems:

...
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);
...