Firehose / Client / start_delivery_stream_encryption

start_delivery_stream_encryption#

Firehose.Client.start_delivery_stream_encryption(**kwargs)#

Enables server-side encryption (SSE) for the Firehose stream.

This operation is asynchronous. It returns immediately. When you invoke it, Firehose first sets the encryption status of the stream to ENABLING, and then to ENABLED. The encryption status of a Firehose stream is the Status property in DeliveryStreamEncryptionConfiguration. If the operation fails, the encryption status changes to ENABLING_FAILED. You can continue to read and write data to your Firehose stream while the encryption status is ENABLING, but the data is not encrypted. It can take up to 5 seconds after the encryption status changes to ENABLED before all records written to the Firehose stream are encrypted. To find out whether a record or a batch of records was encrypted, check the response elements PutRecordOutput$Encrypted and PutRecordBatchOutput$Encrypted, respectively.

To check the encryption status of a Firehose stream, use DescribeDeliveryStream.

Even if encryption is currently enabled for a Firehose stream, you can still invoke this operation on it to change the ARN of the CMK or both its type and ARN. If you invoke this method to change the CMK, and the old CMK is of type CUSTOMER_MANAGED_CMK, Firehose schedules the grant it had on the old CMK for retirement. If the new CMK is of type CUSTOMER_MANAGED_CMK, Firehose creates a grant that enables it to use the new CMK to encrypt and decrypt data and to manage the grant.

For the KMS grant creation to be successful, the Firehose API operations StartDeliveryStreamEncryption and CreateDeliveryStream should not be called with session credentials that are more than 6 hours old.

If a Firehose stream already has encryption enabled and then you invoke this operation to change the ARN of the CMK or both its type and ARN and you get ENABLING_FAILED, this only means that the attempt to change the CMK failed. In this case, encryption remains enabled with the old CMK.

If the encryption status of your Firehose stream is ENABLING_FAILED, you can invoke this operation again with a valid CMK. The CMK must be enabled and the key policy mustn’t explicitly deny the permission for Firehose to invoke KMS encrypt and decrypt operations.

You can enable SSE for a Firehose stream only if it’s a Firehose stream that uses DirectPut as its source.

The StartDeliveryStreamEncryption and StopDeliveryStreamEncryption operations have a combined limit of 25 calls per Firehose stream per 24 hours. For example, you reach the limit if you call StartDeliveryStreamEncryption 13 times and StopDeliveryStreamEncryption 12 times for the same Firehose stream in a 24-hour period.

Request Syntax

response = client.start_delivery_stream_encryption(
    DeliveryStreamName='string',
    DeliveryStreamEncryptionConfigurationInput={
        'KeyARN': 'string',
        'KeyType': 'AWS_OWNED_CMK'|'CUSTOMER_MANAGED_CMK'
    }
)

Parameters:

DeliveryStreamName (string) –
[REQUIRED]

The name of the Firehose stream for which you want to enable server-side encryption (SSE).
DeliveryStreamEncryptionConfigurationInput (dict) –
Used to specify the type and Amazon Resource Name (ARN) of the KMS key needed for Server-Side Encryption (SSE).
- KeyARN (string) –
  
  If you set KeyType to CUSTOMER_MANAGED_CMK, you must specify the Amazon Resource Name (ARN) of the CMK. If you set KeyType to Amazon Web Services_OWNED_CMK, Firehose uses a service-account CMK.
- KeyType (string) – [REQUIRED]
  
  Indicates the type of customer master key (CMK) to use for encryption. The default setting is Amazon Web Services_OWNED_CMK. For more information about CMKs, see Customer Master Keys (CMKs). When you invoke CreateDeliveryStream or StartDeliveryStreamEncryption with KeyType set to CUSTOMER_MANAGED_CMK, Firehose invokes the Amazon KMS operation CreateGrant to create a grant that allows the Firehose service to use the customer managed CMK to perform encryption and decryption. Firehose manages that grant.
  
  When you invoke StartDeliveryStreamEncryption to change the CMK for a Firehose stream that is encrypted with a customer managed CMK, Firehose schedules the grant it had on the old CMK for retirement.
  
  You can use a CMK of type CUSTOMER_MANAGED_CMK to encrypt up to 500 Firehose streams. If a CreateDeliveryStream or StartDeliveryStreamEncryption operation exceeds this limit, Firehose throws a LimitExceededException.
  
  Warning
  To encrypt your Firehose stream, use symmetric CMKs. Firehose doesn’t support asymmetric CMKs. For information about symmetric and asymmetric CMKs, see About Symmetric and Asymmetric CMKs in the Amazon Web Services Key Management Service developer guide.

Return type:

dict

Returns:

Response Syntax

{}

Response Structure

(dict) –

Exceptions

Firehose.Client.exceptions.ResourceNotFoundException
Firehose.Client.exceptions.ResourceInUseException
Firehose.Client.exceptions.InvalidArgumentException
Firehose.Client.exceptions.LimitExceededException
Firehose.Client.exceptions.InvalidKMSResourceException