2025/10/30 - AWS Key Management Service - 3 updated api methods
Changes Add cross account VPC endpoint service connectivity support to CustomKeyStore.
{'XksProxyVpcEndpointServiceOwner': 'string'}
Creates a custom key store backed by a key store that you own and manage. When you use a KMS key in a custom key store for a cryptographic operation, the cryptographic operation is actually performed in your key store using your keys. KMS supports CloudHSM key stores backed by an CloudHSM cluster and external key stores backed by an external key store proxy and external key manager outside of Amazon Web Services.
This operation is part of the custom key stores feature in KMS, which combines the convenience and extensive integration of KMS with the isolation and control of a key store that you own and manage.
Before you create the custom key store, the required elements must be in place and operational. We recommend that you use the test tools that KMS provides to verify the configuration your external key store proxy. For details about the required elements and verification tests, see Assemble the prerequisites (for CloudHSM key stores) or Assemble the prerequisites (for external key stores) in the Key Management Service Developer Guide.
To create a custom key store, use the following parameters.
To create an CloudHSM key store, specify the CustomKeyStoreName, CloudHsmClusterId, KeyStorePassword, and TrustAnchorCertificate. The CustomKeyStoreType parameter is optional for CloudHSM key stores. If you include it, set it to the default value, AWS_CLOUDHSM. For help with failures, see Troubleshooting an CloudHSM key store in the Key Management Service Developer Guide.
To create an external key store, specify the CustomKeyStoreName and a CustomKeyStoreType of EXTERNAL_KEY_STORE. Also, specify values for XksProxyConnectivity, XksProxyAuthenticationCredential, XksProxyUriEndpoint, and XksProxyUriPath. If your XksProxyConnectivity value is VPC_ENDPOINT_SERVICE, specify the XksProxyVpcEndpointServiceName parameter. For help with failures, see Troubleshooting an external key store in the Key Management Service Developer Guide.
When the operation completes successfully, it returns the ID of the new custom key store. Before you can use your new custom key store, you need to use the ConnectCustomKeyStore operation to connect a new CloudHSM key store to its CloudHSM cluster, or to connect a new external key store to the external key store proxy for your external key manager. Even if you are not going to use your custom key store immediately, you might want to connect it to verify that all settings are correct and then disconnect it until you are ready to use it.
Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
Required permissions: kms:CreateCustomKeyStore (IAM policy).
Related operations:
ConnectCustomKeyStore
DeleteCustomKeyStore
DescribeCustomKeyStores
DisconnectCustomKeyStore
UpdateCustomKeyStore
Eventual consistency: The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.
See also: AWS API Documentation
Request Syntax
client.create_custom_key_store(
CustomKeyStoreName='string',
CloudHsmClusterId='string',
TrustAnchorCertificate='string',
KeyStorePassword='string',
CustomKeyStoreType='AWS_CLOUDHSM'|'EXTERNAL_KEY_STORE',
XksProxyUriEndpoint='string',
XksProxyUriPath='string',
XksProxyVpcEndpointServiceName='string',
XksProxyVpcEndpointServiceOwner='string',
XksProxyAuthenticationCredential={
'AccessKeyId': 'string',
'RawSecretAccessKey': 'string'
},
XksProxyConnectivity='PUBLIC_ENDPOINT'|'VPC_ENDPOINT_SERVICE'
)
string
[REQUIRED]
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.
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.
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.
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.
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.
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.
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.
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.
string
Specifies the Amazon Web Services account ID that owns the Amazon VPC service endpoint for the interface that is used to communicate with your external key store proxy (XKS proxy). This parameter is optional. If not provided, the Amazon Web Services account ID calling the action will be used.
dict
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.
AccessKeyId (string) -- [REQUIRED]
A unique identifier for the raw secret access key.
RawSecretAccessKey (string) -- [REQUIRED]
A secret string of 43-64 characters. Valid characters are a-z, A-Z, 0-9, /, +, and =.
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.
dict
Response Syntax
{
'CustomKeyStoreId': 'string'
}
Response Structure
(dict) --
CustomKeyStoreId (string) --
A unique identifier for the new custom key store.
{'CustomKeyStores': {'XksProxyConfiguration': {'VpcEndpointServiceOwner': 'string'}}}
Gets information about custom key stores in the account and Region.
This operation is part of the custom key stores feature in KMS, which combines the convenience and extensive integration of KMS with the isolation and control of a key store that you own and manage.
By default, this operation returns information about all custom key stores in the account and Region. To get only information about a particular custom key store, use either the CustomKeyStoreName or CustomKeyStoreId parameter (but not both).
To determine whether the custom key store is connected to its CloudHSM cluster or external key store proxy, use the ConnectionState element in the response. If an attempt to connect the custom key store failed, the ConnectionState value is FAILED and the ConnectionErrorCode element in the response indicates the cause of the failure. For help interpreting the ConnectionErrorCode, see CustomKeyStoresListEntry.
Custom key stores have a DISCONNECTED connection state if the key store has never been connected or you used the DisconnectCustomKeyStore operation to disconnect it. Otherwise, the connection state is CONNECTED. If your custom key store connection state is CONNECTED but you are having trouble using it, verify that the backing store is active and available. For an CloudHSM key store, verify that the associated CloudHSM cluster is active and contains the minimum number of HSMs required for the operation, if any. For an external key store, verify that the external key store proxy and its associated external key manager are reachable and enabled.
For help repairing your CloudHSM key store, see the Troubleshooting CloudHSM key stores. For help repairing your external key store, see the Troubleshooting external key stores. Both topics are in the Key Management Service Developer Guide.
Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
Required permissions: kms:DescribeCustomKeyStores (IAM policy)
Related operations:
ConnectCustomKeyStore
CreateCustomKeyStore
DeleteCustomKeyStore
DisconnectCustomKeyStore
UpdateCustomKeyStore
Eventual consistency: The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.
See also: AWS API Documentation
Request Syntax
client.describe_custom_key_stores(
CustomKeyStoreId='string',
CustomKeyStoreName='string',
Limit=123,
Marker='string'
)
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.
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.
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.
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.
dict
Response Syntax
{
'CustomKeyStores': [
{
'CustomKeyStoreId': 'string',
'CustomKeyStoreName': 'string',
'CloudHsmClusterId': 'string',
'TrustAnchorCertificate': 'string',
'ConnectionState': 'CONNECTED'|'CONNECTING'|'FAILED'|'DISCONNECTED'|'DISCONNECTING',
'ConnectionErrorCode': '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',
'CreationDate': datetime(2015, 1, 1),
'CustomKeyStoreType': 'AWS_CLOUDHSM'|'EXTERNAL_KEY_STORE',
'XksProxyConfiguration': {
'Connectivity': 'PUBLIC_ENDPOINT'|'VPC_ENDPOINT_SERVICE',
'AccessKeyId': 'string',
'UriEndpoint': 'string',
'UriPath': 'string',
'VpcEndpointServiceName': 'string',
'VpcEndpointServiceOwner': 'string'
}
},
],
'NextMarker': 'string',
'Truncated': True|False
}
Response Structure
(dict) --
CustomKeyStores (list) --
Contains metadata about each custom key store.
(dict) --
Contains information about each custom key store in the custom key store list.
CustomKeyStoreId (string) --
A unique identifier for the custom key store.
CustomKeyStoreName (string) --
The user-specified friendly name for the custom key store.
CloudHsmClusterId (string) --
A unique identifier for the CloudHSM cluster that is associated with an CloudHSM key store. This field appears only when the CustomKeyStoreType is AWS_CLOUDHSM.
TrustAnchorCertificate (string) --
The trust anchor certificate of the CloudHSM cluster associated with an CloudHSM key store. When you initialize the cluster, you create this certificate and save it in the customerCA.crt file.
This field appears only when the CustomKeyStoreType is AWS_CLOUDHSM.
ConnectionState (string) --
Indicates whether the custom key store is connected to its backing key store. For an CloudHSM key store, the ConnectionState indicates whether it is connected to its CloudHSM cluster. For an external key store, the ConnectionState indicates whether it is connected to the external key store proxy that communicates with your external key manager.
You can create and use KMS keys in your custom key stores only when its ConnectionState is CONNECTED.
The ConnectionState value is DISCONNECTED only if the key store has never been connected or you use the DisconnectCustomKeyStore operation to disconnect it. If the value is CONNECTED but you are having trouble using the custom key store, make sure that the backing key store is reachable and active. For an CloudHSM key store, verify that its associated CloudHSM cluster is active and contains at least one active HSM. For an external key store, verify that the external key store proxy and external key manager are connected and enabled.
A value of FAILED indicates that an attempt to connect was unsuccessful. The ConnectionErrorCode field in the response indicates the cause of the failure. For help resolving a connection failure, see Troubleshooting a custom key store in the Key Management Service Developer Guide.
ConnectionErrorCode (string) --
Describes the connection error. This field appears in the response only when the ConnectionState is FAILED.
Many failures can be resolved by updating the properties of the custom key store. To update a custom key store, disconnect it ( DisconnectCustomKeyStore), correct the errors ( UpdateCustomKeyStore), and try to connect again ( ConnectCustomKeyStore). For additional help resolving these errors, see How to Fix a Connection Failure in Key Management Service Developer Guide.
All custom key stores:
INTERNAL_ERROR — KMS could not complete the request due to an internal error. Retry the request. For ConnectCustomKeyStore requests, disconnect the custom key store before trying to connect again.
NETWORK_ERRORS — Network errors are preventing KMS from connecting the custom key store to its backing key store.
CloudHSM key stores:
CLUSTER_NOT_FOUND — KMS cannot find the CloudHSM cluster with the specified cluster ID.
INSUFFICIENT_CLOUDHSM_HSMS — The associated CloudHSM cluster does not contain any active HSMs. To connect a custom key store to its CloudHSM cluster, the cluster must contain at least one active HSM.
INSUFFICIENT_FREE_ADDRESSES_IN_SUBNET — At least one private subnet associated with the CloudHSM cluster doesn't have any available IP addresses. A CloudHSM key store connection requires one free IP address in each of the associated private subnets, although two are preferable. For details, see How to Fix a Connection Failure in the Key Management Service Developer Guide.
INVALID_CREDENTIALS — The KeyStorePassword for the custom key store doesn't match the current password of the kmsuser crypto user in the CloudHSM cluster. Before you can connect your custom key store to its CloudHSM cluster, you must change the kmsuser account password and update the KeyStorePassword value for the custom key store.
SUBNET_NOT_FOUND — A subnet in the CloudHSM cluster configuration was deleted. If KMS cannot find all of the subnets in the cluster configuration, attempts to connect the custom key store to the CloudHSM cluster fail. To fix this error, create a cluster from a recent backup and associate it with your custom key store. (This process creates a new cluster configuration with a VPC and private subnets.) For details, see How to Fix a Connection Failure in the Key Management Service Developer Guide.
USER_LOCKED_OUT — The kmsuser CU account is locked out of the associated CloudHSM cluster due to too many failed password attempts. Before you can connect your custom key store to its CloudHSM cluster, you must change the kmsuser account password and update the key store password value for the custom key store.
USER_LOGGED_IN — The kmsuser CU account is logged into the associated CloudHSM cluster. This prevents KMS from rotating the kmsuser account password and logging into the cluster. Before you can connect your custom key store to its CloudHSM cluster, you must log the kmsuser CU out of the cluster. If you changed the kmsuser password to log into the cluster, you must also and update the key store password value for the custom key store. For help, see How to Log Out and Reconnect in the Key Management Service Developer Guide.
USER_NOT_FOUND — KMS cannot find a kmsuser CU account in the associated CloudHSM cluster. Before you can connect your custom key store to its CloudHSM cluster, you must create a kmsuser CU account in the cluster, and then update the key store password value for the custom key store.
External key stores:
INVALID_CREDENTIALS — One or both of the XksProxyAuthenticationCredential values is not valid on the specified external key store proxy.
XKS_PROXY_ACCESS_DENIED — KMS requests are denied access to the external key store proxy. If the external key store proxy has authorization rules, verify that they permit KMS to communicate with the proxy on your behalf.
XKS_PROXY_INVALID_CONFIGURATION — A configuration error is preventing the external key store from connecting to its proxy. Verify the value of the XksProxyUriPath.
XKS_PROXY_INVALID_RESPONSE — KMS cannot interpret the response from the external key store proxy. If you see this connection error code repeatedly, notify your external key store proxy vendor.
XKS_PROXY_INVALID_TLS_CONFIGURATION — KMS cannot connect to the external key store proxy because the TLS configuration is invalid. Verify that the XKS proxy supports TLS 1.2 or 1.3. Also, verify that the TLS certificate is not expired, and that it matches the hostname in the XksProxyUriEndpoint value, and that it is signed by a certificate authority included in the Trusted Certificate Authorities list.
XKS_PROXY_NOT_REACHABLE — KMS can't communicate with your external key store proxy. Verify that the XksProxyUriEndpoint and XksProxyUriPath are correct. Use the tools for your external key store proxy to verify that the proxy is active and available on its network. Also, verify that your external key manager instances are operating properly. Connection attempts fail with this connection error code if the proxy reports that all external key manager instances are unavailable.
XKS_PROXY_TIMED_OUT — KMS can connect to the external key store proxy, but the proxy does not respond to KMS in the time allotted. If you see this connection error code repeatedly, notify your external key store proxy vendor.
XKS_VPC_ENDPOINT_SERVICE_INVALID_CONFIGURATION — The Amazon VPC endpoint service configuration doesn't conform to the requirements for an KMS external key store.
The VPC endpoint service must be an endpoint service for interface endpoints in the caller's Amazon Web Services account.
It must have a network load balancer (NLB) connected to at least two subnets, each in a different Availability Zone.
The Allow principals list must include the KMS service principal for the Region, cks.kms.<region>.amazonaws.com, such as cks.kms.us-east-1.amazonaws.com.
It must not require acceptance of connection requests.
It must have a private DNS name. The private DNS name for an external key store with VPC_ENDPOINT_SERVICE connectivity must be unique in its Amazon Web Services Region.
The domain of the private DNS name must have a verification status of verified.
The TLS certificate specifies the private DNS hostname at which the endpoint is reachable.
XKS_VPC_ENDPOINT_SERVICE_NOT_FOUND — KMS can't find the VPC endpoint service that it uses to communicate with the external key store proxy. Verify that the XksProxyVpcEndpointServiceName is correct and the KMS service principal has service consumer permissions on the Amazon VPC endpoint service.
CreationDate (datetime) --
The date and time when the custom key store was created.
CustomKeyStoreType (string) --
Indicates the type of the custom key store. AWS_CLOUDHSM indicates a custom key store backed by an CloudHSM cluster. EXTERNAL_KEY_STORE indicates a custom key store backed by an external key store proxy and external key manager outside of Amazon Web Services.
XksProxyConfiguration (dict) --
Configuration settings for the external key store proxy (XKS proxy). The external key store proxy translates KMS requests into a format that your external key manager can understand. The proxy configuration includes connection information that KMS requires.
This field appears only when the CustomKeyStoreType is EXTERNAL_KEY_STORE.
Connectivity (string) --
Indicates whether the external key store proxy uses a public endpoint or an Amazon VPC endpoint service to communicate with KMS.
AccessKeyId (string) --
The part of the external key store proxy authentication credential that uniquely identifies the secret access key.
UriEndpoint (string) --
The URI endpoint for the external key store proxy.
If the external key store proxy has a public endpoint, it is displayed here.
If the external key store proxy uses an Amazon VPC endpoint service name, this field displays the private DNS name associated with the VPC endpoint service.
UriPath (string) --
The path to the external key store proxy APIs.
VpcEndpointServiceName (string) --
The Amazon VPC endpoint service used to communicate with the external key store proxy. This field appears only when the external key store proxy uses an Amazon VPC endpoint service to communicate with KMS.
VpcEndpointServiceOwner (string) --
The Amazon Web Services account ID that owns the Amazon VPC endpoint service used to communicate with the external key store proxy (XKS). This field appears only when the XKS uses an VPC endpoint service to communicate with KMS.
NextMarker (string) --
When Truncated is true, this element is present and contains the value to use for the Marker parameter in a subsequent request.
Truncated (boolean) --
A flag that indicates whether there are more items in the list. When this value is true, the list in this response is truncated. To get more items, pass the value of the NextMarker element in this response to the Marker parameter in a subsequent request.
{'XksProxyVpcEndpointServiceOwner': 'string'}
Changes the properties of a custom key store. You can use this operation to change the properties of an CloudHSM key store or an external key store.
Use the required CustomKeyStoreId parameter to identify the custom key store. Use the remaining optional parameters to change its properties. This operation does not return any property values. To verify the updated property values, use the DescribeCustomKeyStores operation.
This operation is part of the custom key stores feature in KMS, which combines the convenience and extensive integration of KMS with the isolation and control of a key store that you own and manage.
For an CloudHSM key store, you can use this operation to change the custom key store friendly name ( NewCustomKeyStoreName), to tell KMS about a change to the kmsuser crypto user password ( KeyStorePassword), or to associate the custom key store with a different, but related, CloudHSM cluster ( CloudHsmClusterId). To update any property of an CloudHSM key store, the ConnectionState of the CloudHSM key store must be DISCONNECTED.
For an external key store, you can use this operation to change the custom key store friendly name ( NewCustomKeyStoreName), or to tell KMS about a change to the external key store proxy authentication credentials ( XksProxyAuthenticationCredential), connection method ( XksProxyConnectivity), external proxy endpoint ( XksProxyUriEndpoint) and path ( XksProxyUriPath). For external key stores with an XksProxyConnectivity of VPC_ENDPOINT_SERVICE, you can also update the Amazon VPC endpoint service name ( XksProxyVpcEndpointServiceName). To update most properties of an external key store, the ConnectionState of the external key store must be DISCONNECTED. However, you can update the CustomKeyStoreName, XksProxyAuthenticationCredential, and XksProxyUriPath of an external key store when it is in the CONNECTED or DISCONNECTED state.
If your update requires a DISCONNECTED state, before using UpdateCustomKeyStore, use the DisconnectCustomKeyStore operation to disconnect the custom key store. After the UpdateCustomKeyStore operation completes, use the ConnectCustomKeyStore to reconnect the custom key store. To find the ConnectionState of the custom key store, use the DescribeCustomKeyStores operation.
Before updating the custom key store, verify that the new values allow KMS to connect the custom key store to its backing key store. For example, before you change the XksProxyUriPath value, verify that the external key store proxy is reachable at the new path.
If the operation succeeds, it returns a JSON object with no properties.
Cross-account use: No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.
Required permissions: kms:UpdateCustomKeyStore (IAM policy)
Related operations:
ConnectCustomKeyStore
CreateCustomKeyStore
DeleteCustomKeyStore
DescribeCustomKeyStores
DisconnectCustomKeyStore
Eventual consistency: The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.
See also: AWS API Documentation
Request Syntax
client.update_custom_key_store(
CustomKeyStoreId='string',
NewCustomKeyStoreName='string',
KeyStorePassword='string',
CloudHsmClusterId='string',
XksProxyUriEndpoint='string',
XksProxyUriPath='string',
XksProxyVpcEndpointServiceName='string',
XksProxyVpcEndpointServiceOwner='string',
XksProxyAuthenticationCredential={
'AccessKeyId': 'string',
'RawSecretAccessKey': 'string'
},
XksProxyConnectivity='PUBLIC_ENDPOINT'|'VPC_ENDPOINT_SERVICE'
)
string
[REQUIRED]
Identifies the custom key store that you want to update. Enter the ID of the custom key store. To find the ID of a custom key store, use the DescribeCustomKeyStores operation.
string
Changes the friendly name of the custom key store to the value that you specify. The custom key store name must be unique in the Amazon Web Services account.
To change this value, an CloudHSM key store must be disconnected. An external key store can be connected or disconnected.
string
Enter the current password of the kmsuser crypto user (CU) in the CloudHSM cluster that is associated with the custom key store. This parameter is valid only for custom key stores with a CustomKeyStoreType of AWS_CLOUDHSM.
This parameter tells KMS the current password of the kmsuser crypto user (CU). It does not set or change the password of any users in the CloudHSM cluster.
To change this value, the CloudHSM key store must be disconnected.
string
Associates the custom key store with a related CloudHSM cluster. This parameter is valid only for custom key stores with a CustomKeyStoreType of AWS_CLOUDHSM.
Enter the cluster ID of the cluster that you used to create the custom key store or a cluster that shares a backup history and has the same cluster certificate as the original cluster. You cannot use this parameter to associate a custom key store with an unrelated cluster. In addition, the replacement cluster must fulfill the requirements for a cluster associated with a custom key store. To view the cluster certificate of a cluster, use the DescribeClusters operation.
To change this value, the CloudHSM key store must be disconnected.
string
Changes the URI endpoint that KMS uses to connect to your external key store proxy (XKS proxy). This parameter is valid only for custom key stores with a CustomKeyStoreType of EXTERNAL_KEY_STORE.
For external key stores with an XksProxyConnectivity value of PUBLIC_ENDPOINT, the protocol must be HTTPS.
For external key stores with an XksProxyConnectivity value of VPC_ENDPOINT_SERVICE, specify https:// followed by the private DNS name associated with the VPC endpoint service. Each external key store must use a different private DNS name.
The combined XksProxyUriEndpoint and XksProxyUriPath values must be unique in the Amazon Web Services account and Region.
To change this value, the external key store must be disconnected.
string
Changes the base path to the proxy APIs for this external key store. To find this value, see the documentation for your external key manager and external key store proxy (XKS proxy). This parameter is valid only for 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. You can include an optional prefix between the required elements such as /example/kms/xks/v1.
The combined XksProxyUriEndpoint and XksProxyUriPath values must be unique in the Amazon Web Services account and Region.
You can change this value when the external key store is connected or disconnected.
string
Changes the name that KMS uses to identify the Amazon VPC endpoint service for your external key store proxy (XKS proxy). This parameter is valid when the CustomKeyStoreType is EXTERNAL_KEY_STORE and the XksProxyConnectivity is VPC_ENDPOINT_SERVICE.
To change this value, the external key store must be disconnected.
string
Changes the Amazon Web Services account ID that KMS uses to identify the Amazon VPC endpoint service for your external key store proxy (XKS proxy). This parameter is optional. If not specified, the current Amazon Web Services account ID for the VPC endpoint service will not be updated.
To change this value, the external key store must be disconnected.
dict
Changes the credentials that KMS uses to sign requests to the external key store proxy (XKS proxy). This parameter is valid only for custom key stores with a CustomKeyStoreType of EXTERNAL_KEY_STORE.
You must specify both the AccessKeyId and SecretAccessKey value in the authentication credential, even if you are only updating one value.
This parameter doesn't establish or change your authentication credentials on the proxy. It just tells KMS the credential that you established with your external key store proxy. For example, if you rotate the credential on your external key store proxy, you can use this parameter to update the credential in KMS.
You can change this value when the external key store is connected or disconnected.
AccessKeyId (string) -- [REQUIRED]
A unique identifier for the raw secret access key.
RawSecretAccessKey (string) -- [REQUIRED]
A secret string of 43-64 characters. Valid characters are a-z, A-Z, 0-9, /, +, and =.
string
Changes the connectivity setting for the external key store. To indicate that the external key store proxy uses a Amazon VPC endpoint service to communicate with KMS, specify VPC_ENDPOINT_SERVICE. Otherwise, specify PUBLIC_ENDPOINT.
If you change the XksProxyConnectivity to VPC_ENDPOINT_SERVICE, you must also change the XksProxyUriEndpoint and add an XksProxyVpcEndpointServiceName value.
If you change the XksProxyConnectivity to PUBLIC_ENDPOINT, you must also change the XksProxyUriEndpoint and specify a null or empty string for the XksProxyVpcEndpointServiceName value.
To change this value, the external key store must be disconnected.
dict
Response Syntax
{}
Response Structure
(dict) --