play.libs
Class Crypto

java.lang.Object
  extended by play.libs.Crypto

public class Crypto
extends java.lang.Object

Cryptographic utilities.
These utilities are intended as a convenience, however it is important to read each methods documentation and understand the concepts behind encryption to use this class properly. Safe encryption is hard, and there is no substitute for an adequate understanding of cryptography. These methods will not be suitable for all encryption needs. For more information about cryptography, we recommend reading the OWASP Cryptographic Storage Cheatsheet: https://www.owasp.org/index.php/Cryptographic_Storage_Cheat_Sheet


Constructor Summary
Crypto()
           
 
Method Summary
static boolean compareSignedTokens(java.lang.String tokenA, java.lang.String tokenB)
          Compare two signed tokens
static boolean constantTimeEquals(java.lang.String a, java.lang.String b)
          Constant time equals method.
static java.lang.String decryptAES(java.lang.String value)
          Decrypt a String with the AES encryption standard using the application's secret key.
static java.lang.String decryptAES(java.lang.String value, java.lang.String privateKey)
          Decrypt a String with the AES encryption standard.
static java.lang.String encryptAES(java.lang.String value)
          Encrypt a String with the AES encryption standard using the application's secret key.
static java.lang.String encryptAES(java.lang.String value, java.lang.String privateKey)
          Encrypt a String with the AES encryption standard and the supplied private key.
static java.lang.String extractSignedToken(java.lang.String token)
          Extract a signed token that was signed by signToken(String).
static java.lang.String generateSignedToken()
          Generate a signed token
static java.lang.String generateToken()
          Generate a cryptographically secure token
static java.lang.String sign(java.lang.String message)
          Signs the given String with HMAC-SHA1 using the application's secret key.
static java.lang.String sign(java.lang.String message, byte[] key)
          Signs the given String with HMAC-SHA1 using the given key.
static java.lang.String signToken(java.lang.String token)
          Sign a token.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Crypto

public Crypto()
Method Detail

sign

public static java.lang.String sign(java.lang.String message,
                                    byte[] key)
Signs the given String with HMAC-SHA1 using the given key.
By default this uses the platform default JSSE provider. This can be overridden by defining application.crypto.provider in application.conf.

Parameters:
message - The message to sign.
key - The private key to sign with.
Returns:
A hexadecimal encoded signature.

sign

public static java.lang.String sign(java.lang.String message)
Signs the given String with HMAC-SHA1 using the application's secret key.
By default this uses the platform default JSSE provider. This can be overridden by defining application.crypto.provider in application.conf.

Parameters:
message - The message to sign.
Returns:
A hexadecimal encoded signature.

signToken

public static java.lang.String signToken(java.lang.String token)
Sign a token. This produces a new token, that has this token signed with a nonce. This primarily exists to defeat the BREACH vulnerability, as it allows the token to effectively be random per request, without actually changing the value.

Parameters:
token - The token to sign
Returns:
The signed token

extractSignedToken

public static java.lang.String extractSignedToken(java.lang.String token)
Extract a signed token that was signed by signToken(String).

Parameters:
token - The signed token to extract.
Returns:
The verified raw token, or null if the token isn't valid.

generateToken

public static java.lang.String generateToken()
Generate a cryptographically secure token


generateSignedToken

public static java.lang.String generateSignedToken()
Generate a signed token


compareSignedTokens

public static boolean compareSignedTokens(java.lang.String tokenA,
                                          java.lang.String tokenB)
Compare two signed tokens


constantTimeEquals

public static boolean constantTimeEquals(java.lang.String a,
                                         java.lang.String b)
Constant time equals method. Given a length that both Strings are equal to, this method will always run in constant time. This prevents timing attacks.


encryptAES

public static java.lang.String encryptAES(java.lang.String value)
Encrypt a String with the AES encryption standard using the application's secret key.
The provider used is by default this uses the platform default JSSE provider. This can be overridden by defining application.crypto.provider in application.conf.
The transformation algorithm used is the provider specific implementation of the AES name. On Oracles JDK, this is AES/ECB/PKCS5Padding. This algorithm is suitable for small amounts of data, typically less than 32 bytes, hence is useful for encrypting credit card numbers, passwords etc. For larger blocks of data, this algorithm may expose patterns and be vulnerable to repeat attacks.
The transformation algorithm can be configured by defining application.crypto.aes.transformation in application.conf. Although any cipher transformation algorithm can be selected here, the secret key spec used is always AES, so only AES transformation algorithms will work.

Parameters:
value - The String to encrypt.
Returns:
An hexadecimal encrypted string.

encryptAES

public static java.lang.String encryptAES(java.lang.String value,
                                          java.lang.String privateKey)
Encrypt a String with the AES encryption standard and the supplied private key.
The private key must have a length of 16 bytes.
The provider used is by default this uses the platform default JSSE provider. This can be overridden by defining application.crypto.provider in application.conf.
The transformation algorithm used is the provider specific implementation of the AES name. On Oracles JDK, this is AES/ECB/PKCS5Padding. This algorithm is suitable for small amounts of data, typically less than 32bytes, hence is useful for encrypting credit card numbers, passwords etc. For larger blocks of data, this algorithm may expose patterns and be vulnerable to repeat attacks.
The transformation algorithm can be configured by defining application.crypto.aes.transformation in application.conf. Although any cipher transformation algorithm can be selected here, the secret key spec used is always AES, so only AES transformation algorithms will work.

Parameters:
value - The String to encrypt.
privateKey - The key used to encrypt.
Returns:
An hexadecimal encrypted string.

decryptAES

public static java.lang.String decryptAES(java.lang.String value)
Decrypt a String with the AES encryption standard using the application's secret key.
The provider used is by default this uses the platform default JSSE provider. This can be overridden by defining application.crypto.provider in application.conf.
The transformation used is by default AES/ECB/PKCS5Padding. It can be configured by defining application.crypto.aes.transformation in application.conf. Although any cipher transformation algorithm can be selected here, the secret key spec used is always AES, so only AES transformation algorithms will work.

Parameters:
value - An hexadecimal encrypted string.
Returns:
The decrypted String.

decryptAES

public static java.lang.String decryptAES(java.lang.String value,
                                          java.lang.String privateKey)
Decrypt a String with the AES encryption standard.
The private key must have a length of 16 bytes.
The provider used is by default this uses the platform default JSSE provider. This can be overridden by defining application.crypto.provider in application.conf.
The transformation used is by default AES/ECB/PKCS5Padding. It can be configured by defining application.crypto.aes.transformation in application.conf. Although any cipher transformation algorithm can be selected here, the secret key spec used is always AES, so only AES transformation algorithms will work.

Parameters:
value - An hexadecimal encrypted string.
privateKey - The key used to encrypt.
Returns:
The decrypted String.