AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.
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.
GenerateRandom also supports Amazon
Web Services Nitro Enclaves, which provide an isolated compute environment in
Amazon EC2. To call GenerateRandom for a Nitro enclave, use the Amazon
Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the Recipient
parameter to provide the attestation document for the enclave. Instead of plaintext
bytes, the response includes the plaintext bytes encrypted under the public key from
the attestation document (CiphertextForRecipient).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.
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)
Eventual consistency: The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.
For .NET Core this operation is only available in asynchronous form. Please refer to GenerateRandomAsync.
Namespace: Amazon.KeyManagementService
Assembly: AWSSDK.KeyManagementService.dll
Version: 3.x.y.z
public virtual GenerateRandomResponse GenerateRandom( GenerateRandomRequest request )
Container for the necessary parameters to execute the GenerateRandom service method.
| Exception | Condition |
|---|---|
| CustomKeyStoreInvalidStateException | The request was rejected because of the ConnectionState of the custom key store. To get the ConnectionState of a custom key store, use the DescribeCustomKeyStores operation. This exception is thrown under the following conditions: You requested the ConnectCustomKeyStore operation on a custom key store with a ConnectionState of DISCONNECTING or FAILED. This operation is valid for all other ConnectionState values. To reconnect a custom key store in a FAILED state, disconnect it (DisconnectCustomKeyStore), then connect it (ConnectCustomKeyStore). You requested the CreateKey operation in a custom key store that is not connected. This operations is valid only when the custom key store ConnectionState is CONNECTED. You requested the DisconnectCustomKeyStore operation on a custom key store with a ConnectionState of DISCONNECTING or DISCONNECTED. This operation is valid for all other ConnectionState values. You requested the UpdateCustomKeyStore or DeleteCustomKeyStore operation on a custom key store that is not disconnected. This operation is valid only when the custom key store ConnectionState is DISCONNECTED. You requested the GenerateRandom operation in an CloudHSM key store that is not connected. This operation is valid only when the CloudHSM key store ConnectionState is CONNECTED. |
| CustomKeyStoreNotFoundException | The request was rejected because KMS cannot find a custom key store with the specified key store name or ID. |
| DependencyTimeoutException | The system timed out while trying to fulfill the request. You can retry the request. |
| KMSInternalException | The request was rejected because an internal exception occurred. The request can be retried. |
| UnsupportedOperationException | The request was rejected because a specified parameter is not supported or a specified resource is not valid for this operation. |
The following example generates 32 bytes of random data.
var client = new AmazonKeyManagementServiceClient();
var response = client.GenerateRandom(new GenerateRandomRequest
{
NumberOfBytes = 32 // The length of the random data, specified in number of bytes.
});
MemoryStream plaintext = response.Plaintext; // The random data.
The following example includes the Recipient parameter with a signed attestation document from an AWS Nitro enclave. Instead of returning a plaintext (unencrypted) byte string, GenerateRandom returns the byte string encrypted by the public key from the enclave's attestation document.
var client = new AmazonKeyManagementServiceClient();
var response = client.GenerateRandom(new GenerateRandomRequest
{
NumberOfBytes = 1024, // The length of the random byte string
Recipient = new RecipientInfo {
AttestationDocument = new MemoryStream(<attestation document>),
KeyEncryptionAlgorithm = "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
});
MemoryStream ciphertextForRecipient = response.CiphertextForRecipient; // The random data encrypted under the public key from the attestation document
MemoryStream plaintext = response.Plaintext; // This field is null or empty
.NET Framework:
Supported in: 4.5 and newer, 3.5