Additional support for managing HMAC keys that adheres to changes documented in X9.143-2021 and provides better interoperability for key import/export

Author: aws-sdk-dotnet-automation

generator/ServiceModels/payment-cryptography/payment-cryptography-2021-09-14.api.json

@@ -893,6 +893,10 @@
         "AES_128",
         "AES_192",
         "AES_256",
+        "HMAC_SHA256",
+        "HMAC_SHA384",
+        "HMAC_SHA512",
+        "HMAC_SHA224",
         "RSA_2048",
         "RSA_3072",
         "RSA_4096",
@@ -947,7 +951,8 @@
       "type":"string",
       "enum":[
         "CMAC",
-        "ANSI_X9_24"
+        "ANSI_X9_24",
+        "HMAC"
       ]
     },
     "KeyClass":{
@@ -1260,7 +1265,11 @@
         "TDES_3KEY",
         "AES_128",
         "AES_192",
-        "AES_256"
+        "AES_256",
+        "HMAC_SHA256",
+        "HMAC_SHA384",
+        "HMAC_SHA512",
+        "HMAC_SHA224"
       ]
     },
     "Tag":{

generator/ServiceModels/payment-cryptography/payment-cryptography-2021-09-14.docs.json

@@ -47,17 +47,36 @@ namespace Amazon.PaymentCryptography.Model
     /// The immutable data contains key attributes that define the scope and cryptographic
     /// operations that you can perform using the key, for example key class (example: <c>SYMMETRIC_KEY</c>),
     /// key algorithm (example: <c>TDES_2KEY</c>), key usage (example: <c>TR31_P0_PIN_ENCRYPTION_KEY</c>)
-    /// and key modes of use (example: <c>Encrypt</c>). For information about valid combinations
-    /// of key attributes, see <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-validattributes.html">Understanding
+    /// and key modes of use (example: <c>Encrypt</c>). Amazon Web Services Payment Cryptography
+    /// binds key attributes to keys using key blocks when you store or export them. Amazon
+    /// Web Services Payment Cryptography stores the key contents wrapped and never stores
+    /// or transmits them in the clear.
+    /// </para>
+    ///  
+    /// <para>
+    /// For information about valid combinations of key attributes, see <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-validattributes.html">Understanding
     /// key attributes</a> in the <i>Amazon Web Services Payment Cryptography User Guide</i>.
     /// The mutable data contained within a key includes usage timestamp and key deletion
     /// timestamp and can be modified after creation.
     /// </para>
     ///  
     /// <para>
-    /// Amazon Web Services Payment Cryptography binds key attributes to keys using key blocks
-    /// when you store or export them. Amazon Web Services Payment Cryptography stores the
-    /// key contents wrapped and never stores or transmits them in the clear. 
+    /// You can use the <c>CreateKey</c> operation to generate an ECC (Elliptic Curve Cryptography)
+    /// key pair used for establishing an ECDH (Elliptic Curve Diffie-Hellman) key agreement
+    /// between two parties. In the ECDH key agreement process, both parties generate their
+    /// own ECC key pair with key usage K3 and exchange the public keys. Each party then use
+    /// their private key, the received public key from the other party, and the key derivation
+    /// parameters including key derivation function, hash algorithm, derivation data, and
+    /// key algorithm to derive a shared key.
+    /// </para>
+    ///  
+    /// <para>
+    /// To maintain the single-use principle of cryptographic keys in payments, ECDH derived
+    /// keys should not be used for multiple purposes, such as a <c>TR31_P0_PIN_ENCRYPTION_KEY</c>
+    /// and <c>TR31_K1_KEY_BLOCK_PROTECTION_KEY</c>. When creating ECC key pairs in Amazon
+    /// Web Services Payment Cryptography you can optionally set the <c>DeriveKeyUsage</c>
+    /// parameter, which defines the key usage bound to the symmetric key that will be derived
+    /// using the ECC key pair.
     /// </para>
     ///  
     /// <para>
@@ -97,8 +116,12 @@ public partial class CreateKeyRequest : AmazonPaymentCryptographyRequest
         /// <summary>
         /// Gets and sets the property DeriveKeyUsage. 
         /// <para>
-        /// The cryptographic usage of an ECDH derived key as defined in section A.5.2 of the TR-31
-        /// spec.
+        /// The intended cryptographic usage of keys derived from the ECC key pair to be created.
+        /// </para>
+        ///  
+        /// <para>
+        /// After creating an ECC key pair, you cannot change the intended cryptographic usage
+        /// of keys derived from it using ECDH.
         /// </para>
         /// </summary>
         public DeriveKeyUsage DeriveKeyUsage

generator/ServiceModels/payment-cryptography/payment-cryptography-2021-09-14.normal.json

@@ -30,7 +30,7 @@
 namespace Amazon.PaymentCryptography.Model
 {
     /// <summary>
-    /// Derivation data used to derive an ECDH key.
+    /// The shared information used when deriving a key using ECDH.
     /// </summary>
     public partial class DiffieHellmanDerivationData
     {
@@ -39,14 +39,15 @@ public partial class DiffieHellmanDerivationData
         /// <summary>
         /// Gets and sets the property SharedInformation. 
         /// <para>
-        /// A byte string containing information that binds the ECDH derived key to the two parties
+        /// A string containing information that binds the ECDH derived key to the two parties
         /// involved or to the context of the key.
         /// </para>
         ///  
         /// <para>
         /// It may include details like identities of the two parties deriving the key, context
-        /// of the operation, session IDs, and optionally a nonce. It must not contain zero bytes,
-        /// and re-using shared information for multiple ECDH key derivations is not recommended.
+        /// of the operation, session IDs, and optionally a nonce. It must not contain zero bytes.
+        /// It is not recommended to reuse shared information for multiple ECDH key derivations,
+        /// as it could result in derived key material being the same across different derivations.
         /// </para>
         /// </summary>
         [AWSProperty(Min=2, Max=2048)]

sdk/src/Services/PaymentCryptography/Generated/Model/CreateKeyRequest.cs

@@ -30,8 +30,8 @@
 namespace Amazon.PaymentCryptography.Model
 {
     /// <summary>
-    /// Parameter information for key material export using the asymmetric ECDH key exchange
-    /// method.
+    /// Key derivation parameter information for key material export using asymmetric ECDH
+    /// key exchange method.
     /// </summary>
     public partial class ExportDiffieHellmanTr31KeyBlock
     {
@@ -47,7 +47,8 @@ public partial class ExportDiffieHellmanTr31KeyBlock
         /// <summary>
         /// Gets and sets the property CertificateAuthorityPublicKeyIdentifier. 
         /// <para>
-        /// The <c>keyARN</c> of the certificate that signed the client's <c>PublicKeyCertificate</c>.
+        /// The <c>keyARN</c> of the CA that signed the <c>PublicKeyCertificate</c> for the client's
+        /// receiving ECC key pair.
         /// </para>
         /// </summary>
         [AWSProperty(Required=true, Min=7, Max=322)]
@@ -66,7 +67,7 @@ internal bool IsSetCertificateAuthorityPublicKeyIdentifier()
         /// <summary>
         /// Gets and sets the property DerivationData. 
         /// <para>
-        /// Derivation data used to derive an ECDH key.
+        /// The shared information used when deriving a key using ECDH.
         /// </para>
         /// </summary>
         [AWSProperty(Required=true)]
@@ -85,7 +86,7 @@ internal bool IsSetDerivationData()
         /// <summary>
         /// Gets and sets the property DeriveKeyAlgorithm. 
         /// <para>
-        /// The key algorithm of the derived ECDH key.
+        /// The key algorithm of the shared derived ECDH key.
         /// </para>
         /// </summary>
         [AWSProperty(Required=true)]
@@ -119,7 +120,7 @@ internal bool IsSetKeyBlockHeaders()
         /// <summary>
         /// Gets and sets the property KeyDerivationFunction. 
         /// <para>
-        /// The key derivation function to use for deriving a key using ECDH.
+        /// The key derivation function to use when deriving a key using ECDH.
         /// </para>
         /// </summary>
         [AWSProperty(Required=true)]
@@ -138,7 +139,7 @@ internal bool IsSetKeyDerivationFunction()
         /// <summary>
         /// Gets and sets the property KeyDerivationHashAlgorithm. 
         /// <para>
-        /// The hash type to use for deriving a key using ECDH.
+        /// The hash type to use when deriving a key using ECDH.
         /// </para>
         /// </summary>
         [AWSProperty(Required=true)]
@@ -157,7 +158,8 @@ internal bool IsSetKeyDerivationHashAlgorithm()
         /// <summary>
         /// Gets and sets the property PrivateKeyIdentifier. 
         /// <para>
-        /// The <c>keyARN</c> of the asymmetric ECC key.
+        /// The <c>keyARN</c> of the asymmetric ECC key created within Amazon Web Services Payment
+        /// Cryptography.
         /// </para>
         /// </summary>
         [AWSProperty(Required=true, Min=7, Max=322)]
@@ -176,8 +178,8 @@ internal bool IsSetPrivateKeyIdentifier()
         /// <summary>
         /// Gets and sets the property PublicKeyCertificate. 
         /// <para>
-        /// The client's public key certificate in PEM format (base64 encoded) to use for ECDH
-        /// key derivation.
+        /// The public key certificate of the client's receiving ECC key pair, in PEM format (base64
+        /// encoded), to use for ECDH key derivation.
         /// </para>
         /// </summary>
         [AWSProperty(Required=true, Sensitive=true, Min=1, Max=32768)]

sdk/src/Services/PaymentCryptography/Generated/Model/DiffieHellmanDerivationData.cs

@@ -43,8 +43,8 @@ public partial class ExportKeyMaterial
         /// <summary>
         /// Gets and sets the property DiffieHellmanTr31KeyBlock. 
         /// <para>
-        /// Parameter information for key material export using the asymmetric ECDH key exchange
-        /// method.
+        /// Key derivation parameter information for key material export using asymmetric ECDH
+        /// key exchange method.
         /// </para>
         /// </summary>
         public ExportDiffieHellmanTr31KeyBlock DiffieHellmanTr31KeyBlock

sdk/src/Services/PaymentCryptography/Generated/Model/ExportDiffieHellmanTr31KeyBlock.cs

@@ -46,20 +46,21 @@ namespace Amazon.PaymentCryptography.Model
     /// <para>
     /// For symmetric key exchange, Amazon Web Services Payment Cryptography uses the ANSI
     /// X9 TR-31 norm in accordance with PCI PIN guidelines. And for asymmetric key exchange,
-    /// Amazon Web Services Payment Cryptography supports ANSI X9 TR-34 norm and RSA wrap
-    /// and unwrap key exchange mechanism. Asymmetric key exchange methods are typically used
-    /// to establish bi-directional trust between the two parties exhanging keys and are used
-    /// for initial key exchange such as Key Encryption Key (KEK). After which you can export
-    /// working keys using symmetric method to perform various cryptographic operations within
-    /// Amazon Web Services Payment Cryptography.
+    /// Amazon Web Services Payment Cryptography supports ANSI X9 TR-34 norm, RSA unwrap,
+    /// and ECDH (Elliptic Curve Diffie-Hellman) key exchange mechanisms. Asymmetric key exchange
+    /// methods are typically used to establish bi-directional trust between the two parties
+    /// exhanging keys and are used for initial key exchange such as Key Encryption Key (KEK).
+    /// After which you can export working keys using symmetric method to perform various
+    /// cryptographic operations within Amazon Web Services Payment Cryptography.
     /// </para>
     ///  
     /// <para>
-    /// The TR-34 norm is intended for exchanging 3DES keys only and keys are imported in
-    /// a WrappedKeyBlock format. Key attributes (such as KeyUsage, KeyAlgorithm, KeyModesOfUse,
-    /// Exportability) are contained within the key block. With RSA wrap and unwrap, you can
-    /// exchange both 3DES and AES-128 keys. The keys are imported in a WrappedKeyCryptogram
-    /// format and you will need to specify the key attributes during import. 
+    /// PCI requires specific minimum key strength of wrapping keys used to protect the keys
+    /// being exchanged electronically. These requirements can change when PCI standards are
+    /// revised. The rules specify that wrapping keys used for transport must be at least
+    /// as strong as the key being protected. For more information on recommended key strength
+    /// of wrapping keys and key exchange mechanism, see <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-importexport.html">Importing
+    /// and exporting keys</a> in the <i>Amazon Web Services Payment Cryptography User Guide</i>.
     /// </para>
     ///  
     /// <para>
@@ -113,7 +114,7 @@ namespace Amazon.PaymentCryptography.Model
     /// the export payload and the signing public key certificate is provided to KRD to verify
     /// the signature. The KRD can import the root certificate into its Hardware Security
     /// Module (HSM), as required. The export token and the associated KDH signing certificate
-    /// expires after 7 days. 
+    /// expires after 30 days. 
     /// </para>
     ///  
     /// <para>
@@ -238,8 +239,50 @@ namespace Amazon.PaymentCryptography.Model
     /// </para>
     ///  </li> </ul> 
     /// <para>
+    ///  <b>To export working keys using ECDH</b> 
+    /// </para>
+    ///  
+    /// <para>
+    /// You can also use ECDH key agreement to export working keys in a TR-31 keyblock, where
+    /// the wrapping key is an ECDH derived key.
+    /// </para>
+    ///  
+    /// <para>
+    /// To initiate a TR-31 key export using ECDH, both sides must create an ECC key pair
+    /// with key usage K3 and exchange public key certificates. In Amazon Web Services Payment
+    /// Cryptography, you can do this by calling <c>CreateKey</c>. If you have not already
+    /// done so, you must import the CA chain that issued the receiving public key certificate
+    /// by calling <c>ImportKey</c> with input <c>RootCertificatePublicKey</c> for root CA
+    /// or <c>TrustedPublicKey</c> for intermediate CA. You can then complete a TR-31 key
+    /// export by deriving a shared wrapping key using the service ECC key pair, public certificate
+    /// of your ECC key pair outside of Amazon Web Services Payment Cryptography, and the
+    /// key derivation parameters including key derivation function, hash algorithm, derivation
+    /// data, key algorithm.
+    /// </para>
+    ///  <ul> <li> 
+    /// <para>
+    ///  <c>KeyMaterial</c>: Use <c>DiffieHellmanTr31KeyBlock</c> parameters.
+    /// </para>
+    ///  </li> <li> 
+    /// <para>
+    ///  <c>PrivateKeyIdentifier</c>: The <c>KeyArn</c> of the ECC key pair created within
+    /// Amazon Web Services Payment Cryptography to derive a shared KEK.
+    /// </para>
+    ///  </li> <li> 
+    /// <para>
+    ///  <c>PublicKeyCertificate</c>: The public key certificate of the receiving ECC key
+    /// pair in PEM format (base64 encoded) to derive a shared KEK.
+    /// </para>
+    ///  </li> <li> 
+    /// <para>
+    ///  <c>CertificateAuthorityPublicKeyIdentifier</c>: The <c>keyARN</c> of the CA that
+    /// signed the public key certificate of the receiving ECC key pair.
+    /// </para>
+    ///  </li> </ul> 
+    /// <para>
     /// When this operation is successful, Amazon Web Services Payment Cryptography returns
-    /// the working key or IPEK as a TR-31 WrappedKeyBlock.
+    /// the working key as a TR-31 WrappedKeyBlock, where the wrapping key is the ECDH derived
+    /// key.
     /// </para>
     ///  
     /// <para>

sdk/src/Services/PaymentCryptography/Generated/Model/ExportKeyMaterial.cs

@@ -68,8 +68,8 @@ internal bool IsSetCertificateAuthorityPublicKeyIdentifier()
         /// The export token to initiate key export from Amazon Web Services Payment Cryptography.
         /// It also contains the signing key certificate that will sign the wrapped key during
         /// TR-34 key block generation. Call <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_GetParametersForExport.html">GetParametersForExport</a>
-        /// to receive an export token. It expires after 7 days. You can use the same export token
-        /// to export multiple keys from the same service account.
+        /// to receive an export token. It expires after 30 days. You can use the same export
+        /// token to export multiple keys from the same service account.
         /// </para>
         /// </summary>
         [AWSProperty(Required=true)]

sdk/src/Services/PaymentCryptography/Generated/Model/ExportKeyRequest.cs

@@ -39,7 +39,7 @@ namespace Amazon.PaymentCryptography.Model
     /// The signing key certificate signs the wrapped key under export within the TR-34 key
     /// payload. The export token and signing key certificate must be in place and operational
     /// before calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ExportKey.html">ExportKey</a>.
-    /// The export token expires in 7 days. You can use the same export token to export multiple
+    /// The export token expires in 30 days. You can use the same export token to export multiple
     /// keys from your service account.
     /// </para>
     ///