Crypto
A micro-library for all Crypto related infrastructure.
In the example below 'cookie.encryption' is the baseConfigKey that is specified when the crypto utility is created. The 'previousKeys' element is optional.
# Base 64 encoded MD5 hash of application.secret
cookie.encryption {
key="gvBoGdgzqG1AarzF1LY0zQ=="
previousKeys=["AwMDAwMDAwMDAwMDAwMDAw==","BAQEBAQEBAQEBAQEBAQEBA=="]
}
Installing
Add the following to your SBT build:
resolvers += MavenRepository("HMRC-open-artefacts-maven2", "https://open.artefacts.tax.service.gov.uk/maven2")
libraryDependencies += "uk.gov.hmrc" %% "crypto" % "[INSERT-VERSION]"
Use
Symmetric encrypter/decrypters
Represented by the model Encrypter
and Decrypter
. Or AdEncrypter
AdDecrypter
for the associated data variant.
The different variants are provided by SymmetricCryptoFactory
.
The supported types are:
-
AesCrypto
An implementation of "AES" Cipher.
It represents the encypted data as
Crypted
, which contains a single base64 encoded String.Note, it is recommended to use
AesGCMCrypto
instead which uses a nonce to prevent repeatable encryptions.To create, either call
SymmetricCryptoFactory.aesCrypto
with the secret key, orSymmetricCryptoFactory.aesCryptoFromConfig
to look up the keys from config.SymmetricCryptoFactory.aesCryptoFromConfig
additionally supports decrypting with any available previous keys, to support key rotation. -
AesGCMCrypto
Similar to AesCrypto, but uses the GCM algorithm. This includes the use of a nonce, to prevent repeatable encryptions. Note, the associated data is always set to an empty array. Use
AesGcmAdCrypto
if setting the associated data is required.It represents the encypted data as
Crypted
, which contains a single base64 encoded String.To create, either call
SymmetricCryptoFactory.aesGcmCrypto
with the secret key, orSymmetricCryptoFactory.aesGcmCryptoFromConfig
to look up the keys from config.SymmetricCryptoFactory.aesGcmCryptoFromConfig
additionally supports decrypting with any available previous keys, to support key rotation. -
AesGcmAdCrypto
It is similar to
AesGCMCrypto
, but it additionally takes some associated data when encrypting and decrypting. This can be used to prevent copying encrypted data to another context.It is a replacement to
SecreGCMCipher
that was previously included in many clients; and to simplify migration, it represents the encrypted data withEncryptedValue
rather thanCrypted
.Note, if you are migrating from
SecureGCMCipher
, you will provide the key (and any previous keys) to the construction ofAesGcmAdCrypto
and not to each call toencrypt
/decrypt
. You will also need to importCryptoFormats.encryptedValueFormat
fromcrypto-json
.To create, either call
SymmetricCryptoFactory.aesGcmAdCrypto
with the secret key, orSymmetricCryptoFactory.aesGcmAdCryptoFromConfig
to look up the keys from config.SymmetricCryptoFactory.aesGcmAdCryptoFromConfig
additionally supports decrypting with any available previous keys, to support key rotation.
See java docs for more details.
Oneway hashers/verifiers
Represented by the model Hasher
and Verifier
.
The supported variants are provided by OnewayCryptoFactory
.
Sensitive
This model identifies data which should be encrypted. It can be used in conjunction with Crypto Json to encrypt in JSON for storing in database or sending over the wire. It also overrides toString
to suppress logging.
It is recommended to use Sensitive
rather than Protected
as provided by json-encyption
since the parameterised type is not erased, which can be useful with looking up a mongo codec in runtime for example.
Crypto Json
Provides Play json formats which encrypt the Sensitive
type. See Sensitive.
This replaces the json-encryption
library.
resolvers += MavenRepository("HMRC-open-artefacts-maven2", "https://open.artefacts.tax.service.gov.uk/maven2")
libraryDependencies += "uk.gov.hmrc" %% "crypto-json-play-xx" % "[INSERT-VERSION]"
Where play-xx
is your version of Play (e.g. play-28
).
Changes
Version 7.0.0
- The
secure
library has been rolled intocrypto
. The package has changed fromhmrc.gov.uk.secure
tohmrc.gov.uk.crypto.secure
. - The artefact
crypto-json-play-xx
has been added to replace thejson-encryption
library. It providesSensitive
rather thanProvided
to avoid erasure and doesn't leak the value intoString
. AesGcmAdCrypto
has been added. It is different fromAesGCMCrypto
in that it supports associated data to be provided on each encrypt/decrypt. This should replace customSecureGCMCipher
.SymmetricCryptoFactory
has been added to make finding/using symetric cryptos easier.CompositeSymmetricCrypto
has been deprecated. To compose cryptos, clients should useSymmetricCryptoFactory.composeCrypto
. Clients should not use theCompositeSymmetricCrypto
abstraction, which is implementation details of the composition of previous decrypters. Instead, they should useEncrypter with Decrypter
.
License
This code is open source software licensed under the Apache 2.0 License