TRANSLATEKEYMATERIAL()`¶

About TranslateKeyMaterial¶

Translates an encryption 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 Pin Encryption Key (PEK) generated for each transaction and wrapped with an ECDH (Elliptic Curve Diffie-Hellman) derived wrapping key to another KEK (Key Encryption Key) 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 more information on establishing ECDH derived keys, see the Creating keys in the Amazon Web Services Payment Cryptography User Guide.

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 can't be used across different Amazon Web Services accounts.

Related operations:

Method Signature¶

METHODS /AWS1/IF_PCD~TRANSLATEKEYMATERIAL
  IMPORTING
    !IO_INCOMINGKEYMATERIAL TYPE REF TO /AWS1/CL_PCDINCOMINGKEYMATER00 OPTIONAL
    !IO_OUTGOINGKEYMATERIAL TYPE REF TO /AWS1/CL_PCDOUTGOINGKEYMATER00 OPTIONAL
    !IV_KEYCHECKVALUEALGORITHM TYPE /AWS1/PCDKEYCHECKVALUEALG OPTIONAL
  RETURNING
    VALUE(OO_OUTPUT) TYPE REF TO /aws1/cl_pcdtranslatekeymate01
  RAISING
    /AWS1/CX_PCDACCESSDENIEDEX
    /AWS1/CX_PCDINTERNALSERVEREX
    /AWS1/CX_PCDRESOURCENOTFOUNDEX
    /AWS1/CX_PCDTHROTTLINGEX
    /AWS1/CX_PCDVALIDATIONEX
    /AWS1/CX_PCDCLIENTEXC
    /AWS1/CX_PCDSERVEREXC
    /AWS1/CX_RT_TECHNICAL_GENERIC
    /AWS1/CX_RT_SERVICE_GENERIC.

IMPORTING¶

Required arguments:¶

`io_incomingkeymaterial` `TYPE REF TO /AWS1/CL_PCDINCOMINGKEYMATER00` `/AWS1/CL_PCDINCOMINGKEYMATER00`¶

Parameter information of the TR31WrappedKeyBlock containing the transaction key.

`io_outgoingkeymaterial` `TYPE REF TO /AWS1/CL_PCDOUTGOINGKEYMATER00` `/AWS1/CL_PCDOUTGOINGKEYMATER00`¶

Parameter information of the wrapping key used to wrap the transaction key in the outgoing TR31WrappedKeyBlock.

Optional arguments:¶

`iv_keycheckvaluealgorithm` `TYPE /AWS1/PCDKEYCHECKVALUEALG` `/AWS1/PCDKEYCHECKVALUEALG`¶

The key check value (KCV) algorithm used for calculating the KCV.

RETURNING¶

`oo_output` `TYPE REF TO /aws1/cl_pcdtranslatekeymate01` `/AWS1/CL_PCDTRANSLATEKEYMATE01`¶

Domain /AWS1/RT_ACCOUNT_ID

Primitive Type NUMC

Examples¶

Syntax Example¶

This is an example of the syntax for calling the method. It includes every possible argument and initializes every possible value. The data provided is not necessarily semantically accurate (for example the value "string" may be provided for something that is intended to be an instance ID, or in some cases two arguments may be mutually exclusive). The syntax shows the ABAP syntax for creating the various data structures.

DATA(lo_result) = lo_client->translatekeymaterial(
  io_incomingkeymaterial = new /aws1/cl_pcdincomingkeymater00(
    io_diffiehellmantr31keyblock = new /aws1/cl_pcdincomingdiffiehe00(
      io_derivationdata = new /aws1/cl_pcddiffiehellmander00( |string| )
      iv_certauthoritypublickeyid = |string|
      iv_derivekeyalgorithm = |string|
      iv_keyderivationfunction = |string|
      iv_keyderivationhashalg = |string|
      iv_privatekeyidentifier = |string|
      iv_publickeycertificate = |string|
      iv_wrappedkeyblock = |string|
    )
  )
  io_outgoingkeymaterial = new /aws1/cl_pcdoutgoingkeymater00( new /aws1/cl_pcdoutgoingtr31keyblk( |string| ) )
  iv_keycheckvaluealgorithm = |string|
).

This is an example of reading all possible response values

lo_result = lo_result.
IF lo_result IS NOT INITIAL.
  lo_wrappedworkingkey = lo_result->get_wrappedkey( ).
  IF lo_wrappedworkingkey IS NOT INITIAL.
    lv_keymaterial = lo_wrappedworkingkey->get_wrappedkeymaterial( ).
    lv_keycheckvalue = lo_wrappedworkingkey->get_keycheckvalue( ).
    lv_wrappedkeymaterialforma = lo_wrappedworkingkey->get_wrappedkeymaterialformat( ).
  ENDIF.
ENDIF.

/AWS1/IF_PCD=>TRANSLATEKEYMATERIAL()¶