@aws-sdk/client-kms 3.288.0 → 3.289.0

package/dist-types/commands/UpdateCustomKeyStoreCommand.d.ts

@@ -121,6 +121,83 @@ export interface UpdateCustomKeyStoreCommandOutput extends UpdateCustomKeyStoreR
  * @see {@link UpdateCustomKeyStoreCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To edit the friendly name of a custom key store
+ * ```javascript
+ * // This example changes the friendly name of the AWS KMS custom key store to the name that you specify. This operation does not return any data. To verify that the operation worked, use the DescribeCustomKeyStores operation.
+ * const input = {
+ *   "CustomKeyStoreId": "cks-1234567890abcdef0",
+ *   "NewCustomKeyStoreName": "DevelopmentKeys"
+ * };
+ * const command = new UpdateCustomKeyStoreCommand(input);
+ * await client.send(command);
+ * // example id: to-edit-the-friendly-name-of-a-custom-key-store-1
+ * ```
+ *
+ * @example To edit the password of an AWS CloudHSM key store
+ * ```javascript
+ * // This example tells AWS KMS the password for the kmsuser crypto user in the AWS CloudHSM cluster that is associated with the AWS KMS custom key store. (It does not change the password in the CloudHSM cluster.) This operation does not return any data.
+ * const input = {
+ *   "CustomKeyStoreId": "cks-1234567890abcdef0",
+ *   "KeyStorePassword": "ExamplePassword"
+ * };
+ * const command = new UpdateCustomKeyStoreCommand(input);
+ * await client.send(command);
+ * // example id: to-edit-the-properties-of-an-aws-cloudhsm-key-store-2
+ * ```
+ *
+ * @example To associate the custom key store with a different, but related, AWS CloudHSM cluster.
+ * ```javascript
+ * // This example changes the AWS CloudHSM cluster that is associated with an AWS CloudHSM key store to a related cluster, such as a different backup of the same cluster. This operation does not return any data. To verify that the operation worked, use the DescribeCustomKeyStores operation.
+ * const input = {
+ *   "CloudHsmClusterId": "cluster-1a23b4cdefg",
+ *   "CustomKeyStoreId": "cks-1234567890abcdef0"
+ * };
+ * const command = new UpdateCustomKeyStoreCommand(input);
+ * await client.send(command);
+ * // example id: to-associate-the-custom-key-store-with-a-different-but-related-aws-cloudhsm-cluster-3
+ * ```
+ *
+ * @example To update the proxy authentication credential of an external key store
+ * ```javascript
+ * // To update the proxy authentication credential for your external key store, specify both the <code>RawSecretAccessKey</code> and the <code>AccessKeyId</code>, even if you are changing only one of the values. You can use this feature to fix an invalid credential or to change the credential when the external key store proxy rotates it.
+ * const input = {
+ *   "CustomKeyStoreId": "cks-1234567890abcdef0",
+ *   "XksProxyAuthenticationCredential": {
+ *     "AccessKeyId": "ABCDE12345670EXAMPLE",
+ *     "RawSecretAccessKey": "DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo="
+ *   }
+ * };
+ * const command = new UpdateCustomKeyStoreCommand(input);
+ * await client.send(command);
+ * // example id: to-update-the-proxy-authentication-credential-of-an-external-key-store-4
+ * ```
+ *
+ * @example To edit the proxy URI path of an external key store.
+ * ```javascript
+ * // This example updates the proxy URI path for an external key store
+ * const input = {
+ *   "CustomKeyStoreId": "cks-1234567890abcdef0",
+ *   "XksProxyUriPath": "/new-path/kms/xks/v1"
+ * };
+ * const command = new UpdateCustomKeyStoreCommand(input);
+ * await client.send(command);
+ * // example id: to-update-the-xks-proxy-api-path-of-an-external-key-store-5
+ * ```
+ *
+ * @example To update the proxy connectivity of an external key store to VPC_ENDPOINT_SERVICE
+ * ```javascript
+ * // To change the external key store proxy connectivity option from public endpoint connectivity to VPC endpoint service connectivity, in addition to changing the <code>XksProxyConnectivity</code> value, you must change the <code>XksProxyUriEndpoint</code> value to reflect the private DNS name associated with the VPC endpoint service. You must also add an <code>XksProxyVpcEndpointServiceName</code> value.
+ * const input = {
+ *   "CustomKeyStoreId": "cks-1234567890abcdef0",
+ *   "XksProxyConnectivity": "VPC_ENDPOINT_SERVICE",
+ *   "XksProxyUriEndpoint": "https://myproxy-private.xks.example.com",
+ *   "XksProxyVpcEndpointServiceName": "com.amazonaws.vpce.us-east-1.vpce-svc-example"
+ * };
+ * const command = new UpdateCustomKeyStoreCommand(input);
+ * await client.send(command);
+ * // example id: to-update-the-proxy-connectivity-of-an-external-key-store-to-vpc_endpoint_service-6
+ * ```
+ *
  */
 export declare class UpdateCustomKeyStoreCommand extends $Command<UpdateCustomKeyStoreCommandInput, UpdateCustomKeyStoreCommandOutput, KMSClientResolvedConfig> {
     readonly input: UpdateCustomKeyStoreCommandInput;

package/dist-types/commands/UpdateKeyDescriptionCommand.d.ts

@@ -50,6 +50,18 @@ export interface UpdateKeyDescriptionCommandOutput extends __MetadataBearer {
  * @see {@link UpdateKeyDescriptionCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To update the description of a KMS key
+ * ```javascript
+ * // The following example updates the description of the specified KMS key.
+ * const input = {
+ *   "Description": "Example description that indicates the intended use of this KMS key.",
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
+ * };
+ * const command = new UpdateKeyDescriptionCommand(input);
+ * await client.send(command);
+ * // example id: to-update-the-description-of-a-cmk-1481574808619
+ * ```
+ *
  */
 export declare class UpdateKeyDescriptionCommand extends $Command<UpdateKeyDescriptionCommandInput, UpdateKeyDescriptionCommandOutput, KMSClientResolvedConfig> {
     readonly input: UpdateKeyDescriptionCommandInput;

package/dist-types/commands/UpdatePrimaryRegionCommand.d.ts

@@ -93,6 +93,22 @@ export interface UpdatePrimaryRegionCommandOutput extends __MetadataBearer {
  * @see {@link UpdatePrimaryRegionCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To update the primary Region of a multi-Region KMS key
+ * ```javascript
+ * // The following UpdatePrimaryRegion example changes the multi-Region replica key in the eu-central-1 Region to the primary key. The current primary key in the us-west-1 Region becomes a replica key.
+ * //
+ * // The KeyId parameter identifies the current primary key in the us-west-1 Region. The PrimaryRegion parameter indicates the Region of the replica key that will become the new primary key.
+ * //
+ * // This operation does not return any output. To verify that primary key is changed, use the DescribeKey operation.
+ * const input = {
+ *   "KeyId": "arn:aws:kms:us-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
+ *   "PrimaryRegion": "eu-central-1"
+ * };
+ * const command = new UpdatePrimaryRegionCommand(input);
+ * await client.send(command);
+ * // example id: to-update-the-primary-region-of-a-multi-region-kms-key-1660249555577
+ * ```
+ *
  */
 export declare class UpdatePrimaryRegionCommand extends $Command<UpdatePrimaryRegionCommandInput, UpdatePrimaryRegionCommandOutput, KMSClientResolvedConfig> {
     readonly input: UpdatePrimaryRegionCommandInput;

package/dist-types/commands/VerifyCommand.d.ts

@@ -64,6 +64,50 @@ export interface VerifyCommandOutput extends VerifyResponse, __MetadataBearer {
  * @see {@link VerifyCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To use an asymmetric KMS key to verify a digital signature
+ * ```javascript
+ * // This operation uses the public key in an elliptic curve (ECC) asymmetric key to verify a digital signature within AWS KMS.
+ * const input = {
+ *   "KeyId": "alias/ECC_signing_key",
+ *   "Message": "<message to be verified>",
+ *   "MessageType": "RAW",
+ *   "Signature": "<binary data>",
+ *   "SigningAlgorithm": "ECDSA_SHA_384"
+ * };
+ * const command = new VerifyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "SignatureValid": true,
+ *   "SigningAlgorithm": "ECDSA_SHA_384"
+ * }
+ * *\/
+ * // example id: to-use-an-asymmetric-kms-key-to-verify-a-digital-signature-1
+ * ```
+ *
+ * @example To use an asymmetric KMS key to verify a digital signature on a message digest
+ * ```javascript
+ * // This operation uses the public key in an RSA asymmetric signing key pair to verify the digital signature of a message digest. Hashing a message into a digest before sending it to KMS lets you verify messages that exceed the 4096-byte message size limit. To indicate that the value of Message is a digest, use the MessageType parameter
+ * const input = {
+ *   "KeyId": "arn:aws:kms:us-east-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
+ *   "Message": "<message digest to be verified>",
+ *   "MessageType": "DIGEST",
+ *   "Signature": "<binary data>",
+ *   "SigningAlgorithm": "RSASSA_PSS_SHA_512"
+ * };
+ * const command = new VerifyCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyId": "arn:aws:kms:us-east-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
+ *   "SignatureValid": true,
+ *   "SigningAlgorithm": "RSASSA_PSS_SHA_512"
+ * }
+ * *\/
+ * // example id: to-use-an-asymmetric-kms-key-to-verify-a-digital-signature-on-a-message-digest-2
+ * ```
+ *
  */
 export declare class VerifyCommand extends $Command<VerifyCommandInput, VerifyCommandOutput, KMSClientResolvedConfig> {
     readonly input: VerifyCommandInput;

package/dist-types/commands/VerifyMacCommand.d.ts

@@ -49,6 +49,27 @@ export interface VerifyMacCommandOutput extends VerifyMacResponse, __MetadataBea
  * @see {@link VerifyMacCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @example To verify an HMAC
+ * ```javascript
+ * // This example verifies an HMAC for a particular message, HMAC KMS keys, and MAC algorithm. A value of 'true' in the MacValid value in the response indicates that the HMAC is valid.
+ * const input = {
+ *   "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "Mac": "<HMAC_TAG>",
+ *   "MacAlgorithm": "HMAC_SHA_384",
+ *   "Message": "Hello World"
+ * };
+ * const command = new VerifyMacCommand(input);
+ * const response = await client.send(command);
+ * /* response ==
+ * {
+ *   "KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
+ *   "MacAlgorithm": "HMAC_SHA_384",
+ *   "MacValid": true
+ * }
+ * *\/
+ * // example id: to-verify-an-hmac-1631570863401
+ * ```
+ *
  */
 export declare class VerifyMacCommand extends $Command<VerifyMacCommandInput, VerifyMacCommandOutput, KMSClientResolvedConfig> {
     readonly input: VerifyMacCommandInput;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aws-sdk/client-kms",
   "description": "AWS SDK for JavaScript Kms Client for Node.js, Browser and React Native",
-  "version": "3.288.0",
+  "version": "3.289.0",
   "scripts": {
     "build": "concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types'",
     "build:cjs": "tsc -p tsconfig.cjs.json",
@@ -20,37 +20,37 @@
   "dependencies": {
     "@aws-crypto/sha256-browser": "3.0.0",
     "@aws-crypto/sha256-js": "3.0.0",
-    "@aws-sdk/client-sts": "3.288.0",
-    "@aws-sdk/config-resolver": "3.287.0",
-    "@aws-sdk/credential-provider-node": "3.288.0",
-    "@aws-sdk/fetch-http-handler": "3.282.0",
-    "@aws-sdk/hash-node": "3.272.0",
-    "@aws-sdk/invalid-dependency": "3.272.0",
-    "@aws-sdk/middleware-content-length": "3.282.0",
-    "@aws-sdk/middleware-endpoint": "3.282.0",
-    "@aws-sdk/middleware-host-header": "3.282.0",
-    "@aws-sdk/middleware-logger": "3.288.0",
-    "@aws-sdk/middleware-recursion-detection": "3.282.0",
-    "@aws-sdk/middleware-retry": "3.287.0",
-    "@aws-sdk/middleware-serde": "3.272.0",
-    "@aws-sdk/middleware-signing": "3.282.0",
-    "@aws-sdk/middleware-stack": "3.272.0",
-    "@aws-sdk/middleware-user-agent": "3.282.0",
-    "@aws-sdk/node-config-provider": "3.287.0",
-    "@aws-sdk/node-http-handler": "3.282.0",
-    "@aws-sdk/protocol-http": "3.282.0",
-    "@aws-sdk/smithy-client": "3.279.0",
-    "@aws-sdk/types": "3.272.0",
-    "@aws-sdk/url-parser": "3.272.0",
+    "@aws-sdk/client-sts": "3.289.0",
+    "@aws-sdk/config-resolver": "3.289.0",
+    "@aws-sdk/credential-provider-node": "3.289.0",
+    "@aws-sdk/fetch-http-handler": "3.289.0",
+    "@aws-sdk/hash-node": "3.289.0",
+    "@aws-sdk/invalid-dependency": "3.289.0",
+    "@aws-sdk/middleware-content-length": "3.289.0",
+    "@aws-sdk/middleware-endpoint": "3.289.0",
+    "@aws-sdk/middleware-host-header": "3.289.0",
+    "@aws-sdk/middleware-logger": "3.289.0",
+    "@aws-sdk/middleware-recursion-detection": "3.289.0",
+    "@aws-sdk/middleware-retry": "3.289.0",
+    "@aws-sdk/middleware-serde": "3.289.0",
+    "@aws-sdk/middleware-signing": "3.289.0",
+    "@aws-sdk/middleware-stack": "3.289.0",
+    "@aws-sdk/middleware-user-agent": "3.289.0",
+    "@aws-sdk/node-config-provider": "3.289.0",
+    "@aws-sdk/node-http-handler": "3.289.0",
+    "@aws-sdk/protocol-http": "3.289.0",
+    "@aws-sdk/smithy-client": "3.289.0",
+    "@aws-sdk/types": "3.289.0",
+    "@aws-sdk/url-parser": "3.289.0",
     "@aws-sdk/util-base64": "3.208.0",
     "@aws-sdk/util-body-length-browser": "3.188.0",
     "@aws-sdk/util-body-length-node": "3.208.0",
-    "@aws-sdk/util-defaults-mode-browser": "3.279.0",
-    "@aws-sdk/util-defaults-mode-node": "3.287.0",
-    "@aws-sdk/util-endpoints": "3.272.0",
-    "@aws-sdk/util-retry": "3.272.0",
-    "@aws-sdk/util-user-agent-browser": "3.282.0",
-    "@aws-sdk/util-user-agent-node": "3.287.0",
+    "@aws-sdk/util-defaults-mode-browser": "3.289.0",
+    "@aws-sdk/util-defaults-mode-node": "3.289.0",
+    "@aws-sdk/util-endpoints": "3.289.0",
+    "@aws-sdk/util-retry": "3.289.0",
+    "@aws-sdk/util-user-agent-browser": "3.289.0",
+    "@aws-sdk/util-user-agent-node": "3.289.0",
     "@aws-sdk/util-utf8": "3.254.0",
     "tslib": "^2.3.1"
   },