Class: Aws::KMS::Client

# This example connects an AWS KMS custom key store to its backing key store. For an AWS CloudHSM key store, it connects
# the key store to its AWS CloudHSM cluster. For an external key store, it connects the key store to the external key
# store proxy that communicates with your external key manager. This operation does not return any data. To verify that
# the custom key store is connected, use the <code>DescribeCustomKeyStores</code> operation.

resp = client.connect_custom_key_store({
  custom_key_store_id: "cks-1234567890abcdef0", # The ID of the AWS KMS custom key store.
})
resp.to_h outputs the following:
{
}

resp = client.connect_custom_key_store({
  custom_key_store_id: "CustomKeyStoreIdType", # required
})

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :custom_key_store_id (required, String) —

  Enter the key store ID of the custom key store that you want to connect. To find the ID of a custom key store, use the DescribeCustomKeyStores operation.

Returns:

• (Struct) —

  Returns an empty response.

See Also:

• AWS API Documentation

# The following example creates an alias for the specified KMS key.

resp = client.create_alias({
  alias_name: "alias/ExampleAlias", # The alias to create. Aliases must begin with 'alias/'. Do not use aliases that begin with 'alias/aws' because they are reserved for use by AWS.
  target_key_id: "1234abcd-12ab-34cd-56ef-1234567890ab", # The identifier of the KMS key whose alias you are creating. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
})

resp = client.create_alias({
  alias_name: "AliasNameType", # required
  target_key_id: "KeyIdType", # required
})

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :alias_name (required, String) —

  Specifies the alias name. This value must begin with alias/ followed by a name, such as alias/ExampleAlias.

  Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.

  The AliasName value must be string of 1-256 characters. It can contain only alphanumeric characters, forward slashes (/), underscores (_), and dashes (-). The alias name cannot begin with alias/aws/. The alias/aws/ prefix is reserved for Amazon Web Services managed keys.

• :target_key_id (required, String) —

  Associates the alias with the specified customer managed key. The KMS key must be in the same Amazon Web Services Region.

  A valid key ID is required. If you supply a null or empty string value, this operation returns an error.

  For help finding the key ID and ARN, see Find the key ID and key ARN in the Key Management Service Developer Guide .

  Specify the key ID or key ARN of the KMS key.

  For example:

  • Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab

  • Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

  To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey.

Returns:

• (Struct) —

  Returns an empty response.

See Also:

• AWS API Documentation

# This example creates a custom key store that is associated with an AWS CloudHSM cluster.

resp = client.create_custom_key_store({
  cloud_hsm_cluster_id: "cluster-234abcdefABC", # The ID of the CloudHSM cluster.
  custom_key_store_name: "ExampleKeyStore", # A friendly name for the custom key store.
  key_store_password: "kmsPswd", # The password for the kmsuser CU account in the specified cluster.
  trust_anchor_certificate: "<certificate-goes-here>", # The content of the customerCA.crt file that you created when you initialized the cluster.
})
resp.to_h outputs the following:
{
  custom_key_store_id: "cks-1234567890abcdef0", # The ID of the new custom key store.
}

# This example creates an external key store that uses an Amazon VPC endpoint service to communicate with AWS KMS.

resp = client.create_custom_key_store({
  custom_key_store_name: "ExampleVPCEndpointKeyStore", # A friendly name for the custom key store
  custom_key_store_type: "EXTERNAL_KEY_STORE", # For external key stores, the value must be EXTERNAL_KEY_STORE
  xks_proxy_authentication_credential: {
    access_key_id: "ABCDE12345670EXAMPLE", 
    raw_secret_access_key: "DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo=", 
  }, # The access key ID and secret access key that KMS uses to authenticate to your external key store proxy
  xks_proxy_connectivity: "VPC_ENDPOINT_SERVICE", # Indicates how AWS KMS communicates with the external key store proxy
  xks_proxy_uri_endpoint: "https://myproxy-private.xks.example.com", # The URI that AWS KMS uses to connect to the external key store proxy
  xks_proxy_uri_path: "/example-prefix/kms/xks/v1", # The URI path to the external key store proxy APIs
  xks_proxy_vpc_endpoint_service_name: "com.amazonaws.vpce.us-east-1.vpce-svc-example1", # The VPC endpoint service that KMS uses to communicate with the external key store proxy
})
resp.to_h outputs the following:
{
  custom_key_store_id: "cks-1234567890abcdef0", # The ID of the new custom key store.
}

# This example creates an external key store with public endpoint connectivity.

resp = client.create_custom_key_store({
  custom_key_store_name: "ExamplePublicEndpointKeyStore", # A friendly name for the custom key store
  custom_key_store_type: "EXTERNAL_KEY_STORE", # For external key stores, the value must be EXTERNAL_KEY_STORE
  xks_proxy_authentication_credential: {
    access_key_id: "ABCDE12345670EXAMPLE", 
    raw_secret_access_key: "DXjSUawnel2fr6SKC7G25CNxTyWKE5PF9XX6H/u9pSo=", 
  }, # The access key ID and secret access key that KMS uses to authenticate to your external key store proxy
  xks_proxy_connectivity: "PUBLIC_ENDPOINT", # Indicates how AWS KMS communicates with the external key store proxy
  xks_proxy_uri_endpoint: "https://myproxy.xks.example.com", # The URI that AWS KMS uses to connect to the external key store proxy
  xks_proxy_uri_path: "/kms/xks/v1", # The URI path to your external key store proxy API
})
resp.to_h outputs the following:
{
  custom_key_store_id: "cks-987654321abcdef0", # The ID of the new custom key store.
}

resp = client.create_custom_key_store({
  custom_key_store_name: "CustomKeyStoreNameType", # required
  cloud_hsm_cluster_id: "CloudHsmClusterIdType",
  trust_anchor_certificate: "TrustAnchorCertificateType",
  key_store_password: "KeyStorePasswordType",
  custom_key_store_type: "AWS_CLOUDHSM", # accepts AWS_CLOUDHSM, EXTERNAL_KEY_STORE
  xks_proxy_uri_endpoint: "XksProxyUriEndpointType",
  xks_proxy_uri_path: "XksProxyUriPathType",
  xks_proxy_vpc_endpoint_service_name: "XksProxyVpcEndpointServiceNameType",
  xks_proxy_authentication_credential: {
    access_key_id: "XksProxyAuthenticationAccessKeyIdType", # required
    raw_secret_access_key: "XksProxyAuthenticationRawSecretAccessKeyType", # required
  },
  xks_proxy_connectivity: "PUBLIC_ENDPOINT", # accepts PUBLIC_ENDPOINT, VPC_ENDPOINT_SERVICE
})

resp.custom_key_store_id #=> String

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :custom_key_store_name (required, String) —

  Specifies a friendly name for the custom key store. The name must be unique in your Amazon Web Services account and Region. This parameter is required for all custom key stores.

  Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.

• :cloud_hsm_cluster_id (String) —

  Identifies the CloudHSM cluster for an CloudHSM key store. This parameter is required for custom key stores with CustomKeyStoreType of AWS_CLOUDHSM.

  Enter the cluster ID of any active CloudHSM cluster that is not already associated with a custom key store. To find the cluster ID, use the DescribeClusters operation.

• :trust_anchor_certificate (String) —

  Specifies the certificate for an CloudHSM key store. This parameter is required for custom key stores with a CustomKeyStoreType of AWS_CLOUDHSM.

  Enter the content of the trust anchor certificate for the CloudHSM cluster. This is the content of the customerCA.crt file that you created when you initialized the cluster.

• :key_store_password (String) —

  Specifies the kmsuser password for an CloudHSM key store. This parameter is required for custom key stores with a CustomKeyStoreType of AWS_CLOUDHSM.

  Enter the password of the kmsuser crypto user (CU) account in the specified CloudHSM cluster. KMS logs into the cluster as this user to manage key material on your behalf.

  The password must be a string of 7 to 32 characters. Its value is case sensitive.

  This parameter tells KMS the kmsuser account password; it does not change the password in the CloudHSM cluster.

• :custom_key_store_type (String) —

  Specifies the type of custom key store. The default value is AWS_CLOUDHSM.

  For a custom key store backed by an CloudHSM cluster, omit the parameter or enter AWS_CLOUDHSM. For a custom key store backed by an external key manager outside of Amazon Web Services, enter EXTERNAL_KEY_STORE. You cannot change this property after the key store is created.

• :xks_proxy_uri_endpoint (String) —

  Specifies the endpoint that KMS uses to send requests to the external key store proxy (XKS proxy). This parameter is required for custom key stores with a CustomKeyStoreType of EXTERNAL_KEY_STORE.

  The protocol must be HTTPS. KMS communicates on port 443. Do not specify the port in the XksProxyUriEndpoint value.

  For external key stores with XksProxyConnectivity value of VPC_ENDPOINT_SERVICE, specify https:// followed by the private DNS name of the VPC endpoint service.

  For external key stores with PUBLIC_ENDPOINT connectivity, this endpoint must be reachable before you create the custom key store. KMS connects to the external key store proxy while creating the custom key store. For external key stores with VPC_ENDPOINT_SERVICE connectivity, KMS connects when you call the ConnectCustomKeyStore operation.

  The value of this parameter must begin with https://. The remainder can contain upper and lower case letters (A-Z and a-z), numbers (0-9), dots (.), and hyphens (-). Additional slashes (/ and ``) are not permitted.

  Uniqueness requirements:

  • The combined XksProxyUriEndpoint and XksProxyUriPath values must be unique in the Amazon Web Services account and Region.

  • An external key store with PUBLIC_ENDPOINT connectivity cannot use the same XksProxyUriEndpoint value as an external key store with VPC_ENDPOINT_SERVICE connectivity in this Amazon Web Services Region.

  • Each external key store with VPC_ENDPOINT_SERVICE connectivity must have its own private DNS name. The XksProxyUriEndpoint value for external key stores with VPC_ENDPOINT_SERVICE connectivity (private DNS name) must be unique in the Amazon Web Services account and Region.

• :xks_proxy_uri_path (String) —

  Specifies the base path to the proxy APIs for this external key store. To find this value, see the documentation for your external key store proxy. This parameter is required for all custom key stores with a CustomKeyStoreType of EXTERNAL_KEY_STORE.

  The value must start with / and must end with /kms/xks/v1 where v1 represents the version of the KMS external key store proxy API. This path can include an optional prefix between the required elements such as /prefix/kms/xks/v1.

  Uniqueness requirements:

  • The combined XksProxyUriEndpoint and XksProxyUriPath values must be unique in the Amazon Web Services account and Region.

  ^

• :xks_proxy_vpc_endpoint_service_name (String) —

  Specifies the name of the Amazon VPC endpoint service for interface endpoints that is used to communicate with your external key store proxy (XKS proxy). This parameter is required when the value of CustomKeyStoreType is EXTERNAL_KEY_STORE and the value of XksProxyConnectivity is VPC_ENDPOINT_SERVICE.

  The Amazon VPC endpoint service must fulfill all requirements for use with an external key store.

  Uniqueness requirements:

  • External key stores with VPC_ENDPOINT_SERVICE connectivity can share an Amazon VPC, but each external key store must have its own VPC endpoint service and private DNS name.

  ^

• :xks_proxy_authentication_credential (Types::XksProxyAuthenticationCredentialType) —

  Specifies an authentication credential for the external key store proxy (XKS proxy). This parameter is required for all custom key stores with a CustomKeyStoreType of EXTERNAL_KEY_STORE.

  The XksProxyAuthenticationCredential has two required elements: RawSecretAccessKey, a secret key, and AccessKeyId, a unique identifier for the RawSecretAccessKey. For character requirements, see XksProxyAuthenticationCredentialType.

  KMS uses this authentication credential to sign requests to the external key store proxy on your behalf. This credential is unrelated to Identity and Access Management (IAM) and Amazon Web Services credentials.

  This parameter doesn't set or change the authentication credentials on the XKS proxy. It just tells KMS the credential that you established on your external key store proxy. If you rotate your proxy authentication credential, use the UpdateCustomKeyStore operation to provide the new credential to KMS.

• :xks_proxy_connectivity (String) —

  Indicates how KMS communicates with the external key store proxy. This parameter is required for custom key stores with a CustomKeyStoreType of EXTERNAL_KEY_STORE.

  If the external key store proxy uses a public endpoint, specify PUBLIC_ENDPOINT. If the external key store proxy uses a Amazon VPC endpoint service for communication with KMS, specify VPC_ENDPOINT_SERVICE. For help making this choice, see Choosing a connectivity option in the Key Management Service Developer Guide.

  An Amazon VPC endpoint service keeps your communication with KMS in a private address space entirely within Amazon Web Services, but it requires more configuration, including establishing a Amazon VPC with multiple subnets, a VPC endpoint service, a network load balancer, and a verified private DNS name. A public endpoint is simpler to set up, but it might be slower and might not fulfill your security requirements. You might consider testing with a public endpoint, and then establishing a VPC endpoint service for production tasks. Note that this choice does not determine the location of the external key store proxy. Even if you choose a VPC endpoint service, the proxy can be hosted within the VPC or outside of Amazon Web Services such as in your corporate data center.

Returns:

• (Types::CreateCustomKeyStoreResponse) —

  Returns a response object which responds to the following methods:

  • #custom_key_store_id => String

See Also:

• AWS API Documentation

# The following example creates a grant that allows the specified IAM role to encrypt data with the specified KMS key.

resp = client.create_grant({
  grantee_principal: "arn:aws:iam::111122223333:role/ExampleRole", # The identity that is given permission to perform the operations specified in the grant.
  key_id: "arn:aws:kms:us-east-2:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab", # The identifier of the KMS key to which the grant applies. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
  operations: [
    "Encrypt", 
    "Decrypt", 
  ], # A list of operations that the grant allows.
})
resp.to_h outputs the following:
{
  grant_id: "0c237476b39f8bc44e45212e08498fbe3151305030726c0590dd8d3e9f3d6a60", # The unique identifier of the grant.
  grant_token: "AQpAM2RhZTk1MGMyNTk2ZmZmMzEyYWVhOWViN2I1MWM4Mzc0MWFiYjc0ZDE1ODkyNGFlNTIzODZhMzgyZjBlNGY3NiKIAgEBAgB4Pa6VDCWW__MSrqnre1HIN0Grt00ViSSuUjhqOC8OT3YAAADfMIHcBgkqhkiG9w0BBwaggc4wgcsCAQAwgcUGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMmqLyBTAegIn9XlK5AgEQgIGXZQjkBcl1dykDdqZBUQ6L1OfUivQy7JVYO2-ZJP7m6f1g8GzV47HX5phdtONAP7K_HQIflcgpkoCqd_fUnE114mSmiagWkbQ5sqAVV3ov-VeqgrvMe5ZFEWLMSluvBAqdjHEdMIkHMlhlj4ENZbzBfo9Wxk8b8SnwP4kc4gGivedzFXo-dwN8fxjjq_ZZ9JFOj2ijIbj5FyogDCN0drOfi8RORSEuCEmPvjFRMFAwcmwFkN2NPp89amA", # The grant token.
}

resp = client.create_grant({
  key_id: "KeyIdType", # required
  grantee_principal: "PrincipalIdType", # required
  retiring_principal: "PrincipalIdType",
  operations: ["Decrypt"], # required, accepts Decrypt, Encrypt, GenerateDataKey, GenerateDataKeyWithoutPlaintext, ReEncryptFrom, ReEncryptTo, Sign, Verify, GetPublicKey, CreateGrant, RetireGrant, DescribeKey, GenerateDataKeyPair, GenerateDataKeyPairWithoutPlaintext, GenerateMac, VerifyMac, DeriveSharedSecret
  constraints: {
    encryption_context_subset: {
      "EncryptionContextKey" => "EncryptionContextValue",
    },
    encryption_context_equals: {
      "EncryptionContextKey" => "EncryptionContextValue",
    },
  },
  grant_tokens: ["GrantTokenType"],
  name: "GrantNameType",
  dry_run: false,
})

resp.grant_token #=> String
resp.grant_id #=> String

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :key_id (required, String) —

  Identifies the KMS key for the grant. The grant gives principals permission to use this KMS key.

  Specify the key ID or key ARN of the KMS key. To specify a KMS key in a different Amazon Web Services account, you must use the key ARN.

  For example:

  • Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab

  • Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

  To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey.

• :grantee_principal (required, String) —

  The identity that gets the permissions specified in the grant.

  To specify the grantee principal, use the Amazon Resource Name (ARN) of an Amazon Web Services principal. Valid principals include Amazon Web Services accounts, IAM users, IAM roles, federated users, and assumed role users. For help with the ARN syntax for a principal, see IAM ARNs in the Identity and Access Management User Guide .

• :retiring_principal (String) —

  The principal that has permission to use the RetireGrant operation to retire the grant.

  To specify the principal, use the Amazon Resource Name (ARN) of an Amazon Web Services principal. Valid principals include Amazon Web Services accounts, IAM users, IAM roles, federated users, and assumed role users. For help with the ARN syntax for a principal, see IAM ARNs in the Identity and Access Management User Guide .

  The grant determines the retiring principal. Other principals might have permission to retire the grant or revoke the grant. For details, see RevokeGrant and Retiring and revoking grants in the Key Management Service Developer Guide.

• :operations (required, Array<String>) —

  A list of operations that the grant permits.

  This list must include only operations that are permitted in a grant. Also, the operation must be supported on the KMS key. For example, you cannot create a grant for a symmetric encryption KMS key that allows the Sign operation, or a grant for an asymmetric KMS key that allows the GenerateDataKey operation. If you try, KMS returns a ValidationError exception. For details, see Grant operations in the Key Management Service Developer Guide.

• :constraints (Types::GrantConstraints) —

  Specifies a grant constraint.

  Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.

  KMS supports the EncryptionContextEquals and EncryptionContextSubset grant constraints, which allow the permissions in the grant only when the encryption context in the request matches (EncryptionContextEquals) or includes (EncryptionContextSubset) the encryption context specified in the constraint.

  The encryption context grant constraints are supported only on grant operations that include an EncryptionContext parameter, such as cryptographic operations on symmetric encryption KMS keys. Grants with grant constraints can include the DescribeKey and RetireGrant operations, but the constraint doesn't apply to these operations. If a grant with a grant constraint includes the CreateGrant operation, the constraint requires that any grants created with the CreateGrant permission have an equally strict or stricter encryption context constraint.

  You cannot use an encryption context grant constraint for cryptographic operations with asymmetric KMS keys or HMAC KMS keys. Operations with these keys don't support an encryption context.

  Each constraint value can include up to 8 encryption context pairs. The encryption context value in each constraint cannot exceed 384 characters. For information about grant constraints, see Using grant constraints in the Key Management Service Developer Guide. For more information about encryption context, see Encryption context in the Key Management Service Developer Guide .

• :grant_tokens (Array<String>) —

  A list of grant tokens.

  Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. For more information, see Grant token and Using a grant token in the Key Management Service Developer Guide.

• :name (String) —

  A friendly name for the grant. Use this value to prevent the unintended creation of duplicate grants when retrying this request.

  Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.

  When this value is absent, all CreateGrant requests result in a new grant with a unique GrantId even if all the supplied parameters are identical. This can result in unintended duplicates when you retry the CreateGrant request.

  When this value is present, you can retry a CreateGrant request with identical parameters; if the grant already exists, the original GrantId is returned without creating a new grant. Note that the returned grant token is unique with every CreateGrant request, even when a duplicate GrantId is returned. All grant tokens for the same grant ID can be used interchangeably.

• :dry_run (Boolean) —

  Checks if your request will succeed. DryRun is an optional parameter.

  To learn more about how to use this parameter, see Testing your permissions in the Key Management Service Developer Guide.

Returns:

• (Types::CreateGrantResponse) —

  Returns a response object which responds to the following methods:

  • #grant_token => String
  • #grant_id => String

See Also:

• AWS API Documentation

# The following example creates a symmetric KMS key for encryption and decryption. No parameters are required for this
# operation.

resp = client.create_key({
})
resp.to_h outputs the following:
{
  key_metadata: {
    aws_account_id: "111122223333", 
    arn: "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", 
    creation_date: Time.parse("2017-07-05T14:04:55-07:00"), 
    current_key_material_id: "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", 
    customer_master_key_spec: "SYMMETRIC_DEFAULT", 
    description: "", 
    enabled: true, 
    encryption_algorithms: [
      "SYMMETRIC_DEFAULT", 
    ], 
    key_id: "1234abcd-12ab-34cd-56ef-1234567890ab", 
    key_manager: "CUSTOMER", 
    key_spec: "SYMMETRIC_DEFAULT", 
    key_state: "Enabled", 
    key_usage: "ENCRYPT_DECRYPT", 
    multi_region: false, 
    origin: "AWS_KMS", 
  }, # Detailed information about the KMS key that this operation creates.
}

# This example creates a KMS key that contains an asymmetric RSA key pair for encryption and decryption. The key spec and
# key usage can't be changed after the key is created.

resp = client.create_key({
  key_spec: "RSA_4096", # Describes the type of key material in the KMS key.
  key_usage: "ENCRYPT_DECRYPT", # The cryptographic operations for which you can use the KMS key.
})
resp.to_h outputs the following:
{
  key_metadata: {
    aws_account_id: "111122223333", 
    arn: "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", 
    creation_date: Time.parse("2021-04-05T14:04:55-07:00"), 
    customer_master_key_spec: "RSA_4096", 
    description: "", 
    enabled: true, 
    encryption_algorithms: [
      "RSAES_OAEP_SHA_1", 
      "RSAES_OAEP_SHA_256", 
    ], 
    key_id: "1234abcd-12ab-34cd-56ef-1234567890ab", 
    key_manager: "CUSTOMER", 
    key_spec: "RSA_4096", 
    key_state: "Enabled", 
    key_usage: "ENCRYPT_DECRYPT", 
    multi_region: false, 
    origin: "AWS_KMS", 
  }, # Detailed information about the KMS key that this operation creates.
}

# This example creates a KMS key that contains an asymmetric elliptic curve (ECC) key pair for signing and verification.
# The key spec and key usage can't be changed after the key is created.

resp = client.create_key({
  key_spec: "ECC_NIST_P521", # Describes the type of key material in the KMS key.
  key_usage: "SIGN_VERIFY", # The cryptographic operations for which you can use the KMS key.
})
resp.to_h outputs the following:
{
  key_metadata: {
    aws_account_id: "111122223333", 
    arn: "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", 
    creation_date: Time.parse("2019-12-02T07:48:55-07:00"), 
    customer_master_key_spec: "ECC_NIST_P521", 
    description: "", 
    enabled: true, 
    key_id: "1234abcd-12ab-34cd-56ef-1234567890ab", 
    key_manager: "CUSTOMER", 
    key_spec: "ECC_NIST_P521", 
    key_state: "Enabled", 
    key_usage: "SIGN_VERIFY", 
    multi_region: false, 
    origin: "AWS_KMS", 
    signing_algorithms: [
      "ECDSA_SHA_512", 
    ], 
  }, # Detailed information about the KMS key that this operation creates.
}

# This example creates a 384-bit symmetric HMAC KMS key. The GENERATE_VERIFY_MAC key usage value is required even though
# it's the only valid value for HMAC KMS keys. The key spec and key usage can't be changed after the key is created.

resp = client.create_key({
  key_spec: "HMAC_384", # Describes the type of key material in the KMS key.
  key_usage: "GENERATE_VERIFY_MAC", # The cryptographic operations for which you can use the KMS key.
})
resp.to_h outputs the following:
{
  key_metadata: {
    aws_account_id: "111122223333", 
    arn: "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", 
    creation_date: Time.parse("2022-04-05T14:04:55-07:00"), 
    customer_master_key_spec: "HMAC_384", 
    description: "", 
    enabled: true, 
    key_id: "1234abcd-12ab-34cd-56ef-1234567890ab", 
    key_manager: "CUSTOMER", 
    key_spec: "HMAC_384", 
    key_state: "Enabled", 
    key_usage: "GENERATE_VERIFY_MAC", 
    mac_algorithms: [
      "HMAC_SHA_384", 
    ], 
    multi_region: false, 
    origin: "AWS_KMS", 
  }, # Detailed information about the KMS key that this operation creates.
}

# This example creates a module-lattice digital signature algorithm (ML-DSA) key for signing and verification. The
# key-usage parameter is required even though SIGN_VERIFY is the only valid value for ML-DSA keys.

resp = client.create_key({
  key_spec: "ML_DSA_65", # Describes the type of key material in the KMS key.
  key_usage: "SIGN_VERIFY", # The cryptographic operations for which you can use the KMS key.
})
resp.to_h outputs the following:
{
  key_metadata: {
    aws_account_id: "111122223333", 
    arn: "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", 
    creation_date: Time.parse(1748371316.734), 
    customer_master_key_spec: "ML_DSA_65", 
    description: "", 
    enabled: true, 
    key_id: "1234abcd-12ab-34cd-56ef-1234567890ab", 
    key_manager: "CUSTOMER", 
    key_spec: "ML_DSA_65", 
    key_state: "Enabled", 
    key_usage: "SIGN_VERIFY", 
    multi_region: false, 
    origin: "AWS_KMS", 
    signing_algorithms: [
      "ML_DSA_SHAKE_256", 
    ], 
  }, # Detailed information about the KMS key that this operation creates.
}

# This example creates a multi-Region primary symmetric encryption key. Because the default values for all parameters
# create a symmetric encryption key, only the MultiRegion parameter is required for this KMS key.

resp = client.create_key({
  multi_region: true, # Indicates whether the KMS key is a multi-Region (True) or regional (False) key.
})
resp.to_h outputs the following:
{
  key_metadata: {
    aws_account_id: "111122223333", 
    arn: "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab", 
    creation_date: Time.parse("2021-09-02T016:15:21-09:00"), 
    current_key_material_id: "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", 
    customer_master_key_spec: "SYMMETRIC_DEFAULT", 
    description: "", 
    enabled: true, 
    encryption_algorithms: [
      "SYMMETRIC_DEFAULT", 
    ], 
    key_id: "mrk-1234abcd12ab34cd56ef12345678990ab", 
    key_manager: "CUSTOMER", 
    key_spec: "SYMMETRIC_DEFAULT", 
    key_state: "Enabled", 
    key_usage: "ENCRYPT_DECRYPT", 
    multi_region: true, 
    multi_region_configuration: {
      multi_region_key_type: "PRIMARY", 
      primary_key: {
        arn: "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab", 
        region: "us-west-2", 
      }, 
      replica_keys: [
      ], 
    }, 
    origin: "AWS_KMS", 
  }, # Detailed information about the KMS key that this operation creates.
}

# This example creates a symmetric KMS key with no key material. When the operation is complete, you can import your own
# key material into the KMS key. To create this KMS key, set the Origin parameter to EXTERNAL.

resp = client.create_key({
  origin: "EXTERNAL", # The source of the key material for the KMS key.
})
resp.to_h outputs the following:
{
  key_metadata: {
    aws_account_id: "111122223333", 
    arn: "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", 
    creation_date: Time.parse("2019-12-02T07:48:55-07:00"), 
    customer_master_key_spec: "SYMMETRIC_DEFAULT", 
    description: "", 
    enabled: false, 
    encryption_algorithms: [
      "SYMMETRIC_DEFAULT", 
    ], 
    key_id: "1234abcd-12ab-34cd-56ef-1234567890ab", 
    key_manager: "CUSTOMER", 
    key_spec: "SYMMETRIC_DEFAULT", 
    key_state: "PendingImport", 
    key_usage: "ENCRYPT_DECRYPT", 
    multi_region: false, 
    origin: "EXTERNAL", 
  }, # Detailed information about the KMS key that this operation creates.
}

# This example creates a KMS key in the specified AWS CloudHSM key store. The operation creates the KMS key and its
# metadata in AWS KMS and creates the key material in the AWS CloudHSM cluster associated with the custom key store. This
# example requires the CustomKeyStoreId  and Origin parameters.

resp = client.create_key({
  custom_key_store_id: "cks-1234567890abcdef0", # Identifies the custom key store that hosts the KMS key.
  origin: "AWS_CLOUDHSM", # Indicates the source of the key material for the KMS key.
})
resp.to_h outputs the following:
{
  key_metadata: {
    aws_account_id: "111122223333", 
    arn: "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", 
    cloud_hsm_cluster_id: "cluster-234abcdefABC", 
    creation_date: Time.parse("2019-12-02T07:48:55-07:00"), 
    custom_key_store_id: "cks-1234567890abcdef0", 
    customer_master_key_spec: "SYMMETRIC_DEFAULT", 
    description: "", 
    enabled: true, 
    encryption_algorithms: [
      "SYMMETRIC_DEFAULT", 
    ], 
    key_id: "1234abcd-12ab-34cd-56ef-1234567890ab", 
    key_manager: "CUSTOMER", 
    key_spec: "SYMMETRIC_DEFAULT", 
    key_state: "Enabled", 
    key_usage: "ENCRYPT_DECRYPT", 
    multi_region: false, 
    origin: "AWS_CLOUDHSM", 
  }, # Detailed information about the KMS key that this operation creates.
}

# This example creates a KMS key in the specified external key store. It uses the XksKeyId parameter to associate the KMS
# key with an existing symmetric encryption key in your external key manager. This CustomKeyStoreId, Origin, and XksKeyId
# parameters are required in this operation.

resp = client.create_key({
  custom_key_store_id: "cks-9876543210fedcba9", # Identifies the custom key store that hosts the KMS key.
  origin: "EXTERNAL_KEY_STORE", # Indicates the source of the key material for the KMS key.
  xks_key_id: "bb8562717f809024", # Identifies the encryption key in your external key manager that is associated with the KMS key
})
resp.to_h outputs the following:
{
  key_metadata: {
    aws_account_id: "111122223333", 
    arn: "arn:aws:kms:us-east-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321", 
    creation_date: Time.parse("2022-02-02T07:48:55-07:00"), 
    custom_key_store_id: "cks-9876543210fedcba9", 
    customer_master_key_spec: "SYMMETRIC_DEFAULT", 
    description: "", 
    enabled: true, 
    encryption_algorithms: [
      "SYMMETRIC_DEFAULT", 
    ], 
    key_id: "0987dcba-09fe-87dc-65ba-ab0987654321", 
    key_manager: "CUSTOMER", 
    key_spec: "SYMMETRIC_DEFAULT", 
    key_state: "Enabled", 
    key_usage: "ENCRYPT_DECRYPT", 
    multi_region: false, 
    origin: "EXTERNAL_KEY_STORE", 
    xks_key_configuration: {
      id: "bb8562717f809024", 
    }, 
  }, # Detailed information about the KMS key that this operation creates.
}

resp = client.create_key({
  policy: "PolicyType",
  description: "DescriptionType",
  key_usage: "SIGN_VERIFY", # accepts SIGN_VERIFY, ENCRYPT_DECRYPT, GENERATE_VERIFY_MAC, KEY_AGREEMENT
  customer_master_key_spec: "RSA_2048", # accepts RSA_2048, RSA_3072, RSA_4096, ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521, ECC_SECG_P256K1, SYMMETRIC_DEFAULT, HMAC_224, HMAC_256, HMAC_384, HMAC_512, SM2
  key_spec: "RSA_2048", # accepts RSA_2048, RSA_3072, RSA_4096, ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521, ECC_SECG_P256K1, SYMMETRIC_DEFAULT, HMAC_224, HMAC_256, HMAC_384, HMAC_512, SM2, ML_DSA_44, ML_DSA_65, ML_DSA_87
  origin: "AWS_KMS", # accepts AWS_KMS, EXTERNAL, AWS_CLOUDHSM, EXTERNAL_KEY_STORE
  custom_key_store_id: "CustomKeyStoreIdType",
  bypass_policy_lockout_safety_check: false,
  tags: [
    {
      tag_key: "TagKeyType", # required
      tag_value: "TagValueType", # required
    },
  ],
  multi_region: false,
  xks_key_id: "XksKeyIdType",
})

resp.key_metadata.aws_account_id #=> String
resp.key_metadata.key_id #=> String
resp.key_metadata.arn #=> String
resp.key_metadata.creation_date #=> Time
resp.key_metadata.enabled #=> Boolean
resp.key_metadata.description #=> String
resp.key_metadata.key_usage #=> String, one of "SIGN_VERIFY", "ENCRYPT_DECRYPT", "GENERATE_VERIFY_MAC", "KEY_AGREEMENT"
resp.key_metadata.key_state #=> String, one of "Creating", "Enabled", "Disabled", "PendingDeletion", "PendingImport", "PendingReplicaDeletion", "Unavailable", "Updating"
resp.key_metadata.deletion_date #=> Time
resp.key_metadata.valid_to #=> Time
resp.key_metadata.origin #=> String, one of "AWS_KMS", "EXTERNAL", "AWS_CLOUDHSM", "EXTERNAL_KEY_STORE"
resp.key_metadata.custom_key_store_id #=> String
resp.key_metadata.cloud_hsm_cluster_id #=> String
resp.key_metadata.expiration_model #=> String, one of "KEY_MATERIAL_EXPIRES", "KEY_MATERIAL_DOES_NOT_EXPIRE"
resp.key_metadata.key_manager #=> String, one of "AWS", "CUSTOMER"
resp.key_metadata.customer_master_key_spec #=> String, one of "RSA_2048", "RSA_3072", "RSA_4096", "ECC_NIST_P256", "ECC_NIST_P384", "ECC_NIST_P521", "ECC_SECG_P256K1", "SYMMETRIC_DEFAULT", "HMAC_224", "HMAC_256", "HMAC_384", "HMAC_512", "SM2"
resp.key_metadata.key_spec #=> String, one of "RSA_2048", "RSA_3072", "RSA_4096", "ECC_NIST_P256", "ECC_NIST_P384", "ECC_NIST_P521", "ECC_SECG_P256K1", "SYMMETRIC_DEFAULT", "HMAC_224", "HMAC_256", "HMAC_384", "HMAC_512", "SM2", "ML_DSA_44", "ML_DSA_65", "ML_DSA_87"
resp.key_metadata.encryption_algorithms #=> Array
resp.key_metadata.encryption_algorithms[0] #=> String, one of "SYMMETRIC_DEFAULT", "RSAES_OAEP_SHA_1", "RSAES_OAEP_SHA_256", "SM2PKE"
resp.key_metadata.signing_algorithms #=> Array
resp.key_metadata.signing_algorithms[0] #=> String, one of "RSASSA_PSS_SHA_256", "RSASSA_PSS_SHA_384", "RSASSA_PSS_SHA_512", "RSASSA_PKCS1_V1_5_SHA_256", "RSASSA_PKCS1_V1_5_SHA_384", "RSASSA_PKCS1_V1_5_SHA_512", "ECDSA_SHA_256", "ECDSA_SHA_384", "ECDSA_SHA_512", "SM2DSA", "ML_DSA_SHAKE_256"
resp.key_metadata.key_agreement_algorithms #=> Array
resp.key_metadata.key_agreement_algorithms[0] #=> String, one of "ECDH"
resp.key_metadata.multi_region #=> Boolean
resp.key_metadata.multi_region_configuration.multi_region_key_type #=> String, one of "PRIMARY", "REPLICA"
resp.key_metadata.multi_region_configuration.primary_key.arn #=> String
resp.key_metadata.multi_region_configuration.primary_key.region #=> String
resp.key_metadata.multi_region_configuration.replica_keys #=> Array
resp.key_metadata.multi_region_configuration.replica_keys[0].arn #=> String
resp.key_metadata.multi_region_configuration.replica_keys[0].region #=> String
resp.key_metadata.pending_deletion_window_in_days #=> Integer
resp.key_metadata.mac_algorithms #=> Array
resp.key_metadata.mac_algorithms[0] #=> String, one of "HMAC_SHA_224", "HMAC_SHA_256", "HMAC_SHA_384", "HMAC_SHA_512"
resp.key_metadata.xks_key_configuration.id #=> String
resp.key_metadata.current_key_material_id #=> String

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :policy (String) —

  The key policy to attach to the KMS key.

  If you provide a key policy, it must meet the following criteria:

  • The key policy must allow the calling principal to make a subsequent PutKeyPolicy request on the KMS key. This reduces the risk that the KMS key becomes unmanageable. For more information, see Default key policy in the Key Management Service Developer Guide. (To omit this condition, set BypassPolicyLockoutSafetyCheck to true.)

  • Each statement in the key policy must contain one or more principals. The principals in the key policy must exist and be visible to KMS. When you create a new Amazon Web Services principal, you might need to enforce a delay before including the new principal in a key policy because the new principal might not be immediately visible to KMS. For more information, see Changes that I make are not always immediately visible in the Amazon Web Services Identity and Access Management User Guide.

  If either of the required Resource or Action elements are missing from a key policy statement, the policy statement has no effect. When a key policy statement is missing one of these elements, the KMS console correctly reports an error, but the CreateKey and PutKeyPolicy API requests succeed, even though the policy statement is ineffective.

  For more information on required key policy elements, see Elements in a key policy in the Key Management Service Developer Guide.

  If you do not provide a key policy, KMS attaches a default key policy to the KMS key. For more information, see Default key policy in the Key Management Service Developer Guide.

  If the key policy exceeds the length constraint, KMS returns a LimitExceededException.

  For help writing and formatting a JSON policy document, see the IAM JSON Policy Reference in the Identity and Access Management User Guide .

• :description (String) —

  A description of the KMS key. Use a description that helps you decide whether the KMS key is appropriate for a task. The default value is an empty string (no description).

  Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.

  To set or change the description after the key is created, use UpdateKeyDescription.

• :key_usage (String) —

  Determines the cryptographic operations for which you can use the KMS key. The default value is ENCRYPT_DECRYPT. This parameter is optional when you are creating a symmetric encryption KMS key; otherwise, it is required. You can't change the KeyUsage value after the KMS key is created.

  Select only one valid value.

  • For symmetric encryption KMS keys, omit the parameter or specify ENCRYPT_DECRYPT.

  • For HMAC KMS keys (symmetric), specify GENERATE_VERIFY_MAC.

  • For asymmetric KMS keys with RSA key pairs, specify ENCRYPT_DECRYPT or SIGN_VERIFY.

  • For asymmetric KMS keys with NIST-recommended elliptic curve key pairs, specify SIGN_VERIFY or KEY_AGREEMENT.

  • For asymmetric KMS keys with ECC_SECG_P256K1 key pairs, specify SIGN_VERIFY.

  • For asymmetric KMS keys with ML-DSA key pairs, specify SIGN_VERIFY.

  • For asymmetric KMS keys with SM2 key pairs (China Regions only), specify ENCRYPT_DECRYPT, SIGN_VERIFY, or KEY_AGREEMENT.

• :customer_master_key_spec (String) —

  Instead, use the KeySpec parameter.

  The KeySpec and CustomerMasterKeySpec parameters work the same way. Only the names differ. We recommend that you use KeySpec parameter in your code. However, to avoid breaking changes, KMS supports both parameters.

• :key_spec (String) —

  Specifies the type of KMS key to create. The default value, SYMMETRIC_DEFAULT, creates a KMS key with a 256-bit AES-GCM key that is used for encryption and decryption, except in China Regions, where it creates a 128-bit symmetric key that uses SM4 encryption. For a detailed description of all supported key specs, see Key spec reference in the Key Management Service Developer Guide .

  The KeySpec determines whether the KMS key contains a symmetric key or an asymmetric key pair. It also determines the algorithms that the KMS key supports. You can't change the KeySpec after the KMS key is created. To further restrict the algorithms that can be used with the KMS key, use a condition key in its key policy or IAM policy. For more information, see kms:EncryptionAlgorithm, kms:MacAlgorithm, kms:KeyAgreementAlgorithm, or kms:SigningAlgorithm in the Key Management Service Developer Guide .

  Amazon Web Services services that are integrated with KMS use symmetric encryption KMS keys to protect your data. These services do not support asymmetric KMS keys or HMAC KMS keys.

  KMS supports the following key specs for KMS keys:

  • Symmetric encryption key (default)

    • SYMMETRIC_DEFAULT

    ^

  • HMAC keys (symmetric)

    • HMAC_224

    • HMAC_256

    • HMAC_384

    • HMAC_512

  • Asymmetric RSA key pairs (encryption and decryption -or- signing and verification)

    • RSA_2048

    • RSA_3072

    • RSA_4096

  • Asymmetric NIST-recommended elliptic curve key pairs (signing and verification -or- deriving shared secrets)

    • ECC_NIST_P256 (secp256r1)

    • ECC_NIST_P384 (secp384r1)

    • ECC_NIST_P521 (secp521r1)

  • Other asymmetric elliptic curve key pairs (signing and verification)

    • ECC_SECG_P256K1 (secp256k1), commonly used for cryptocurrencies.

    ^

  • Asymmetric ML-DSA key pairs (signing and verification)

    • ML_DSA_44

    • ML_DSA_65

    • ML_DSA_87

  • SM2 key pairs (encryption and decryption -or- signing and verification -or- deriving shared secrets)

    • SM2 (China Regions only)

    ^

• :origin (String) —

  The source of the key material for the KMS key. You cannot change the origin after you create the KMS key. The default is AWS_KMS, which means that KMS creates the key material.

  To create a KMS key with no key material (for imported key material), set this value to EXTERNAL. For more information about importing key material into KMS, see Importing Key Material in the Key Management Service Developer Guide. The EXTERNAL origin value is valid only for symmetric KMS keys.

  To create a KMS key in an CloudHSM key store and create its key material in the associated CloudHSM cluster, set this value to AWS_CLOUDHSM. You must also use the CustomKeyStoreId parameter to identify the CloudHSM key store. The KeySpec value must be SYMMETRIC_DEFAULT.

  To create a KMS key in an external key store, set this value to EXTERNAL_KEY_STORE. You must also use the CustomKeyStoreId parameter to identify the external key store and the XksKeyId parameter to identify the associated external key. The KeySpec value must be SYMMETRIC_DEFAULT.

• :custom_key_store_id (String) —

  Creates the KMS key in the specified custom key store. The ConnectionState of the custom key store must be CONNECTED. To find the CustomKeyStoreID and ConnectionState use the DescribeCustomKeyStores operation.

  This parameter is valid only for symmetric encryption KMS keys in a single Region. You cannot create any other type of KMS key in a custom key store.

  When you create a KMS key in an CloudHSM key store, KMS generates a non-exportable 256-bit symmetric key in its associated CloudHSM cluster and associates it with the KMS key. When you create a KMS key in an external key store, you must use the XksKeyId parameter to specify an external key that serves as key material for the KMS key.

• :bypass_policy_lockout_safety_check (Boolean) —

  Skips ("bypasses") the key policy lockout safety check. The default value is false.

  Setting this value to true increases the risk that the KMS key becomes unmanageable. Do not set this value to true indiscriminately.

  For more information, see Default key policy in the Key Management Service Developer Guide.

  Use this parameter only when you intend to prevent the principal that is making the request from making a subsequent PutKeyPolicy request on the KMS key.

• :tags (Array<Types::Tag>) —

  Assigns one or more tags to the KMS key. Use this parameter to tag the KMS key when it is created. To tag an existing KMS key, use the TagResource operation.

  Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.

  Tagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key Management Service Developer Guide.

  To use this parameter, you must have kms:TagResource permission in an IAM policy.

  Each tag consists of a tag key and a tag value. Both the tag key and the tag value are required, but the tag value can be an empty (null) string. You cannot have more than one tag on a KMS key with the same tag key. If you specify an existing tag key with a different tag value, KMS replaces the current tag value with the specified one.

  When you add tags to an Amazon Web Services resource, Amazon Web Services generates a cost allocation report with usage and costs aggregated by tags. Tags can also be used to control access to a KMS key. For details, see Tags in KMS.

• :multi_region (Boolean) —

  Creates a multi-Region primary key that you can replicate into other Amazon Web Services Regions. You cannot change this value after you create the KMS key.

  For a multi-Region key, set this parameter to True. For a single-Region KMS key, omit this parameter or set it to False. The default value is False.

  This operation supports multi-Region keys, an KMS feature that lets you create multiple interoperable KMS keys in different Amazon Web Services Regions. Because these KMS keys have the same key ID, key material, and other metadata, you can use them interchangeably to encrypt data in one Amazon Web Services Region and decrypt it in a different Amazon Web Services Region without re-encrypting the data or making a cross-Region call. For more information about multi-Region keys, see Multi-Region keys in KMS in the Key Management Service Developer Guide.

  This value creates a primary key, not a replica. To create a replica key, use the ReplicateKey operation.

  You can create a symmetric or asymmetric multi-Region key, and you can create a multi-Region key with imported key material. However, you cannot create a multi-Region key in a custom key store.

• :xks_key_id (String) —

  Identifies the external key that serves as key material for the KMS key in an external key store. Specify the ID that the external key store proxy uses to refer to the external key. For help, see the documentation for your external key store proxy.

  This parameter is required for a KMS key with an Origin value of EXTERNAL_KEY_STORE. It is not valid for KMS keys with any other Origin value.

  The external key must be an existing 256-bit AES symmetric encryption key hosted outside of Amazon Web Services in an external key manager associated with the external key store specified by the CustomKeyStoreId parameter. This key must be enabled and configured to perform encryption and decryption. Each KMS key in an external key store must use a different external key. For details, see Requirements for a KMS key in an external key store in the Key Management Service Developer Guide.

  Each KMS key in an external key store is associated two backing keys. One is key material that KMS generates. The other is the external key specified by this parameter. When you use the KMS key in an external key store to encrypt data, the encryption operation is performed first by KMS using the KMS key material, and then by the external key manager using the specified external key, a process known as double encryption. For details, see Double encryption in the Key Management Service Developer Guide.

Returns:

• (Types::CreateKeyResponse) —

  Returns a response object which responds to the following methods:

  • #key_metadata => Types::KeyMetadata

See Also:

• AWS API Documentation

# The following example decrypts data that was encrypted with a symmetric encryption KMS key. The KeyId is not required
# when decrypting with a symmetric encryption key, but it is a best practice.

resp = client.decrypt({
  ciphertext_blob: "<binary data>", # The encrypted data (ciphertext).
  key_id: "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", # A key identifier for the KMS key to use to decrypt the data.
})
resp.to_h outputs the following:
{
  encryption_algorithm: "SYMMETRIC_DEFAULT", # The encryption algorithm that was used to decrypt the ciphertext. SYMMETRIC_DEFAULT is the only valid value for symmetric encryption in AWS KMS.
  key_id: "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", # The Amazon Resource Name (ARN) of the KMS key that was used to decrypt the data.
  key_material_id: "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", # The identifier of the key material used to decrypt the ciphertext.
  plaintext: "<binary data>", # The decrypted (plaintext) data.
}

# The following example decrypts data that was encrypted with an asymmetric encryption KMS key. When the KMS encryption
# key is asymmetric, you must specify the KMS key ID and the encryption algorithm that was used to encrypt the data.

resp = client.decrypt({
  ciphertext_blob: "<binary data>", # The encrypted data (ciphertext).
  encryption_algorithm: "RSAES_OAEP_SHA_256", # The encryption algorithm that was used to encrypt the data. This parameter is required to decrypt with an asymmetric KMS key.
  key_id: "0987dcba-09fe-87dc-65ba-ab0987654321", # A key identifier for the KMS key to use to decrypt the data. This parameter is required to decrypt with an asymmetric KMS key.
})
resp.to_h outputs the following:
{
  encryption_algorithm: "RSAES_OAEP_SHA_256", # The encryption algorithm that was used to decrypt the ciphertext.
  key_id: "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321", # The Amazon Resource Name (ARN) of the KMS key that was used to decrypt the data.
  plaintext: "<binary data>", # The decrypted (plaintext) data.
}

# The following Decrypt example includes the Recipient parameter with a signed attestation document from an AWS Nitro
# enclave. Instead of returning the decrypted data in plaintext (Plaintext), the operation returns the decrypted data
# encrypted by the public key from the attestation document (CiphertextForRecipient).

resp = client.decrypt({
  ciphertext_blob: "<binary data>", # The encrypted data. This ciphertext was encrypted with the KMS key
  key_id: "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", # The KMS key to use to decrypt the ciphertext
  recipient: {
    attestation_document: "<attestation document>", 
    key_encryption_algorithm: "RSAES_OAEP_SHA_256", 
  }, # Specifies the attestation document from the Nitro enclave and the encryption algorithm to use with the public key from the attestation document
})
resp.to_h outputs the following:
{
  ciphertext_for_recipient: "<binary data>", # The decrypted CiphertextBlob encrypted with the public key from the attestation document
  key_id: "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", # The KMS key that was used to decrypt the encrypted data (CiphertextBlob)
  plaintext: "", # This field is null or empty
}

resp = client.decrypt({
  ciphertext_blob: "data", # required
  encryption_context: {
    "EncryptionContextKey" => "EncryptionContextValue",
  },
  grant_tokens: ["GrantTokenType"],
  key_id: "KeyIdType",
  encryption_algorithm: "SYMMETRIC_DEFAULT", # accepts SYMMETRIC_DEFAULT, RSAES_OAEP_SHA_1, RSAES_OAEP_SHA_256, SM2PKE
  recipient: {
    key_encryption_algorithm: "RSAES_OAEP_SHA_256", # accepts RSAES_OAEP_SHA_256
    attestation_document: "data",
  },
  dry_run: false,
})

resp.key_id #=> String
resp.plaintext #=> String
resp.encryption_algorithm #=> String, one of "SYMMETRIC_DEFAULT", "RSAES_OAEP_SHA_1", "RSAES_OAEP_SHA_256", "SM2PKE"
resp.ciphertext_for_recipient #=> String
resp.key_material_id #=> String

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :ciphertext_blob (required, String, StringIO, File) —

  Ciphertext to be decrypted. The blob includes metadata.

• :encryption_context (Hash<String,String>) —

  Specifies the encryption context to use when decrypting the data. An encryption context is valid only for cryptographic operations with a symmetric encryption KMS key. The standard asymmetric encryption algorithms and HMAC algorithms that KMS uses do not support an encryption context.

  An encryption context is a collection of non-secret key-value pairs that represent additional authenticated data. When you use an encryption context to encrypt data, you must specify the same (an exact case-sensitive match) encryption context to decrypt the data. An encryption context is supported only on operations with symmetric encryption KMS keys. On operations with symmetric encryption KMS keys, an encryption context is optional, but it is strongly recommended.

  For more information, see Encryption context in the Key Management Service Developer Guide.

• :grant_tokens (Array<String>) —

  A list of grant tokens.

  Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. For more information, see Grant token and Using a grant token in the Key Management Service Developer Guide.

• :key_id (String) —

  Specifies the KMS key that KMS uses to decrypt the ciphertext.

  Enter a key ID of the KMS key that was used to encrypt the ciphertext. If you identify a different KMS key, the Decrypt operation throws an IncorrectKeyException.

  This parameter is required only when the ciphertext was encrypted under an asymmetric KMS key. If you used a symmetric encryption KMS key, KMS can get the KMS key from metadata that it adds to the symmetric ciphertext blob. However, it is always recommended as a best practice. This practice ensures that you use the KMS key that you intend.

  To specify a KMS key, use its key ID, key ARN, alias name, or alias ARN. When using an alias name, prefix it with "alias/". To specify a KMS key in a different Amazon Web Services account, you must use the key ARN or alias ARN.

  For example:

  • Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab

  • Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

  • Alias name: alias/ExampleAlias

  • Alias ARN: arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias

  To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey. To get the alias name and alias ARN, use ListAliases.

• :encryption_algorithm (String) —

  Specifies the encryption algorithm that will be used to decrypt the ciphertext. Specify the same algorithm that was used to encrypt the data. If you specify a different algorithm, the Decrypt operation fails.

  This parameter is required only when the ciphertext was encrypted under an asymmetric KMS key. The default value, SYMMETRIC_DEFAULT, represents the only supported algorithm that is valid for symmetric encryption KMS keys.

• :recipient (Types::RecipientInfo) —

  A signed attestation document from an Amazon Web Services Nitro enclave and the encryption algorithm to use with the enclave's public key. The only valid encryption algorithm is RSAES_OAEP_SHA_256.

  This parameter only supports attestation documents for Amazon Web Services Nitro Enclaves. To include this parameter, use the Amazon Web Services Nitro Enclaves SDK or any Amazon Web Services SDK.

  When you use this parameter, instead of returning the plaintext data, KMS encrypts the plaintext data with the public key in the attestation document, and returns the resulting ciphertext in the CiphertextForRecipient field in the response. This ciphertext can be decrypted only with the private key in the enclave. The Plaintext field in the response is null or empty.

  For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see How Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service Developer Guide.

• :dry_run (Boolean) —

  Checks if your request will succeed. DryRun is an optional parameter.

  To learn more about how to use this parameter, see Testing your permissions in the Key Management Service Developer Guide.

Returns:

• (Types::DecryptResponse) —

  Returns a response object which responds to the following methods:

  • #key_id => String
  • #plaintext => String
  • #encryption_algorithm => String
  • #ciphertext_for_recipient => String
  • #key_material_id => String

See Also:

• AWS API Documentation

# The following example deletes the specified alias.

resp = client.delete_alias({
  alias_name: "alias/ExampleAlias", # The alias to delete.
})

resp = client.delete_alias({
  alias_name: "AliasNameType", # required
})

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :alias_name (required, String) —

  The alias to be deleted. The alias name must begin with alias/ followed by the alias name, such as alias/ExampleAlias.

Returns:

• (Struct) —

  Returns an empty response.

See Also:

• AWS API Documentation

# This example deletes a custom key store from AWS KMS. This operation does not affect the backing key store, such as a
# CloudHSM cluster, external key store proxy, or your external key manager. This operation doesn't return any data. To
# verify that the operation was successful, use the DescribeCustomKeyStores operation.

resp = client.delete_custom_key_store({
  custom_key_store_id: "cks-1234567890abcdef0", # The ID of the custom key store to be deleted.
})
resp.to_h outputs the following:
{
}

resp = client.delete_custom_key_store({
  custom_key_store_id: "CustomKeyStoreIdType", # required
})

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :custom_key_store_id (required, String) —

  Enter the ID of the custom key store you want to delete. To find the ID of a custom key store, use the DescribeCustomKeyStores operation.

Returns:

• (Struct) —

  Returns an empty response.

See Also:

• AWS API Documentation

# The following example deletes the imported key material from the specified KMS key.

resp = client.delete_imported_key_material({
  key_id: "1234abcd-12ab-34cd-56ef-1234567890ab", # The identifier of the KMS key whose imported key material you are deleting. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
  key_material_id: "0b7fd7ddbac6eef27907413567cad8c810e2883dc8a7534067a82ee1142fc1e6", # Identifies the deleted key material.
})

resp = client.delete_imported_key_material({
  key_id: "KeyIdType", # required
  key_material_id: "BackingKeyIdType",
})

resp.key_id #=> String
resp.key_material_id #=> String

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :key_id (required, String) —

  Identifies the KMS key from which you are deleting imported key material. The Origin of the KMS key must be EXTERNAL.

  Specify the key ID or key ARN of the KMS key.

  For example:

  • Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab

  • Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

  To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey.

• :key_material_id (String) —

  Identifies the imported key material you are deleting.

  If no KeyMaterialId is specified, KMS deletes the current key material.

  To get the list of key material IDs associated with a KMS key, use ListKeyRotations.

Returns:

• (Types::DeleteImportedKeyMaterialResponse) —

  Returns a response object which responds to the following methods:

  • #key_id => String
  • #key_material_id => String

See Also:

• AWS API Documentation

# The following example derives a shared secret using a key agreement algorithm.

resp = client.derive_shared_secret({
  key_agreement_algorithm: "ECDH", # The key agreement algorithm used to derive the shared secret. The only valid value is ECDH.
  key_id: "1234abcd-12ab-34cd-56ef-1234567890ab", # The key identifier for an asymmetric KMS key pair. The private key in the specified key pair is used to derive the shared secret.
  public_key: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvH3Yj0wbkLEpUl95Cv1cJVjsVNSjwGq3tCLnzXfhVwVvmzGN8pYj3U8nKwgouaHbBWNJYjP5VutbbkKS4Kv4GojwZBJyHN17kmxo8yTjRmjR15SKIQ8cqRA2uaERMLnpztIXdZp232PQPbWGxDyXYJ0aJ5EFSag", # The public key in your peer's asymmetric key pair.
})
resp.to_h outputs the following:
{
  key_agreement_algorithm: "ECDH", # The key agreement algorithm used to derive the shared secret.
  key_id: "1234abcd-12ab-34cd-56ef-1234567890ab", # The asymmetric KMS key pair used to derive the shared secret.
  key_origin: "AWS_KMS", # The source of the key material for the specified KMS key.
  shared_secret: "MEYCIQCKZLWyTk5runarx6XiAkU9gv3lbwPO/pHa+DXFehzdDwIhANwpsIV2g/9SPWLLsF6p/hiSskuIXMTRwqrMdVKWTMHG", # The raw secret derived from the specified key agreement algorithm, private key in the asymmetric KMS key, and your peer's public key.
}

resp = client.derive_shared_secret({
  key_id: "KeyIdType", # required
  key_agreement_algorithm: "ECDH", # required, accepts ECDH
  public_key: "data", # required
  grant_tokens: ["GrantTokenType"],
  dry_run: false,
  recipient: {
    key_encryption_algorithm: "RSAES_OAEP_SHA_256", # accepts RSAES_OAEP_SHA_256
    attestation_document: "data",
  },
})

resp.key_id #=> String
resp.shared_secret #=> String
resp.ciphertext_for_recipient #=> String
resp.key_agreement_algorithm #=> String, one of "ECDH"
resp.key_origin #=> String, one of "AWS_KMS", "EXTERNAL", "AWS_CLOUDHSM", "EXTERNAL_KEY_STORE"

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :key_id (required, String) —

  Identifies an asymmetric NIST-recommended ECC or SM2 (China Regions only) KMS key. KMS uses the private key in the specified key pair to derive the shared secret. The key usage of the KMS key must be KEY_AGREEMENT. To find the KeyUsage of a KMS key, use the DescribeKey operation.

  To specify a KMS key, use its key ID, key ARN, alias name, or alias ARN. When using an alias name, prefix it with "alias/". To specify a KMS key in a different Amazon Web Services account, you must use the key ARN or alias ARN.

  For example:

  • Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab

  • Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

  • Alias name: alias/ExampleAlias

  • Alias ARN: arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias

  To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey. To get the alias name and alias ARN, use ListAliases.

• :key_agreement_algorithm (required, String) —

  Specifies the key agreement algorithm used to derive the shared secret. The only valid value is ECDH.

• :public_key (required, String, StringIO, File) —

  Specifies the public key in your peer's NIST-recommended elliptic curve (ECC) or SM2 (China Regions only) key pair.

  The public key must be a DER-encoded X.509 public key, also known as SubjectPublicKeyInfo (SPKI), as defined in RFC 5280.

  GetPublicKey returns the public key of an asymmetric KMS key pair in the required DER-encoded format.

  If you use Amazon Web Services CLI version 1, you must provide the DER-encoded X.509 public key in a file. Otherwise, the Amazon Web Services CLI Base64-encodes the public key a second time, resulting in a ValidationException.

  You can specify the public key as binary data in a file using fileb (fileb://<path-to-file>) or in-line using a Base64 encoded string.

• :grant_tokens (Array<String>) —

  A list of grant tokens.

  Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. For more information, see Grant token and Using a grant token in the Key Management Service Developer Guide.

• :dry_run (Boolean) —

  Checks if your request will succeed. DryRun is an optional parameter.

  To learn more about how to use this parameter, see Testing your permissions in the Key Management Service Developer Guide.

• :recipient (Types::RecipientInfo) —

  A signed attestation document from an Amazon Web Services Nitro enclave and the encryption algorithm to use with the enclave's public key. The only valid encryption algorithm is RSAES_OAEP_SHA_256.

  This parameter only supports attestation documents for Amazon Web Services Nitro Enclaves. To call DeriveSharedSecret for an Amazon Web Services Nitro Enclaves, use the Amazon Web Services Nitro Enclaves SDK to generate the attestation document and then use the Recipient parameter from any Amazon Web Services SDK to provide the attestation document for the enclave.

  When you use this parameter, instead of returning a plaintext copy of the shared secret, KMS encrypts the plaintext shared secret under the public key in the attestation document, and returns the resulting ciphertext in the CiphertextForRecipient field in the response. This ciphertext can be decrypted only with the private key in the enclave. The CiphertextBlob field in the response contains the encrypted shared secret derived from the KMS key specified by the KeyId parameter and public key specified by the PublicKey parameter. The SharedSecret field in the response is null or empty.

  For information about the interaction between KMS and Amazon Web Services Nitro Enclaves, see How Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service Developer Guide.

Returns:

• (Types::DeriveSharedSecretResponse) —

  Returns a response object which responds to the following methods:

  • #key_id => String
  • #shared_secret => String
  • #ciphertext_for_recipient => String
  • #key_agreement_algorithm => String
  • #key_origin => String

See Also:

• AWS API Documentation

# This example gets detailed information about all AWS KMS custom key stores in an AWS account and Region. To get all key
# stores, do not enter a custom key store name or ID.

resp = client.describe_custom_key_stores({
})
resp.to_h outputs the following:
{
  custom_key_stores: [
  ], # Details about each custom key store in the account and Region.
}

# This example gets detailed information about a particular AWS CloudHSM key store by specifying its friendly name. To
# limit the output to a particular custom key store, provide either the custom key store name or ID.

resp = client.describe_custom_key_stores({
  custom_key_store_name: "ExampleKeyStore", # The friendly name of the custom key store.
})
resp.to_h outputs the following:
{
  custom_key_stores: [
    {
      cloud_hsm_cluster_id: "cluster-234abcdefABC", 
      connection_state: "CONNECTED", 
      creation_date: Time.parse("1.499288695918E9"), 
      custom_key_store_id: "cks-1234567890abcdef0", 
      custom_key_store_name: "ExampleKeyStore", 
      custom_key_store_type: "AWS_CLOUDHSM", 
      trust_anchor_certificate: "<certificate appears here>", 
    }, 
  ], # Detailed information about the specified custom key store.
}

# This example gets detailed information about an external key store by specifying its ID.  The example external key store
# proxy uses public endpoint connectivity.

resp = client.describe_custom_key_stores({
  custom_key_store_id: "cks-9876543210fedcba9", # The ID of the custom key store.
})
resp.to_h outputs the following:
{
  custom_key_stores: [
    {
      connection_state: "CONNECTED", 
      creation_date: Time.parse("1.599288695918E9"), 
      custom_key_store_id: "cks-9876543210fedcba9", 
      custom_key_store_name: "ExampleExternalKeyStore", 
      custom_key_store_type: "EXTERNAL_KEY_STORE", 
      xks_proxy_configuration: {
        access_key_id: "ABCDE12345670EXAMPLE", 
        connectivity: "PUBLIC_ENDPOINT", 
        uri_endpoint: "https://myproxy.xks.example.com", 
        uri_path: "/kms/xks/v1", 
      }, 
    }, 
  ], # Detailed information about the specified custom key store.
}

# This example gets detailed information about a particular external key store by specifying its friendly name. To limit
# the output to a particular custom key store, provide either the custom key store name or ID. The proxy URI path for this
# external key store includes an optional prefix. Also, because this example external key store uses VPC endpoint
# connectivity, the response includes the associated VPC endpoint service name.

resp = client.describe_custom_key_stores({
  custom_key_store_name: "VPCExternalKeystore", 
})
resp.to_h outputs the following:
{
  custom_key_stores: [
    {
      connection_state: "CONNECTED", 
      creation_date: Time.parse("1.643057863.842"), 
      custom_key_store_id: "cks-876543210fedcba98", 
      custom_key_store_name: "ExampleVPCExternalKeyStore", 
      custom_key_store_type: "EXTERNAL_KEY_STORE", 
      xks_proxy_configuration: {
        access_key_id: "ABCDE12345670EXAMPLE", 
        connectivity: "VPC_ENDPOINT_SERVICE", 
        uri_endpoint: "https://myproxy-private.xks.example.com", 
        uri_path: "/example-prefix/kms/xks/v1", 
        vpc_endpoint_service_name: "com.amazonaws.vpce.us-east-1.vpce-svc-example1", 
      }, 
    }, 
  ], # Detailed information about the specified custom key store.
}

resp = client.describe_custom_key_stores({
  custom_key_store_id: "CustomKeyStoreIdType",
  custom_key_store_name: "CustomKeyStoreNameType",
  limit: 1,
  marker: "MarkerType",
})

resp.custom_key_stores #=> Array
resp.custom_key_stores[0].custom_key_store_id #=> String
resp.custom_key_stores[0].custom_key_store_name #=> String
resp.custom_key_stores[0].cloud_hsm_cluster_id #=> String
resp.custom_key_stores[0].trust_anchor_certificate #=> String
resp.custom_key_stores[0].connection_state #=> String, one of "CONNECTED", "CONNECTING", "FAILED", "DISCONNECTED", "DISCONNECTING"
resp.custom_key_stores[0].connection_error_code #=> String, one of "INVALID_CREDENTIALS", "CLUSTER_NOT_FOUND", "NETWORK_ERRORS", "INTERNAL_ERROR", "INSUFFICIENT_CLOUDHSM_HSMS", "USER_LOCKED_OUT", "USER_NOT_FOUND", "USER_LOGGED_IN", "SUBNET_NOT_FOUND", "INSUFFICIENT_FREE_ADDRESSES_IN_SUBNET", "XKS_PROXY_ACCESS_DENIED", "XKS_PROXY_NOT_REACHABLE", "XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND", "XKS_PROXY_INVALID_RESPONSE", "XKS_PROXY_INVALID_CONFIGURATION", "XKS_VPC_ENDPOINT_SERVICE_INVALID_CONFIGURATION", "XKS_PROXY_TIMED_OUT", "XKS_PROXY_INVALID_TLS_CONFIGURATION"
resp.custom_key_stores[0].creation_date #=> Time
resp.custom_key_stores[0].custom_key_store_type #=> String, one of "AWS_CLOUDHSM", "EXTERNAL_KEY_STORE"
resp.custom_key_stores[0].xks_proxy_configuration.connectivity #=> String, one of "PUBLIC_ENDPOINT", "VPC_ENDPOINT_SERVICE"
resp.custom_key_stores[0].xks_proxy_configuration.access_key_id #=> String
resp.custom_key_stores[0].xks_proxy_configuration.uri_endpoint #=> String
resp.custom_key_stores[0].xks_proxy_configuration.uri_path #=> String
resp.custom_key_stores[0].xks_proxy_configuration.vpc_endpoint_service_name #=> String
resp.next_marker #=> String
resp.truncated #=> Boolean

Parameters:

• params (Hash) (defaults to: {}) —

  ({})

Options Hash (params):

• :custom_key_store_id (String) —

  Gets only information about the specified custom key store. Enter the key store ID.

  By default, this operation gets information about all custom key stores in the account and Region. To limit the output to a particular custom key store, provide either the CustomKeyStoreId or CustomKeyStoreName parameter, but not both.

• :custom_key_store_name (String) —

  Gets only information about the specified custom key store. Enter the friendly name of the custom key store.

  By default, this operation gets information about all custom key stores in the account and Region. To limit the output to a particular custom key store, provide either the CustomKeyStoreId or CustomKeyStoreName parameter, but not both.

• :limit (Integer) —

  Use this parameter to specify the maximum number of items to return. When this value is present, KMS does not return more than the specified number of items, but it might return fewer.

• :marker (String) —

  Use this parameter in a subsequent request after you receive a response with truncated results. Set it to the value of NextMarker from the truncated response you just received.

Returns:

• (Types::DescribeCustomKeyStoresResponse) —

  Returns a response object which responds to the following methods:

  • #custom_key_stores => Array<Types::CustomKeyStoresListEntry>
  • #next_marker => String
  • #truncated => Boolean

See Also:

• AWS API Documentation