npm - @aws-sdk/client-kms - Versions diffs - 3.218.0 → 3.220.0 - Mend

@aws-sdk/client-kms 3.218.0 → 3.220.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

package/dist-types/KMSClient.d.ts CHANGED Viewed

@@ -180,7 +180,7 @@ export interface KMSClientResolvedConfig extends KMSClientResolvedConfigType {
  *                <i>Key Management Service Developer Guide</i>
  *             </a>.</p>
  *          <note>
- *             <p>KMS is replacing the term <i>customer master key (CMK)</i> with <i>KMS key</i> and <i>KMS key</i>. The concept has not changed. To prevent breaking changes, KMS is keeping some variations of this term.</p>
+ *             <p>KMS has replaced the term <i>customer master key (CMK)</i> with <i>KMS key</i> and <i>KMS key</i>. The concept has not changed. To prevent breaking changes, KMS is keeping some variations of this term.</p>
  *             <p>Amazon Web Services provides SDKs that consist of libraries and sample code for various programming
  *         languages and platforms (Java, Ruby, .Net, macOS, Android, etc.). The SDKs provide a
  *         convenient way to create programmatic access to KMS and other Amazon Web Services services. For example,
@@ -189,23 +189,24 @@ export interface KMSClientResolvedConfig extends KMSClientResolvedConfigType {
  *         download and install them, see <a href="http://aws.amazon.com/tools/">Tools for Amazon Web
  *           Services</a>.</p>
  *          </note>
- *          <p>We recommend that you use the Amazon Web Services SDKs to make programmatic API calls to KMS. </p>
+ *          <p>We recommend that you use the Amazon Web Services SDKs to make programmatic API calls to KMS.</p>
  *          <p>If you need to use FIPS 140-2 validated cryptographic modules when communicating with
  *       Amazon Web Services, use the FIPS endpoint in your preferred Amazon Web Services Region. For more information about the
- *       available FIPS endpoints, see <a href="https://docs.aws.amazon.com/general/latest/gr/kms.html#kms_region">Service endpoints</a> in the Key Management Service topic of the <i>Amazon Web Services General Reference</i>.</p>
- *          <p>All KMS API calls must be signed and be transmitted using Transport Layer Security (TLS).
- *       KMS recommends you always use the latest supported TLS version. Clients
- *       must also support cipher suites with Perfect Forward Secrecy (PFS) such as Ephemeral
- *       Diffie-Hellman (DHE) or Elliptic Curve Ephemeral Diffie-Hellman (ECDHE). Most modern systems
- *       such as Java 7 and later support these modes.</p>
+ *       available FIPS endpoints, see <a href="https://docs.aws.amazon.com/general/latest/gr/kms.html#kms_region">Service endpoints</a> in the Key Management Service topic of
+ *       the <i>Amazon Web Services General Reference</i>.</p>
+ *          <p>All KMS API calls must be signed and be transmitted using Transport Layer Security
+ *       (TLS). KMS recommends you always use the latest supported TLS version. Clients must also
+ *       support cipher suites with Perfect Forward Secrecy (PFS) such as Ephemeral Diffie-Hellman
+ *       (DHE) or Elliptic Curve Ephemeral Diffie-Hellman (ECDHE). Most modern systems such as Java 7
+ *       and later support these modes.</p>
  *          <p>
  *             <b>Signing Requests</b>
  *          </p>
  *          <p>Requests must be signed by using an access key ID and a secret access key. We strongly
  *       recommend that you <i>do not</i> use your Amazon Web Services account (root) access key ID and
- *       secret key for everyday work with KMS. Instead, use the access key ID and secret access key
- *       for an IAM user. You can also use the Amazon Web Services Security Token Service to generate temporary
- *       security credentials that you can use to sign requests.</p>
+ *       secret access key for everyday work with KMS. Instead, use the access key ID and secret
+ *       access key for an IAM user. You can also use the Amazon Web Services Security Token Service to generate
+ *       temporary security credentials that you can use to sign requests.</p>
  *          <p>All KMS operations require <a href="https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html">Signature Version 4</a>.</p>
  *          <p>
  *             <b>Logging API Requests</b>

package/dist-types/commands/CancelKeyDeletionCommand.d.ts CHANGED Viewed

@@ -15,8 +15,7 @@ export interface CancelKeyDeletionCommandOutput extends CancelKeyDeletionRespons
  *          <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>
- *             <b>Cross-account
- *         use</b>: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.</p>
+ *             <b>Cross-account use</b>: No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.</p>
  *          <p>
  *             <b>Required permissions</b>: <a href="https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html">kms:CancelKeyDeletion</a> (key policy)</p>
  *          <p>

package/dist-types/commands/ConnectCustomKeyStoreCommand.d.ts CHANGED Viewed

@@ -8,24 +8,21 @@ export interface ConnectCustomKeyStoreCommandInput extends ConnectCustomKeyStore
 export interface ConnectCustomKeyStoreCommandOutput extends ConnectCustomKeyStoreResponse, __MetadataBearer {
 }
 /**
- * <p>Connects or reconnects a <a href="https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html">custom key store</a> to its associated CloudHSM cluster.</p>
+ * <p>Connects or reconnects a <a href="https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html">custom key store</a> to its backing key store. For an CloudHSM key
+ *       store, <code>ConnectCustomKeyStore</code> connects the key store to its associated CloudHSM
+ *       cluster. For an external key store, <code>ConnectCustomKeyStore</code> connects the key store
+ *       to the external key store proxy that communicates with your external key manager.</p>
  *          <p>The custom key store must be connected before you can create KMS keys in the key store or
  *       use the KMS keys it contains. You can disconnect and reconnect a custom key store at any
  *       time.</p>
- *          <p>To connect a custom key store, its associated CloudHSM cluster must have at least one active
- *       HSM. To get the number of active HSMs in a cluster, use the <a href="https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html">DescribeClusters</a> operation. To add HSMs
- *       to the cluster, use the <a href="https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html">CreateHsm</a> operation. Also, the <a href="https://docs.aws.amazon.com/kms/latest/developerguide/key-store-concepts.html#concept-kmsuser">
- *                <code>kmsuser</code> crypto
- *         user</a> (CU) must not be logged into the cluster. This prevents KMS from using this
- *       account to log in.</p>
- *          <p>The connection process can take an extended amount of time to complete; up to 20 minutes.
- *       This operation starts the connection process, but it does not wait for it to complete. When it
- *       succeeds, this operation quickly returns an HTTP 200 response and a JSON object with no
- *       properties. However, this response does not indicate that the custom key store is connected.
- *       To get the connection state of the custom key store, use the <a>DescribeCustomKeyStores</a> operation.</p>
- *          <p>During the connection process, KMS finds the CloudHSM cluster that is associated with the
- *       custom key store, creates the connection infrastructure, connects to the cluster, logs into
- *       the CloudHSM client as the <code>kmsuser</code> CU, and rotates its password.</p>
+ *          <p>The connection process for a custom key store can take an extended amount of time to
+ *       complete. This operation starts the connection process, but it does not wait for it to
+ *       complete. When it succeeds, this operation quickly returns an HTTP 200 response and a JSON
+ *       object with no properties. However, this response does not indicate that the custom key store
+ *       is connected. To get the connection state of the custom key store, use the <a>DescribeCustomKeyStores</a> operation.</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>
  *          <p>The <code>ConnectCustomKeyStore</code> operation might fail for various reasons. To find
  *       the reason, use the <a>DescribeCustomKeyStores</a> operation and see the
  *         <code>ConnectionErrorCode</code> in the response. For help interpreting the
@@ -33,8 +30,37 @@ export interface ConnectCustomKeyStoreCommandOutput extends ConnectCustomKeyStor
  *          <p>To fix the failure, use the <a>DisconnectCustomKeyStore</a> operation to
  *       disconnect the custom key store, correct the error, use the <a>UpdateCustomKeyStore</a> operation if necessary, and then use
  *         <code>ConnectCustomKeyStore</code> again.</p>
- *          <p>If you are having trouble connecting or disconnecting a custom key store, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html">Troubleshooting a Custom Key
- *         Store</a> in the <i>Key Management Service Developer Guide</i>.</p>
+ *          <p>
+ *             <b>CloudHSM key store</b>
+ *          </p>
+ *          <p>During the connection process for an CloudHSM key store, KMS finds the CloudHSM cluster that
+ *       is associated with the custom key store, creates the connection infrastructure, connects to
+ *       the cluster, logs into the CloudHSM client as the <code>kmsuser</code> CU, and rotates its
+ *       password.</p>
+ *          <p>To connect an CloudHSM key store, its associated CloudHSM cluster must have at least one active
+ *       HSM. To get the number of active HSMs in a cluster, use the <a href="https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html">DescribeClusters</a> operation. To add HSMs
+ *       to the cluster, use the <a href="https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_CreateHsm.html">CreateHsm</a> operation. Also, the <a href="https://docs.aws.amazon.com/kms/latest/developerguide/key-store-concepts.html#concept-kmsuser">
+ *                <code>kmsuser</code> crypto
+ *         user</a> (CU) must not be logged into the cluster. This prevents KMS from using this
+ *       account to log in.</p>
+ *          <p>If you are having trouble connecting or disconnecting a CloudHSM key store, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html">Troubleshooting an CloudHSM key
+ *         store</a> in the <i>Key Management Service Developer Guide</i>.</p>
+ *          <p>
+ *             <b>External key store</b>
+ *          </p>
+ *          <p>When you connect an external key store that uses public endpoint connectivity, KMS tests
+ *       its ability to communicate with your external key manager by sending a request via the
+ *       external key store proxy.</p>
+ *          <p>When you connect to an external key store that uses VPC endpoint service connectivity,
+ *       KMS establishes the networking elements that it needs to communicate with your external key
+ *       manager via the external key store proxy. This includes creating an interface endpoint to the
+ *       VPC endpoint service and a private hosted zone for traffic between KMS and the VPC endpoint
+ *       service.</p>
+ *          <p>To connect an external key store, KMS must be able to connect to the external key store
+ *       proxy, the external key store proxy must be able to communicate with your external key
+ *       manager, and the external key manager must be available for cryptographic operations.</p>
+ *          <p>If you are having trouble connecting or disconnecting an external key store, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/xks-troubleshooting.html">Troubleshooting an external
+ *         key store</a> 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>
  *

package/dist-types/commands/CreateAliasCommand.d.ts CHANGED Viewed

@@ -10,7 +10,7 @@ export interface CreateAliasCommandOutput extends __MetadataBearer {
 /**
  * <p>Creates a friendly name for a KMS key. </p>
  *          <note>
- *             <p>Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/abac.html">ABAC in KMS</a> in the <i>Key Management Service Developer Guide</i>.</p>
+ *             <p>Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/abac.html">ABAC for KMS</a> in the <i>Key Management Service Developer Guide</i>.</p>
  *          </note>
  *          <p>You can use an alias to identify a KMS key in the KMS console, in the <a>DescribeKey</a> operation and in <a href="https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#cryptographic-operations">cryptographic operations</a>, such as <a>Encrypt</a> and
  *         <a>GenerateDataKey</a>. You can also change the KMS key that's associated with

package/dist-types/commands/CreateCustomKeyStoreCommand.d.ts CHANGED Viewed

@@ -8,21 +8,59 @@ export interface CreateCustomKeyStoreCommandInput extends CreateCustomKeyStoreRe
 export interface CreateCustomKeyStoreCommandOutput extends CreateCustomKeyStoreResponse, __MetadataBearer {
 }
 /**
- * <p>Creates a <a href="https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html">custom key store</a> that is associated with an <a href="https://docs.aws.amazon.com/cloudhsm/latest/userguide/clusters.html">CloudHSM cluster</a> that you own and
- *     manage.</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 store feature</a> feature in KMS, which
+ * <p>Creates a <a href="https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html">custom key store</a> backed by a key store that you own and manage. When you use a
+ *       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>
+ *          <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
- * single-tenant key store.</p>
- *          <p>Before you create the custom key store, you must assemble
- *       the required elements, including an CloudHSM cluster that fulfills the requirements for a custom
- *       key store. For details about the required elements, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/create-keystore.html#before-keystore">Assemble the Prerequisites</a>
- *       in the <i>Key Management Service Developer Guide</i>.</p>
+ * key store that you own and manage.</p>
+ *          <p>Before you create the custom key store, the required elements must be in place and
+ *       operational. We recommend that you use the test tools that KMS provides to verify the
+ *       configuration your external key store proxy. For details about the required elements and
+ *       verification tests, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/create-keystore.html#before-keystore">Assemble the prerequisites (for
+ *         CloudHSM key stores)</a> or <a href="https://docs.aws.amazon.com/kms/latest/developerguide/create-xks-keystore.html#xks-requirements">Assemble the prerequisites (for
+ *         external key stores)</a> in the <i>Key Management Service Developer Guide</i>.</p>
+ *          <p>To create a custom key store, use the following parameters.</p>
+ *          <ul>
+ *             <li>
+ *                <p>To create an CloudHSM key store, specify the <code>CustomKeyStoreName</code>,
+ *             <code>CloudHsmClusterId</code>, <code>KeyStorePassword</code>, and
+ *             <code>TrustAnchorCertificate</code>. The <code>CustomKeyStoreType</code> parameter is
+ *           optional for CloudHSM key stores. If you include it, set it to the default value,
+ *             <code>AWS_CLOUDHSM</code>. For help with failures, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html">Troubleshooting an CloudHSM key store</a> in the
+ *           <i>Key Management Service Developer Guide</i>.</p>
+ *             </li>
+ *             <li>
+ *                <p>To create an external key store, specify the <code>CustomKeyStoreName</code> and a
+ *             <code>CustomKeyStoreType</code> of <code>EXTERNAL_KEY_STORE</code>. Also, specify values
+ *           for <code>XksProxyConnectivity</code>, <code>XksProxyAuthenticationCredential</code>,
+ *             <code>XksProxyUriEndpoint</code>, and <code>XksProxyUriPath</code>. If your
+ *             <code>XksProxyConnectivity</code> value is <code>VPC_ENDPOINT_SERVICE</code>, specify
+ *           the <code>XksProxyVpcEndpointServiceName</code> parameter. For help with failures, see
+ *             <a href="https://docs.aws.amazon.com/kms/latest/developerguide/xks-troubleshooting.html">Troubleshooting
+ *             an external key store</a> in the <i>Key Management Service Developer Guide</i>.</p>
+ *             </li>
+ *          </ul>
+ *          <note>
+ *             <p>For external key stores:</p>
+ *             <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>
+ *         parameters.</p>
+ *          </note>
  *          <p>When the operation completes successfully, it returns the ID of the new custom key store.
- *       Before you can use your new custom key store, you need to use the <a>ConnectCustomKeyStore</a> operation to connect the new key store to its CloudHSM
- *       cluster. Even if you are not going to use your custom key store immediately, you might want to
- *       connect it to verify that all settings are correct and then disconnect it until you are ready
- *       to use it.</p>
- *          <p>For help with failures, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html">Troubleshooting a Custom Key Store</a> in the
+ *       Before you can use your new custom key store, you need to use the <a>ConnectCustomKeyStore</a> operation to connect a new CloudHSM key store to its CloudHSM
+ *       cluster, or to connect a new external key store to the external key store proxy for your
+ *       external key manager. Even if you are not going to use your custom key store immediately, you
+ *       might want to connect it to verify that all settings are correct and then disconnect it until
+ *       you are ready to use it.</p>
+ *          <p>For help with failures, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html">Troubleshooting a custom key store</a> 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>

package/dist-types/commands/CreateGrantCommand.d.ts CHANGED Viewed

@@ -41,8 +41,7 @@ export interface CreateGrantCommandOutput extends CreateGrantResponse, __Metadat
  *          <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>
- *             <b>Cross-account use</b>: Yes.
- *       To perform this operation on a KMS key in a different Amazon Web Services account, specify the key
+ *             <b>Cross-account use</b>: Yes. To perform this operation on a KMS key in a different Amazon Web Services account, specify the key
  *   ARN in the value of the <code>KeyId</code> parameter. </p>
  *          <p>
  *             <b>Required permissions</b>: <a href="https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html">kms:CreateGrant</a> (key policy)</p>

package/dist-types/commands/CreateKeyCommand.d.ts CHANGED Viewed

@@ -8,25 +8,41 @@ export interface CreateKeyCommandInput extends CreateKeyRequest {
 export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBearer {
 }
 /**
- * <p>Creates a unique customer managed <a href="https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms-keys">KMS key</a> in your Amazon Web Services account and
- *       Region.</p>
- *          <p>In addition to the required parameters, you can use the optional parameters to specify a key policy, description, tags, and other useful elements for any key type.</p>
+ * <p>Creates a unique customer managed <a href="https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms-keys">KMS key</a> in your Amazon Web Services account and Region.
+ *       You can use a KMS key in cryptographic operations, such as encryption and signing. Some Amazon Web Services
+ *       services let you use KMS keys that you create and manage to protect your service
+ *       resources.</p>
+ *          <p>A KMS key is a logical representation of a cryptographic key. In addition to the key
+ *       material used in cryptographic operations, a KMS key includes metadata, such as the key ID,
+ *       key policy, creation date, description, and key state. For details, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/getting-started.html">Managing keys</a> in the
+ *       <i>Key Management Service Developer Guide</i>
+ *          </p>
+ *          <p>Use the parameters of <code>CreateKey</code> to specify the type of KMS key, the source of
+ *       its key material, its key policy, description, tags, and other properties.</p>
  *          <note>
- *             <p>KMS is replacing the term <i>customer master key (CMK)</i> with <i>KMS key</i> and <i>KMS key</i>. The concept has not changed. To prevent breaking changes, KMS is keeping some variations of this term.</p>
+ *             <p>KMS has replaced the term <i>customer master key (CMK)</i> with <i>KMS key</i> and <i>KMS key</i>. The concept has not changed. To prevent breaking changes, KMS is keeping some variations of this term.</p>
  *          </note>
  *
+ *
  *          <p>To create different types of KMS keys, use the following guidance:</p>
  *
  *          <dl>
  *             <dt>Symmetric encryption KMS key</dt>
  *             <dd>
- *                <p>To create a symmetric encryption KMS key, you aren't required to specify any parameters. The default value for
- *             <code>KeySpec</code>, <code>SYMMETRIC_DEFAULT</code>, and the default value for
- *             <code>KeyUsage</code>, <code>ENCRYPT_DECRYPT</code>, create a symmetric encryption KMS key. For technical details, see
- *             <a href="https://docs.aws.amazon.com/kms/latest/developerguide/asymmetric-key-specs.html#key-spec-symmetric-default">
- *               SYMMETRIC_DEFAULT key spec</a> in the <i>Key Management Service Developer Guide</i>.</p>
- *                <p>If you need a key for basic encryption and decryption or you
- *             are creating a KMS key to protect your resources in an Amazon Web Services service, create a symmetric encryption KMS key. The key material in a symmetric encryption key never leaves KMS unencrypted. You can use a symmetric encryption KMS key to encrypt and decrypt data up to 4,096 bytes, but they are typically used to generate data keys and data keys pairs. For details, see <a>GenerateDataKey</a> and <a>GenerateDataKeyPair</a>.</p>
+ *                <p>By default, <code>CreateKey</code> creates a symmetric encryption KMS key with key
+ *             material that KMS generates. This is the basic and most widely used type of KMS key, and
+ *             provides the best performance.</p>
+ *                <p>To create a symmetric encryption KMS key, you don't need to specify any parameters.
+ *             The default value for <code>KeySpec</code>, <code>SYMMETRIC_DEFAULT</code>, the default
+ *             value for <code>KeyUsage</code>, <code>ENCRYPT_DECRYPT</code>, and the default value for
+ *               <code>Origin</code>, <code>AWS_KMS</code>, create a symmetric encryption KMS key with
+ *             KMS key material.</p>
+ *                <p>If you need a key for basic encryption and decryption or you are creating a KMS key
+ *             to protect your resources in an Amazon Web Services service, create a symmetric encryption KMS key.
+ *             The key material in a symmetric encryption key never leaves KMS unencrypted. You can
+ *             use a symmetric encryption KMS key to encrypt and decrypt data up to 4,096 bytes, but
+ *             they are typically used to generate data keys and data keys pairs. For details, see
+ *               <a>GenerateDataKey</a> and <a>GenerateDataKeyPair</a>.</p>
  *                <p> </p>
  *             </dd>
  *             <dt>Asymmetric KMS keys</dt>
@@ -44,11 +60,11 @@ export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBea
  *             </dd>
  *             <dt>HMAC KMS key</dt>
  *             <dd>
- *                <p>To create an HMAC KMS key, set the <code>KeySpec</code> parameter to a
- *           key spec value for HMAC KMS keys. Then set the <code>KeyUsage</code> parameter to
- *           <code>GENERATE_VERIFY_MAC</code>. You must set the key usage even though
- *           <code>GENERATE_VERIFY_MAC</code> is the only valid key usage value for HMAC KMS keys.
- *           You can't change these properties after the KMS key is created.</p>
+ *                <p>To create an HMAC KMS key, set the <code>KeySpec</code> parameter to a key spec
+ *             value for HMAC KMS keys. Then set the <code>KeyUsage</code> parameter to
+ *               <code>GENERATE_VERIFY_MAC</code>. You must set the key usage even though
+ *               <code>GENERATE_VERIFY_MAC</code> is the only valid key usage value for HMAC KMS keys.
+ *             You can't change these properties after the KMS key is created.</p>
  *                <p>HMAC KMS keys are symmetric keys that never leave KMS unencrypted. You can use
  *             HMAC keys to generate (<a>GenerateMac</a>) and verify (<a>VerifyMac</a>) HMAC codes for messages up to 4096 bytes.</p>
  *                <p>HMAC KMS keys are not supported in all Amazon Web Services Regions. If you try to create an HMAC
@@ -79,34 +95,59 @@ export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBea
  *                <p> </p>
  *             </dd>
  *             <dd>
- *                <p>To import your own key material, begin by creating a symmetric encryption 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, and use the 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>
+ *                <p>To import your own key material into a KMS key, begin by creating a symmetric
+ *             encryption 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, and use the 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>This feature supports only symmetric encryption KMS keys, including multi-Region symmetric encryption KMS keys. You cannot import key
- *             material into any other type of KMS key.</p>
+ *                <p>This feature supports only symmetric encryption KMS keys, including multi-Region
+ *             symmetric encryption KMS keys. You cannot import key material into any other type of KMS
+ *             key.</p>
  *                <p>To create a multi-Region primary key with imported key material, use the
  *               <code>Origin</code> parameter of <code>CreateKey</code> with a value of
  *               <code>EXTERNAL</code> and the <code>MultiRegion</code> parameter with a value of
- *               <code>True</code>. To create replicas of the multi-Region primary key, use the <a>ReplicateKey</a> operation. For more information about multi-Region keys, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html">Multi-Region keys in KMS</a> in the <i>Key Management Service Developer Guide</i>.</p>
+ *               <code>True</code>. To create replicas of the multi-Region primary key, use the <a>ReplicateKey</a> operation. For instructions, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-import.html ">Importing key material into
+ *               multi-Region keys</a>. For more information about multi-Region keys, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html">Multi-Region keys in KMS</a> in the <i>Key Management Service Developer Guide</i>.</p>
  *                <p> </p>
  *             </dd>
  *             <dt>Custom key store</dt>
  *             <dd>
- *                <p>To create a symmetric encryption KMS key in a <a href="https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html">custom key store</a>, use the
- *               <code>CustomKeyStoreId</code> parameter to specify the custom key store. You must also
- *             use the <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>Custom key stores support only symmetric encryption KMS keys. You cannot create an
- *             HMAC KMS key or an asymmetric KMS key in a custom key store. For information about
- *             custom key stores in KMS see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html">Custom key stores in KMS</a> in
- *             the <i>
- *                      <i>Key Management Service Developer Guide</i>
- *                   </i>.</p>
+ *                <p>A <a href="https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html">custom key store</a> lets you protect your Amazon Web Services resources using keys in a backing key
+ *             store that you own and manage. When you request a cryptographic operation with a KMS key
+ *             in a custom key store, the operation is performed in the backing key store using its
+ *             cryptographic keys.</p>
+ *                <p>KMS supports <a href="https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html">CloudHSM key stores</a> backed by an CloudHSM cluster and <a href="https://docs.aws.amazon.com/kms/latest/developerguide/keystore-external.html">external key stores</a> backed by an
+ *             external key manager outside of Amazon Web Services. When you create a KMS key in an CloudHSM key store,
+ *             KMS generates an encryption key in the CloudHSM cluster and associates it with the KMS
+ *             key. When you create a KMS key in an external key store, you specify an existing
+ *             encryption key in the external key manager.</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>
+ *                </note>
+ *                <p>Before you create a KMS key in a custom key store, the <code>ConnectionState</code>
+ *             of the key store must be <code>CONNECTED</code>. To connect the custom key store, use
+ *             the <a>ConnectCustomKeyStore</a> operation. To find the
+ *               <code>ConnectionState</code>, use the <a>DescribeCustomKeyStores</a>
+ *             operation.</p>
+ *                <p>To create a KMS key in a custom key store, use the <code>CustomKeyStoreId</code>.
+ *             Use the default <code>KeySpec</code> value, <code>SYMMETRIC_DEFAULT</code>, and the
+ *             default <code>KeyUsage</code> value, <code>ENCRYPT_DECRYPT</code> to create a symmetric
+ *             encryption key. No other key type is supported in a custom key store.</p>
+ *                <p>To create a KMS key in an <a href="https://docs.aws.amazon.com/kms/latest/developerguide/keystore-cloudhsm.html">CloudHSM key store</a>, use the
+ *               <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>
+ *                <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>
+ *                </note>
  *             </dd>
  *          </dl>
  *          <p>

package/dist-types/commands/DecryptCommand.d.ts CHANGED Viewed

@@ -37,22 +37,22 @@ export interface DecryptCommandOutput extends DecryptResponse, __MetadataBearer
  *                </p>
  *             </li>
  *          </ul>
- *          <p>You can use this operation to decrypt ciphertext that was encrypted under a symmetric encryption KMS key or an
- *       asymmetric encryption KMS key. When the KMS key is asymmetric, you must specify the KMS key and the
- *       encryption algorithm that was used to encrypt the ciphertext. 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>The <code>Decrypt</code> operation also decrypts ciphertext that was encrypted outside of KMS by the
- *       public key in an KMS asymmetric KMS key. However, it cannot decrypt ciphertext produced by
- *       other libraries, such as the <a href="https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/">Amazon Web Services
- *         Encryption SDK</a> or <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingClientSideEncryption.html">Amazon S3 client-side encryption</a>.
+ *          <p>You can use this operation to decrypt ciphertext that was encrypted under a symmetric
+ *       encryption KMS key or an asymmetric encryption KMS key. When the KMS key is asymmetric, you
+ *       must specify the KMS key and the encryption algorithm that was used to encrypt the ciphertext.
+ *       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>The <code>Decrypt</code> operation also decrypts ciphertext that was encrypted outside of
+ *       KMS by the public key in an KMS asymmetric KMS key. However, it cannot decrypt symmetric
+ *       ciphertext produced by other libraries, such as the <a href="https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/">Amazon Web Services Encryption SDK</a> or <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingClientSideEncryption.html">Amazon S3 client-side encryption</a>.
  *       These libraries return a ciphertext format that is incompatible with KMS.</p>
- *          <p>If the ciphertext was encrypted under a symmetric encryption KMS key, the <code>KeyId</code>
- *       parameter is optional. KMS can get this information from metadata that it adds to the
- *       symmetric ciphertext blob. This feature adds durability to your implementation by ensuring
- *       that authorized users can decrypt ciphertext decades after it was encrypted, even if they've
- *       lost track of the key ID. However, specifying the KMS key is always recommended as a best
- *       practice. When you use the <code>KeyId</code> parameter to specify a KMS key, KMS only uses
- *       the KMS key you specify. If the ciphertext was encrypted under a different KMS key, the
- *         <code>Decrypt</code> operation fails. This practice ensures that you use the KMS key that
+ *          <p>If the ciphertext was encrypted under a symmetric encryption KMS key, the
+ *         <code>KeyId</code> parameter is optional. KMS can get this information from metadata that
+ *       it adds to the symmetric ciphertext blob. This feature adds durability to your implementation
+ *       by ensuring that authorized users can decrypt ciphertext decades after it was encrypted, even
+ *       if they've lost track of the key ID. However, specifying the KMS key is always recommended as
+ *       a best practice. When you use the <code>KeyId</code> parameter to specify a KMS key, KMS
+ *       only uses the KMS key you specify. If the ciphertext was encrypted under a different KMS key,
+ *       the <code>Decrypt</code> operation fails. This practice ensures that you use the KMS key that
  *       you intend.</p>
  *          <p>Whenever possible, use key policies to give users permission to call the
  *         <code>Decrypt</code> operation on a particular KMS key, instead of using IAM policies.
@@ -66,8 +66,7 @@ export interface DecryptCommandOutput extends DecryptResponse, __MetadataBearer
  *          <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>
- *             <b>Cross-account
- *         use</b>: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify
+ *             <b>Cross-account use</b>: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify
  *   the key ARN or alias ARN in the value of the <code>KeyId</code> parameter. </p>
  *
  *          <p>

package/dist-types/commands/DeleteAliasCommand.d.ts CHANGED Viewed

@@ -10,7 +10,7 @@ export interface DeleteAliasCommandOutput extends __MetadataBearer {
 /**
  * <p>Deletes the specified alias. </p>
  *          <note>
- *             <p>Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/abac.html">ABAC in KMS</a> in the <i>Key Management Service Developer Guide</i>.</p>
+ *             <p>Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/abac.html">ABAC for KMS</a> in the <i>Key Management Service Developer Guide</i>.</p>
  *          </note>
  *          <p>Because an alias is not a property of a KMS key, you can delete and change the aliases of
  *       a KMS key without affecting the KMS key. Also, aliases do not appear in the response from the

package/dist-types/commands/DeleteCustomKeyStoreCommand.d.ts CHANGED Viewed

@@ -8,28 +8,33 @@ export interface DeleteCustomKeyStoreCommandInput extends DeleteCustomKeyStoreRe
 export interface DeleteCustomKeyStoreCommandOutput extends DeleteCustomKeyStoreResponse, __MetadataBearer {
 }
 /**
- * <p>Deletes a <a href="https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html">custom key store</a>. This operation does not delete the CloudHSM cluster that is
- *       associated with the custom key store, or affect any users or keys in the cluster.</p>
+ * <p>Deletes a <a href="https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html">custom key store</a>. This operation does not affect any backing elements of the
+ *       custom key store. It does not delete the CloudHSM cluster that is associated with an CloudHSM key
+ *       store, or affect any users or keys in the cluster. For an external key store, it does not
+ *       affect the external key store proxy, external key manager, or any external keys.</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>
  *          <p>The custom key store that you delete cannot contain any <a href="https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys">KMS keys</a>. Before deleting the key store,
  *       verify that you will never need to use any of the KMS keys in the key store for any
  *       <a href="https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#cryptographic-operations">cryptographic operations</a>. Then, use <a>ScheduleKeyDeletion</a> to delete the KMS keys from the
- *       key store. When the scheduled waiting period expires, the <code>ScheduleKeyDeletion</code>
- *       operation deletes the KMS keys. Then it makes a best effort to delete the key material from
- *       the associated cluster. However, you might need to manually <a href="https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html#fix-keystore-orphaned-key">delete the orphaned key
- *         material</a> from the cluster and its backups.</p>
- *          <p>After all KMS keys are deleted from KMS, use <a>DisconnectCustomKeyStore</a>
- *       to disconnect the key store from KMS. Then, you can delete the custom key store.</p>
- *          <p>Instead of deleting the custom key store, consider using <a>DisconnectCustomKeyStore</a> to disconnect it from KMS. While the key store is
- *       disconnected, you cannot create or use the KMS keys in the key store. But, you do not need to
- *       delete KMS keys and you can reconnect a disconnected custom key store at any time.</p>
+ *       key store. After the required waiting period expires and all KMS keys are deleted from the
+ *       custom key store, use <a>DisconnectCustomKeyStore</a> to disconnect the key store
+ *       from KMS. Then, you can delete the custom key store.</p>
+ *          <p>For keys in an CloudHSM key store, the <code>ScheduleKeyDeletion</code> operation makes a
+ *       best effort to delete the key material from the associated cluster. However, you might need to
+ *       manually <a href="https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html#fix-keystore-orphaned-key">delete the orphaned key
+ *         material</a> from the cluster and its backups. KMS never creates, manages, or deletes
+ *       cryptographic keys in the external key manager associated with an external key store. You must
+ *       manage them using your external key manager tools.</p>
+ *          <p>Instead of deleting the custom key store, consider using the <a>DisconnectCustomKeyStore</a> operation to disconnect the custom key store from its
+ *       backing key store. While the key store is disconnected, you cannot create or use the KMS keys
+ *       in the key store. But, you do not need to delete KMS keys and you can reconnect a disconnected
+ *       custom key store at any time.</p>
  *          <p>If the operation succeeds, it returns a JSON object with no
  * properties.</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 store feature</a> feature in KMS, which
- * combines the convenience and extensive integration of KMS with the isolation and control of a
- * single-tenant key store.</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>
+ *             <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>
  *             <b>Required permissions</b>: <a href="https://docs.aws.amazon.com/kms/latest/developerguide/kms-api-permissions-reference.html">kms:DeleteCustomKeyStore</a> (IAM policy)</p>

package/dist-types/commands/DescribeCustomKeyStoresCommand.d.ts CHANGED Viewed

@@ -9,25 +9,30 @@ export interface DescribeCustomKeyStoresCommandOutput extends DescribeCustomKeyS
 }
 /**
  * <p>Gets information about <a href="https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html">custom key stores</a> in the account and Region.</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 store feature</a> feature in KMS, which
+ *          <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
- * single-tenant key store.</p>
- *          <p>By default, this operation returns information about all custom key
- *       stores in the account and Region. To get only information about a particular custom key store,
- *       use either the <code>CustomKeyStoreName</code> or <code>CustomKeyStoreId</code> parameter (but
- *       not both).</p>
- *          <p>To determine whether the custom key store is connected to its CloudHSM cluster, use the
- *         <code>ConnectionState</code> element in the response. If an attempt to connect the custom
- *       key store failed, the <code>ConnectionState</code> value is <code>FAILED</code> and the
- *         <code>ConnectionErrorCode</code> element in the response indicates the cause of the failure.
- *       For help interpreting the <code>ConnectionErrorCode</code>, see <a>CustomKeyStoresListEntry</a>.</p>
+ * key store that you own and manage.</p>
+ *          <p>By default, this operation returns information about all custom key stores in the account
+ *       and Region. To get only information about a particular custom key store, use either the
+ *         <code>CustomKeyStoreName</code> or <code>CustomKeyStoreId</code> parameter (but not
+ *       both).</p>
+ *          <p>To determine whether the custom key store is connected to its CloudHSM cluster or external
+ *       key store proxy, use the <code>ConnectionState</code> element in the response. If an attempt
+ *       to connect the custom key store failed, the <code>ConnectionState</code> value is
+ *         <code>FAILED</code> and the <code>ConnectionErrorCode</code> element in the response
+ *       indicates the cause of the failure. For help interpreting the
+ *       <code>ConnectionErrorCode</code>, see <a>CustomKeyStoresListEntry</a>.</p>
  *          <p>Custom key stores have a <code>DISCONNECTED</code> connection state if the key store has
- *       never been connected or you use the <a>DisconnectCustomKeyStore</a> operation to
- *       disconnect it. If your custom key store state is <code>CONNECTED</code> but you are having
- *       trouble using it, make sure that its associated CloudHSM cluster is active and contains the
- *       minimum number of HSMs required for the operation, if any.</p>
- *          <p> For help repairing your custom key store, see the <a href="https://docs.aws.amazon.com/kms/latest/developerguide/fix-keystore.html">Troubleshooting Custom Key Stores</a> topic in the
- *       <i>Key Management Service Developer Guide</i>.</p>
+ *       never been connected or you used the <a>DisconnectCustomKeyStore</a> operation to
+ *       disconnect it. Otherwise, the connection state is CONNECTED. If your custom key store
+ *       connection state is <code>CONNECTED</code> but you are having trouble using it, verify that
+ *       the backing store is active and available. For an CloudHSM key store, verify that the associated
+ *       CloudHSM cluster is active and contains the minimum number of HSMs required for the operation, if
+ *       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>
  *          <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>