Skip to main content

DeriveSharedSecret

Combines the caller's private key and the recipient's public key to create a unique shared secret.

Description​

The `DeriveSharedSecret` operation performs a key agreement operation that combines the private key from a KMS key with a public key provided by the caller. This operation returns a shared secret that is unique to each combination of private and public key pair.

note
  • The KMS key you use for this operation must be an asymmetric KMS key with a key usage of `DERIVE_SHARED_SECRET`.
  • The public key must use the same algorithm as your KMS key.
  • The shared secret is not stored by QKMS. You must use it immediately or store it securely.

Request Syntax​

POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.DeriveSharedSecret
{ "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "PublicKey": "Base64-encoded public key", "RecipientInfo": "Base64-encoded recipient info" }
Values in italics indicate user input and should be replaced with actual values.

Request Parameters​

Headers​

NameDescriptionRequiredType
Content-TypeMust be "application/x-amz-json-1.1"Yesstring
X-Amz-TargetMust be "TrentService.DeriveSharedSecret"Yesstring

Request Body​

NameDescriptionRequiredType
KeyIdSpecifies the KMS key that contains the private key in the key pair. The value can be the ID or ARN of a KMS key.Yesstring
PublicKeyThe public key of the other party in the key agreement scheme. This key must use the same algorithm as your KMS key.Yesblob
RecipientInfoInformation about the party that will receive the shared secret. This parameter is optional and is used only by some key agreement algorithms.Noblob

Examples​

Example 1: Derive a shared secret using a KMS key​

POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.DeriveSharedSecret
{ "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "PublicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..." }
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
{ "KeyId": "arn:verenc:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "SharedSecret": "Base64-encoded shared secret" }
Values in italics indicate variable response values.

Response Syntax​

HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
{ "KeyId": "string", "SharedSecret": "blob" }
Values in italics indicate variable response values.

Response Elements​

NameDescriptionRequiredType
KeyIdThe Amazon Resource Name (ARN) of the KMS key that was used in the key agreement operation.NoString
SharedSecretThe shared secret that was derived from the key agreement operation.NoString

Special Errors​

Error CodeDescription
DependencyTimeoutExceptionThe system timed out while trying to fulfill the request.
DisabledExceptionThe request was rejected because the specified KMS key is disabled.
InvalidKeyUsageExceptionThe request was rejected because the specified KeyId value cannot be used for this operation.
InvalidPublicKeyExceptionThe request was rejected because the provided public key is invalid or incompatible with the KMS key.
KMSInternalExceptionThe request was rejected because an internal error occurred.
KMSInvalidStateExceptionThe request was rejected because the key state is not valid for this operation.
NotFoundExceptionThe request was rejected because the specified entity or resource could not be found.
UnsupportedOperationExceptionThe request was rejected because a specified parameter is not supported or a specified resource is not valid for this operation.

Permissions​

To use the `DeriveSharedSecret` operation, you must have the following permissions:

  • `kms:DeriveSharedSecret` on the KMS key (specified in the policy)

Try It Out​

Test DeriveSharedSecret

Derive a shared secret using a KMS key.

Coming Soon

This feature is currently under development and will be available soon.