StartStreamEncryptionCommand

Suggest an Edit

Enables or updates server-side encryption using an Amazon Web Services KMS key for a specified stream.

When invoking this API, you must use either the StreamARN or the StreamName parameter, or both. It is recommended that you use the StreamARN input parameter when you invoke this API.

Starting encryption is an asynchronous operation. Upon receiving the request, Kinesis Data Streams returns immediately and sets the status of the stream to UPDATING. After the update is complete, Kinesis Data Streams sets the status of the stream back to ACTIVE. Updating or applying encryption normally takes a few seconds to complete, but it can take minutes. You can continue to read and write data to your stream while its status is UPDATING. Once the status of the stream is ACTIVE, encryption begins for records written to the stream.

API Limits: You can successfully apply a new Amazon Web Services KMS key for server-side encryption 25 times in a rolling 24-hour period.

Note: It can take up to 5 seconds after the stream is in an ACTIVE status before all records written to the stream are encrypted. After you enable encryption, you can verify that encryption is applied by inspecting the API response from PutRecord or PutRecords.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { KinesisClient, StartStreamEncryptionCommand } from "@aws-sdk/client-kinesis"; // ES Modules import
// const { KinesisClient, StartStreamEncryptionCommand } = require("@aws-sdk/client-kinesis"); // CommonJS import
const client = new KinesisClient(config);
const input = { // StartStreamEncryptionInput
  StreamName: "STRING_VALUE",
  EncryptionType: "NONE" || "KMS", // required
  KeyId: "STRING_VALUE", // required
  StreamARN: "STRING_VALUE",
};
const command = new StartStreamEncryptionCommand(input);
const response = await client.send(command);
// {};

StartStreamEncryptionCommand Input

See StartStreamEncryptionCommandInput for more details

Parameter
Type
Description
EncryptionType
Required
EncryptionType | undefined

The encryption type to use. The only valid value is KMS.

KeyId
Required
string | undefined

The GUID for the customer-managed Amazon Web Services KMS key to use for encryption. This value can be a globally unique identifier, a fully specified Amazon Resource Name (ARN) to either an alias or a key, or an alias name prefixed by "alias/".You can also use a master key owned by Kinesis Data Streams by specifying the alias aws/kinesis.

  • Key ARN example: arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012

  • Alias ARN example: arn:aws:kms:us-east-1:123456789012:alias/MyAliasName

  • Globally unique key ID example: 12345678-1234-1234-1234-123456789012

  • Alias name example: alias/MyAliasName

  • Master key owned by Kinesis Data Streams: alias/aws/kinesis

StreamARN
string | undefined

The ARN of the stream.

StreamName
string | undefined

The name of the stream for which to start encrypting records.

StartStreamEncryptionCommand Output

See StartStreamEncryptionCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.

Throws

Name
Fault
Details
AccessDeniedException
client

Specifies that you do not have the permissions required to perform this operation.

InvalidArgumentException
client

A specified parameter exceeds its restrictions, is not supported, or can't be used. For more information, see the returned message.

KMSAccessDeniedException
client

The ciphertext references a key that doesn't exist or that you don't have access to.

KMSDisabledException
client

The request was rejected because the specified customer master key (CMK) isn't enabled.

KMSInvalidStateException
client

The request was rejected because the state of the specified resource isn't valid for this request. For more information, see How Key State Affects Use of a Customer Master Key  in the Amazon Web Services Key Management Service Developer Guide.

KMSNotFoundException
client

The request was rejected because the specified entity or resource can't be found.

KMSOptInRequired
client

The Amazon Web Services access key ID needs a subscription for the service.

KMSThrottlingException
client

The request was denied due to request throttling. For more information about throttling, see Limits  in the Amazon Web Services Key Management Service Developer Guide.

LimitExceededException
client

The requested resource exceeds the maximum number allowed, or the number of concurrent stream requests exceeds the maximum number allowed.

ResourceInUseException
client

The resource is not available for this operation. For successful operation, the resource must be in the ACTIVE state.

ResourceNotFoundException
client

The requested resource could not be found. The stream might not be specified correctly.

KinesisServiceException
Base exception class for all service exceptions from Kinesis service.