KMS / Client / generate_random

generate_random#

KMS.Client.generate_random(**kwargs)#

Returns a random byte string that is cryptographically secure.

You must use the NumberOfBytes parameter to specify the length of the random byte string. There is no default value for string length.

By default, the random byte string is generated in KMS. To generate the byte string in the CloudHSM cluster associated with an CloudHSM key store, use the CustomKeyStoreId parameter.

Applications in Amazon Web Services Nitro Enclaves can call this operation by using the Amazon Web Services Nitro Enclaves Development Kit. For information about the supporting parameters, see How Amazon Web Services Nitro Enclaves use KMS in the Key Management Service Developer Guide.

For more information about entropy and random number generation, see Key Management Service Cryptographic Details.

Cross-account use: Not applicable. GenerateRandom does not use any account-specific resources, such as KMS keys.

Required permissions: kms:GenerateRandom (IAM policy)

See also: AWS API Documentation

Request Syntax

response = client.generate_random(
    NumberOfBytes=123,
    CustomKeyStoreId='string'
)
Parameters:

  • NumberOfBytes (integer) – The length of the random byte string. This parameter is required.

  • CustomKeyStoreId (string) –

    Generates the random byte string in the CloudHSM cluster that is associated with the specified CloudHSM key store. To find the ID of a custom key store, use the DescribeCustomKeyStores operation.

    External key store IDs are not valid for this parameter. If you specify the ID of an external key store, GenerateRandom throws an UnsupportedOperationException.

Return type:

dict

Returns:

Response Syntax

{
    'Plaintext': b'bytes'
}

Response Structure

  • (dict) –

    • Plaintext (bytes) –

      The random byte string. When you use the HTTP API or the Amazon Web Services CLI, the value is Base64-encoded. Otherwise, it is not Base64-encoded.

Exceptions

  • KMS.Client.exceptions.DependencyTimeoutException

  • KMS.Client.exceptions.KMSInternalException

  • KMS.Client.exceptions.UnsupportedOperationException

  • KMS.Client.exceptions.CustomKeyStoreNotFoundException

  • KMS.Client.exceptions.CustomKeyStoreInvalidStateException

Examples

The following example generates 32 bytes of random data.

response = client.generate_random(
    # The length of the random data, specified in number of bytes.
    NumberOfBytes=32,
)

print(response)

Expected Output:

{
    # The random data.
    'Plaintext': '<binary data>',
    'ResponseMetadata': {
        '...': '...',
    },
}