AWS API Changes

2019/05/02 - AWS Key Management Service - 1 updated api methods

Changes AWS Key Management Service (KMS) can return an INTERNAL_ERROR connection error code if it cannot connect a custom key store to its AWS CloudHSM cluster. INTERNAL_ERROR is one of several connection error codes that help you to diagnose and fix a problem with your custom key store.

DescribeCustomKeyStores (updated)

Link ¶
Changes (response)

{'CustomKeyStores': {'ConnectionErrorCode': ['INTERNAL_ERROR']}}

Gets information about custom key stores in the account and region.

This operation is part of the Custom Key Store feature feature in AWS KMS, which combines the convenience and extensive integration of AWS KMS with the isolation and control of a single-tenant key store.

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 AWS CloudHSM cluster, 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 use the DisconnectCustomKeyStore operation to disconnect it. If your custom key store state is CONNECTED but you are having trouble using it, make sure that its associated AWS CloudHSM cluster is active and contains the minimum number of HSMs required for the operation, if any.

For help repairing your custom key store, see the Troubleshooting Custom Key Stores topic in the AWS Key Management Service Developer Guide .

See also: AWS API Documentation

Request Syntax

client.describe_custom_key_stores(
    CustomKeyStoreId='string',
    CustomKeyStoreName='string',
    Limit=123,
    Marker='string'
)

type CustomKeyStoreId

string

param CustomKeyStoreId

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, you can use either the CustomKeyStoreId or CustomKeyStoreName parameter, but not both.

type CustomKeyStoreName

string

param CustomKeyStoreName

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

type Limit

integer

param Limit

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

type Marker

string

param Marker

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.

rtype

dict

returns

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',
            'CreationDate': datetime(2015, 1, 1)
        },
    ],
    '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 AWS CloudHSM cluster that is associated with the custom key store.
    - TrustAnchorCertificate (string) --
      
      The trust anchor certificate of the associated AWS CloudHSM cluster. When you initialize the cluster , you create this certificate and save it in the customerCA.crt file.
    - ConnectionState (string) --
      
      Indicates whether the custom key store is connected to its AWS CloudHSM cluster.
      
      You can create and use CMKs in your custom key stores only when its connection state is CONNECTED .
      
      The value is DISCONNECTED 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 its associated AWS CloudHSM cluster is active and contains at least one active HSM.
      
      A value of FAILED indicates that an attempt to connect was unsuccessful. For help resolving a connection failure, see Troubleshooting a Custom Key Store in the AWS Key Management Service Developer Guide .
    - ConnectionErrorCode (string) --
      
      Describes the connection error. Valid values are:
      - CLUSTER_NOT_FOUND - AWS KMS cannot find the AWS CloudHSM cluster with the specified cluster ID.
      - INSUFFICIENT_CLOUDHSM_HSMS - The associated AWS CloudHSM cluster does not contain any active HSMs. To connect a custom key store to its AWS CloudHSM cluster, the cluster must contain at least one active HSM.
      - INTERNAL_ERROR - AWS 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.
      - INVALID_CREDENTIALS - AWS KMS does not have the correct password for the kmsuser crypto user in the AWS CloudHSM cluster.
      - NETWORK_ERRORS - Network errors are preventing AWS KMS from connecting to the custom key store.
      - USER_LOCKED_OUT - The kmsuser CU account is locked out of the associated AWS CloudHSM cluster due to too many failed password attempts. Before you can connect your custom key store to its AWS CloudHSM cluster, you must change the kmsuser account password and update the password value for the custom key store.
      For help with connection failures, see Troubleshooting Custom Key Stores in the AWS Key Management Service Developer Guide .
    - CreationDate (datetime) --
      
      The date and time when the custom key store was created.
- 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 thisresponse to the Marker parameter in a subsequent request.