2024/04/12 - AWS Key Management Service - 2 new 2 updated api methods
Changes This feature supports the ability to specify a custom rotation period for automatic key rotations, the ability to perform on-demand key rotations, and visibility into your key material rotations.
Immediately initiates rotation of the key material of the specified symmetric encryption KMS key.
You can perform on-demand rotation of the key material in customer managed KMS keys, regardless of whether or not automatic key rotation is enabled. On-demand rotations do not change existing automatic rotation schedules. For example, consider a KMS key that has automatic key rotation enabled with a rotation period of 730 days. If the key is scheduled to automatically rotate on April 14, 2024, and you perform an on-demand rotation on April 10, 2024, the key will automatically rotate, as scheduled, on April 14, 2024 and every 730 days thereafter.
Note
You can perform on-demand key rotation a maximum of 10 times per KMS key. You can use the KMS console to view the number of remaining on-demand rotations available for a KMS key.
You can use GetKeyRotationStatus to identify any in progress on-demand rotations. You can use ListKeyRotations to identify the date that completed on-demand rotations were performed. You can monitor rotation of the key material for your KMS keys in CloudTrail and Amazon CloudWatch.
On-demand key rotation is supported only on symmetric encryption KMS keys. You cannot perform on-demand rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To perform on-demand rotation of a set of related multi-Region keys, invoke the on-demand rotation on the primary key.
You cannot initiate on-demand rotation of Amazon Web Services managed KMS keys. KMS always rotates the key material of Amazon Web Services managed keys every year. Rotation of Amazon Web Services owned KMS keys is managed by the Amazon Web Services service that owns the key.
The KMS key that you use for this operation must be in a compatible key state. For details, see Key states of KMS keys in the Key Management Service Developer Guide .
Cross-account use : No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
Required permissions : kms:RotateKeyOnDemand (key policy)
Related operations:
EnableKeyRotation
DisableKeyRotation
GetKeyRotationStatus
ListKeyRotations
Eventual consistency : The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.
See also: AWS API Documentation
Request Syntax
client.rotate_key_on_demand(
KeyId='string'
)
string
[REQUIRED]
Identifies a symmetric encryption KMS key. You cannot perform on-demand rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To perform on-demand rotation of a set of related multi-Region keys, invoke the on-demand rotation on the primary key.
Specify the key ID or key ARN of the KMS key.
For example:
Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab
Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey.
dict
Response Syntax
{
'KeyId': 'string'
}
Response Structure
(dict) --
KeyId (string) --
Identifies the symmetric encryption KMS key that you initiated on-demand rotation on.
Returns information about all completed key material rotations for the specified KMS key.
You must specify the KMS key in all requests. You can refine the key rotations list by limiting the number of rotations returned.
For detailed information about automatic and on-demand key rotations, see Rotating KMS keys in the Key Management Service Developer Guide .
Cross-account use : No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
Required permissions : kms:ListKeyRotations (key policy)
Related operations:
EnableKeyRotation
DisableKeyRotation
GetKeyRotationStatus
RotateKeyOnDemand
Eventual consistency : The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.
See also: AWS API Documentation
Request Syntax
client.list_key_rotations(
KeyId='string',
Limit=123,
Marker='string'
)
string
[REQUIRED]
Gets the key rotations for the specified KMS key.
Specify the key ID or key ARN of the KMS key.
For example:
Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab
Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey.
integer
Use this parameter to specify the maximum number of items to return. When this value is present, KMS does not return more than the specified number of items, but it might return fewer.
This value is optional. If you include a value, it must be between 1 and 1000, inclusive. If you do not include a value, it defaults to 100.
string
Use this parameter in a subsequent request after you receive a response with truncated results. Set it to the value of NextMarker from the truncated response you just received.
dict
Response Syntax
{
'Rotations': [
{
'KeyId': 'string',
'RotationDate': datetime(2015, 1, 1),
'RotationType': 'AUTOMATIC'|'ON_DEMAND'
},
],
'NextMarker': 'string',
'Truncated': True|False
}
Response Structure
(dict) --
Rotations (list) --
A list of completed key material rotations.
(dict) --
Contains information about completed key material rotations.
KeyId (string) --
Unique identifier of the key.
RotationDate (datetime) --
Date and time that the key material rotation completed. Formatted as Unix time.
RotationType (string) --
Identifies whether the key material rotation was a scheduled automatic rotation or an on-demand rotation.
NextMarker (string) --
When Truncated is true, this element is present and contains the value to use for the Marker parameter in a subsequent request.
Truncated (boolean) --
A flag that indicates whether there are more items in the list. When this value is true, the list in this response is truncated. To get more items, pass the value of the NextMarker element in this response to the Marker parameter in a subsequent request.
{'RotationPeriodInDays': 'integer'}
Enables automatic rotation of the key material of the specified symmetric encryption KMS key.
By default, when you enable automatic rotation of a customer managed KMS key, KMS rotates the key material of the KMS key one year (approximately 365 days) from the enable date and every year thereafter. You can use the optional RotationPeriodInDays parameter to specify a custom rotation period when you enable key rotation, or you can use RotationPeriodInDays to modify the rotation period of a key that you previously enabled automatic key rotation on.
You can monitor rotation of the key material for your KMS keys in CloudTrail and Amazon CloudWatch. To disable rotation of the key material in a customer managed KMS key, use the DisableKeyRotation operation. You can use the GetKeyRotationStatus operation to identify any in progress rotations. You can use the ListKeyRotations operation to view the details of completed rotations.
Automatic key rotation is supported only on symmetric encryption KMS keys. You cannot enable automatic rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To enable or disable automatic rotation of a set of related multi-Region keys, set the property on the primary key.
You cannot enable or disable automatic rotation of Amazon Web Services managed KMS keys. KMS always rotates the key material of Amazon Web Services managed keys every year. Rotation of Amazon Web Services owned KMS keys is managed by the Amazon Web Services service that owns the key.
Note
In May 2022, KMS changed the rotation schedule for Amazon Web Services managed keys from every three years (approximately 1,095 days) to every year (approximately 365 days).
New Amazon Web Services managed keys are automatically rotated one year after they are created, and approximately every year thereafter.
Existing Amazon Web Services managed keys are automatically rotated one year after their most recent rotation, and every year thereafter.
The KMS key that you use for this operation must be in a compatible key state. For details, see Key states of KMS keys in the Key Management Service Developer Guide .
Cross-account use : No. You cannot perform this operation on a KMS key in a different Amazon Web Services account.
Required permissions : kms:EnableKeyRotation (key policy)
Related operations:
DisableKeyRotation
GetKeyRotationStatus
ListKeyRotations
RotateKeyOnDemand
Note
You can perform on-demand ( RotateKeyOnDemand ) rotation of the key material in customer managed KMS keys, regardless of whether or not automatic key rotation is enabled.
Eventual consistency : The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.
See also: AWS API Documentation
Request Syntax
client.enable_key_rotation(
KeyId='string',
RotationPeriodInDays=123
)
string
[REQUIRED]
Identifies a symmetric encryption KMS key. You cannot enable automatic rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To enable or disable automatic rotation of a set of related multi-Region keys, set the property on the primary key.
Specify the key ID or key ARN of the KMS key.
For example:
Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab
Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey.
integer
Use this parameter to specify a custom period of time between each rotation date. If no value is specified, the default value is 365 days.
The rotation period defines the number of days after you enable automatic key rotation that KMS will rotate your key material, and the number of days between each automatic rotation thereafter.
You can use the kms:RotationPeriodInDays condition key to further constrain the values that principals can specify in the RotationPeriodInDays parameter.
None
{'KeyId': 'string',
'NextRotationDate': 'timestamp',
'OnDemandRotationStartDate': 'timestamp',
'RotationPeriodInDays': 'integer'}
Provides detailed information about the rotation status for a KMS key, including whether automatic rotation of the key material is enabled for the specified KMS key, the rotation period, and the next scheduled rotation date.
Automatic key rotation is supported only on symmetric encryption KMS keys. You cannot enable automatic rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To enable or disable automatic rotation of a set of related multi-Region keys, set the property on the primary key..
You can enable ( EnableKeyRotation ) and disable automatic rotation ( DisableKeyRotation ) of the key material in customer managed KMS keys. Key material rotation of Amazon Web Services managed KMS keys is not configurable. KMS always rotates the key material in Amazon Web Services managed KMS keys every year. The key rotation status for Amazon Web Services managed KMS keys is always true .
You can perform on-demand ( RotateKeyOnDemand ) rotation of the key material in customer managed KMS keys, regardless of whether or not automatic key rotation is enabled. You can use GetKeyRotationStatus to identify the date and time that an in progress on-demand rotation was initiated. You can use ListKeyRotations to view the details of completed rotations.
Note
In May 2022, KMS changed the rotation schedule for Amazon Web Services managed keys from every three years to every year. For details, see EnableKeyRotation.
The KMS key that you use for this operation must be in a compatible key state. For details, see Key states of KMS keys in the Key Management Service Developer Guide .
Disabled: The key rotation status does not change when you disable a KMS key. However, while the KMS key is disabled, KMS does not rotate the key material. When you re-enable the KMS key, rotation resumes. If the key material in the re-enabled KMS key hasn't been rotated in one year, KMS rotates it immediately, and every year thereafter. If it's been less than a year since the key material in the re-enabled KMS key was rotated, the KMS key resumes its prior rotation schedule.
Pending deletion: While a KMS key is pending deletion, its key rotation status is false and KMS does not rotate the key material. If you cancel the deletion, the original key rotation status returns to true .
Cross-account use : Yes. To perform this operation on a KMS key in a different Amazon Web Services account, specify the key ARN in the value of the KeyId parameter.
Required permissions : kms:GetKeyRotationStatus (key policy)
Related operations:
DisableKeyRotation
EnableKeyRotation
ListKeyRotations
RotateKeyOnDemand
Eventual consistency : The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.
See also: AWS API Documentation
Request Syntax
client.get_key_rotation_status(
KeyId='string'
)
string
[REQUIRED]
Gets the rotation status for the specified KMS key.
Specify the key ID or key ARN of the KMS key. To specify a KMS key in a different Amazon Web Services account, you must use the key ARN.
For example:
Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab
Key ARN: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey.
dict
Response Syntax
{
'KeyRotationEnabled': True|False,
'KeyId': 'string',
'RotationPeriodInDays': 123,
'NextRotationDate': datetime(2015, 1, 1),
'OnDemandRotationStartDate': datetime(2015, 1, 1)
}
Response Structure
(dict) --
KeyRotationEnabled (boolean) --
A Boolean value that specifies whether key rotation is enabled.
KeyId (string) --
Identifies the specified symmetric encryption KMS key.
RotationPeriodInDays (integer) --
The number of days between each automatic rotation. The default value is 365 days.
NextRotationDate (datetime) --
The next date that KMS will automatically rotate the key material.
OnDemandRotationStartDate (datetime) --
Identifies the date and time that an in progress on-demand rotation was initiated.
The KMS API follows an eventual consistency model due to the distributed nature of the system. As a result, there might be a slight delay between initiating on-demand key rotation and the rotation's completion. Once the on-demand rotation is complete, use ListKeyRotations to view the details of the on-demand rotation.