Package org.cryptomator.siv

Class SivMode

  • public final class SivMode
extends Object
    Implements the RFC 5297 SIV mode.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static interface  SivMode.BlockCipherFactory
      Creates BlockCiphers.

    • Constructor Summary

      Constructors 
      Constructor Description
      SivMode()
      Creates an AES-SIV instance using JCE's cipher implementation, which should normally be the best choice.
      SivMode​(Provider jceSecurityProvider)
      Creates an AES-SIV instance using a custom JCE's security provider
      SivMode​(SivMode.BlockCipherFactory cipherFactory)
      Creates an instance using a specific Blockcipher.get().

    • Constructor Detail

      • SivMode

        public SivMode()
        Creates an AES-SIV instance using JCE's cipher implementation, which should normally be the best choice.

        For embedded systems, you might want to consider using SivMode(BlockCipherFactory) with BouncyCastle's AESLightEngine instead.

        See Also:
        SivMode(BlockCipherFactory)

      • SivMode

        public SivMode​(Provider jceSecurityProvider)
        Creates an AES-SIV instance using a custom JCE's security provider

        For embedded systems, you might want to consider using SivMode(BlockCipherFactory) with BouncyCastle's AESLightEngine instead.

        Parameters:
        jceSecurityProvider - to use to create the internal Cipher instance
        See Also:
        SivMode(BlockCipherFactory)

      • SivMode

        public SivMode​(SivMode.BlockCipherFactory cipherFactory)
        Creates an instance using a specific Blockcipher.get(). If you want to use AES, just use the default constructor.
        Parameters:
        cipherFactory - A factory method creating a Blockcipher.get(). Must use a block size of 128 bits (16 bytes).

    • Method Detail

      • encrypt

        public byte[] encrypt​(SecretKey ctrKey,
                      SecretKey macKey,
                      byte[] plaintext,
                      byte[]... associatedData)
        Convenience method, if you are using the javax.crypto API. This is just a wrapper for encrypt(byte[], byte[], byte[], byte[]...).
        Parameters:
        ctrKey - SIV mode requires two separate keys. You can use one long key, which is splitted in half. See https://tools.ietf.org/html/rfc5297#section-2.2
        macKey - SIV mode requires two separate keys. You can use one long key, which is splitted in half. See https://tools.ietf.org/html/rfc5297#section-2.2
        plaintext - Your plaintext, which shall be encrypted.
        associatedData - Optional associated data, which gets authenticated but not encrypted.
        Returns:
        IV + Ciphertext as a concatenated byte array.
        Throws:
        IllegalArgumentException - if keys are invalid or Key.getEncoded() is not supported.

      • encrypt

        public byte[] encrypt​(byte[] ctrKey,
                      byte[] macKey,
                      byte[] plaintext,
                      byte[]... associatedData)
        Encrypts plaintext using SIV mode. A block cipher defined by the constructor is being used.
        Parameters:
        ctrKey - SIV mode requires two separate keys. You can use one long key, which is splitted in half. See https://tools.ietf.org/html/rfc5297#section-2.2
        macKey - SIV mode requires two separate keys. You can use one long key, which is splitted in half. See https://tools.ietf.org/html/rfc5297#section-2.2
        plaintext - Your plaintext, which shall be encrypted.
        associatedData - Optional associated data, which gets authenticated but not encrypted.
        Returns:
        IV + Ciphertext as a concatenated byte array.
        Throws:
        IllegalArgumentException - if the either of the two keys is of invalid length for the used BlockCipher.

      • decrypt

        public byte[] decrypt​(SecretKey ctrKey,
                      SecretKey macKey,
                      byte[] ciphertext,
                      byte[]... associatedData)
               throws UnauthenticCiphertextException,
                      IllegalBlockSizeException
        Convenience method, if you are using the javax.crypto API. This is just a wrapper for decrypt(byte[], byte[], byte[], byte[]...).
        Parameters:
        ctrKey - SIV mode requires two separate keys. You can use one long key, which is splitted in half. See https://tools.ietf.org/html/rfc5297#section-2.2
        macKey - SIV mode requires two separate keys. You can use one long key, which is splitted in half. See https://tools.ietf.org/html/rfc5297#section-2.2
        ciphertext - Your cipehrtext, which shall be decrypted.
        associatedData - Optional associated data, which needs to be authenticated during decryption.
        Returns:
        Plaintext byte array.
        Throws:
        IllegalArgumentException - If keys are invalid or Key.getEncoded() is not supported.
        UnauthenticCiphertextException - If the authentication failed, e.g. because ciphertext and/or associatedData are corrupted.
        IllegalBlockSizeException - If the provided ciphertext is of invalid length.

      • decrypt

        public byte[] decrypt​(byte[] ctrKey,
                      byte[] macKey,
                      byte[] ciphertext,
                      byte[]... associatedData)
               throws UnauthenticCiphertextException,
                      IllegalBlockSizeException
        Decrypts ciphertext using SIV mode. A block cipher defined by the constructor is being used.
        Parameters:
        ctrKey - SIV mode requires two separate keys. You can use one long key, which is splitted in half. See https://tools.ietf.org/html/rfc5297#section-2.2
        macKey - SIV mode requires two separate keys. You can use one long key, which is splitted in half. See https://tools.ietf.org/html/rfc5297#section-2.2
        ciphertext - Your ciphertext, which shall be encrypted.
        associatedData - Optional associated data, which needs to be authenticated during decryption.
        Returns:
        Plaintext byte array.
        Throws:
        IllegalArgumentException - If the either of the two keys is of invalid length for the used BlockCipher.
        UnauthenticCiphertextException - If the authentication failed, e.g. because ciphertext and/or associatedData are corrupted.
        IllegalBlockSizeException - If the provided ciphertext is of invalid length.