Package io.axoniq.dataprotection.cryptoengine

## Interface CryptoEngine

- All Known Implementing Classes:
    `DatabaseBackedCryptoEngine`, `InMemoryCryptoEngine`, `JavaKeyStoreCryptoEngine`, `JdbcCryptoEngine`, `JpaCryptoEngine`, `PKCS11CryptoEngine`, `VaultCryptoEngine`

      public interface CryptoEngine

  Interface towards the cryptographic functionality needed by the Axon Data Protection Module. The module provides functionality for retrieval, generation/storage and deletion of AES-256 keys, and obtaining a Cipher object to perform encryption and decryption using a `SecretKey`. The Axon Data Protection Module offers various implementations for this interface, including an in-memory implementation for test, an implementation that stored keys in a database, and an implementation that works with a hardware security module (HSM).

  Both the `SecretKey` management functionality and obtaining a `Cipher` must be in a single interface to support those cases where HSMs are used. In those cases, a SecretKey object won't contain any actual key material. Instead it's just a reference to a secret key stored on the device. The Cipher object interfacing to the HSM will be able to deal with this.

  In principle, we could have directly used the `Provider` and `KeyStore` abstractions instead of this one. This would have led to unnecessary complexity in the most common use case where keys are stored in a regular database. Therefore, this simpler abstraction is offered instead.

  Implementations of this class are responsible for selecting the symmetric encryption algorithm, mode, padding, and key length. All standard implementations in the Axon Data Protection Module use AES in CBC mode with PKCS#5 padding and a 256-bit key length.

  See Also:
    `InMemoryCryptoEngine`, `JavaKeyStoreCryptoEngine`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Cipher` | `createCipher()` | Creates an uninitialized `Cipher` instance for the correct transformation (AES, CBC, PKCS#5) and provider.
    `Cipher` | `createDigestCipher()` | Creates an uninitialized `Cipher` instance for calculating the encrypted digest.
    `void` | `deleteKey​(String id)` | Deletes the key for a given id.
    `SecretKey` | `getKey​(String id)` | Retrieves the key for a given id.
    `KeyType` | `getKeyType()` | Retrieves the currently used `KeyType` for new keys
    `SecretKey` | `getOrCreateKey​(String id)` | Retrieves the key for a given id.
    `void` | `setKeyType​(KeyType keyType)` | Sets the `KeyType` to use, which determines the length of newly generated keys.

- - ### Method Detail

    - #### getOrCreateKey

          SecretKey getOrCreateKey​(String id)

      Retrieves the key for a given id. If no such key is registered, generates a new random key and stores it under the alias before returning it.
      Parameters:
        `id` - the id of the `SecretKey`
      Returns:
        the potentially new `SecretKey` associated with the id

    - #### getKey

          SecretKey getKey​(String id)

      Retrieves the key for a given id.
      Parameters:
        `id` - the id of the `SecretKey`
      Returns:
        the existing `SecretKey` associated with the id, or `null` if no such key exists

    - #### deleteKey

          void deleteKey​(String id)

      Deletes the key for a given id. Does nothing if the key doesn't exist.
      Parameters:
        `id` - the id of the `SecretKey`

    - #### createCipher

          Cipher createCipher()

      Creates an uninitialized `Cipher` instance for the correct transformation (AES, CBC, PKCS#5) and provider. Clients should still call the `Cipher.init(int, java.security.Key, AlgorithmParameterSpec)` to specify operation mode (encryption or decryption), key and initialization vector.
      Returns:
        the `Cipher`

    - #### createDigestCipher

          Cipher createDigestCipher()

      Creates an uninitialized `Cipher` instance for calculating the encrypted digest. For this specific purpose, it should use AES, EBC and no padding, and the same provider as for the other operations. Clients should still call the `Cipher.init(int, java.security.Key)` to specify operation mode (always encryption) and key.
      Returns:
        the `Cipher`

    - #### setKeyType

          void setKeyType​(KeyType keyType)

      Sets the `KeyType` to use, which determines the length of newly generated keys. Defaults to `KeyType.AES_256` if not set.
      Parameters:
        `keyType` - the new `KeyType`

    - #### getKeyType

          KeyType getKeyType()

      Retrieves the currently used `KeyType` for new keys
      Returns:
        the current value