CryptoSupport (The Adobe AEM Quickstart and Web Application.)

```
@ProviderType
public interface CryptoSupport
```
The CryptoSupport provides a simple API to encrypt and decrypt binary and string data.
This interface is not intended to be implemented by consumers. To use the API get the service from the service registry under the name "com.adobe.granite.crypto.CryptoSupport".

Field Summary

Fields
Modifier and Type Field and Description

static java.lang.String NAME
Name of the Encryption/Decryption service which may be used securily store sensitive data.

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`NAME` Name of the Encryption/Decryption service which may be used securily store sensitive data.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`java.security.KeyPair`	`createKeyPair(java.lang.String algorithm)` Generates a key pair.
`byte[]`	`decrypt(byte[] cipherText)` Decrypts the given `cipherText` data into plain text.
`byte[]`	`decrypt(byte[] key, byte[] cipherText)` Decrypts the given `cipherText` data into plain text.
`byte[]`	`encrypt(byte[] plainText)` Encrypts the given `plainText` data into a cipher text.
`byte[]`	`encrypt(byte[] key, byte[] plainText)` Encrypts the given `plainText` data into a cipher text.
`byte[]`	`hmac_sha256(byte[] text)` Generate HMAC bytes given some text.
`byte[]`	`hmac_sha256(byte[] key, byte[] text)` Generate HMAC bytes given a key and some text.
`boolean`	`isProtected(java.lang.String text)` Returns `true` if the given string is to be considered protected by the `protect(String)` method and can be converted to plain text by calling the `unprotect(String)` method.
`void`	`nextRandomBytes(byte[] bytes)` Fill the byte buffer with securely-generated pseudo-random bytes.
`java.lang.String`	`protect(byte[] key, java.lang.String plainText)` Encrypts the given `plainText` data into a cipher text.
`java.lang.String`	`protect(java.lang.String plainText)` Encrypts the given `plainText` data into a cipher text.
`byte[]`	`sign(byte[] text, java.security.PrivateKey privateKey, java.lang.String algorithm)` Sign some data using the given private key
`java.security.cert.Certificate`	`sign(java.security.cert.Certificate issuerCertificate, java.security.KeyPair keyPair, javax.security.auth.x500.X500Principal subject, long before, long after)` Sign a `Certificate` either using a provided issuer certificate or using the `Certificate` subject as issuer (self signed).
`java.lang.String`	`unprotect(byte[] key, java.lang.String cipherText)` Unprotects the given string such that the resulting plain text string if given to the `protect(byte[], String)` returns the protected string given to this method.
`java.lang.String`	`unprotect(java.lang.String cipherText)` Unprotects the given string such that the resulting plain text string if given to the `protect(String)` returns the protected string given to this method.
`byte[]`	`unwrapKey(byte[] wrappedKeyData)` Unwraps the given `wrappedKey` using a symmetric key wrap algorithm.
`byte[]`	`unwrapKey(byte[] kek, byte[] wrappedKeyData)` Unwraps the given `wrappedKey` using a symmetric key wrap algorithm.
`boolean`	`verify(byte[] text, byte[] signedText, java.security.PublicKey publicKey, java.lang.String algorithm)` Perform a signature verification with the given public key.
`byte[]`	`wrapKey(byte[] keyData)` Wraps the given `keyData` using a symmetric key wrap algorithm.
`byte[]`	`wrapKey(byte[] kek, byte[] keyData)` Wraps the given `keyData` using a symmetric key wrap algorithm.

- Field Detail
  - NAME
```
static final java.lang.String NAME
```
    Name of the Encryption/Decryption service which may be used securily store sensitive data.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - encrypt
```
byte[] encrypt(byte[] plainText)
        throws CryptoException
```
    Encrypts the given plainText data into a cipher text.
    Note that this method and the decrypt(byte[]) method provide full round trip support:
```
 decrypt(encrypt(plainText)).equals(plainText) == true
 
```
    Please note, that calling this method twice on the same plainText does not return the same cipher text:
```
 encrypt(plainText).equals(encrypt(plainText)) == false
 
```
    Parameters:
    
    plainText - The plain text data to encrypt
    
    Returns:
    
    The encrypted data
    
    Throws:
    
    CryptoException - If any problem occurrs encrypting the plain text data. The Throwable.getCause() method may provide additional information on the encryption failure.
  - decrypt
```
byte[] decrypt(byte[] cipherText)
        throws CryptoException
```
    Decrypts the given cipherText data into plain text.
    Note that this method and the encrypt(byte[]) method provide full round trip support:
```
 decrypt(encrypt(plainText)).equals(plainText) == true
 
```
    Parameters:
    
    cipherText - The encrypted data to decrypt
    
    Returns:
    
    The plain text data
    
    Throws:
    
    CryptoException - If any problem occurrs decrypting the cipher text. The Throwable.getCause() method may provide additional information on the decryption failure.
  - encrypt
```
byte[] encrypt(byte[] key,
               byte[] plainText)
        throws CryptoException
```
    Encrypts the given plainText data into a cipher text.
    Note that this method and the decrypt(byte [], byte[]) method provide full round trip support:
```
 decrypt(encrypt(key,plainText)).equals(key,plainText) == true
 
```
    Please note that the implementation will not clear the byte[] key.
    Please note, that calling this method twice on the same plainText does not return the same cipher text:
```
 encrypt(key, plainText).equals(encrypt(key, plainText)) == false
 
```
    Parameters:
    
    key - The bytes used to seed the algorithm. This must be a non- null, non empty array of bytes. If the array is larger than 512 elements, only the first 512 entries are used.
    
    plainText - The plain text data to encrypt
    
    Returns:
    
    The encrypted data
    
    Throws:
    
    CryptoException - If any problem occurrs encrypting the plain text data. The Throwable.getCause() method may provide additional information on the encryption failure.
    
    Since:
    
    1.2
  - decrypt
```
byte[] decrypt(byte[] key,
               byte[] cipherText)
        throws CryptoException
```
    Decrypts the given cipherText data into plain text.
    Please note that the implementation will not clear the byte[] key.
    Note that this method and the encrypt(byte [], byte[]) method provide full round trip support:
```
 decrypt(encrypt(key, plainText)).equals(key, plainText) == true
 
```
    Parameters:
    
    key - The bytes used to seed the algorithm. This must be a non- null, non empty array of bytes. If the array is larger than 512 elements, only the first 512 entries are used.
    
    cipherText - The encrypted data to decrypt
    
    Returns:
    
    The plain text data
    
    Throws:
    
    CryptoException - If any problem occurrs decrypting the cipher text. The Throwable.getCause() method may provide additional information on the decryption failure.
    
    Since:
    
    1.2
  - isProtected
```
boolean isProtected(java.lang.String text)
```
    Returns true if the given string is to be considered protected by the protect(String) method and can be converted to plain text by calling the unprotect(String) method.
    
    Parameters:
    
    text - the string to test for protection
    
    Returns:
    
    true if the given string is to be considered protected by the protect(String) method and can be converted to plain text by calling the unprotect(String) method
  - protect
```
java.lang.String protect(java.lang.String plainText)
                  throws CryptoException
```
    Encrypts the given plainText data into a cipher text.
    This method is like encrypt(byte[]) but for character data.
    Note that this method and the unprotect(String) method provide full round trip support:
```
 unprotect(protect(plainText)).equals(plainText) == true
 
```
    Please note, that calling this method twice on the same plainText does not return the same cipher text:
```
 protect(plainText).equals(protect(plainText)) == false
 
```
    Parameters:
    
    plainText - The plain text data to encrypt
    
    Returns:
    
    The encrypted data
    
    Throws:
    
    CryptoException - If any problem occurrs encrypting the plain text data. The Throwable.getCause() method may provide additional information on the encryption failure.
  - unprotect
```
java.lang.String unprotect(java.lang.String cipherText)
                    throws CryptoException
```
    Unprotects the given string such that the resulting plain text string if given to the protect(String) returns the protected string given to this method.
    Note that this method and the protect(String) method provide full round trip support:
```
 unprotect(protect(plainText)).equals(plainText) == true
 
```
    Parameters:
    
    cipherText - The encrypted data to decrypt
    
    Returns:
    
    The plain text data
    
    Throws:
    
    CryptoException - If any problem occurrs decrypting the cipher text. The Throwable.getCause() method may provide additional information on the decryption failure. Particularly this exception may be thrown if the cipherText has obviously not been protected by the protect(String) method and isProtected(String) would return false.
  - protect
```
java.lang.String protect(byte[] key,
                         java.lang.String plainText)
                  throws CryptoException
```
    Encrypts the given plainText data into a cipher text.
    This method is like encrypt(byte[], byte[]) but for character data.
    Please note that the implementation will not clear the byte[] key.
    Note that this method and the unprotect(byte[], String) method provide full round trip support:
```
 unprotect(protect(key, plainText)).equals(key, plainText) == true
 
```
    Please note, that calling this method twice on the same plainText does not return the same cipher text:
```
 protect(key, plainText).equals(protect(key, plainText)) == false
 
```
    Parameters:
    
    key - The bytes used to seed the algorithm. This must be a non- null, non empty array of bytes. If the array is larger than 512 elements, only the first 512 entries are used.
    
    plainText - The plain text data to encrypt
    
    Returns:
    
    The encrypted data
    
    Throws:
    
    CryptoException - If any problem occurrs encrypting the plain text data. The Throwable.getCause() method may provide additional information on the encryption failure.
    
    Since:
    
    1.2
  - unprotect
```
java.lang.String unprotect(byte[] key,
                           java.lang.String cipherText)
                    throws CryptoException
```
    Unprotects the given string such that the resulting plain text string if given to the protect(byte[], String) returns the protected string given to this method.
    Please note that the implementation will not clear the byte[] key.
    Note that this method and the protect(byte[], String) method provide full round trip support:
```
 unprotect(protect(key, plainText)).equals(key, plainText) == true
 
```
    Parameters:
    
    key - The bytes used to seed the algorithm. This must be a non- null, non empty array of bytes. If the array is larger than 512 elements, only the first 512 entries are used.
    
    cipherText - The encrypted data to decrypt
    
    Returns:
    
    The plain text data
    
    Throws:
    
    CryptoException - If any problem occurrs decrypting the cipher text. The Throwable.getCause() method may provide additional information on the decryption failure. Particularly this exception may be thrown if the cipherText has obviously not been protected by the protect(String) method and isProtected(String) would return false.
    
    Since:
    
    1.2
  - wrapKey
```
byte[] wrapKey(byte[] kek,
               byte[] keyData)
        throws CryptoException
```
    Wraps the given keyData using a symmetric key wrap algorithm.
    Note that this method and the unwrapKey(byte[], byte[]) method provide full round trip support:
```
 unwrapKey(wrapKey(kek,keyData)).equals(kek,keyData) == true
 
```
    Please note that the implementation will not clear the byte[] key.
    Please note, that unlike for encryption methods, calling this method twice with the same keyData may return the same cipher text.
    Parameters:
    
    kek - the key-encryption key used to seed the key wrap algorithm. This must be a non-null, non empty array of bytes. Refer to the implementation for supported algorithm and key lengths.
    
    keyData - The key data to be wrapped. This must ve a non-null, non empty array of bytes. Refer to the implementation for limitations regarding the size.
    
    Returns:
    
    The wrapped key data
    
    Throws:
    
    CryptoException - If any problem occurs wrapping the key data. The Throwable.getCause() method may provide additional information on the wrapping failure.
    
    Since:
    
    1.5
  - wrapKey
```
byte[] wrapKey(byte[] keyData)
        throws CryptoException
```
    Wraps the given keyData using a symmetric key wrap algorithm.
    Note that the kek the key-encryption key used to seed the key wrap algorithm is selected by the implementation.
    Note that this method and the unwrapKey(byte[]) method provide full round trip support:
```
 unwrapKey(wrapKey(keyData)).equals(keyData) == true
 
```
    Please note that the implementation will not clear the byte[] key.
    Please note, that unlike for encryption methods, calling this method twice with the same keyData may return the same cipher text.
    Parameters:
    
    keyData - The key data to be wrapped. This must ve a non-null, non empty array of bytes. Refer to the implementation for limitations regarding the size.
    
    Returns:
    
    The wrapped key data
    
    Throws:
    
    CryptoException - If any problem occurs wrapping the key data. The Throwable.getCause() method may provide additional information on the wrapping failure.
    
    Since:
    
    1.5
  - unwrapKey
```
byte[] unwrapKey(byte[] kek,
                 byte[] wrappedKeyData)
          throws CryptoException
```
    Unwraps the given wrappedKey using a symmetric key wrap algorithm.
    Note that this method and the wrapKey(byte[], byte[]) method provide full round trip support:
```
 unwrapKey(wrapKey(kek,keyData)).equals(kek,keyData) == true
 
```
    Please note that the implementation will not clear the byte[] key.
    Parameters:
    
    kek - the key-encryption key used to seed the key wrap algorithm. This must be a non-null, non empty array of bytes. Refer to the implementation for supported algorithm and key lengths.
    
    wrappedKeyData - The key data to be wrapped. This must ve a non-null, non empty array of bytes. Refer to the implementation for limitations regarding the size.
    
    Returns:
    
    The wrapped key data
    
    Throws:
    
    CryptoException - If any problem occurs wrapping the key data. The Throwable.getCause() method may provide additional information on the wrapping failure.
    
    Since:
    
    1.5
  - unwrapKey
```
byte[] unwrapKey(byte[] wrappedKeyData)
          throws CryptoException
```
    Unwraps the given wrappedKey using a symmetric key wrap algorithm.
    Note that the kek the key-encryption key used to seed the key wrap algorithm is selected by the implementation.
    Note that this method and the wrapKey(byte[]) method provide full round trip support:
```
 unwrapKey(wrapKey(keyData)).equals(keyData) == true
 
```
    Please note that the implementation will not clear the byte[] key.
    Parameters:
    
    wrappedKeyData - The key data to be wrapped. This must ve a non-null, non empty array of bytes. Refer to the implementation for limitations regarding the size.
    
    Returns:
    
    The wrapped key data
    
    Throws:
    
    CryptoException - If any problem occurs wrapping the key data. The Throwable.getCause() method may provide additional information on the wrapping failure.
    
    Since:
    
    1.5
  - nextRandomBytes
```
void nextRandomBytes(byte[] bytes)
              throws CryptoException
```
    Fill the byte buffer with securely-generated pseudo-random bytes.
    
    Parameters:
    
    bytes - Buffer to fill with random bytes.
    
    Throws:
    
    CryptoException - If any problem occurrs calculating the random data. The Throwable.getCause() method may provide additional information on the failure.
    
    Since:
    
    1.1, Crypto Support 0.4
  - hmac_sha256
```
byte[] hmac_sha256(byte[] key,
                   byte[] text)
            throws CryptoException
```
    Generate HMAC bytes given a key and some text. In other, perhaps less cryptographically correct words, generates and returns a hash of 'text' encrypted by 'keyBytes'.
    The implementation is expected to implement the keyed hashing function using SHA-256 as the hash algorithm. See RFC 2104 for the HMAC specification.
    Please note that the implementation will not clear the byte[] key.
    If a string of character is to be hashed, it is suggested but not required to convert the String to a byte array using UTF-8.
    
    Parameters:
    
    key - The bytes used to seed the algorithm. This must be a non- null, non empty array of bytes. If the array is larger than 512 elements, only the first 512 entries are used.
    
    text - The clear text to apply the hash algorithm to.
    
    Returns:
    
    The hash code.
    
    Throws:
    
    CryptoException - If any problem occurrs calculating the hash code of the text. The Throwable.getCause() method may provide additional information on the failure.
    
    java.lang.IllegalArgumentException - if the key or text is null or an empty array.
    
    Since:
    
    1.1, Crypto Support 0.4
  - hmac_sha256
```
byte[] hmac_sha256(byte[] text)
            throws CryptoException
```
    Generate HMAC bytes given some text. In other, perhaps less cryptographically correct words, generates and returns a hash of 'text' encrypted by 'keyBytes'.
    The implementation is expected to implement the keyed hashing function using SHA-256 as the hash algorithm. See RFC 2104 for the HMAC specification.
    If a string of character is to be hashed, it is suggested but not required to convert the String to a byte array using UTF-8.
    
    Parameters:
    
    text - The clear text to apply the hash algorithm to.
    
    Returns:
    
    The hash code.
    
    Throws:
    
    CryptoException - If any problem occurrs calculating the hash code of the text. The Throwable.getCause() method may provide additional information on the failure.
    
    java.lang.IllegalArgumentException - if the key or text is null or an empty array.
    
    Since:
    
    1.2
  - createKeyPair
```
java.security.KeyPair createKeyPair(java.lang.String algorithm)
                             throws CryptoException
```
    Generates a key pair. This will generate a new key pair every time it is called.
    
    Parameters:
    
    algorithm - the standard string name of the algorithm
    
    Returns:
    
    the generated key pair
    
    Throws:
    
    CryptoException - If any problem occurs creating the key pair. The Throwable.getCause() method may provide additional information on the encryption failure.
    
    java.lang.IllegalArgumentException - if the algorithm is null or incorrect.
    
    Since:
    
    1.3
  - sign
```
java.security.cert.Certificate sign(java.security.cert.Certificate issuerCertificate,
                                    java.security.KeyPair keyPair,
                                    javax.security.auth.x500.X500Principal subject,
                                    long before,
                                    long after)
                             throws CryptoException
```
    Sign a Certificate either using a provided issuer certificate or using the Certificate subject as issuer (self signed).
    
    Parameters:
    
    issuerCertificate - the Certificate of the issuer or null to self-sign the certificate.
    
    keyPair - the key pair containing the certificate subject PublicKey and the issuer PrivateKey key.
    
    subject - the subject of the certificate to be issued
    
    before - the notBefore UTC timestamp for the certificate validity period
    
    after - the notAfter UTC timestamp for the certificate validity period
    
    Returns:
    
    the signed Certificate
    
    Throws:
    
    CryptoException - if any problem occurs when signing
    
    Since:
    
    1.4
  - sign
```
byte[] sign(byte[] text,
            java.security.PrivateKey privateKey,
            java.lang.String algorithm)
     throws CryptoException
```
    Sign some data using the given private key
    Please note that the implementation will not clear the private key.
    
    Parameters:
    
    text - the clear text to sign
    
    privateKey - the private key used to sign the clear text
    
    algorithm - the standard string name of the algorithm
    
    Returns:
    
    the signedText
    
    Throws:
    
    CryptoException - If any problem occurs signing the clear text. The Throwable.getCause() method may provide additional information on the encryption failure.
    
    java.lang.IllegalArgumentException - if the algorithm or privateKey is null or incorrect.
    
    Since:
    
    1.3
  - verify
```
boolean verify(byte[] text,
               byte[] signedText,
               java.security.PublicKey publicKey,
               java.lang.String algorithm)
        throws CryptoException
```
    Perform a signature verification with the given public key.
    Please note that the implementation will not clear the public key.
    
    Parameters:
    
    text - The clear text which has been signed
    
    signedText - the signed text to be verified
    
    publicKey - the public key used to verify the signature
    
    algorithm - the standard string name of the algorithm
    
    Returns:
    
    true if the alleged signature (signedText) is the actual signature of the specified data (text)
    
    Throws:
    
    CryptoException - If any problem occurs verifying the signed text. The Throwable.getCause() method may provide additional information on the encryption failure.
    
    java.lang.IllegalArgumentException - if the algorithm or publicKey is null or incorrect.
    
    Since:
    
    1.3

Interface CryptoSupport

Field Summary

Method Summary

Field Detail

NAME

Method Detail

encrypt

decrypt

encrypt

decrypt

isProtected

protect

unprotect

protect

unprotect

wrapKey

wrapKey

unwrapKey

unwrapKey

nextRandomBytes

hmac_sha256

hmac_sha256

createKeyPair

sign

sign

verify