Translates an cryptographic key between different wrapping keys without importing the key into Amazon Web Services Payment Cryptography.
This operation can be used when key material is frequently rotated, such as during every card transaction, and there is a need to avoid importing short-lived keys into Amazon Web Services Payment Cryptography. It translates short-lived transaction keys such as PEK generated for each transaction and wrapped with an ECDH derived wrapping key to another KEK wrapping key.
Before using this operation, you must first request the public key certificate of the ECC key pair generated within Amazon Web Services Payment Cryptography to establish an ECDH key agreement. In TranslateKeyData, the service uses its own ECC key pair, public certificate of receiving ECC key pair, and the key derivation parameters to generate a derived key. The service uses this derived key to unwrap the incoming transaction key received as a TR31WrappedKeyBlock and re-wrap using a user provided KEK to generate an outgoing Tr31WrappedKeyBlock.
For information about valid keys for this operation, see Understanding key attributes and Key types for specific data operations in the Amazon Web Services Payment Cryptography User Guide.
Cross-account use: This operation supports cross-account use when the key has a resource-based policy that grants access. For more information, see Resource-based policies.
Related operations:
Parameters:
-
incoming_key_material
(IncomingKeyMaterial)
–
Parameter information of the TR31WrappedKeyBlock containing the transaction key.
-
outgoing_key_material
(OutgoingKeyMaterial)
–
Parameter information of the wrapping key used to wrap the transaction key in the outgoing TR31WrappedKeyBlock.
-
key_check_value_algorithm
(Optional[KeyCheckValueAlgorithm], default:
None
)
–
The key check value (KCV) algorithm used for calculating the KCV of the derived key.
Raises:
Source code in docs_src/capo_payment_cryptography_data/_services/payment_cryptography_data.py
| def translate_key_material(
self,
incoming_key_material: "capo_payment_cryptography_data.types.incoming_key_material.IncomingKeyMaterial",
outgoing_key_material: "capo_payment_cryptography_data.types.outgoing_key_material.OutgoingKeyMaterial",
*,
config_overrides: Optional[PaymentCryptographyDataClientConfig] = None,
key_check_value_algorithm: Optional[
"capo_payment_cryptography_data.types.key_check_value_algorithm.KeyCheckValueAlgorithm"
] = None,
) -> "capo_payment_cryptography_data.types.translate_key_material_output.TranslateKeyMaterialOutput":
"""<p>Translates an cryptographic key between different wrapping keys without importing the key into Amazon Web Services Payment Cryptography.</p> <p>This operation can be used when key material is frequently rotated, such as during every card transaction, and there is a need to avoid importing short-lived keys into Amazon Web Services Payment Cryptography. It translates short-lived transaction keys such as <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/terminology.html#terms.pek">PEK</a> generated for each transaction and wrapped with an <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/terminology.html#terms.ecdh">ECDH</a> derived wrapping key to another <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/terminology.html#terms.kek">KEK</a> wrapping key. </p> <p>Before using this operation, you must first request the public key certificate of the ECC key pair generated within Amazon Web Services Payment Cryptography to establish an ECDH key agreement. In <code>TranslateKeyData</code>, the service uses its own ECC key pair, public certificate of receiving ECC key pair, and the key derivation parameters to generate a derived key. The service uses this derived key to unwrap the incoming transaction key received as a TR31WrappedKeyBlock and re-wrap using a user provided KEK to generate an outgoing Tr31WrappedKeyBlock.</p> <p>For information about valid keys for this operation, see <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-validattributes.html">Understanding key attributes</a> and <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html">Key types for specific data operations</a> in the <i>Amazon Web Services Payment Cryptography User Guide</i>. </p> <p> <b>Cross-account use</b>: This operation supports cross-account use when the key has a resource-based policy that grants access. For more information, see <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/security_iam_resource-based-policies.html">Resource-based policies</a>.</p> <p> <b>Related operations:</b> </p> <ul> <li> <p> <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html">CreateKey</a> </p> </li> <li> <p> <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_GetPublicKeyCertificate.html">GetPublicCertificate</a> </p> </li> <li> <p> <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html">ImportKey</a> </p> </li> </ul>
Args:
incoming_key_material: <p>Parameter information of the TR31WrappedKeyBlock containing the transaction key.</p>
outgoing_key_material: <p>Parameter information of the wrapping key used to wrap the transaction key in the outgoing TR31WrappedKeyBlock.</p>
key_check_value_algorithm: <p>The key check value (KCV) algorithm used for calculating the KCV of the derived key.</p>
Raises:
capo_payment_cryptography_data.errors.access_denied_exception.AccessDeniedException: <p>You do not have sufficient access to perform this action.</p>
capo_payment_cryptography_data.errors.internal_server_exception.InternalServerException: <p>The request processing has failed because of an unknown error, exception, or failure.</p>
capo_payment_cryptography_data.errors.resource_not_found_exception.ResourceNotFoundException: <p>The request was denied due to an invalid resource error.</p>
capo_payment_cryptography_data.errors.throttling_exception.ThrottlingException: <p>The request was denied due to request throttling.</p>
capo_payment_cryptography_data.errors.validation_exception.ValidationException: <p>The request was denied due to an invalid request error.</p>
capo_payment_cryptography_data.errors.UnknownServiceError: The service returned an error code this client does not model.
"""
def _handler(
req: "OperationRequest[capo_payment_cryptography_data.types.translate_key_material_input.TranslateKeyMaterialInput]",
) -> OperationResponse[
"capo_payment_cryptography_data.types.translate_key_material_output.TranslateKeyMaterialOutput"
]:
import capo_payment_cryptography_data._operations.payment_cryptography_data_plane.translate_key_material
output, http_response = (
capo_payment_cryptography_data._operations.payment_cryptography_data_plane.translate_key_material.translate_key_material(
req.options, req.input
)
)
return OperationResponse(output=output, response=http_response)
def _redact_input(
input_: "capo_payment_cryptography_data.types.translate_key_material_input.TranslateKeyMaterialInput",
) -> dict[str, Any]:
import capo_payment_cryptography_data.types.translate_key_material_input
return capo_payment_cryptography_data.types.translate_key_material_input.redact_sensitive(
input_
)
def _redact_output(
output: "capo_payment_cryptography_data.types.translate_key_material_output.TranslateKeyMaterialOutput",
) -> dict[str, Any]:
import capo_payment_cryptography_data.types.translate_key_material_output
return capo_payment_cryptography_data.types.translate_key_material_output.redact_sensitive(
output
)
interceptors_, options_ = self.operation_options(
config_overrides,
OperationLogging(
"TranslateKeyMaterial",
redact_input=_redact_input,
redact_output=_redact_output,
),
)
input_: capo_payment_cryptography_data.types.translate_key_material_input.TranslateKeyMaterialInput = {
"incoming_key_material": incoming_key_material,
"outgoing_key_material": outgoing_key_material,
}
if key_check_value_algorithm is not None:
input_["key_check_value_algorithm"] = key_check_value_algorithm
response = execute_pipeline(
OperationRequest(input=input_, options=options_),
handler=_handler,
interceptors=list(interceptors_),
)
response.response.close()
return response.output
|