Package com.adobe.granite.crypto

Interface CryptoSupport

@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
    Description
    static final String
    NAME
    Name of the Encryption/Decryption service which may be used securely store sensitive data.

  • Method Summary

    Modifier and Type
    Method
    Description
    KeyPair
    createKeyPair(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(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.
    String
    protect(byte[] key, String plainText)
    Encrypts the given plainText data into a cipher text.
    String
    protect(String plainText)
    Encrypts the given plainText data into a cipher text.
    byte[]
    sign(byte[] text, PrivateKey privateKey, String algorithm)
    Sign some data using the given private key
    Certificate
    sign(Certificate issuerCertificate, KeyPair keyPair, X500Principal subject, long before, long after)
    Sign a Certificate either using a provided issuer certificate or using the Certificate subject as issuer (self-signed).
    String
    unprotect(byte[] key, String cipherText)
    Unprotect 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.
    String
    unprotect(String cipherText)
    Unprotect 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, PublicKey publicKey, 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 Details

    • NAME

      static final String NAME
      Name of the Encryption/Decryption service which may be used securely store sensitive data.
      See Also:

  • Method Details

    • 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 occurs 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 occurs 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 key material used by the encryption algorithm. This must be a non- null, non-empty array of bytes. The current implementations use AES for this operation and therefore require a key length of 16, 24, or 32 bytes (128, 192, or 256 bits).
      plainText - The plain text data to encrypt
      Returns:
      The encrypted data
      Throws:
      CryptoException - If any problem occurs 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 key material used by the encryption algorithm. This must be a non- null, non-empty array of bytes. The current implementations use AES for this operation and therefore require a key length of 16, 24, or 32 bytes (128, 192, or 256 bits).
      cipherText - The encrypted data to decrypt
      Returns:
      The plain text data
      Throws:
      CryptoException - If any problem occurs decrypting the cipher text. The Throwable.getCause() method may provide additional information on the decryption failure.
      Since:
      1.2

    • isProtected

      boolean isProtected(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

      String protect(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 occurs encrypting the plain text data. The Throwable.getCause() method may provide additional information on the encryption failure.

    • unprotect

      String unprotect(String cipherText) throws CryptoException
      Unprotect 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 occurs 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

      String protect(byte[] key, 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 key material used by the encryption algorithm. This must be a non- null, non-empty array of bytes. The current implementations use AES for this operation and therefore require a key length of 16, 24, or 32 bytes (128, 192, or 256 bits).
      plainText - The plain text data to encrypt
      Returns:
      The encrypted data
      Throws:
      CryptoException - If any problem occurs encrypting the plain text data. The Throwable.getCause() method may provide additional information on the encryption failure.
      Since:
      1.2

    • unprotect

      String unprotect(byte[] key, String cipherText) throws CryptoException
      Unprotect 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 key material used by the encryption algorithm. This must be a non- null, non-empty array of bytes. The current implementations use AES for this operation and therefore require a key length of 16, 24, or 32 bytes (128, 192, or 256 bits).
      cipherText - The encrypted data to decrypt
      Returns:
      The plain text data
      Throws:
      CryptoException - If any problem occurs 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. The current implementations use AES key wrapping and require an effective key length of 16, 24, or 32 bytes (128, 192, or 256 bits). If kek is longer than 32 bytes, only the first 32 bytes are used.
      keyData - The key data to be wrapped. This must be a non-null, non-empty array of bytes. The current implementations require at least 16 bytes and a length that is a multiple of 8 bytes.
      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 be a non-null, non-empty array of bytes. The current implementations require at least 16 bytes and a length that is a multiple of 8 bytes.
      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. The current implementations use AES key wrapping and require an effective key length of 16, 24, or 32 bytes (128, 192, or 256 bits). If kek is longer than 32 bytes, only the first 32 bytes are used.
      wrappedKeyData - The wrapped key data. This must be a non-null, non-empty array of bytes.
      Returns:
      The unwrapped key data
      Throws:
      CryptoException - If any problem occurs unwrapping the key data. The Throwable.getCause() method may provide additional information on the unwrapping 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 wrapped key data. This must be a non-null, non-empty array of bytes.
      Returns:
      The unwrapped key data
      Throws:
      CryptoException - If any problem occurs unwrapping the key data. The Throwable.getCause() method may provide additional information on the unwrapping 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:
      NullPointerException - if bytes is null.
      CryptoException - If any problem occurs 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 key material for the HMAC operation. This must be a non- null, non-empty array of bytes.
      text - The clear text to apply the hash algorithm to.
      Returns:
      The hash code.
      Throws:
      CryptoException - If any problem occurs calculating the hash code of the text. The Throwable.getCause() method may provide additional information on the failure.
      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 occurs calculating the hash code of the text. The Throwable.getCause() method may provide additional information on the failure.
      IllegalArgumentException - if text is null or an empty array.
      Since:
      1.2

    • createKeyPair

      KeyPair createKeyPair(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. The current implementations support only RSA.
      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 key generation failure.
      IllegalArgumentException - if the algorithm is null or incorrect.
      Since:
      1.3

    • sign

      Certificate sign(Certificate issuerCertificate, KeyPair keyPair, 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, PrivateKey privateKey, 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. The current implementations support SHA224withRSA, SHA256withRSA, SHA384withRSA, and SHA512withRSA.
      Returns:
      the signedText
      Throws:
      CryptoException - If any problem occurs signing the clear text. The Throwable.getCause() method may provide additional information on the signing failure.
      IllegalArgumentException - if the algorithm or privateKey is null or incorrect.
      Since:
      1.3

    • verify

      boolean verify(byte[] text, byte[] signedText, PublicKey publicKey, 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. The current implementations support SHA224withRSA, SHA256withRSA, SHA384withRSA, and SHA512withRSA.
      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 verification failure.
      IllegalArgumentException - if the algorithm or publicKey is null or incorrect.
      Since:
      1.3