@aws-sdk/client-kms 3.288.0 → 3.290.0

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

@@ -93,6 +93,60 @@ export interface UpdatePrimaryRegionCommandOutput extends __MetadataBearer {
  * @see {@link UpdatePrimaryRegionCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @throws {@link DisabledException} (client fault)
+ *  <p>The request was rejected because the specified KMS key is not enabled.</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>
+ *
+ * @throws {@link KMSInternalException} (server fault)
+ *  <p>The request was rejected because an internal exception occurred. The request can be
+ *       retried.</p>
+ *
+ * @throws {@link KMSInvalidStateException} (client fault)
+ *  <p>The request was rejected because the state of the specified resource is not valid for this
+ *       request.</p>
+ *          <p>This exceptions means one of the following:</p>
+ *          <ul>
+ *             <li>
+ *                <p>The key state of the KMS key is not compatible with the operation. </p>
+ *                <p>To find the key state, use the <a>DescribeKey</a> operation. For more
+ *           information about which key states are compatible with each KMS operation, see
+ *           <a href="https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html">Key states of KMS keys</a> in the <i>
+ *                      <i>Key Management Service Developer Guide</i>
+ *                   </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>
+ *             </li>
+ *          </ul>
+ *
+ * @throws {@link NotFoundException} (client fault)
+ *  <p>The request was rejected because the specified entity or resource could not be
+ *       found.</p>
+ *
+ * @throws {@link UnsupportedOperationException} (client fault)
+ *  <p>The request was rejected because a specified parameter is not supported or a specified
+ *       resource is not valid for this operation.</p>
+ *
+ *
+ * @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,117 @@ export interface VerifyCommandOutput extends VerifyResponse, __MetadataBearer {
  * @see {@link VerifyCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @throws {@link DependencyTimeoutException} (server fault)
+ *  <p>The system timed out while trying to fulfill the request. You can retry the
+ *       request.</p>
+ *
+ * @throws {@link DisabledException} (client fault)
+ *  <p>The request was rejected because the specified KMS key is not enabled.</p>
+ *
+ * @throws {@link InvalidGrantTokenException} (client fault)
+ *  <p>The request was rejected because the specified grant token is not valid.</p>
+ *
+ * @throws {@link InvalidKeyUsageException} (client fault)
+ *  <p>The request was rejected for one of the following reasons: </p>
+ *          <ul>
+ *             <li>
+ *                <p>The <code>KeyUsage</code> value of the KMS key is incompatible with the API
+ *           operation.</p>
+ *             </li>
+ *             <li>
+ *                <p>The encryption algorithm or signing algorithm specified for the operation is
+ *           incompatible with the type of key material in the KMS key <code>(KeySpec</code>).</p>
+ *             </li>
+ *          </ul>
+ *          <p>For encrypting, decrypting, re-encrypting, and generating data keys, the
+ *         <code>KeyUsage</code> must be <code>ENCRYPT_DECRYPT</code>. For signing and verifying
+ *       messages, the <code>KeyUsage</code> must be <code>SIGN_VERIFY</code>. For generating and
+ *       verifying message authentication codes (MACs), the <code>KeyUsage</code> must be
+ *         <code>GENERATE_VERIFY_MAC</code>. To find the <code>KeyUsage</code> of a KMS key, use the
+ *         <a>DescribeKey</a> operation.</p>
+ *          <p>To find the encryption or signing algorithms supported for a particular KMS key, use the
+ *         <a>DescribeKey</a> operation.</p>
+ *
+ * @throws {@link KeyUnavailableException} (server fault)
+ *  <p>The request was rejected because the specified KMS key was not available. You can retry
+ *       the request.</p>
+ *
+ * @throws {@link KMSInternalException} (server fault)
+ *  <p>The request was rejected because an internal exception occurred. The request can be
+ *       retried.</p>
+ *
+ * @throws {@link KMSInvalidSignatureException} (client fault)
+ *  <p>The request was rejected because the signature verification failed. Signature verification
+ *       fails when it cannot confirm that signature was produced by signing the specified message with
+ *       the specified KMS key and signing algorithm.</p>
+ *
+ * @throws {@link KMSInvalidStateException} (client fault)
+ *  <p>The request was rejected because the state of the specified resource is not valid for this
+ *       request.</p>
+ *          <p>This exceptions means one of the following:</p>
+ *          <ul>
+ *             <li>
+ *                <p>The key state of the KMS key is not compatible with the operation. </p>
+ *                <p>To find the key state, use the <a>DescribeKey</a> operation. For more
+ *           information about which key states are compatible with each KMS operation, see
+ *           <a href="https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html">Key states of KMS keys</a> in the <i>
+ *                      <i>Key Management Service Developer Guide</i>
+ *                   </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>
+ *             </li>
+ *          </ul>
+ *
+ * @throws {@link NotFoundException} (client fault)
+ *  <p>The request was rejected because the specified entity or resource could not be
+ *       found.</p>
+ *
+ *
+ * @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,90 @@ export interface VerifyMacCommandOutput extends VerifyMacResponse, __MetadataBea
  * @see {@link VerifyMacCommandOutput} for command's `response` shape.
  * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape.
  *
+ * @throws {@link DisabledException} (client fault)
+ *  <p>The request was rejected because the specified KMS key is not enabled.</p>
+ *
+ * @throws {@link InvalidGrantTokenException} (client fault)
+ *  <p>The request was rejected because the specified grant token is not valid.</p>
+ *
+ * @throws {@link InvalidKeyUsageException} (client fault)
+ *  <p>The request was rejected for one of the following reasons: </p>
+ *          <ul>
+ *             <li>
+ *                <p>The <code>KeyUsage</code> value of the KMS key is incompatible with the API
+ *           operation.</p>
+ *             </li>
+ *             <li>
+ *                <p>The encryption algorithm or signing algorithm specified for the operation is
+ *           incompatible with the type of key material in the KMS key <code>(KeySpec</code>).</p>
+ *             </li>
+ *          </ul>
+ *          <p>For encrypting, decrypting, re-encrypting, and generating data keys, the
+ *         <code>KeyUsage</code> must be <code>ENCRYPT_DECRYPT</code>. For signing and verifying
+ *       messages, the <code>KeyUsage</code> must be <code>SIGN_VERIFY</code>. For generating and
+ *       verifying message authentication codes (MACs), the <code>KeyUsage</code> must be
+ *         <code>GENERATE_VERIFY_MAC</code>. To find the <code>KeyUsage</code> of a KMS key, use the
+ *         <a>DescribeKey</a> operation.</p>
+ *          <p>To find the encryption or signing algorithms supported for a particular KMS key, use the
+ *         <a>DescribeKey</a> operation.</p>
+ *
+ * @throws {@link KeyUnavailableException} (server fault)
+ *  <p>The request was rejected because the specified KMS key was not available. You can retry
+ *       the request.</p>
+ *
+ * @throws {@link KMSInternalException} (server fault)
+ *  <p>The request was rejected because an internal exception occurred. The request can be
+ *       retried.</p>
+ *
+ * @throws {@link KMSInvalidMacException} (client fault)
+ *  <p>The request was rejected because the HMAC verification failed. HMAC verification fails
+ *       when the HMAC computed by using the specified message, HMAC KMS key, and MAC algorithm does
+ *       not match the HMAC specified in the request.</p>
+ *
+ * @throws {@link KMSInvalidStateException} (client fault)
+ *  <p>The request was rejected because the state of the specified resource is not valid for this
+ *       request.</p>
+ *          <p>This exceptions means one of the following:</p>
+ *          <ul>
+ *             <li>
+ *                <p>The key state of the KMS key is not compatible with the operation. </p>
+ *                <p>To find the key state, use the <a>DescribeKey</a> operation. For more
+ *           information about which key states are compatible with each KMS operation, see
+ *           <a href="https://docs.aws.amazon.com/kms/latest/developerguide/key-state.html">Key states of KMS keys</a> in the <i>
+ *                      <i>Key Management Service Developer Guide</i>
+ *                   </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>
+ *             </li>
+ *          </ul>
+ *
+ * @throws {@link NotFoundException} (client fault)
+ *  <p>The request was rejected because the specified entity or resource could not be
+ *       found.</p>
+ *
+ *
+ * @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.290.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.290.0",
+    "@aws-sdk/config-resolver": "3.290.0",
+    "@aws-sdk/credential-provider-node": "3.290.0",
+    "@aws-sdk/fetch-http-handler": "3.290.0",
+    "@aws-sdk/hash-node": "3.290.0",
+    "@aws-sdk/invalid-dependency": "3.290.0",
+    "@aws-sdk/middleware-content-length": "3.290.0",
+    "@aws-sdk/middleware-endpoint": "3.290.0",
+    "@aws-sdk/middleware-host-header": "3.290.0",
+    "@aws-sdk/middleware-logger": "3.290.0",
+    "@aws-sdk/middleware-recursion-detection": "3.290.0",
+    "@aws-sdk/middleware-retry": "3.290.0",
+    "@aws-sdk/middleware-serde": "3.290.0",
+    "@aws-sdk/middleware-signing": "3.290.0",
+    "@aws-sdk/middleware-stack": "3.290.0",
+    "@aws-sdk/middleware-user-agent": "3.290.0",
+    "@aws-sdk/node-config-provider": "3.290.0",
+    "@aws-sdk/node-http-handler": "3.290.0",
+    "@aws-sdk/protocol-http": "3.290.0",
+    "@aws-sdk/smithy-client": "3.290.0",
+    "@aws-sdk/types": "3.290.0",
+    "@aws-sdk/url-parser": "3.290.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.290.0",
+    "@aws-sdk/util-defaults-mode-node": "3.290.0",
+    "@aws-sdk/util-endpoints": "3.290.0",
+    "@aws-sdk/util-retry": "3.290.0",
+    "@aws-sdk/util-user-agent-browser": "3.290.0",
+    "@aws-sdk/util-user-agent-node": "3.290.0",
     "@aws-sdk/util-utf8": "3.254.0",
     "tslib": "^2.3.1"
   },