feat(client-kms): Added Dry Run Feature to cryptographic and cross-ac…

…count mutating KMS APIs (14 in all). This feature allows users to test their permissions and parameters before making the actual API call.
aws · Jul 5, 2023 · 4bdf266 · 4bdf266
1 parent be38fc8
commit 4bdf266
Show file tree

Hide file tree

Showing 45 changed files with 804 additions and 298 deletions.
diff --git a/clients/client-kms/src/commands/CancelKeyDeletionCommand.ts b/clients/client-kms/src/commands/CancelKeyDeletionCommand.ts
@@ -98,7 +98,9 @@ export interface CancelKeyDeletionCommandOutput extends CancelKeyDeletionRespons
  *                   </i>.</p>
  *             </li>
  *             <li>
- *                <p>For cryptographic operations on KMS keys in custom key stores, this exception represents a general failure with many possible causes. To identify the cause, see the error message that accompanies the exception.</p>
+ *                <p>For cryptographic operations on KMS keys in custom key stores, this exception
+ *           represents a general failure with many possible causes. To identify the cause, see the
+ *           error message that accompanies the exception.</p>
  *             </li>
  *          </ul>
  *

diff --git a/clients/client-kms/src/commands/CreateAliasCommand.ts b/clients/client-kms/src/commands/CreateAliasCommand.ts
@@ -144,7 +144,9 @@ export interface CreateAliasCommandOutput extends __MetadataBearer {}
  *                   </i>.</p>
  *             </li>
  *             <li>
- *                <p>For cryptographic operations on KMS keys in custom key stores, this exception represents a general failure with many possible causes. To identify the cause, see the error message that accompanies the exception.</p>
+ *                <p>For cryptographic operations on KMS keys in custom key stores, this exception
+ *           represents a general failure with many possible causes. To identify the cause, see the
+ *           error message that accompanies the exception.</p>
  *             </li>
  *          </ul>
  *

diff --git a/clients/client-kms/src/commands/CreateCustomKeyStoreCommand.ts b/clients/client-kms/src/commands/CreateCustomKeyStoreCommand.ts
@@ -44,8 +44,9 @@ export interface CreateCustomKeyStoreCommandOutput extends CreateCustomKeyStoreR
  *       KMS key in a custom key store for a cryptographic operation, the cryptographic operation is
  *       actually performed in your key store using your keys. KMS supports <a href="https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html">CloudHSM key stores</a>
  *       backed by an <a href="https://docs.aws.amazon.com/cloudhsm/latest/userguide/clusters.html">CloudHSM cluster</a>
- *       and <a href="https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html">external key stores</a> backed by an external key store proxy and
- *       external key manager outside of Amazon Web Services.</p>
+ *       and <a href="https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html">external key
+ *         stores</a> backed by an external key store proxy and external key manager outside of
+ *       Amazon Web Services.</p>
  *          <p> This operation is part of the <a href="https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html">custom key stores</a> feature in KMS, which
  * combines the convenience and extensive integration of KMS with the isolation and control of a
  * key store that you own and manage.</p>
@@ -81,9 +82,9 @@ export interface CreateCustomKeyStoreCommandOutput extends CreateCustomKeyStoreR
  *             <p>Some external key managers provide a simpler method for creating an external key store.
  *         For details, see your external key manager documentation.</p>
  *             <p>When creating an external key store in the KMS console, you can upload a JSON-based
- *         proxy configuration file with the desired values. You cannot use a proxy configuration
- *         with the <code>CreateCustomKeyStore</code> operation. However, you can use the values in
- *         the file to help you determine the correct values for the <code>CreateCustomKeyStore</code>
+ *         proxy configuration file with the desired values. You cannot use a proxy configuration with
+ *         the <code>CreateCustomKeyStore</code> operation. However, you can use the values in the file
+ *         to help you determine the correct values for the <code>CreateCustomKeyStore</code>
  *         parameters.</p>
  *          </note>
  *          <p>When the operation completes successfully, it returns the ID of the new custom key store.
@@ -266,8 +267,9 @@ export interface CreateCustomKeyStoreCommandOutput extends CreateCustomKeyStoreR
  * @throws {@link XksProxyUriUnreachableException} (client fault)
  *  <p>KMS was unable to reach the specified <code>XksProxyUriPath</code>. The path must be
  *       reachable before you create the external key store or update its settings.</p>
- *          <p>This exception is also thrown when the external key store proxy response to a <code>GetHealthStatus</code>
- *       request indicates that all external key manager instances are unavailable.</p>
+ *          <p>This exception is also thrown when the external key store proxy response to a
+ *         <code>GetHealthStatus</code> request indicates that all external key manager instances are
+ *       unavailable.</p>
  *
  * @throws {@link XksProxyVpcEndpointServiceInUseException} (client fault)
  *  <p>The request was rejected because the specified Amazon VPC endpoint service is already
@@ -277,7 +279,8 @@ export interface CreateCustomKeyStoreCommandOutput extends CreateCustomKeyStoreR
  * @throws {@link XksProxyVpcEndpointServiceInvalidConfigurationException} (client fault)
  *  <p>The request was rejected because the Amazon VPC endpoint service configuration does not fulfill
  *       the requirements for an external key store proxy. For details, see the exception message and
- *         <a href="kms/latest/developerguide/vpc-connectivity.html#xks-vpc-requirements">review the requirements</a> for Amazon VPC endpoint service connectivity for an external key
+ *         <a href="kms/latest/developerguide/vpc-connectivity.html#xks-vpc-requirements">review the
+ *         requirements</a> for Amazon VPC endpoint service connectivity for an external key
  *       store.</p>
  *
  * @throws {@link XksProxyVpcEndpointServiceNotFoundException} (client fault)

diff --git a/clients/client-kms/src/commands/CreateGrantCommand.ts b/clients/client-kms/src/commands/CreateGrantCommand.ts
@@ -123,6 +123,7 @@ export interface CreateGrantCommandOutput extends CreateGrantResponse, __Metadat
  *     "STRING_VALUE",
  *   ],
  *   Name: "STRING_VALUE",
+ *   DryRun: true || false,
  * };
  * const command = new CreateGrantCommand(input);
  * const response = await client.send(command);
@@ -146,6 +147,11 @@ export interface CreateGrantCommandOutput extends CreateGrantResponse, __Metadat
  * @throws {@link DisabledException} (client fault)
  *  <p>The request was rejected because the specified KMS key is not enabled.</p>
  *
+ * @throws {@link DryRunOperationException} (client fault)
+ *  <p>
+ *       The request was rejected because the DryRun parameter was specified.
+ *     </p>
+ *
  * @throws {@link InvalidArnException} (client fault)
  *  <p>The request was rejected because a specified ARN, or an ARN in a key policy, is not
  *       valid.</p>
@@ -171,7 +177,9 @@ export interface CreateGrantCommandOutput extends CreateGrantResponse, __Metadat
  *                   </i>.</p>
  *             </li>
  *             <li>
- *                <p>For cryptographic operations on KMS keys in custom key stores, this exception represents a general failure with many possible causes. To identify the cause, see the error message that accompanies the exception.</p>
+ *                <p>For cryptographic operations on KMS keys in custom key stores, this exception
+ *           represents a general failure with many possible causes. To identify the cause, see the
+ *           error message that accompanies the exception.</p>
  *             </li>
  *          </ul>
  *

diff --git a/clients/client-kms/src/commands/CreateKeyCommand.ts b/clients/client-kms/src/commands/CreateKeyCommand.ts
@@ -76,11 +76,14 @@ export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBea
  *             the type of key material in the KMS key. Then, use the <code>KeyUsage</code> parameter
  *             to determine whether the KMS key will be used to encrypt and decrypt or sign and verify.
  *             You can't change these properties after the KMS key is created.</p>
- *                <p>Asymmetric KMS keys contain an RSA key pair, Elliptic Curve (ECC) key pair, or an SM2 key pair (China Regions only). The private key in an asymmetric
- *             KMS key never leaves KMS unencrypted. However, you can use the <a>GetPublicKey</a> operation to download the public key
- *             so it can be used outside of KMS. KMS keys with RSA or SM2 key pairs can be used to encrypt or decrypt data or sign and verify messages (but not both).
- *             KMS keys with ECC key pairs can be used only to sign and verify messages.
- *             For information about asymmetric KMS keys, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html">Asymmetric KMS keys</a> in the <i>Key Management Service Developer Guide</i>.</p>
+ *                <p>Asymmetric KMS keys contain an RSA key pair, Elliptic Curve (ECC) key pair, or an
+ *             SM2 key pair (China Regions only). The private key in an asymmetric KMS key never leaves
+ *             KMS unencrypted. However, you can use the <a>GetPublicKey</a> operation to
+ *             download the public key so it can be used outside of KMS. KMS keys with RSA or SM2 key
+ *             pairs can be used to encrypt or decrypt data or sign and verify messages (but not both).
+ *             KMS keys with ECC key pairs can be used only to sign and verify messages. For
+ *             information about asymmetric KMS keys, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html">Asymmetric KMS keys</a> in the
+ *             <i>Key Management Service Developer Guide</i>.</p>
  *                <p> </p>
  *             </dd>
  *             <dt>HMAC KMS key</dt>
@@ -117,8 +120,8 @@ export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBea
  *                <p>To import your own key material into a KMS key, begin by creating a KMS key with no
  *             key material. To do this, use the <code>Origin</code> parameter of
  *               <code>CreateKey</code> with a value of <code>EXTERNAL</code>. Next, use <a>GetParametersForImport</a> operation to get a public key and import token. Use
- *             the wrapping public key to encrypt your key material. Then, use <a>ImportKeyMaterial</a> with your import token to import the key material. For step-by-step instructions, see
- *               <a href="https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html">Importing Key Material</a> in the <i>
+ *             the wrapping public key to encrypt your key material. Then, use <a>ImportKeyMaterial</a> with your import token to import the key material. For
+ *             step-by-step instructions, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html">Importing Key Material</a> in the <i>
  *                      <i>Key Management Service Developer Guide</i>
  *                   </i>.</p>
  *                <p>You can import key material into KMS keys of all supported KMS key types: symmetric
@@ -160,9 +163,9 @@ export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBea
  *               <code>Origin</code> parameter with a value of <code>AWS_CLOUDHSM</code>. The CloudHSM
  *             cluster that is associated with the custom key store must have at least two active HSMs
  *             in different Availability Zones in the Amazon Web Services Region.</p>
- *                <p>To create a KMS key in an <a href="https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html">external key store</a>, use the <code>Origin</code> parameter
- *             with a value of <code>EXTERNAL_KEY_STORE</code> and an <code>XksKeyId</code> parameter
- *             that identifies an existing external key.</p>
+ *                <p>To create a KMS key in an <a href="https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html">external key store</a>, use the
+ *               <code>Origin</code> parameter with a value of <code>EXTERNAL_KEY_STORE</code> and an
+ *               <code>XksKeyId</code> parameter that identifies an existing external key.</p>
  *                <note>
  *                   <p>Some external key managers provide a simpler method for creating a KMS key in an
  *               external key store. For details, see your external key manager documentation.</p>
@@ -393,9 +396,9 @@ export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBea
  *       and decryption.</p>
  *
  * @throws {@link XksKeyNotFoundException} (client fault)
- *  <p>The request was rejected because the external key store proxy could not find the external key. This
- *       exception is thrown when the value of the <code>XksKeyId</code> parameter doesn't identify a
- *       key in the external key manager associated with the external key proxy.</p>
+ *  <p>The request was rejected because the external key store proxy could not find the external
+ *       key. This exception is thrown when the value of the <code>XksKeyId</code> parameter doesn't
+ *       identify a key in the external key manager associated with the external key proxy.</p>
  *          <p>Verify that the <code>XksKeyId</code> represents an existing key in the external key
  *       manager. Use the key identifier that the external key store proxy uses to identify the key.
  *       For details, see the documentation provided with your external key store proxy or key

diff --git a/clients/client-kms/src/commands/DecryptCommand.ts b/clients/client-kms/src/commands/DecryptCommand.ts
@@ -96,7 +96,7 @@ export interface DecryptCommandOutput extends DecryptResponse, __MetadataBearer
  *       the <a href="https://docs.aws.amazon.com/enclaves/latest/user/developing-applications.html#sdk">Amazon Web Services Nitro Enclaves SDK</a> or any Amazon Web Services SDK. Use the <code>Recipient</code> parameter to provide the
  *       attestation document for the enclave. Instead of the plaintext data, the response includes the
  *       plaintext data encrypted with the public key from the attestation document
- *       (<code>CiphertextForRecipient</code>).For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/services-nitro-enclaves.html">How Amazon Web Services Nitro Enclaves uses KMS</a> in the <i>Key Management Service Developer Guide</i>..</p>
+ *         (<code>CiphertextForRecipient</code>).For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/services-nitro-enclaves.html">How Amazon Web Services Nitro Enclaves uses KMS</a> in the <i>Key Management Service Developer Guide</i>..</p>
  *          <p>The KMS key that you use for this operation must be in a compatible key state. For
  * details, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html">Key states of KMS keys</a> in the <i>Key Management Service Developer Guide</i>.</p>
  *          <p>
@@ -150,6 +150,7 @@ export interface DecryptCommandOutput extends DecryptResponse, __MetadataBearer
  *     KeyEncryptionAlgorithm: "RSAES_OAEP_SHA_256",
  *     AttestationDocument: "BLOB_VALUE",
  *   },
+ *   DryRun: true || false,
  * };
  * const command = new DecryptCommand(input);
  * const response = await client.send(command);
@@ -175,6 +176,11 @@ export interface DecryptCommandOutput extends DecryptResponse, __MetadataBearer
  * @throws {@link DisabledException} (client fault)
  *  <p>The request was rejected because the specified KMS key is not enabled.</p>
  *
+ * @throws {@link DryRunOperationException} (client fault)
+ *  <p>
+ *       The request was rejected because the DryRun parameter was specified.
+ *     </p>
+ *
  * @throws {@link IncorrectKeyException} (client fault)
  *  <p>The request was rejected because the specified KMS key cannot decrypt the data. The
  *         <code>KeyId</code> in a <a>Decrypt</a> request and the <code>SourceKeyId</code>
@@ -235,7 +241,9 @@ export interface DecryptCommandOutput extends DecryptResponse, __MetadataBearer
  *                   </i>.</p>
  *             </li>
  *             <li>
- *                <p>For cryptographic operations on KMS keys in custom key stores, this exception represents a general failure with many possible causes. To identify the cause, see the error message that accompanies the exception.</p>
+ *                <p>For cryptographic operations on KMS keys in custom key stores, this exception
+ *           represents a general failure with many possible causes. To identify the cause, see the
+ *           error message that accompanies the exception.</p>
  *             </li>
  *          </ul>
  *

diff --git a/clients/client-kms/src/commands/DeleteAliasCommand.ts b/clients/client-kms/src/commands/DeleteAliasCommand.ts
@@ -127,7 +127,9 @@ export interface DeleteAliasCommandOutput extends __MetadataBearer {}
  *                   </i>.</p>
  *             </li>
  *             <li>
- *                <p>For cryptographic operations on KMS keys in custom key stores, this exception represents a general failure with many possible causes. To identify the cause, see the error message that accompanies the exception.</p>
+ *                <p>For cryptographic operations on KMS keys in custom key stores, this exception
+ *           represents a general failure with many possible causes. To identify the cause, see the
+ *           error message that accompanies the exception.</p>
  *             </li>
  *          </ul>
  *

diff --git a/clients/client-kms/src/commands/DeleteImportedKeyMaterialCommand.ts b/clients/client-kms/src/commands/DeleteImportedKeyMaterialCommand.ts
@@ -111,7 +111,9 @@ export interface DeleteImportedKeyMaterialCommandOutput extends __MetadataBearer
  *                   </i>.</p>
  *             </li>
  *             <li>
- *                <p>For cryptographic operations on KMS keys in custom key stores, this exception represents a general failure with many possible causes. To identify the cause, see the error message that accompanies the exception.</p>
+ *                <p>For cryptographic operations on KMS keys in custom key stores, this exception
+ *           represents a general failure with many possible causes. To identify the cause, see the
+ *           error message that accompanies the exception.</p>
  *             </li>
  *          </ul>
  *

diff --git a/clients/client-kms/src/commands/DescribeCustomKeyStoresCommand.ts b/clients/client-kms/src/commands/DescribeCustomKeyStoresCommand.ts
@@ -63,8 +63,8 @@ export interface DescribeCustomKeyStoresCommandOutput extends DescribeCustomKeyS
  *       any. For an external key store, verify that the external key store proxy and its associated
  *       external key manager are reachable and enabled.</p>
  *          <p> For help repairing your CloudHSM key store, see the <a href="https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html">Troubleshooting CloudHSM key stores</a>. For help
- *       repairing your external key store, see the <a href="https://docs.aws.amazon.com/kms/latest/developerguide/xks-troubleshooting.html">Troubleshooting external key stores</a>. Both
- *       topics are in the <i>Key Management Service Developer Guide</i>.</p>
+ *       repairing your external key store, see the <a href="https://docs.aws.amazon.com/kms/latest/developerguide/xks-troubleshooting.html">Troubleshooting external key stores</a>.
+ *       Both topics are in the <i>Key Management Service Developer Guide</i>.</p>
  *          <p>
  *             <b>Cross-account use</b>: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.</p>
  *          <p>

diff --git a/clients/client-kms/src/commands/DisableKeyCommand.ts b/clients/client-kms/src/commands/DisableKeyCommand.ts
@@ -98,7 +98,9 @@ export interface DisableKeyCommandOutput extends __MetadataBearer {}
  *                   </i>.</p>
  *             </li>
  *             <li>
- *                <p>For cryptographic operations on KMS keys in custom key stores, this exception represents a general failure with many possible causes. To identify the cause, see the error message that accompanies the exception.</p>
+ *                <p>For cryptographic operations on KMS keys in custom key stores, this exception
+ *           represents a general failure with many possible causes. To identify the cause, see the
+ *           error message that accompanies the exception.</p>
  *             </li>
  *          </ul>
  *