copy code from internal

Author: rishav-karanjit

DynamoDbEncryption/runtimes/java/src/main/sdkv2/software/amazon/cryptools/dynamodbencryptionclientsdk2/encryption/DelegatedKey.java

@@ -0,0 +1,146 @@
+/*
+ * Copyright 2014-2019 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 software.amazon.cryptools.dynamodbencryptionclientsdk2.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.
+ * 
+ * <p>
+ * 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 <code>sign</code> and <code>verify</code>.)
+ * {@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 <code>null</code> 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 <code>additionalAssociatedData</code> is
+     *             provided, but not supported.
+     */
+    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 <code>null</code> 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
+     *             <code>additionalAssociatedData</code> is provided, but not
+     *             supported.
+     */
+    byte[] decrypt(byte[] cipherText, byte[] additionalAssociatedData, String algorithm)
+            throws InvalidKeyException, IllegalBlockSizeException, BadPaddingException, NoSuchAlgorithmException,
+            NoSuchPaddingException, InvalidAlgorithmParameterException;
+
+    /**
+     * Wraps (encrypts) the provided <code>key</code> 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 <code>null</code> 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
+     *             <code>additionalAssociatedData</code> is provided, but not
+     *             supported.
+     */
+    byte[] wrap(Key key, byte[] additionalAssociatedData, String algorithm) throws InvalidKeyException,
+            NoSuchAlgorithmException, NoSuchPaddingException, IllegalBlockSizeException;
+
+    /**
+     * Unwraps (decrypts) the provided <code>wrappedKey</code> to recover the
+     * original key.
+     * 
+     * @param wrappedKey
+     * @param additionalAssociatedData
+     *            Optional additional data which was provided during wrapping.
+     *            Both <code>null</code> 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
+     *             <code>additionalAssociatedData</code> is provided, but not
+     *             supported.
+     */
+    Key unwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType,
+            byte[] additionalAssociatedData, String algorithm) throws NoSuchAlgorithmException, NoSuchPaddingException,
+            InvalidKeyException;
+
+    /**
+     * Calculates and returns a signature for <code>dataToSign</code>.
+     * 
+     * @param dataToSign
+     * @param algorithm
+     * @return the signature
+     * @throws UnsupportedOperationException if signing is not supported
+     */
+    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 <code>signature</code> matches the <code>dataToSign</code>.
+     * @throws UnsupportedOperationException if signature validation is not supported 
+     */
+    boolean verify(byte[] dataToSign, byte[] signature, String algorithm);
+}