Frequently Asked Questions

About Jasypt

  1. Where does Jasypt come from? Is it made or backed by any software company?
  2. Does it implement or include any cryptographic algorithms?
  3. Is it stable? Can it be considered production-ready?
  4. Does Jasypt offer any type of commercial support or warranty?
  5. How can I contribute to Jasypt?
  6. What is Jasypt's export classification in the United States of America?

General

  1. What is jasypt useful for? Give me some examples of use, please...
  2. Is it "simplified encryption" because it is less safe?
  3. Is jasypt intended for use only in web applications?
  4. I don't use Hibernate at all. Can I use jasypt anyway?
  5. I don't use Spring at all. Can I use jasypt anyway?
  6. I don't use Spring Security (or Acegi) at all. Can I use jasypt anyway?
  7. Can jasypt use the Bouncy Castle JCE provider? Is it required?
  8. Are algorithms like AES or WHIRLPOOL supported in jasypt?
  9. Which is the difference between digests and password-based encryption?
  10. How can I use a SNAPSHOT release of Jasypt?

Encrypting paswords

  1. I am already using X for encrypting passwords. Why would I want to use jasypt instead?
  2. I am already using Spring Security / Acegi for encrypting passwords. Why would I want to add jasypt to my security infrastructure?
  3. I want to encrypt passwords and I know NOTHING about encryption. What do I have to do?
  4. Can I decrypt an encrypted password?

Behaviour

  1. What does jasypt do to create message/password digests, exactly? They are so different to the ones I create manually with a MessageDigest object...
  2. If I create two digests of the same message (or I encrypt the same password twice), results differ. Is that normal?
  3. I see jasypt uses salt and iteration count for creating digests. Does it also use them for generating keys for password-based encryption?
  4. Why does jasypt number encryption support only apply to BigInteger and BigDecimal?
  5. Does jasypt store PBE encryption passwords as Strings in-memory? Isn't that a security issue?

Problems

  1. I receive a ClassNotFoundException when I try to encrypt or digest data.
  2. I receive a ClassNotFoundException for class com/ibm/icu/text/Normalizer when I try to encrypt or digest data.
  3. I do not get correct results when querying a Hibernate-mapped entity with encrypted fields when I set conditions on some of those fields.
  4. I receive an InvalidKeyException when trying to use the StrongTextEncryptor or the TripleDES or other strong algorithms, although some algorithms work alright.
  5. I keep on receiving EncryptionOperationNotPossibleException exceptions when trying to decrypt my data.

About Jasypt

Where does Jasypt come from? Is it made or backed by any software company?

Jasypt is Open Source Software created in his spare time by a Spanish Software Engineer called Daniel Fernández --also author of other popular java libraries like thymeleaf or op4j--, and which has also received contributions of diverse kind from some other people.

It is neither made nor backed by any software (or any other type of) company, and it is offered to the public totally free of charge, both in binary and in source code forms, under the Apache License 2.0.

[top]


Does it implement or include any cryptographic algorithms?

No, it doesn't, Jasypt by itself does not implement nor distribute in any of its forms any cryptographic algorithms. It simply uses the algorithms already present in the users' Java installations via the Java Cryptography Extension.

[top]


Is it stable? Can it be considered production-ready?

Yes, it can be considered stable and production-ready.

[top]


Does Jasypt offer any type of commercial support or warranty?

No, it does not. Commercial support is not offered at the moment.

Also, jasypt is offered without warranties of any kind, as expressed in the Apache 2.0 License.

[top]


How can I contribute to Jasypt?

In many ways:

  • You can write to the Team with your ideas for improving Jasypt.
  • You can contribute some code, write a patch for a new feature or behaviour (please, tell the project admins first about your idea so that effort can be correctly coordinated).
  • You can write articles, reviews, blog posts, etc. about Jasypt, showing how it works or how it integrates with other technologies.
  • You can promote Jasypt in your company/work, showing your colleagues or customers how encryption can be an easy and powerful task by using Jasypt.

If you want to contribute some code to Jasypt, please read first the page on Contributing to Jasypt.

[top]


What is Jasypt's export classification in the United States of America?

Although Jasypt does not implement nor distribute in any of its forms any cryptographic algorithms, it can use them via the Java Cryptography Extension API and, as such, it is classified under ECCN code 5D002 and approved for export under License Exception TSU.

[top]

General

What is jasypt useful for? Give me some examples of use, please...

Jasypt is useful for many encryption tasks associated with applications, for example:

  • Encrypting (digesting) passwords.
  • Encrypting sensitive information.
  • Encrypting data communications.
  • Creating sums for integrity checking of data.
  • ...and many more.

[top]


Is it "simplified encryption" because it is less safe?

No. Jasypt does not implement any encryption algorithms, but instead delegates to the ones already provided by a JCE (Java Cryptography Extension) provider, which can be either the default VM one or any other of your choice, adding a layer for ease and correctness of use, configurability, integration with many other technologies, etc.

It is "simplified encryption" because it is much easier to use and integrate than the standard APIs, but you will get the same encryption power as if you were using the JCE API directly, or even more, as jasypt will enforce best practices and use standards that will ensure that you always get the highest level of security from the encryption features present in your Java installation.

[top]


Is jasypt intended for use only in web applications?

No, not at all. Jasypt offers some special configuration facilities to web applications, but it is not necessary for an application to be web-based in order to use jasypt. Jasypt will not add any dependency on any web-related API to your application if you don't want it to.

[top]


I don't use Hibernate at all. Can I use jasypt anyway?

Yes, you can. Jasypt provides an optional integration package for Hibernate, but it does not need Hibernate for normal operation. It won't add a dependency on Hibernate to your project.

[top]


I don't use Spring at all. Can I use jasypt anyway?

Yes, you can. Jasypt is designed to be seamlessly integrated into a Spring-based application if required, but it does not depend on Spring in any way. It won't add a dependency on Spring to your project nor will force you to develop in an IoC-friendly manner.

[top]


I don't use Spring Security (or Acegi) at all. Can I use jasypt anyway?

Yes, you can. Jasypt provides an optional integration package for Spring Security, but it does not need Spring Security for normal operation.It won't add a dependency on Spring Security to your project.

[top]


Can jasypt use the Bouncy Castle JCE provider? Is it required?

Yes, since version 1.3, it can. The provider API in jasypt is open, so that you can use Bouncy Castle or any other JCE provider of your choice. You will only have to specify your provider to the encryptors or digesters you are using when configurig them.

But, Bouncy Castle is not required. Jasypt has no dependency on it, and thus you can decide not to use Bouncy Castle at all, for example if you want to use the algorithms shipped with your JVM's JCE default provider.

[top]


Are algorithms like AES or WHIRLPOOL supported in jasypt?

Yes and no. Jasypt by itself does not implement any algorithms, but it lets you use any JCE provider of your choice.

Both AES (encryption) and WHIRLPOOL (digests) are algorithms supported by the Bouncy Castle JCE provider, and thus you can use them from jasypt as long as you set Bouncy Castle as your JCE provider for your jasypt encryptors or digesters.

[top]


Which is the difference between digests and password-based encryption?

Digests are the results of applying cryptographic hash functions such as MD5, and are a type of one-way encryption. This means that an original input cannot be reconstructed from its digest, once it has been generated.

Password-based encryption is a type of bidirectional encryption, which means that encrypted data can be decypted to reconstruct the original input. Encryption is done by generating an encryption key, and passing it to an encryption algorithm such as DES. This key, in password-based encryption, is derived from a password set by the user (usually by a applying a digest algorithm to it).

[top]


How can I use a SNAPSHOT release of Jasypt?

From time to time, Jasypt will produce a snapshot release that will allow you to test new or being-developed features. These are non production ready releases, but will be stable enough for most testing purposes, and will enable you to try new features before they are generally available.

In order to use snapshot releases, you need to add the Sonatype OSS Snapshots repository in your Maven pom.xml file, like this (the · dots are only for indenting, remove them in your code):

<repositories>

··<repository>

····<id>sonatype-nexus-snapshots</id>

····<name>Sonatype Nexus Snapshots</name>

····<url>https://oss.sonatype.org/content/repositories/snapshots</url>

····<snapshots>

······<enabled>true</enabled>

····</snapshots>

··</repository>

</repositories>

Also, you will have to modify your Jasypt dependency/ies to use a snapshot version, which usually consists of the version number of the next release (not the current one), followed by -SNAPSHOT. For example, while 1.9.2 is the latest published stable release, snapshots will probably appear under the 1.9.3-SNAPSHOT or maybe 1.10.0-SNAPSHOT version numbers:

<dependency>

··<groupId>org.jasypt</groupId>

··<artifactId>jasypt</artifactId>

··<version>1.9.3-SNAPSHOT</version>

··<scope>compile</scope>

</dependency>

[top]

Encrypting paswords

I am already using X for encrypting passwords. Why would I want to use jasypt instead?

Well, first of all, if you are simply using a Message.digest() or a DigestUtils.md5() call to encrypt your passwords and store them in a database, you should know that your password system is much weaker than you think, and that acquiring access to your application could be easy for any attackers. And it even becomes worse as the number of users in your application increases.

If you want to learn why this happens and how you could try to avoid it, have a look at the article "How to encrypt user passwords".

...and, if you are not using such calls but some other APIs or techniques, maybe you should consider reading it anyway to know if jasypt can help you do things better.

If you are using Spring Security (former Acegi Security) for encrypting passwords in your application, check the corresponding question in this FAQ (below) to see what jasypt can do for you.

[top]


I am already using Spring Security / Acegi for encrypting passwords. Why would I want to add jasypt to my security infrastructure?

Before all, understand that jasypt is not a substitute for Spring Security / Acegi, which is a powerful and very complete security framework (and which use the Jasypt author recommends). Jasypt will instead integrate into Spring Security / Acegi and improve its password encoding capabilities.

Some reasons for considering this integration are:

  • First and most important, because the default standard encryptors (PasswordEncoder implementations) shipped with Spring Security (as of 2.0.1) are simple message digesters (one hashing iteration, none or user-property based fixed salt...), and are not as safe as jasypt's password encryptors can be (learn more about random salt and iteration count at the article "How to encrypt user passwords").
  • Second, because they don't provide the same level of configuration capabilities as jasypt's password encryptors: algorithms, parameters resolution...
  • And third, because using jasypt will help you decoupling your user management logic (more bussiness-oriented) from the authentication and authorization component represented by Spring Security (you won't need to add dependencies on Spring Security's PasswordEncoders to your user management logic, and will instead use classes from a more neutral library like jasypt).

For more information on integrating Jasypt into an Spring Security-enabled application, please check the Jasypt + Spring Security guide.

[top]


I want to encrypt passwords and I know NOTHING about encryption. What do I have to do?

Simply use org.jasypt.util.password.BasicPasswordEncryptor. There is nothing more you need to know (if you don't want to :-)).

If you want more power (such as deciding which algorithm to use), then you can have a look at org.jasypt.digest.StandardStringDigester.

And if you want to know more, have a look at the article How to encrypt user passwords to learn about how a password should be encrypted.

[top]


Can I decrypt an encrypted password?

If you have encrypted it using a message digesting technique, which is precisely what you should have done (by using a PasswordEncryptor implementation, StandardStringDigester or similar...), you cannot.

This is because digests are a one-way technique. Once you have created the digest, there is no way to reconstruct the original message (or password) back. To check if an input password matches a stored digest, the password is digested itself and then both digests are matched.

And why should passwords be encrypted in a way they cannot be decrypted? Because this is safest way to ensure that a password is known only to the user that created it, and that no one, not even system or database administrators, can know it.

[top]

Behaviour

What does jasypt do to create message/password digests, exactly? They are so different to the ones I create manually with a MessageDigest object...

Jasypt follows the RSA standards for the creation of digests (in fact, keys), specifically the use of both a (preferably random) salt and an iteration count.

The salt is an array of bytes (randomly and securely generated by default) which is added to the message prior to digest. The iteration count specifies how many times the hash function will be applied to the message.

This means that the process of digesting your passwords (or any other messages) with jasypt is not as simple (internally speaking) as just using MessageDigest, and because of this results look quite different.

For learning more about how password/message digesting works in jasypt, see Encrypting Passwords or the javadoc for the StandardStringDigester class.

For more info about the RSA standard, see PKCS #5: Password-Based Cryptography Standard.

[top]


If I create two digests of the same message (or I encrypt the same password twice), results differ. Is that normal?

If you are using a random salt generator (which is the default), yes, it is. It is normal and, specially if you are encrypting a password, it is good for you.

Using a random salt offers you several important security advantages as you can read in Encrypting Passwords, but if it is important for you that two digests of the same message be equal, you can set the salt size to 0 bytes or, if you prefer, use a different implementation of SaltGenerator.

A salt is also used for the obtention of keys for password-based encryption and so, when using a random salt generator (default), two password-based encryption results for the same original input will also differ. Nevertheless, this behaviour cannot be avoided in password-based encryption by setting a zero-byte long salt, as a salt is required by the PBE Java API itself. Thus, in this case you will have to use a fixed-salt SaltGenerator.

[top]


I see jasypt uses salt and iteration count for creating digests. Does it also use them for generating keys for password-based encryption?

Of course. You see the use of salt and iteration count more thoroughly explained in jasypt documentation when referred to digests, but this is simply because many people wrongly (and dangerously) forget about using them when doing digests of, say, passwords. Thus, it seemed important to remark its use when digesting.

On the contrary, password-based encryption is usually done the right way, partly because the Java API for PBE enforces it to some extent. Anyway, jasypt offers you the advantage of transparently dealing with secure salt generation and checking.

For more info about the way password-based encryption should be done (and is done by jasypt), see see PKCS #5: Password-Based Cryptography Standard.

[top]


Why does jasypt number encryption support only apply to BigInteger and BigDecimal?

Because numbers are encrypted using the byte encryption support (encryption algorithms refer to bytes, not numbers), and so the result of encrypting a number will span a higher number of bytes than the original number. This provokes that a 4-byte integer needs no less than 16 bytes when it is in encrypted form.

Because of this, only BigIntegers and BigDecimals are supported in jasypt, as they provide arbitrary precision and so can handle such a big amount of bytes.

Nevertheless, if you are looking for hibernate encryption support for Longs, Doubles, Integers... jasypt provides support for encrypting them stored into SQL VARCHAR fields (instead of NUMERIC ones). Have a look at the Hibernate Integration Guide for further details.

[top]


Does jasypt store PBE encryption passwords as Strings in-memory? Isn't that a security issue?

From version 1.8, Jasypt's out-of-the-box encryptor implementations do not store passwords as Strings in memory, but rather as char[] objects that are zeroed as soon as they are used. This improves jasypt's Java Virtual Machine environment safety in extreme security-conscious scenarios.

Besides not storing passwords as Strings (which can pose a risk because of being immutable objects), jasypt does its best for not creating temporary Strings storing the password at all during its operation --thus not having to rely on garbage collection for removing these from memory--, but because of the String-based java.text.Normalizer API for normalizing unicode, this can only be accomplished completely by adding icu4j at the classpath so that jasypt can use this library for normalization instead of java.text.Normalizer (icu4j provides a char[]-based API).

[top]

Problems

I receive a ClassNotFoundException when I try to encrypt or digest data.

You probably haven't added all the required dependencies to your classpath. Please check the Dependencies Page.

[top]


I receive a ClassNotFoundException for class com/ibm/icu/text/Normalizer when I try to encrypt or digest data.

Since version 1.5, jasypt does not include ICU4j's jar files in its standard distribution, as this dependency is not required unless java 1.5 or older versions are being used and the ICU4j library is a very large jar file.

You can manually download icu4j from the ICU4j website or from your maven repository. Please check the Dependencies and Jasypt + Maven pages for further information.

If you are receiving this error when using the CLI tools, check the CLI page about adding ICU4j to your classpath when executing the tools.

[top]


I do not get correct results when querying a Hibernate-mapped entity with encrypted fields when I set conditions on some of those fields.

This is normal behaviour if you are using a random salt generator for your encryptor (which is the default). In this case, two different encryption operations on the same data should not return the same value (due to the use of a random salt). Because of this, none of the fields that are set to be encrypted when persisted can be a part of a WHERE clause in your search queries for the entity they belong to.

If you need to query encrypted fields, you should set a fixed salt generator to your encryptor, so that the same text encrypted twice will produce the same results. Although, be warned that this will only allow you to use that field in EQUALITY comparisons inside a WHERE clause, and that you will be reducing your level of security for that field.

[top]


I receive an InvalidKeyException when trying to use the StrongTextEncryptor or the TripleDES or other strong algorithms, although some algorithms work alright.

This probably happens because you need download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files in order to be able to use strong-encryption algorithms like TripleDES.

[top]


I keep on receiving EncryptionOperationNotPossibleException exceptions when trying to decrypt my data.

EncryptionOperationNotPossibleException is a very general exception which jasypt raises whenever there is a problem with encryption or decryption operations. It does not provide any further information to prevent the encryption infrastructure from showing too much information about what is going on (we wouldn't want an attacker to get any algorithm-specific errors...)

When you get that error while decrypting, most of the times it will simply mean that the encrypted string you input was not adequate for the algorithm/password/keyObtentionIterations configuration you provided. Check that your encryptor is configured in exactly the same way as the one with which you originally encrypted the data.

Also, if you are storing your encrypted data into a database, check that the table columns that you use to store it are big enough to host the encrypted data (which is always bigger than the original data). If you are transmitting your encrypted data via HTTP, check that you are not having problems with the transmission of BASE64-encoded data as URL parameters (BASE64 uses characters which are forbidden in URL parameters, like "="). For these uses, try using hexadecimal output.

[top]