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 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 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