com.amazonaws.services.dynamodbv2.datamodeling.encryption.DelegatedKey Maven / Gradle / Ivy
Show all versions of aws-dynamodb-encryption-java Show documentation
/*
* Copyright 2014 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.amazonaws.services.dynamodbv2.datamodeling.encryption;
import java.security.GeneralSecurityException;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.Key;
import java.security.NoSuchAlgorithmException;
import javax.crypto.BadPaddingException;
import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.SecretKey;
/**
* Identifies keys which should not be used directly with {@link Cipher} but
* instead contain their own cryptographic logic. This can be used to wrap more
* complex logic, HSM integration, or service-calls.
*
*
* Most delegated keys will only support a subset of these operations. (For
* example, AES keys will generally not support {@link #sign(byte[], String)} or
* {@link #verify(byte[], byte[], String)} and HMAC keys will generally not
* support anything except sign and verify.)
* {@link UnsupportedOperationException} should be thrown in these cases.
*
* @author Greg Rubin
*/
public interface DelegatedKey extends SecretKey {
/**
* Encrypts the provided plaintext and returns a byte-array containing the ciphertext.
*
* @param plainText
* @param additionalAssociatedData
* Optional additional data which must then also be provided for successful
* decryption. Both null and arrays of length 0 are treated identically.
* Not all keys will support this parameter.
* @param algorithm
* the transformation to be used when encrypting the data
* @return ciphertext the ciphertext produced by this encryption operation
* @throws UnsupportedOperationException
* if encryption is not supported or if additionalAssociatedData is
* provided, but not supported.
*/
public byte[] encrypt(byte[] plainText, byte[] additionalAssociatedData, String algorithm)
throws InvalidKeyException, IllegalBlockSizeException, BadPaddingException, NoSuchAlgorithmException,
NoSuchPaddingException;
/**
* Decrypts the provided ciphertext and returns a byte-array containing the
* plaintext.
*
* @param cipherText
* @param additionalAssociatedData
* Optional additional data which was provided during encryption.
* Both null and arrays of length 0 are treated
* identically. Not all keys will support this parameter.
* @param algorithm
* the transformation to be used when decrypting the data
* @return plaintext the result of decrypting the input ciphertext
* @throws UnsupportedOperationException
* if decryption is not supported or if
* additionalAssociatedData is provided, but not
* supported.
*/
public byte[] decrypt(byte[] cipherText, byte[] additionalAssociatedData, String algorithm)
throws InvalidKeyException, IllegalBlockSizeException, BadPaddingException, NoSuchAlgorithmException,
NoSuchPaddingException, InvalidAlgorithmParameterException;
/**
* Wraps (encrypts) the provided key to make it safe for
* storage or transmission.
*
* @param key
* @param additionalAssociatedData
* Optional additional data which must then also be provided for
* successful unwrapping. Both null and arrays of
* length 0 are treated identically. Not all keys will support
* this parameter.
* @param algorithm
* the transformation to be used when wrapping the key
* @return the wrapped key
* @throws UnsupportedOperationException
* if wrapping is not supported or if
* additionalAssociatedData is provided, but not
* supported.
*/
public byte[] wrap(Key key, byte[] additionalAssociatedData, String algorithm) throws InvalidKeyException,
NoSuchAlgorithmException, NoSuchPaddingException, IllegalBlockSizeException;
/**
* Unwraps (decrypts) the provided wrappedKey to recover the
* original key.
*
* @param wrappedKey
* @param additionalAssociatedData
* Optional additional data which was provided during wrapping.
* Both null and arrays of length 0 are treated
* identically. Not all keys will support this parameter.
* @param algorithm
* the transformation to be used when unwrapping the key
* @return the unwrapped key
* @throws UnsupportedOperationException
* if wrapping is not supported or if
* additionalAssociatedData is provided, but not
* supported.
*/
public Key unwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType,
byte[] additionalAssociatedData, String algorithm) throws NoSuchAlgorithmException, NoSuchPaddingException,
InvalidKeyException;
/**
* Calculates and returns a signature for dataToSign.
*
* @param dataToSign
* @param algorithm
* @return the signature
* @throws UnsupportedOperationException if signing is not supported
*/
public byte[] sign(byte[] dataToSign, String algorithm) throws GeneralSecurityException;
/**
* Checks the provided signature for correctness.
*
* @param dataToSign
* @param signature
* @param algorithm
* @return true if and only if the signature matches the dataToSign.
* @throws UnsupportedOperationException if signature validation is not supported
*/
public boolean verify(byte[] dataToSign, byte[] signature, String algorithm);
}