AWS Key Management Service
Key Management Service Key Management Service (KMS) is an encryption and key management web service. This guide describes the KMS operations that you can call…
Identity & security#openapi#cloud
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Key Management Service
Key Management Service (KMS) is an encryption and key management web service. This guide describes
the KMS operations that you can call programmatically. For general information about KMS,
see the
Key Management Service Developer Guide
.
KMS has replaced the term customer master key (CMK) with Key Management Service key
and KMS key . The concept has not changed. To prevent breaking changes, KMS is keeping some variations of this term.
Amazon Web Services provides SDKs that consist of libraries and sample code for various programming
languages and platforms (Java, Rust, Python, Ruby, .Net, macOS, Android, etc.). The SDKs
provide a convenient way to create programmatic access to KMS and other Amazon Web Services services.
For example, the SDKs take care of tasks such as signing requests (see below), managing
errors, and retrying requests automatically. For more information about the Amazon Web Services SDKs,
including how to download and install them, see Tools
for Amazon Web Services .
We recommend that you use the Amazon Web Services SDKs to make programmatic API calls to KMS.
If you need to use FIPS 140-2 validated cryptographic modules when communicating with
Amazon Web Services, use one of the FIPS endpoints in your preferred Amazon Web Services Region. If you need communicate
over IPv6, use the dual-stack endpoint in your preferred Amazon Web Services Region. For more information
see Service
endpoints in the Key Management Service topic of the Amazon Web Services General Reference and Dual-stack endpoint
support in the KMS Developer Guide.
All KMS API calls must be signed and be transmitted using Transport Layer Security
(TLS). KMS recommends you always use the latest supported TLS version. Clients must also
support cipher suites with Perfect Forward Secrecy (PFS) such as Ephemeral Diffie-Hellman
(DHE) or Elliptic Curve Ephemeral Diffie-Hellman (ECDHE). Most modern systems such as Java 7
and later support these modes.
With current technology, brute force attacks on KMS TLS cipher suite key exchange
mechanisms are not feasible. However, cipher suites that use Rivest–Shamir–Adleman (RSA)
or Diffie-Hellman (DH) key exchange will be susceptible if large-scale quantum computing
becomes practical.
NIST IR 8547
on the NIST website establishes a timeline to phase out quantum-vulnerable algorithms
by 2030 and disallow them entirely by 2035. If your applications rely on the long-term
confidentiality of KMS API traffic, we recommend that you
use post-quantum TLS with KMS .
For more information about post-quantum cybersecurity, see Post-Quantum Cybersecurity Resources on the
National Security Agency (NSA) website.
Signing Requests
Requests must be signed using an access key ID and a secret access key. We strongly
recommend that you do not use your Amazon Web Services account root access key ID and secret access key for
everyday work. You can use the access key ID and secret access key for an IAM user or you
can use the Security Token Service (STS) to generate temporary security credentials and use those to sign
requests.
All KMS requests must be signed with Signature Version 4 .
Logging API Requests
KMS supports CloudTrail, a service that logs Amazon Web Services API calls and related events for your
Amazon Web Services account and delivers them to an Amazon S3 bucket that you specify. By using the
information collected by CloudTrail, you can determine what requests were made to KMS, who made
the request, when it was made, and so on. To learn more about CloudTrail, including how to turn it
on and find your log files, see the CloudTrail User Guide .
Additional Resources
For more information about credentials and request signing, see the following:
Amazon Web Services
Security Credentials - This topic provides general information about the types
of credentials used to access Amazon Web Services.
Temporary
Security Credentials - This section of the IAM User Guide
describes how to create and use temporary security credentials.
Signature Version
4 Signing Process - This set of topics walks you through the process of signing
a request using an access key ID and a secret access key.
Commonly Used API Operations
Of the API operations discussed in this guide, the following will prove the most useful
for most applications. You will likely perform operations other than these, such as…
Endpoints 56
- POSTCancel key deletion
/#X-Amz-Target=TrentService.CancelKeyDeletionCancels the deletion of a KMS key. When this operation succeeds, the key state of the KMS key is Disabled . To enable the KMS key, use EnableKey . For more… - POSTConnect custom key store
/#X-Amz-Target=TrentService.ConnectCustomKeyStoreConnects or reconnects a custom key store to its backing key store. For an CloudHSM key store, ConnectCustomKeyStore connects the key store to its associated… - POSTCreate alias
/#X-Amz-Target=TrentService.CreateAliasCreates a friendly name for a KMS key. Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see ABAC for KMS in… - POSTCreate custom key store
/#X-Amz-Target=TrentService.CreateCustomKeyStoreCreates a custom key store backed by a key store that you own and manage. When you use a KMS key in a custom key store for a cryptographic operation, the… - POSTCreate grant
/#X-Amz-Target=TrentService.CreateGrantAdds a grant to a KMS key. A grant is a policy instrument that allows Amazon Web Services principals to use KMS keys in cryptographic operations. It also can… - POSTCreate key
/#X-Amz-Target=TrentService.CreateKeyCreates a unique customer managed KMS key in your Amazon Web Services account and Region. You can use a KMS key in cryptographic operations, such as… - POSTDecapsulate
/#X-Amz-Target=TrentService.DecapsulateRecovers the shared secret that was encapsulated with the public key of an ML-KEM KMS key. Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM),… - POSTDecrypt
/#X-Amz-Target=TrentService.DecryptDecrypts ciphertext that was encrypted by a KMS key using any of the following operations: Encrypt GenerateDataKey GenerateDataKeyPair… - POSTDelete alias
/#X-Amz-Target=TrentService.DeleteAliasDeletes the specified alias. Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see ABAC for KMS in the Key… - POSTDelete custom key store
/#X-Amz-Target=TrentService.DeleteCustomKeyStoreDeletes a custom key store . This operation does not affect any backing elements of the custom key store. It does not delete the CloudHSM cluster that is… - POSTDelete imported key material
/#X-Amz-Target=TrentService.DeleteImportedKeyMaterialDeletes key material that was previously imported. This operation makes the specified KMS key temporarily unusable. To restore the usability of the KMS key,… - POSTDerive shared secret
/#X-Amz-Target=TrentService.DeriveSharedSecretDerives a shared secret using a key agreement algorithm. You must use an asymmetric NIST-standard elliptic curve (ECC) or SM2 (China Regions only) KMS key… - POSTDescribe custom key stores
/#X-Amz-Target=TrentService.DescribeCustomKeyStoresGets information about custom key stores in the account and Region. This operation is part of the custom key stores feature in KMS, which combines the… - POSTDescribe key
/#X-Amz-Target=TrentService.DescribeKeyProvides detailed information about a KMS key. You can run DescribeKey on a customer managed key or an Amazon Web Services managed key . This detailed… - POSTDisable key
/#X-Amz-Target=TrentService.DisableKeySets the state of a KMS key to disabled. This change temporarily prevents use of the KMS key for cryptographic operations . The KMS key that you use for this… - POSTDisable key rotation
/#X-Amz-Target=TrentService.DisableKeyRotationDisables automatic rotation of the key material of the specified symmetric encryption KMS key. Automatic key rotation is supported only on symmetric… - POSTDisconnect custom key store
/#X-Amz-Target=TrentService.DisconnectCustomKeyStoreDisconnects the custom key store from its backing key store. This operation disconnects an CloudHSM key store from its associated CloudHSM cluster or… - POSTEnable key
/#X-Amz-Target=TrentService.EnableKeySets the key state of a KMS key to enabled. This allows you to use the KMS key for cryptographic operations . The KMS key that you use for this operation must… - POSTEnable key rotation
/#X-Amz-Target=TrentService.EnableKeyRotationEnables automatic rotation of the key material of the specified symmetric encryption KMS key. By default, when you enable automatic rotation of a customer… - POSTEncapsulate
/#X-Amz-Target=TrentService.EncapsulateGenerates a shared secret and its encapsulated (ciphertext) form using the public key of an ML-KEM KMS key pair. Module-Lattice-Based Key-Encapsulation… - POSTEncrypt
/#X-Amz-Target=TrentService.EncryptEncrypts plaintext of up to 4,096 bytes using a KMS key. You can use a symmetric or asymmetric KMS key with a KeyUsage of ENCRYPT_DECRYPT . You can use this… - POSTGenerate data key
/#X-Amz-Target=TrentService.GenerateDataKeyReturns a unique symmetric data key for use outside of KMS. This operation returns a plaintext copy of the data key and a copy that is encrypted under a… - POSTGenerate data key pair
/#X-Amz-Target=TrentService.GenerateDataKeyPairReturns a unique asymmetric data key pair for use outside of KMS. This operation returns a plaintext public key, a plaintext private key, and a copy of the… - POSTGenerate data key pair without plaintext
/#X-Amz-Target=TrentService.GenerateDataKeyPairWithoutPlaintextReturns a unique asymmetric data key pair for use outside of KMS. This operation returns a plaintext public key and a copy of the private key that is… - POSTGenerate data key without plaintext
/#X-Amz-Target=TrentService.GenerateDataKeyWithoutPlaintextReturns a unique symmetric data key for use outside of KMS. This operation returns a data key that is encrypted under a symmetric encryption KMS key that you… - POSTGenerate mac
/#X-Amz-Target=TrentService.GenerateMacGenerates a hash-based message authentication code (HMAC) for a message using an HMAC KMS key and a MAC algorithm that the key supports. HMAC KMS keys and the… - POSTGenerate random
/#X-Amz-Target=TrentService.GenerateRandomReturns a random byte string that is cryptographically secure. You must use the NumberOfBytes parameter to specify the length of the random byte string. There… - POSTGet key last usage
/#X-Amz-Target=TrentService.GetKeyLastUsageReturns usage information about the last successful cryptographic operation performed with a specified KMS key, including the operation type, timestamp, and… - POSTGet key policy
/#X-Amz-Target=TrentService.GetKeyPolicyGets a key policy attached to the specified KMS key. A KMS key can have two key policies. You manage the default key policy. Resource Access Manager (RAM)… - POSTGet key rotation status
/#X-Amz-Target=TrentService.GetKeyRotationStatusProvides detailed information about the rotation status for a KMS key, including whether automatic rotation of the key material is enabled for the specified… - POSTGet parameters for import
/#X-Amz-Target=TrentService.GetParametersForImportReturns the public key and an import token you need to import or reimport key material for a KMS key. By default, KMS keys are created with key material that… - POSTGet public key
/#X-Amz-Target=TrentService.GetPublicKeyReturns the public key of an asymmetric KMS key. Unlike the private key of a asymmetric KMS key, which never leaves KMS unencrypted, callers with… - POSTImport key material
/#X-Amz-Target=TrentService.ImportKeyMaterialImports or reimports key material into an existing KMS key that was created without key material. You can also use this operation to set or update the… - POSTList aliases
/#X-Amz-Target=TrentService.ListAliasesGets a list of aliases in the caller's Amazon Web Services account and region. For more information about aliases, see CreateAlias . By default, the… - POSTList grants
/#X-Amz-Target=TrentService.ListGrantsGets a list of all grants for the specified KMS key. You must specify the KMS key in all requests. You can filter the grant list by grant ID, grantee… - POSTList key policies
/#X-Amz-Target=TrentService.ListKeyPoliciesGets the names of the key policies that are attached to a KMS key. This operation is designed to get policy names that you can use in a GetKeyPolicy… - POSTList key rotations
/#X-Amz-Target=TrentService.ListKeyRotationsReturns information about the key materials associated with the specified KMS key. You can use the optional IncludeKeyMaterial parameter to control which key… - POSTList keys
/#X-Amz-Target=TrentService.ListKeysGets a list of all KMS keys in the caller's Amazon Web Services account and Region. You can also use ListKeys to list KMS keys in the Region that other Amazon… - POSTList resource tags
/#X-Amz-Target=TrentService.ListResourceTagsReturns all tags on the specified KMS key. For general information about tags, including the format and syntax, see Tagging Amazon Web Services resources in… - POSTList retirable grants
/#X-Amz-Target=TrentService.ListRetirableGrantsReturns information about all grants in the Amazon Web Services account and Region that have the specified retiring principal or retiring service principal.… - POSTPut key policy
/#X-Amz-Target=TrentService.PutKeyPolicyAttaches a key policy to the specified KMS key. You can use this operation to set only the default key policy. For more information about key policies, see… - POSTRe encrypt
/#X-Amz-Target=TrentService.ReEncryptDecrypts ciphertext and then reencrypts it entirely within KMS. You can use this operation to change the KMS key under which data is encrypted, such as when… - POSTReplicate key
/#X-Amz-Target=TrentService.ReplicateKeyReplicates a multi-Region key into the specified Region. This operation creates a multi-Region replica key based on a multi-Region primary key in a different… - POSTRetire grant
/#X-Amz-Target=TrentService.RetireGrantDeletes a grant. Typically, you retire a grant when you no longer need its permissions. To identify the grant to retire, use a grant token , or both the grant… - POSTRevoke grant
/#X-Amz-Target=TrentService.RevokeGrantDeletes the specified grant. You revoke a grant to terminate the permissions that the grant allows. For more information, see Retiring and revoking grants in… - POSTRotate key on demand
/#X-Amz-Target=TrentService.RotateKeyOnDemandImmediately initiates rotation of the key material of the specified symmetric encryption KMS key. You can perform on-demand rotation of the key material in… - POSTSchedule key deletion
/#X-Amz-Target=TrentService.ScheduleKeyDeletionSchedules the deletion of a KMS key. By default, KMS applies a waiting period of 30 days, but you can specify a waiting period of 7-30 days. When this… - POSTSign
/#X-Amz-Target=TrentService.SignCreates a digital signature for a message or message digest by using the private key in an asymmetric signing KMS key. To verify the signature, use the Verify… - POSTTag resource
/#X-Amz-Target=TrentService.TagResourceAdds or edits tags on a customer managed key . Tagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see ABAC for KMS in… - POSTUntag resource
/#X-Amz-Target=TrentService.UntagResourceDeletes tags from a customer managed key . To delete a tag, specify the tag key and the KMS key. Tagging or untagging a KMS key can allow or deny permission… - POSTUpdate alias
/#X-Amz-Target=TrentService.UpdateAliasAssociates an existing KMS alias with a different KMS key. Each alias is associated with only one KMS key at a time, although a KMS key can have multiple… - POSTUpdate custom key store
/#X-Amz-Target=TrentService.UpdateCustomKeyStoreChanges the properties of a custom key store. You can use this operation to change the properties of an CloudHSM key store or an external key store. Use the… - POSTUpdate key description
/#X-Amz-Target=TrentService.UpdateKeyDescriptionUpdates the description of a KMS key. To see the description of a KMS key, use DescribeKey . The KMS key that you use for this operation must be in a… - POSTUpdate primary region
/#X-Amz-Target=TrentService.UpdatePrimaryRegionChanges the primary key of a multi-Region key. This operation changes the replica key in the specified Region to a primary key and changes the former primary… - POSTVerify
/#X-Amz-Target=TrentService.VerifyVerifies a digital signature that was generated by the Sign operation. Verification confirms that an authorized user signed the message with the specified KMS… - POSTVerify mac
/#X-Amz-Target=TrentService.VerifyMacVerifies the hash-based message authentication code (HMAC) for a specified message, HMAC KMS key, and MAC algorithm. To verify the HMAC, VerifyMac computes an…
API details
- Base URL
https://kms.{region}.amazonaws.com- Authentication
- AWS Signature Version 4 (requests signed with your AWS access key)
- Operations
- 56 operations on 56 pathsPOST 56
- Description format
- AWS Smithy model, API version
2014-11-01 - Links
- Documentation · OpenAPI document
- Listed from
- AWS Smithy API model (aws/api-models-aws) (Apache-2.0)
How to test the AWS Key Management Service in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the AWS Key Management Service collection, without the publisher's secrets.
- Add your credentialsThis API uses AWS Signature Version 4 (requests signed with your AWS access key). Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Cancel key deletion” (POST /#X-Amz-Target=TrentService.CancelKeyDeletion), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the AWS Key Management Service?
Key Management Service Key Management Service (KMS) is an encryption and key management web service. This guide describes the KMS operations that you can call… It is listed under Identity & security and has 56 endpoints.
Who publishes the AWS Key Management Service?
It is listed from Amazon Web Services, Inc.'s public API description (an OpenAPI document), not published by Amazon Web Services, Inc. on Swastik Codes. Anyone who controls amazonaws.com can claim the profile by adding a DNS TXT record.
What is the base URL of the AWS Key Management Service?
Requests go to https://kms.{region}.amazonaws.com. Endpoint paths are added to this base URL.
How do I authenticate with the AWS Key Management Service?
With AWS Signature Version 4 (requests signed with your AWS access key).
How many endpoints does the AWS Key Management Service have?
56 operations on 56 paths (56 POST).
Is forking the AWS Key Management Service free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.