| Copyright | (c) 2013-2021 Brendan Hay |
|---|---|
| License | Mozilla Public License, v. 2.0. |
| Maintainer | Brendan Hay <brendan.g.hay+amazonka@gmail.com> |
| Stability | auto-generated |
| Portability | non-portable (GHC extensions) |
| Safe Haskell | None |
Amazonka.KMS.GetPublicKey
Description
Returns the public key of an asymmetric KMS key. Unlike the private key
of a asymmetric KMS key, which never leaves KMS unencrypted, callers
with kms:GetPublicKey permission can download the public key of an
asymmetric KMS key. You can share the public key to allow others to
encrypt messages and verify signatures outside of KMS. For information
about symmetric and asymmetric KMS keys, see
Using Symmetric and Asymmetric KMS keys
in the Key Management Service Developer Guide.
You do not need to download the public key. Instead, you can use the public key within KMS by calling the Encrypt, ReEncrypt, or Verify operations with the identifier of an asymmetric KMS key. When you use the public key within KMS, you benefit from the authentication, authorization, and logging that are part of every KMS operation. You also reduce of risk of encrypting data that cannot be decrypted. These features are not effective outside of KMS. For details, see Special Considerations for Downloading Public Keys.
To help you use the public key safely outside of KMS, GetPublicKey
returns important information about the public key in the response,
including:
- KeySpec:
The type of key material in the public key, such as
RSA_4096orECC_NIST_P521. - KeyUsage: Whether the key is used for encryption or signing.
- EncryptionAlgorithms or SigningAlgorithms: A list of the encryption algorithms or the signing algorithms for the key.
Although KMS cannot enforce these restrictions on external operations, it is crucial that you use this information to prevent the public key from being used improperly. For example, you can prevent a public signing key from being used encrypt data, or prevent a public key from being used with an encryption algorithm that is not supported by KMS. You can also avoid errors, such as using the wrong signing algorithm in a verification operation.
The KMS key that you use for this operation must be in a compatible key state. For details, see Key state: Effect on your KMS key in the Key Management Service Developer Guide.
Cross-account use: Yes. To perform this operation with a KMS key in
a different Amazon Web Services account, specify the key ARN or alias
ARN in the value of the KeyId parameter.
Required permissions: kms:GetPublicKey (key policy)
Related operations: CreateKey
Synopsis
- data GetPublicKey = GetPublicKey' {
- grantTokens :: Maybe [Text]
- keyId :: Text
- newGetPublicKey :: Text -> GetPublicKey
- getPublicKey_grantTokens :: Lens' GetPublicKey (Maybe [Text])
- getPublicKey_keyId :: Lens' GetPublicKey Text
- data GetPublicKeyResponse = GetPublicKeyResponse' {}
- newGetPublicKeyResponse :: Int -> GetPublicKeyResponse
- getPublicKeyResponse_keySpec :: Lens' GetPublicKeyResponse (Maybe KeySpec)
- getPublicKeyResponse_keyId :: Lens' GetPublicKeyResponse (Maybe Text)
- getPublicKeyResponse_customerMasterKeySpec :: Lens' GetPublicKeyResponse (Maybe CustomerMasterKeySpec)
- getPublicKeyResponse_encryptionAlgorithms :: Lens' GetPublicKeyResponse (Maybe [EncryptionAlgorithmSpec])
- getPublicKeyResponse_publicKey :: Lens' GetPublicKeyResponse (Maybe ByteString)
- getPublicKeyResponse_signingAlgorithms :: Lens' GetPublicKeyResponse (Maybe [SigningAlgorithmSpec])
- getPublicKeyResponse_keyUsage :: Lens' GetPublicKeyResponse (Maybe KeyUsageType)
- getPublicKeyResponse_httpStatus :: Lens' GetPublicKeyResponse Int
Creating a Request
data GetPublicKey Source #
See: newGetPublicKey smart constructor.
Constructors
| GetPublicKey' | |
Fields
| |
Instances
Arguments
| :: Text | |
| -> GetPublicKey |
Create a value of GetPublicKey with all optional fields omitted.
Use generic-lens or optics to modify other optional fields.
The following record fields are available, with the corresponding lenses provided for backwards compatibility:
$sel:grantTokens:GetPublicKey', getPublicKey_grantTokens - A list of grant tokens.
Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. For more information, see Grant token and Using a grant token in the Key Management Service Developer Guide.
$sel:keyId:GetPublicKey', getPublicKey_keyId - Identifies the asymmetric KMS key that includes the public key.
To specify a KMS key, use its key ID, key ARN, alias name, or alias ARN.
When using an alias name, prefix it with "alias/". To specify a KMS
key in a different Amazon Web Services account, you must use the key ARN
or alias 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 - Alias name:
alias/ExampleAlias - Alias ARN:
arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias
To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey. To get the alias name and alias ARN, use ListAliases.
Request Lenses
getPublicKey_grantTokens :: Lens' GetPublicKey (Maybe [Text]) Source #
A list of grant tokens.
Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. For more information, see Grant token and Using a grant token in the Key Management Service Developer Guide.
getPublicKey_keyId :: Lens' GetPublicKey Text Source #
Identifies the asymmetric KMS key that includes the public key.
To specify a KMS key, use its key ID, key ARN, alias name, or alias ARN.
When using an alias name, prefix it with "alias/". To specify a KMS
key in a different Amazon Web Services account, you must use the key ARN
or alias 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 - Alias name:
alias/ExampleAlias - Alias ARN:
arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias
To get the key ID and key ARN for a KMS key, use ListKeys or DescribeKey. To get the alias name and alias ARN, use ListAliases.
Destructuring the Response
data GetPublicKeyResponse Source #
See: newGetPublicKeyResponse smart constructor.
Constructors
| GetPublicKeyResponse' | |
Fields
| |
Instances
newGetPublicKeyResponse Source #
Arguments
| :: Int | |
| -> GetPublicKeyResponse |
Create a value of GetPublicKeyResponse with all optional fields omitted.
Use generic-lens or optics to modify other optional fields.
The following record fields are available, with the corresponding lenses provided for backwards compatibility:
$sel:keySpec:GetPublicKeyResponse', getPublicKeyResponse_keySpec - The type of the of the public key that was downloaded.
$sel:keyId:GetPublicKey', getPublicKeyResponse_keyId - The Amazon Resource Name
(key ARN)
of the asymmetric KMS key from which the public key was downloaded.
$sel:customerMasterKeySpec:GetPublicKeyResponse', getPublicKeyResponse_customerMasterKeySpec - Instead, use the KeySpec field in the GetPublicKey response.
The KeySpec and CustomerMasterKeySpec fields have the same value. We
recommend that you use the KeySpec field in your code. However, to
avoid breaking changes, KMS will support both fields.
$sel:encryptionAlgorithms:GetPublicKeyResponse', getPublicKeyResponse_encryptionAlgorithms - The encryption algorithms that KMS supports for this key.
This information is critical. If a public key encrypts data outside of KMS by using an unsupported encryption algorithm, the ciphertext cannot be decrypted.
This field appears in the response only when the KeyUsage of the
public key is ENCRYPT_DECRYPT.
$sel:publicKey:GetPublicKeyResponse', getPublicKeyResponse_publicKey - The exported public key.
The value is a DER-encoded X.509 public key, also known as
SubjectPublicKeyInfo (SPKI), as defined in
RFC 5280. When you use the HTTP
API or the Amazon Web Services CLI, the value is Base64-encoded.
Otherwise, it is not Base64-encoded.--
-- Note: This Lens automatically encodes and decodes Base64 data.
-- The underlying isomorphism will encode to Base64 representation during
-- serialisation, and decode from Base64 representation during deserialisation.
-- This Lens accepts and returns only raw unencoded data.
$sel:signingAlgorithms:GetPublicKeyResponse', getPublicKeyResponse_signingAlgorithms - The signing algorithms that KMS supports for this key.
This field appears in the response only when the KeyUsage of the
public key is SIGN_VERIFY.
$sel:keyUsage:GetPublicKeyResponse', getPublicKeyResponse_keyUsage - The permitted use of the public key. Valid values are ENCRYPT_DECRYPT
or SIGN_VERIFY.
This information is critical. If a public key with SIGN_VERIFY key
usage encrypts data outside of KMS, the ciphertext cannot be decrypted.
$sel:httpStatus:GetPublicKeyResponse', getPublicKeyResponse_httpStatus - The response's http status code.
Response Lenses
getPublicKeyResponse_keySpec :: Lens' GetPublicKeyResponse (Maybe KeySpec) Source #
The type of the of the public key that was downloaded.
getPublicKeyResponse_keyId :: Lens' GetPublicKeyResponse (Maybe Text) Source #
The Amazon Resource Name (key ARN) of the asymmetric KMS key from which the public key was downloaded.
getPublicKeyResponse_customerMasterKeySpec :: Lens' GetPublicKeyResponse (Maybe CustomerMasterKeySpec) Source #
Instead, use the KeySpec field in the GetPublicKey response.
The KeySpec and CustomerMasterKeySpec fields have the same value. We
recommend that you use the KeySpec field in your code. However, to
avoid breaking changes, KMS will support both fields.
getPublicKeyResponse_encryptionAlgorithms :: Lens' GetPublicKeyResponse (Maybe [EncryptionAlgorithmSpec]) Source #
The encryption algorithms that KMS supports for this key.
This information is critical. If a public key encrypts data outside of KMS by using an unsupported encryption algorithm, the ciphertext cannot be decrypted.
This field appears in the response only when the KeyUsage of the
public key is ENCRYPT_DECRYPT.
getPublicKeyResponse_publicKey :: Lens' GetPublicKeyResponse (Maybe ByteString) Source #
The exported public key.
The value is a DER-encoded X.509 public key, also known as
SubjectPublicKeyInfo (SPKI), as defined in
RFC 5280. When you use the HTTP
API or the Amazon Web Services CLI, the value is Base64-encoded.
Otherwise, it is not Base64-encoded.--
-- Note: This Lens automatically encodes and decodes Base64 data.
-- The underlying isomorphism will encode to Base64 representation during
-- serialisation, and decode from Base64 representation during deserialisation.
-- This Lens accepts and returns only raw unencoded data.
getPublicKeyResponse_signingAlgorithms :: Lens' GetPublicKeyResponse (Maybe [SigningAlgorithmSpec]) Source #
The signing algorithms that KMS supports for this key.
This field appears in the response only when the KeyUsage of the
public key is SIGN_VERIFY.
getPublicKeyResponse_keyUsage :: Lens' GetPublicKeyResponse (Maybe KeyUsageType) Source #
The permitted use of the public key. Valid values are ENCRYPT_DECRYPT
or SIGN_VERIFY.
This information is critical. If a public key with SIGN_VERIFY key
usage encrypts data outside of KMS, the ciphertext cannot be decrypted.
getPublicKeyResponse_httpStatus :: Lens' GetPublicKeyResponse Int Source #
The response's http status code.