StartDeliveryStreamEncryption
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 PutRecord:Encrypted and
PutRecordBatch: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
{
"DeliveryStreamEncryptionConfigurationInput": {
"KeyARN": "string
",
"KeyType": "string
"
},
"DeliveryStreamName": "string
"
}
Request Parameters
The request accepts the following data in JSON format.
- DeliveryStreamEncryptionConfigurationInput
-
Used to specify the type and Amazon Resource Name (ARN) of the KMS key needed for Server-Side Encryption (SSE).
Type: DeliveryStreamEncryptionConfigurationInput object
Required: No
- DeliveryStreamName
-
The name of the Firehose stream for which you want to enable server-side encryption (SSE).
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern:
[a-zA-Z0-9_.-]+
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors.
- InvalidArgumentException
-
The specified input parameter has a value that is not valid.
HTTP Status Code: 400
- InvalidKMSResourceException
-
Firehose throws this exception when an attempt to put records or to start or stop Firehose stream encryption fails. This happens when the KMS service throws one of the following exception types:
AccessDeniedException
,InvalidStateException
,DisabledException
, orNotFoundException
.HTTP Status Code: 400
- LimitExceededException
-
You have already reached the limit for a requested resource.
HTTP Status Code: 400
- ResourceInUseException
-
The resource is already in use and not available for this operation.
HTTP Status Code: 400
- ResourceNotFoundException
-
The specified resource could not be found.
HTTP Status Code: 400
Examples
To start server-side encryption for a stream
The following JSON example starts server-side encryption (SSE) for the specified stream.
Sample Request
POST / HTTP/1.1
Host: firehose.<region>.<domain>
Content-Length: <PayloadSizeBytes>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.1
Authorization: <AuthParams>
Connection: Keep-Alive
X-Amz-Date: <Date>
X-Amz-Target: Firehose_20150804.StartDeliveryStreamEncryption
{
"DeliveryStreamName": "exampleDeliveryStreamName"
}
Sample Response
HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
See Also
For more information about using this API in one of the language-specific Amazon SDKs, see the following: