Module Values.DeriveSharedSecretResponseSource

Derives a shared secret using a key agreement algorithm. You must use an asymmetric NIST-standard elliptic curve (ECC) or SM2 (China Regions only) KMS key pair with a KeyUsage value of KEY_AGREEMENT to call DeriveSharedSecret. DeriveSharedSecret uses the Elliptic Curve Cryptography Cofactor Diffie-Hellman Primitive (ECDH) to establish a key agreement between two peers by deriving a shared secret from their elliptic curve public-private key pairs. You can use the raw shared secret that DeriveSharedSecret returns to derive a symmetric key that can encrypt and decrypt data that is sent between the two peers, or that can generate and verify HMACs. KMS recommends that you follow NIST recommendations for key derivation when using the raw shared secret to derive a symmetric key. The following workflow demonstrates how to establish key agreement over an insecure communication channel using DeriveSharedSecret. Alice calls CreateKey to create an asymmetric KMS key pair with a KeyUsage value of KEY_AGREEMENT. The asymmetric KMS key must use a NIST-standard elliptic curve (ECC) or SM2 (China Regions only) key spec. Bob creates an elliptic curve key pair. Bob can call CreateKey to create an asymmetric KMS key pair or generate a key pair outside of KMS. Bob's key pair must use the same NIST-standard elliptic curve (ECC) or SM2 (China Regions ony) curve as Alice. Alice and Bob exchange their public keys through an insecure communication channel (like the internet). Use GetPublicKey to download the public key of your asymmetric KMS key pair. KMS strongly recommends verifying that the public key you receive came from the expected party before using it to derive a shared secret. Alice calls DeriveSharedSecret. KMS uses the private key from the KMS key pair generated in Step 1, Bob's public key, and the Elliptic Curve Cryptography Cofactor Diffie-Hellman Primitive to derive the shared secret. The private key in your KMS key pair never leaves KMS unencrypted. DeriveSharedSecret returns the raw shared secret. Bob uses the Elliptic Curve Cryptography Cofactor Diffie-Hellman Primitive to calculate the same raw secret using his private key and Alice's public key. To derive a shared secret you must provide a key agreement algorithm, the private key of the caller's asymmetric NIST-standard elliptic curve or SM2 (China Regions only) KMS key pair, and the public key from your peer's NIST-standard elliptic curve or SM2 (China Regions only) key pair. The public key can be from another asymmetric KMS key pair or from a key pair generated outside of KMS, but both key pairs must be on the same elliptic curve. The KMS key that you use for this operation must be in a compatible key state. For details, see Key states of KMS keys in the Key Management Service Developer Guide. Cross-account use: 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 KeyId parameter. Required permissions: kms:DeriveSharedSecret (key policy) Related operations: CreateKey GetPublicKey DescribeKey Eventual consistency: The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.

Sourcetype nonrec t = {
  1. keyId : KeyIdType.t option;
    (*

    Identifies the KMS key used to derive the shared secret.

    *)
  2. sharedSecret : PlaintextType.t option;
    (*

    The raw secret derived from the specified key agreement algorithm, private key in the asymmetric KMS key, and your peer's public key. If the response includes the CiphertextForRecipient field, the SharedSecret field is null or empty.

    *)
  3. ciphertextForRecipient : CiphertextType.t option;
    (*

    The plaintext shared secret encrypted with the public key from the attestation document. This ciphertext can be decrypted only by using a private key from the attested environment. This field is included in the response only when the Recipient parameter in the request includes a valid attestation document from an Amazon Web Services Nitro enclave or NitroTPM. For information about the interaction between KMS and Amazon Web Services Nitro Enclaves or Amazon Web Services NitroTPM, see Cryptographic attestation support in KMS in the Key Management Service Developer Guide.

    *)
  4. keyAgreementAlgorithm : KeyAgreementAlgorithmSpec.t option;
    (*

    Identifies the key agreement algorithm used to derive the shared secret.

    *)
  5. keyOrigin : OriginType.t option;
    (*

    The source of the key material for the specified KMS key. When this value is AWS_KMS, KMS created the key material. When this value is EXTERNAL, the key material was imported or the KMS key doesn't have any key material. The only valid values for DeriveSharedSecret are AWS_KMS and EXTERNAL. DeriveSharedSecret does not support KMS keys with a KeyOrigin value of AWS_CLOUDHSM or EXTERNAL_KEY_STORE.

    *)
}
Sourcetype nonrec error = [
  1. | `DependencyTimeoutException of DependencyTimeoutException.t
  2. | `DisabledException of DisabledException.t
  3. | `DryRunOperationException of DryRunOperationException.t
  4. | `InvalidGrantTokenException of InvalidGrantTokenException.t
  5. | `InvalidKeyUsageException of InvalidKeyUsageException.t
  6. | `KMSInternalException of KMSInternalException.t
  7. | `KMSInvalidStateException of KMSInvalidStateException.t
  8. | `KeyUnavailableException of KeyUnavailableException.t
  9. | `NotFoundException of NotFoundException.t
  10. | `Unknown_operation_error of string * string option
]
Sourceval make : ?keyId:??? -> ?sharedSecret:??? -> ?ciphertextForRecipient:??? -> ?keyAgreementAlgorithm:??? -> ?keyOrigin:??? -> unit -> t
Sourceval error_of_json : string -> Yojson.Safe.t -> [> `DependencyTimeoutException of DependencyTimeoutException.t | `DisabledException of DisabledException.t | `DryRunOperationException of DryRunOperationException.t | `InvalidGrantTokenException of InvalidGrantTokenException.t | `InvalidKeyUsageException of InvalidKeyUsageException.t | `KMSInternalException of KMSInternalException.t | `KMSInvalidStateException of KMSInvalidStateException.t | `KeyUnavailableException of KeyUnavailableException.t | `NotFoundException of NotFoundException.t | `Unknown_operation_error of string * string option ]
Sourceval error_of_xml : string -> Awso.Xml.t -> [> `DependencyTimeoutException of DependencyTimeoutException.t | `DisabledException of DisabledException.t | `DryRunOperationException of DryRunOperationException.t | `InvalidGrantTokenException of InvalidGrantTokenException.t | `InvalidKeyUsageException of InvalidKeyUsageException.t | `KMSInternalException of KMSInternalException.t | `KMSInvalidStateException of KMSInvalidStateException.t | `KeyUnavailableException of KeyUnavailableException.t | `NotFoundException of NotFoundException.t | `Unknown_operation_error of string * string option ]
Sourceval error_to_json : error -> Yojson.Safe.t
Sourceval to_value : t -> [> `Structure of (string * [> `Blob of PlaintextType.t | `Enum of string | `String of KeyIdType.t ]) list ]
Sourceval to_query : t -> Awso.Client.Query.t
Sourceval of_xml : Awso.Xml.t -> t
Sourceval of_string : string -> t
Sourceval of_json : Yojson.Safe.t -> t
Sourceval to_json : t -> Yojson.Safe.t