We announced the upcoming end-of-support for AWS SDK for JavaScript v2.
We recommend that you migrate to AWS SDK for JavaScript v3. For dates, additional details, and information on how to migrate, please refer to the linked announcement.

Class: AWS.PaymentCryptographyData

Inherits:
AWS.Service show all
Identifier:
paymentcryptographydata
API Version:
2022-02-03
Defined in:
(unknown)

Overview

Constructs a service interface object. Each API operation is exposed as a function on service.

Service Description

You use the Amazon Web Services Payment Cryptography Data Plane to manage how encryption keys are used for payment-related transaction processing and associated cryptographic operations. You can encrypt, decrypt, generate, verify, and translate payment-related cryptographic operations in Amazon Web Services Payment Cryptography. For more information, see Data operations in the Amazon Web Services Payment Cryptography User Guide.

To manage your encryption keys, you use the Amazon Web Services Payment Cryptography Control Plane. You can create, import, export, share, manage, and delete keys. You can also manage Identity and Access Management (IAM) policies for keys.

Sending a Request Using PaymentCryptographyData

var paymentcryptographydata = new AWS.PaymentCryptographyData();
paymentcryptographydata.decryptData(params, function (err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Locking the API Version

In order to ensure that the PaymentCryptographyData object uses this specific API, you can construct the object by passing the apiVersion option to the constructor:

var paymentcryptographydata = new AWS.PaymentCryptographyData({apiVersion: '2022-02-03'});

You can also set the API version globally in AWS.config.apiVersions using the paymentcryptographydata service identifier:

AWS.config.apiVersions = {
  paymentcryptographydata: '2022-02-03',
  // other service API versions
};

var paymentcryptographydata = new AWS.PaymentCryptographyData();

Version:

  • 2022-02-03

Constructor Summary collapse

Property Summary collapse

Properties inherited from AWS.Service

apiVersions

Method Summary collapse

Methods inherited from AWS.Service

makeRequest, makeUnauthenticatedRequest, setupRequestListeners, defineService

Constructor Details

new AWS.PaymentCryptographyData(options = {}) ⇒ Object

Constructs a service object. This object has one method for each API operation.

Examples:

Constructing a PaymentCryptographyData object

var paymentcryptographydata = new AWS.PaymentCryptographyData({apiVersion: '2022-02-03'});

Options Hash (options):

  • params (map)

    An optional map of parameters to bind to every request sent by this service object. For more information on bound parameters, see "Working with Services" in the Getting Started Guide.

  • endpoint (String|AWS.Endpoint)

    The endpoint URI to send requests to. The default endpoint is built from the configured region. The endpoint should be a string like 'https://{service}.{region}.amazonaws.com' or an Endpoint object.

  • accessKeyId (String)

    your AWS access key ID.

  • secretAccessKey (String)

    your AWS secret access key.

  • sessionToken (AWS.Credentials)

    the optional AWS session token to sign requests with.

  • credentials (AWS.Credentials)

    the AWS credentials to sign requests with. You can either specify this object, or specify the accessKeyId and secretAccessKey options directly.

  • credentialProvider (AWS.CredentialProviderChain)

    the provider chain used to resolve credentials if no static credentials property is set.

  • region (String)

    the region to send service requests to. See AWS.PaymentCryptographyData.region for more information.

  • maxRetries (Integer)

    the maximum amount of retries to attempt with a request. See AWS.PaymentCryptographyData.maxRetries for more information.

  • maxRedirects (Integer)

    the maximum amount of redirects to follow with a request. See AWS.PaymentCryptographyData.maxRedirects for more information.

  • sslEnabled (Boolean)

    whether to enable SSL for requests.

  • paramValidation (Boolean|map)

    whether input parameters should be validated against the operation description before sending the request. Defaults to true. Pass a map to enable any of the following specific validation features:

    • min [Boolean] — Validates that a value meets the min constraint. This is enabled by default when paramValidation is set to true.
    • max [Boolean] — Validates that a value meets the max constraint.
    • pattern [Boolean] — Validates that a string value matches a regular expression.
    • enum [Boolean] — Validates that a string value matches one of the allowable enum values.
  • computeChecksums (Boolean)

    whether to compute checksums for payload bodies when the service accepts it (currently supported in S3 only)

  • convertResponseTypes (Boolean)

    whether types are converted when parsing response data. Currently only supported for JSON based services. Turning this off may improve performance on large response payloads. Defaults to true.

  • correctClockSkew (Boolean)

    whether to apply a clock skew correction and retry requests that fail because of an skewed client clock. Defaults to false.

  • s3ForcePathStyle (Boolean)

    whether to force path style URLs for S3 objects.

  • s3BucketEndpoint (Boolean)

    whether the provided endpoint addresses an individual bucket (false if it addresses the root API endpoint). Note that setting this configuration option requires an endpoint to be provided explicitly to the service constructor.

  • s3DisableBodySigning (Boolean)

    whether S3 body signing should be disabled when using signature version v4. Body signing can only be disabled when using https. Defaults to true.

  • s3UsEast1RegionalEndpoint ('legacy'|'regional')

    when region is set to 'us-east-1', whether to send s3 request to global endpoints or 'us-east-1' regional endpoints. This config is only applicable to S3 client. Defaults to legacy

  • s3UseArnRegion (Boolean)

    whether to override the request region with the region inferred from requested resource's ARN. Only available for S3 buckets Defaults to true

  • retryDelayOptions (map)

    A set of options to configure the retry delay on retryable errors. Currently supported options are:

    • base [Integer] — The base number of milliseconds to use in the exponential backoff for operation retries. Defaults to 100 ms for all services except DynamoDB, where it defaults to 50ms.
    • customBackoff [function] — A custom function that accepts a retry count and error and returns the amount of time to delay in milliseconds. If the result is a non-zero negative value, no further retry attempts will be made. The base option will be ignored if this option is supplied. The function is only called for retryable errors.
  • httpOptions (map)

    A set of options to pass to the low-level HTTP request. Currently supported options are:

    • proxy [String] — the URL to proxy requests through
    • agent [http.Agent, https.Agent] — the Agent object to perform HTTP requests with. Used for connection pooling. Defaults to the global agent (http.globalAgent) for non-SSL connections. Note that for SSL connections, a special Agent object is used in order to enable peer certificate verification. This feature is only available in the Node.js environment.
    • connectTimeout [Integer] — Sets the socket to timeout after failing to establish a connection with the server after connectTimeout milliseconds. This timeout has no effect once a socket connection has been established.
    • timeout [Integer] — Sets the socket to timeout after timeout milliseconds of inactivity on the socket. Defaults to two minutes (120000).
    • xhrAsync [Boolean] — Whether the SDK will send asynchronous HTTP requests. Used in the browser environment only. Set to false to send requests synchronously. Defaults to true (async on).
    • xhrWithCredentials [Boolean] — Sets the "withCredentials" property of an XMLHttpRequest object. Used in the browser environment only. Defaults to false.
  • apiVersion (String, Date)

    a String in YYYY-MM-DD format (or a date) that represents the latest possible API version that can be used in all services (unless overridden by apiVersions). Specify 'latest' to use the latest possible version.

  • apiVersions (map<String, String|Date>)

    a map of service identifiers (the lowercase service class name) with the API version to use when instantiating a service. Specify 'latest' for each individual that can use the latest available version.

  • logger (#write, #log)

    an object that responds to .write() (like a stream) or .log() (like the console object) in order to log information about requests

  • systemClockOffset (Number)

    an offset value in milliseconds to apply to all signing times. Use this to compensate for clock skew when your system may be out of sync with the service time. Note that this configuration option can only be applied to the global AWS.config object and cannot be overridden in service-specific configuration. Defaults to 0 milliseconds.

  • signatureVersion (String)

    the signature version to sign requests with (overriding the API configuration). Possible values are: 'v2', 'v3', 'v4'.

  • signatureCache (Boolean)

    whether the signature to sign requests with (overriding the API configuration) is cached. Only applies to the signature version 'v4'. Defaults to true.

  • dynamoDbCrc32 (Boolean)

    whether to validate the CRC32 checksum of HTTP response bodies returned by DynamoDB. Default: true.

  • useAccelerateEndpoint (Boolean)

    Whether to use the S3 Transfer Acceleration endpoint with the S3 service. Default: false.

  • clientSideMonitoring (Boolean)

    whether to collect and publish this client's performance metrics of all its API requests.

  • endpointDiscoveryEnabled (Boolean|undefined)

    whether to call operations with endpoints given by service dynamically. Setting this

  • endpointCacheSize (Number)

    the size of the global cache storing endpoints from endpoint discovery operations. Once endpoint cache is created, updating this setting cannot change existing cache size. Defaults to 1000

  • hostPrefixEnabled (Boolean)

    whether to marshal request parameters to the prefix of hostname. Defaults to true.

  • stsRegionalEndpoints ('legacy'|'regional')

    whether to send sts request to global endpoints or regional endpoints. Defaults to 'legacy'.

  • useFipsEndpoint (Boolean)

    Enables FIPS compatible endpoints. Defaults to false.

  • useDualstackEndpoint (Boolean)

    Enables IPv6 dualstack endpoint. Defaults to false.

Property Details

endpointAWS.Endpoint (readwrite)

Returns an Endpoint object representing the endpoint URL for service requests.

Returns:

  • (AWS.Endpoint)

    an Endpoint object representing the endpoint URL for service requests.

Method Details

decryptData(params = {}, callback) ⇒ AWS.Request

Decrypts ciphertext data to plaintext using a symmetric (TDES, AES), asymmetric (RSA), or derived (DUKPT or EMV) encryption key scheme. For more information, see Decrypt data in the Amazon Web Services Payment Cryptography User Guide.

You can use an encryption key generated within Amazon Web Services Payment Cryptography, or you can import your own encryption key by calling ImportKey. For this operation, the key must have KeyModesOfUse set to Decrypt. In asymmetric decryption, Amazon Web Services Payment Cryptography decrypts the ciphertext using the private component of the asymmetric encryption key pair. For data encryption outside of Amazon Web Services Payment Cryptography, you can export the public component of the asymmetric key pair by calling GetPublicCertificate.

For symmetric and DUKPT decryption, Amazon Web Services Payment Cryptography supports TDES and AES algorithms. For EMV decryption, Amazon Web Services Payment Cryptography supports TDES algorithms. For asymmetric decryption, Amazon Web Services Payment Cryptography supports RSA.

When you use TDES or TDES DUKPT, the ciphertext data length must be a multiple of 8 bytes. For AES or AES DUKPT, the ciphertext data length must be a multiple of 16 bytes. For RSA, it sould be equal to the key size unless padding is enabled.

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:

Service Reference:

Examples:

Calling the decryptData operation

var params = {
  CipherText: 'STRING_VALUE', /* required */
  DecryptionAttributes: { /* required */
    Asymmetric: {
      PaddingType: PKCS1 | OAEP_SHA1 | OAEP_SHA256 | OAEP_SHA512
    },
    Dukpt: {
      KeySerialNumber: 'STRING_VALUE', /* required */
      DukptKeyDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256,
      DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE,
      InitializationVector: 'STRING_VALUE',
      Mode: ECB | CBC
    },
    Emv: {
      MajorKeyDerivationMode: EMV_OPTION_A | EMV_OPTION_B, /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      PrimaryAccountNumber: 'STRING_VALUE', /* required */
      SessionDerivationData: 'STRING_VALUE', /* required */
      InitializationVector: 'STRING_VALUE',
      Mode: ECB | CBC
    },
    Symmetric: {
      Mode: ECB | CBC | CFB | CFB1 | CFB8 | CFB64 | CFB128 | OFB, /* required */
      InitializationVector: 'STRING_VALUE',
      PaddingType: PKCS1 | OAEP_SHA1 | OAEP_SHA256 | OAEP_SHA512
    }
  },
  KeyIdentifier: 'STRING_VALUE', /* required */
  WrappedKey: {
    WrappedKeyMaterial: { /* required */
      Tr31KeyBlock: 'STRING_VALUE'
    },
    KeyCheckValueAlgorithm: CMAC | ANSI_X9_24
  }
};
paymentcryptographydata.decryptData(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • KeyIdentifier — (String)

      The keyARN of the encryption key that Amazon Web Services Payment Cryptography uses for ciphertext decryption.

      When a WrappedKeyBlock is provided, this value will be the identifier to the key wrapping key. Otherwise, it is the key identifier used to perform the operation.

    • CipherText — (String)

      The ciphertext to decrypt.

    • DecryptionAttributes — (map)

      The encryption key type and attributes for ciphertext decryption.

      • Symmetric — (map)

        Parameters that are required to perform encryption and decryption using symmetric keys.

        • Moderequired — (String)

          The block cipher method to use for encryption.

          Possible values include:
          • "ECB"
          • "CBC"
          • "CFB"
          • "CFB1"
          • "CFB8"
          • "CFB64"
          • "CFB128"
          • "OFB"
        • InitializationVector — (String)

          An input used to provide the intial state. If no value is provided, Amazon Web Services Payment Cryptography defaults it to zero.

        • PaddingType — (String)

          The padding to be included with the data.

          Possible values include:
          • "PKCS1"
          • "OAEP_SHA1"
          • "OAEP_SHA256"
          • "OAEP_SHA512"
      • Asymmetric — (map)

        Parameters for plaintext encryption using asymmetric keys.

        • PaddingType — (String)

          The padding to be included with the data.

          Possible values include:
          • "PKCS1"
          • "OAEP_SHA1"
          • "OAEP_SHA256"
          • "OAEP_SHA512"
      • Dukpt — (map)

        Parameters that are required to encrypt plaintext data using DUKPT.

        • KeySerialNumberrequired — (String)

          The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

        • Mode — (String)

          The block cipher method to use for encryption.

          The default is CBC.

          Possible values include:
          • "ECB"
          • "CBC"
        • DukptKeyDerivationType — (String)

          The key type encrypted using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY

          Possible values include:
          • "TDES_2KEY"
          • "TDES_3KEY"
          • "AES_128"
          • "AES_192"
          • "AES_256"
        • DukptKeyVariant — (String)

          The type of use of DUKPT, which can be incoming data decryption, outgoing data encryption, or both.

          Possible values include:
          • "BIDIRECTIONAL"
          • "REQUEST"
          • "RESPONSE"
        • InitializationVector — (String)

          An input used to provide the intial state. If no value is provided, Amazon Web Services Payment Cryptography defaults it to zero.

      • Emv — (map)

        Parameters for plaintext encryption using EMV keys.

        • MajorKeyDerivationModerequired — (String)

          The EMV derivation mode to use for ICC master key derivation as per EMV version 4.3 book 2.

          Possible values include:
          • "EMV_OPTION_A"
          • "EMV_OPTION_B"
        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN), a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • SessionDerivationDatarequired — (String)

          The derivation value used to derive the ICC session key. It is typically the application transaction counter value padded with zeros or previous ARQC value padded with zeros as per EMV version 4.3 book 2.

        • Mode — (String)

          The block cipher method to use for encryption.

          Possible values include:
          • "ECB"
          • "CBC"
        • InitializationVector — (String)

          An input used to provide the intial state. If no value is provided, Amazon Web Services Payment Cryptography defaults it to zero.

    • WrappedKey — (map)

      The WrappedKeyBlock containing the encryption key for ciphertext decryption.

      • WrappedKeyMaterialrequired — (map)

        Parameter information of a WrappedKeyBlock for encryption key exchange.

        • Tr31KeyBlock — (String)

          The TR-31 wrapped key block.

      • KeyCheckValueAlgorithm — (String)

        The algorithm that Amazon Web Services Payment Cryptography uses to calculate the key check value (KCV). It is used to validate the key integrity.

        For TDES keys, the KCV is computed by encrypting 8 bytes, each with value of zero, with the key to be checked and retaining the 3 highest order bytes of the encrypted result. For AES keys, the KCV is computed using a CMAC algorithm where the input data is 16 bytes of zero and retaining the 3 highest order bytes of the encrypted result.

        Possible values include:
        • "CMAC"
        • "ANSI_X9_24"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response)

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • KeyArn — (String)

        The keyARN of the encryption key that Amazon Web Services Payment Cryptography uses for ciphertext decryption.

      • KeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

      • PlainText — (String)

        The decrypted plaintext data in hexBinary format.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

encryptData(params = {}, callback) ⇒ AWS.Request

Encrypts plaintext data to ciphertext using a symmetric (TDES, AES), asymmetric (RSA), or derived (DUKPT or EMV) encryption key scheme. For more information, see Encrypt data in the Amazon Web Services Payment Cryptography User Guide.

You can generate an encryption key within Amazon Web Services Payment Cryptography by calling CreateKey. You can import your own encryption key by calling ImportKey. For this operation, the key must have KeyModesOfUse set to Encrypt. In asymmetric encryption, plaintext is encrypted using public component. You can import the public component of an asymmetric key pair created outside Amazon Web Services Payment Cryptography by calling ImportKey.

For symmetric and DUKPT encryption, Amazon Web Services Payment Cryptography supports TDES and AES algorithms. For EMV encryption, Amazon Web Services Payment Cryptography supports TDES algorithms.For asymmetric encryption, Amazon Web Services Payment Cryptography supports RSA.

When you use TDES or TDES DUKPT, the plaintext data length must be a multiple of 8 bytes. For AES or AES DUKPT, the plaintext data length must be a multiple of 16 bytes. For RSA, it sould be equal to the key size unless padding is enabled.

To encrypt using DUKPT, you must already have a BDK (Base Derivation Key) key in your account with KeyModesOfUse set to DeriveKey, or you can generate a new DUKPT key by calling CreateKey. To encrypt using EMV, you must already have an IMK (Issuer Master Key) key in your account with KeyModesOfUse set to DeriveKey.

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:

Service Reference:

Examples:

Calling the encryptData operation

var params = {
  EncryptionAttributes: { /* required */
    Asymmetric: {
      PaddingType: PKCS1 | OAEP_SHA1 | OAEP_SHA256 | OAEP_SHA512
    },
    Dukpt: {
      KeySerialNumber: 'STRING_VALUE', /* required */
      DukptKeyDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256,
      DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE,
      InitializationVector: 'STRING_VALUE',
      Mode: ECB | CBC
    },
    Emv: {
      MajorKeyDerivationMode: EMV_OPTION_A | EMV_OPTION_B, /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      PrimaryAccountNumber: 'STRING_VALUE', /* required */
      SessionDerivationData: 'STRING_VALUE', /* required */
      InitializationVector: 'STRING_VALUE',
      Mode: ECB | CBC
    },
    Symmetric: {
      Mode: ECB | CBC | CFB | CFB1 | CFB8 | CFB64 | CFB128 | OFB, /* required */
      InitializationVector: 'STRING_VALUE',
      PaddingType: PKCS1 | OAEP_SHA1 | OAEP_SHA256 | OAEP_SHA512
    }
  },
  KeyIdentifier: 'STRING_VALUE', /* required */
  PlainText: 'STRING_VALUE', /* required */
  WrappedKey: {
    WrappedKeyMaterial: { /* required */
      Tr31KeyBlock: 'STRING_VALUE'
    },
    KeyCheckValueAlgorithm: CMAC | ANSI_X9_24
  }
};
paymentcryptographydata.encryptData(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • KeyIdentifier — (String)

      The keyARN of the encryption key that Amazon Web Services Payment Cryptography uses for plaintext encryption.

      When a WrappedKeyBlock is provided, this value will be the identifier to the key wrapping key. Otherwise, it is the key identifier used to perform the operation.

    • PlainText — (String)

      The plaintext to be encrypted.

      Note: For encryption using asymmetric keys, plaintext data length is constrained by encryption key strength that you define in KeyAlgorithm and padding type that you define in AsymmetricEncryptionAttributes. For more information, see Encrypt data in the Amazon Web Services Payment Cryptography User Guide.
    • EncryptionAttributes — (map)

      The encryption key type and attributes for plaintext encryption.

      • Symmetric — (map)

        Parameters that are required to perform encryption and decryption using symmetric keys.

        • Moderequired — (String)

          The block cipher method to use for encryption.

          Possible values include:
          • "ECB"
          • "CBC"
          • "CFB"
          • "CFB1"
          • "CFB8"
          • "CFB64"
          • "CFB128"
          • "OFB"
        • InitializationVector — (String)

          An input used to provide the intial state. If no value is provided, Amazon Web Services Payment Cryptography defaults it to zero.

        • PaddingType — (String)

          The padding to be included with the data.

          Possible values include:
          • "PKCS1"
          • "OAEP_SHA1"
          • "OAEP_SHA256"
          • "OAEP_SHA512"
      • Asymmetric — (map)

        Parameters for plaintext encryption using asymmetric keys.

        • PaddingType — (String)

          The padding to be included with the data.

          Possible values include:
          • "PKCS1"
          • "OAEP_SHA1"
          • "OAEP_SHA256"
          • "OAEP_SHA512"
      • Dukpt — (map)

        Parameters that are required to encrypt plaintext data using DUKPT.

        • KeySerialNumberrequired — (String)

          The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

        • Mode — (String)

          The block cipher method to use for encryption.

          The default is CBC.

          Possible values include:
          • "ECB"
          • "CBC"
        • DukptKeyDerivationType — (String)

          The key type encrypted using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY

          Possible values include:
          • "TDES_2KEY"
          • "TDES_3KEY"
          • "AES_128"
          • "AES_192"
          • "AES_256"
        • DukptKeyVariant — (String)

          The type of use of DUKPT, which can be incoming data decryption, outgoing data encryption, or both.

          Possible values include:
          • "BIDIRECTIONAL"
          • "REQUEST"
          • "RESPONSE"
        • InitializationVector — (String)

          An input used to provide the intial state. If no value is provided, Amazon Web Services Payment Cryptography defaults it to zero.

      • Emv — (map)

        Parameters for plaintext encryption using EMV keys.

        • MajorKeyDerivationModerequired — (String)

          The EMV derivation mode to use for ICC master key derivation as per EMV version 4.3 book 2.

          Possible values include:
          • "EMV_OPTION_A"
          • "EMV_OPTION_B"
        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN), a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • SessionDerivationDatarequired — (String)

          The derivation value used to derive the ICC session key. It is typically the application transaction counter value padded with zeros or previous ARQC value padded with zeros as per EMV version 4.3 book 2.

        • Mode — (String)

          The block cipher method to use for encryption.

          Possible values include:
          • "ECB"
          • "CBC"
        • InitializationVector — (String)

          An input used to provide the intial state. If no value is provided, Amazon Web Services Payment Cryptography defaults it to zero.

    • WrappedKey — (map)

      The WrappedKeyBlock containing the encryption key for plaintext encryption.

      • WrappedKeyMaterialrequired — (map)

        Parameter information of a WrappedKeyBlock for encryption key exchange.

        • Tr31KeyBlock — (String)

          The TR-31 wrapped key block.

      • KeyCheckValueAlgorithm — (String)

        The algorithm that Amazon Web Services Payment Cryptography uses to calculate the key check value (KCV). It is used to validate the key integrity.

        For TDES keys, the KCV is computed by encrypting 8 bytes, each with value of zero, with the key to be checked and retaining the 3 highest order bytes of the encrypted result. For AES keys, the KCV is computed using a CMAC algorithm where the input data is 16 bytes of zero and retaining the 3 highest order bytes of the encrypted result.

        Possible values include:
        • "CMAC"
        • "ANSI_X9_24"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response)

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • KeyArn — (String)

        The keyARN of the encryption key that Amazon Web Services Payment Cryptography uses for plaintext encryption.

      • KeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

      • CipherText — (String)

        The encrypted ciphertext.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

generateCardValidationData(params = {}, callback) ⇒ AWS.Request

Generates card-related validation data using algorithms such as Card Verification Values (CVV/CVV2), Dynamic Card Verification Values (dCVV/dCVV2), or Card Security Codes (CSC). For more information, see Generate card data in the Amazon Web Services Payment Cryptography User Guide.

This operation generates a CVV or CSC value that is printed on a payment credit or debit card during card production. The CVV or CSC, PAN (Primary Account Number) and expiration date of the card are required to check its validity during transaction processing. To begin this operation, a CVK (Card Verification Key) encryption key is required. You can use CreateKey or ImportKey to establish a CVK within Amazon Web Services Payment Cryptography. The KeyModesOfUse should be set to Generate and Verify for a CVK encryption key.

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:

Service Reference:

Examples:

Calling the generateCardValidationData operation

var params = {
  GenerationAttributes: { /* required */
    AmexCardSecurityCodeVersion1: {
      CardExpiryDate: 'STRING_VALUE' /* required */
    },
    AmexCardSecurityCodeVersion2: {
      CardExpiryDate: 'STRING_VALUE', /* required */
      ServiceCode: 'STRING_VALUE' /* required */
    },
    CardHolderVerificationValue: {
      ApplicationTransactionCounter: 'STRING_VALUE', /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      UnpredictableNumber: 'STRING_VALUE' /* required */
    },
    CardVerificationValue1: {
      CardExpiryDate: 'STRING_VALUE', /* required */
      ServiceCode: 'STRING_VALUE' /* required */
    },
    CardVerificationValue2: {
      CardExpiryDate: 'STRING_VALUE' /* required */
    },
    DynamicCardVerificationCode: {
      ApplicationTransactionCounter: 'STRING_VALUE', /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      TrackData: 'STRING_VALUE', /* required */
      UnpredictableNumber: 'STRING_VALUE' /* required */
    },
    DynamicCardVerificationValue: {
      ApplicationTransactionCounter: 'STRING_VALUE', /* required */
      CardExpiryDate: 'STRING_VALUE', /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      ServiceCode: 'STRING_VALUE' /* required */
    }
  },
  KeyIdentifier: 'STRING_VALUE', /* required */
  PrimaryAccountNumber: 'STRING_VALUE', /* required */
  ValidationDataLength: 'NUMBER_VALUE'
};
paymentcryptographydata.generateCardValidationData(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • KeyIdentifier — (String)

      The keyARN of the CVK encryption key that Amazon Web Services Payment Cryptography uses to generate card data.

    • PrimaryAccountNumber — (String)

      The Primary Account Number (PAN), a unique identifier for a payment credit or debit card that associates the card with a specific account holder.

    • GenerationAttributes — (map)

      The algorithm for generating CVV or CSC values for the card within Amazon Web Services Payment Cryptography.

      • AmexCardSecurityCodeVersion1 — (map)

        Card data parameters that are required to generate a Card Security Code (CSC2) for an AMEX payment card.

        • CardExpiryDaterequired — (String)

          The expiry date of a payment card.

      • AmexCardSecurityCodeVersion2 — (map)

        Card data parameters that are required to generate a Card Security Code (CSC2) for an AMEX payment card.

        • CardExpiryDaterequired — (String)

          The expiry date of a payment card.

        • ServiceCoderequired — (String)

          The service code of the AMEX payment card. This is different from the Card Security Code (CSC).

      • CardVerificationValue1 — (map)

        Card data parameters that are required to generate Card Verification Value (CVV) for the payment card.

        • CardExpiryDaterequired — (String)

          The expiry date of a payment card.

        • ServiceCoderequired — (String)

          The service code of the payment card. This is different from Card Security Code (CSC).

      • CardVerificationValue2 — (map)

        Card data parameters that are required to generate Card Verification Value (CVV2) for the payment card.

        • CardExpiryDaterequired — (String)

          The expiry date of a payment card.

      • CardHolderVerificationValue — (map)

        Card data parameters that are required to generate a cardholder verification value for the payment card.

        • UnpredictableNumberrequired — (String)

          A random number generated by the issuer.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • ApplicationTransactionCounterrequired — (String)

          The transaction counter value that comes from a point of sale terminal.

      • DynamicCardVerificationCode — (map)

        Card data parameters that are required to generate CDynamic Card Verification Code (dCVC) for the payment card.

        • UnpredictableNumberrequired — (String)

          A random number generated by the issuer.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • ApplicationTransactionCounterrequired — (String)

          The transaction counter value that comes from the terminal.

        • TrackDatarequired — (String)

          The data on the two tracks of magnetic cards used for financial transactions. This includes the cardholder name, PAN, expiration date, bank ID (BIN) and several other numbers the issuing bank uses to validate the data received.

      • DynamicCardVerificationValue — (map)

        Card data parameters that are required to generate CDynamic Card Verification Value (dCVV) for the payment card.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • CardExpiryDaterequired — (String)

          The expiry date of a payment card.

        • ServiceCoderequired — (String)

          The service code of the payment card. This is different from Card Security Code (CSC).

        • ApplicationTransactionCounterrequired — (String)

          The transaction counter value that comes from the terminal.

    • ValidationDataLength — (Integer)

      The length of the CVV or CSC to be generated. The default value is 3.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response)

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • KeyArn — (String)

        The keyARN of the CVK encryption key that Amazon Web Services Payment Cryptography uses to generate CVV or CSC.

      • KeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

      • ValidationData — (String)

        The CVV or CSC value that Amazon Web Services Payment Cryptography generates for the card.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

generateMac(params = {}, callback) ⇒ AWS.Request

Generates a Message Authentication Code (MAC) cryptogram within Amazon Web Services Payment Cryptography.

You can use this operation to authenticate card-related data by using known data values to generate MAC for data validation between the sending and receiving parties. This operation uses message data, a secret encryption key and MAC algorithm to generate a unique MAC value for transmission. The receiving party of the MAC must use the same message data, secret encryption key and MAC algorithm to reproduce another MAC value for comparision.

You can use this operation to generate a DUPKT, CMAC, HMAC or EMV MAC by setting generation attributes and algorithm to the associated values. The MAC generation encryption key must have valid values for KeyUsage such as TR31_M7_HMAC_KEY for HMAC generation, and they key must have KeyModesOfUse set to Generate and Verify.

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:

Service Reference:

Examples:

Calling the generateMac operation

var params = {
  GenerationAttributes: { /* required */
    Algorithm: ISO9797_ALGORITHM1 | ISO9797_ALGORITHM3 | CMAC | HMAC_SHA224 | HMAC_SHA256 | HMAC_SHA384 | HMAC_SHA512,
    DukptCmac: {
      DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE, /* required */
      KeySerialNumber: 'STRING_VALUE', /* required */
      DukptDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256
    },
    DukptIso9797Algorithm1: {
      DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE, /* required */
      KeySerialNumber: 'STRING_VALUE', /* required */
      DukptDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256
    },
    DukptIso9797Algorithm3: {
      DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE, /* required */
      KeySerialNumber: 'STRING_VALUE', /* required */
      DukptDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256
    },
    EmvMac: {
      MajorKeyDerivationMode: EMV_OPTION_A | EMV_OPTION_B, /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      PrimaryAccountNumber: 'STRING_VALUE', /* required */
      SessionKeyDerivationMode: EMV_COMMON_SESSION_KEY | EMV2000 | AMEX | MASTERCARD_SESSION_KEY | VISA, /* required */
      SessionKeyDerivationValue: { /* required */
        ApplicationCryptogram: 'STRING_VALUE',
        ApplicationTransactionCounter: 'STRING_VALUE'
      }
    }
  },
  KeyIdentifier: 'STRING_VALUE', /* required */
  MessageData: 'STRING_VALUE', /* required */
  MacLength: 'NUMBER_VALUE'
};
paymentcryptographydata.generateMac(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • KeyIdentifier — (String)

      The keyARN of the MAC generation encryption key.

    • MessageData — (String)

      The data for which a MAC is under generation. This value must be hexBinary.

    • GenerationAttributes — (map)

      The attributes and data values to use for MAC generation within Amazon Web Services Payment Cryptography.

      • Algorithm — (String)

        The encryption algorithm for MAC generation or verification.

        Possible values include:
        • "ISO9797_ALGORITHM1"
        • "ISO9797_ALGORITHM3"
        • "CMAC"
        • "HMAC_SHA224"
        • "HMAC_SHA256"
        • "HMAC_SHA384"
        • "HMAC_SHA512"
      • EmvMac — (map)

        Parameters that are required for MAC generation or verification using EMV MAC algorithm.

        • MajorKeyDerivationModerequired — (String)

          The method to use when deriving the master key for EMV MAC generation or verification.

          Possible values include:
          • "EMV_OPTION_A"
          • "EMV_OPTION_B"
        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN), a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • SessionKeyDerivationModerequired — (String)

          The method of deriving a session key for EMV MAC generation or verification.

          Possible values include:
          • "EMV_COMMON_SESSION_KEY"
          • "EMV2000"
          • "AMEX"
          • "MASTERCARD_SESSION_KEY"
          • "VISA"
        • SessionKeyDerivationValuerequired — (map)

          Parameters that are required to generate session key for EMV generation and verification.

          • ApplicationCryptogram — (String)

            The cryptogram provided by the terminal during transaction processing.

          • ApplicationTransactionCounter — (String)

            The transaction counter that is provided by the terminal during transaction processing.

      • DukptIso9797Algorithm1 — (map)

        Parameters that are required for MAC generation or verification using DUKPT ISO 9797 algorithm1.

        • KeySerialNumberrequired — (String)

          The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

        • DukptKeyVariantrequired — (String)

          The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

          Possible values include:
          • "BIDIRECTIONAL"
          • "REQUEST"
          • "RESPONSE"
        • DukptDerivationType — (String)

          The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

          Possible values include:
          • "TDES_2KEY"
          • "TDES_3KEY"
          • "AES_128"
          • "AES_192"
          • "AES_256"
      • DukptIso9797Algorithm3 — (map)

        Parameters that are required for MAC generation or verification using DUKPT ISO 9797 algorithm3.

        • KeySerialNumberrequired — (String)

          The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

        • DukptKeyVariantrequired — (String)

          The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

          Possible values include:
          • "BIDIRECTIONAL"
          • "REQUEST"
          • "RESPONSE"
        • DukptDerivationType — (String)

          The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

          Possible values include:
          • "TDES_2KEY"
          • "TDES_3KEY"
          • "AES_128"
          • "AES_192"
          • "AES_256"
      • DukptCmac — (map)

        Parameters that are required for MAC generation or verification using DUKPT CMAC algorithm.

        • KeySerialNumberrequired — (String)

          The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

        • DukptKeyVariantrequired — (String)

          The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

          Possible values include:
          • "BIDIRECTIONAL"
          • "REQUEST"
          • "RESPONSE"
        • DukptDerivationType — (String)

          The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

          Possible values include:
          • "TDES_2KEY"
          • "TDES_3KEY"
          • "AES_128"
          • "AES_192"
          • "AES_256"
    • MacLength — (Integer)

      The length of a MAC under generation.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response)

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • KeyArn — (String)

        The keyARN of the encryption key that Amazon Web Services Payment Cryptography uses for MAC generation.

      • KeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

      • Mac — (String)

        The MAC cryptogram generated within Amazon Web Services Payment Cryptography.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

generatePinData(params = {}, callback) ⇒ AWS.Request

Generates pin-related data such as PIN, PIN Verification Value (PVV), PIN Block, and PIN Offset during new card issuance or reissuance. For more information, see Generate PIN data in the Amazon Web Services Payment Cryptography User Guide.

PIN data is never transmitted in clear to or from Amazon Web Services Payment Cryptography. This operation generates PIN, PVV, or PIN Offset and then encrypts it using Pin Encryption Key (PEK) to create an EncryptedPinBlock for transmission from Amazon Web Services Payment Cryptography. This operation uses a separate Pin Verification Key (PVK) for VISA PVV generation.

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:

Service Reference:

Examples:

Calling the generatePinData operation

var params = {
  EncryptionKeyIdentifier: 'STRING_VALUE', /* required */
  GenerationAttributes: { /* required */
    Ibm3624NaturalPin: {
      DecimalizationTable: 'STRING_VALUE', /* required */
      PinValidationData: 'STRING_VALUE', /* required */
      PinValidationDataPadCharacter: 'STRING_VALUE' /* required */
    },
    Ibm3624PinFromOffset: {
      DecimalizationTable: 'STRING_VALUE', /* required */
      PinOffset: 'STRING_VALUE', /* required */
      PinValidationData: 'STRING_VALUE', /* required */
      PinValidationDataPadCharacter: 'STRING_VALUE' /* required */
    },
    Ibm3624PinOffset: {
      DecimalizationTable: 'STRING_VALUE', /* required */
      EncryptedPinBlock: 'STRING_VALUE', /* required */
      PinValidationData: 'STRING_VALUE', /* required */
      PinValidationDataPadCharacter: 'STRING_VALUE' /* required */
    },
    Ibm3624RandomPin: {
      DecimalizationTable: 'STRING_VALUE', /* required */
      PinValidationData: 'STRING_VALUE', /* required */
      PinValidationDataPadCharacter: 'STRING_VALUE' /* required */
    },
    VisaPin: {
      PinVerificationKeyIndex: 'NUMBER_VALUE' /* required */
    },
    VisaPinVerificationValue: {
      EncryptedPinBlock: 'STRING_VALUE', /* required */
      PinVerificationKeyIndex: 'NUMBER_VALUE' /* required */
    }
  },
  GenerationKeyIdentifier: 'STRING_VALUE', /* required */
  PinBlockFormat: ISO_FORMAT_0 | ISO_FORMAT_3, /* required */
  PrimaryAccountNumber: 'STRING_VALUE', /* required */
  PinDataLength: 'NUMBER_VALUE'
};
paymentcryptographydata.generatePinData(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • GenerationKeyIdentifier — (String)

      The keyARN of the PEK that Amazon Web Services Payment Cryptography uses for pin data generation.

    • EncryptionKeyIdentifier — (String)

      The keyARN of the PEK that Amazon Web Services Payment Cryptography uses to encrypt the PIN Block.

    • GenerationAttributes — (map)

      The attributes and values to use for PIN, PVV, or PIN Offset generation.

      • VisaPin — (map)

        Parameters that are required to generate or verify Visa PIN.

        • PinVerificationKeyIndexrequired — (Integer)

          The value for PIN verification index. It is used in the Visa PIN algorithm to calculate the PVV (PIN Verification Value).

      • VisaPinVerificationValue — (map)

        Parameters that are required to generate or verify Visa PIN Verification Value (PVV).

        • EncryptedPinBlockrequired — (String)

          The encrypted PIN block data to verify.

        • PinVerificationKeyIndexrequired — (Integer)

          The value for PIN verification index. It is used in the Visa PIN algorithm to calculate the PVV (PIN Verification Value).

      • Ibm3624PinOffset — (map)

        Parameters that are required to generate or verify Ibm3624 PIN offset PIN.

        • EncryptedPinBlockrequired — (String)

          The encrypted PIN block data. According to ISO 9564 standard, a PIN Block is an encoded representation of a payment card Personal Account Number (PAN) and the cardholder Personal Identification Number (PIN).

        • DecimalizationTablerequired — (String)

          The decimalization table to use for IBM 3624 PIN algorithm. The table is used to convert the algorithm intermediate result from hexadecimal characters to decimal.

        • PinValidationDataPadCharacterrequired — (String)

          The padding character for validation data.

        • PinValidationDatarequired — (String)

          The unique data for cardholder identification.

      • Ibm3624NaturalPin — (map)

        Parameters that are required to generate or verify Ibm3624 natural PIN.

        • DecimalizationTablerequired — (String)

          The decimalization table to use for IBM 3624 PIN algorithm. The table is used to convert the algorithm intermediate result from hexadecimal characters to decimal.

        • PinValidationDataPadCharacterrequired — (String)

          The padding character for validation data.

        • PinValidationDatarequired — (String)

          The unique data for cardholder identification.

      • Ibm3624RandomPin — (map)

        Parameters that are required to generate or verify Ibm3624 random PIN.

        • DecimalizationTablerequired — (String)

          The decimalization table to use for IBM 3624 PIN algorithm. The table is used to convert the algorithm intermediate result from hexadecimal characters to decimal.

        • PinValidationDataPadCharacterrequired — (String)

          The padding character for validation data.

        • PinValidationDatarequired — (String)

          The unique data for cardholder identification.

      • Ibm3624PinFromOffset — (map)

        Parameters that are required to generate or verify Ibm3624 PIN from offset PIN.

        • DecimalizationTablerequired — (String)

          The decimalization table to use for IBM 3624 PIN algorithm. The table is used to convert the algorithm intermediate result from hexadecimal characters to decimal.

        • PinValidationDataPadCharacterrequired — (String)

          The padding character for validation data.

        • PinValidationDatarequired — (String)

          The unique data for cardholder identification.

        • PinOffsetrequired — (String)

          The PIN offset value.

    • PinDataLength — (Integer)

      The length of PIN under generation.

    • PrimaryAccountNumber — (String)

      The Primary Account Number (PAN), a unique identifier for a payment credit or debit card that associates the card with a specific account holder.

    • PinBlockFormat — (String)

      The PIN encoding format for pin data generation as specified in ISO 9564. Amazon Web Services Payment Cryptography supports ISO_Format_0 and ISO_Format_3.

      The ISO_Format_0 PIN block format is equivalent to the ANSI X9.8, VISA-1, and ECI-1 PIN block formats. It is similar to a VISA-4 PIN block format. It supports a PIN from 4 to 12 digits in length.

      The ISO_Format_3 PIN block format is the same as ISO_Format_0 except that the fill digits are random values from 10 to 15.

      Possible values include:
      • "ISO_FORMAT_0"
      • "ISO_FORMAT_3"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response)

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • GenerationKeyArn — (String)

        The keyARN of the pin data generation key that Amazon Web Services Payment Cryptography uses for PIN, PVV or PIN Offset generation.

      • GenerationKeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

      • EncryptionKeyArn — (String)

        The keyARN of the PEK that Amazon Web Services Payment Cryptography uses for encrypted pin block generation.

      • EncryptionKeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

      • EncryptedPinBlock — (String)

        The PIN block encrypted under PEK from Amazon Web Services Payment Cryptography. The encrypted PIN block is a composite of PAN (Primary Account Number) and PIN (Personal Identification Number), generated in accordance with ISO 9564 standard.

      • PinData — (map)

        The attributes and values Amazon Web Services Payment Cryptography uses for pin data generation.

        • PinOffset — (String)

          The PIN offset value.

        • VerificationValue — (String)

          The unique data to identify a cardholder. In most cases, this is the same as cardholder's Primary Account Number (PAN). If a value is not provided, it defaults to PAN.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

reEncryptData(params = {}, callback) ⇒ AWS.Request

Re-encrypt ciphertext using DUKPT or Symmetric data encryption keys.

You can either generate an encryption key within Amazon Web Services Payment Cryptography by calling CreateKey or import your own encryption key by calling ImportKey. The KeyArn for use with this operation must be in a compatible key state with KeyModesOfUse set to Encrypt.

For symmetric and DUKPT encryption, Amazon Web Services Payment Cryptography supports TDES and AES algorithms. To encrypt using DUKPT, a DUKPT key must already exist within your account with KeyModesOfUse set to DeriveKey or a new DUKPT can be generated by calling CreateKey.

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:

Service Reference:

Examples:

Calling the reEncryptData operation

var params = {
  CipherText: 'STRING_VALUE', /* required */
  IncomingEncryptionAttributes: { /* required */
    Dukpt: {
      KeySerialNumber: 'STRING_VALUE', /* required */
      DukptKeyDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256,
      DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE,
      InitializationVector: 'STRING_VALUE',
      Mode: ECB | CBC
    },
    Symmetric: {
      Mode: ECB | CBC | CFB | CFB1 | CFB8 | CFB64 | CFB128 | OFB, /* required */
      InitializationVector: 'STRING_VALUE',
      PaddingType: PKCS1 | OAEP_SHA1 | OAEP_SHA256 | OAEP_SHA512
    }
  },
  IncomingKeyIdentifier: 'STRING_VALUE', /* required */
  OutgoingEncryptionAttributes: { /* required */
    Dukpt: {
      KeySerialNumber: 'STRING_VALUE', /* required */
      DukptKeyDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256,
      DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE,
      InitializationVector: 'STRING_VALUE',
      Mode: ECB | CBC
    },
    Symmetric: {
      Mode: ECB | CBC | CFB | CFB1 | CFB8 | CFB64 | CFB128 | OFB, /* required */
      InitializationVector: 'STRING_VALUE',
      PaddingType: PKCS1 | OAEP_SHA1 | OAEP_SHA256 | OAEP_SHA512
    }
  },
  OutgoingKeyIdentifier: 'STRING_VALUE', /* required */
  IncomingWrappedKey: {
    WrappedKeyMaterial: { /* required */
      Tr31KeyBlock: 'STRING_VALUE'
    },
    KeyCheckValueAlgorithm: CMAC | ANSI_X9_24
  },
  OutgoingWrappedKey: {
    WrappedKeyMaterial: { /* required */
      Tr31KeyBlock: 'STRING_VALUE'
    },
    KeyCheckValueAlgorithm: CMAC | ANSI_X9_24
  }
};
paymentcryptographydata.reEncryptData(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • IncomingKeyIdentifier — (String)

      The keyARN of the encryption key of incoming ciphertext data.

      When a WrappedKeyBlock is provided, this value will be the identifier to the key wrapping key. Otherwise, it is the key identifier used to perform the operation.

    • OutgoingKeyIdentifier — (String)

      The keyARN of the encryption key of outgoing ciphertext data after encryption by Amazon Web Services Payment Cryptography.

    • CipherText — (String)

      Ciphertext to be encrypted. The minimum allowed length is 16 bytes and maximum allowed length is 4096 bytes.

    • IncomingEncryptionAttributes — (map)

      The attributes and values for incoming ciphertext.

      • Symmetric — (map)

        Parameters that are required to encrypt data using symmetric keys.

        • Moderequired — (String)

          The block cipher method to use for encryption.

          Possible values include:
          • "ECB"
          • "CBC"
          • "CFB"
          • "CFB1"
          • "CFB8"
          • "CFB64"
          • "CFB128"
          • "OFB"
        • InitializationVector — (String)

          An input used to provide the intial state. If no value is provided, Amazon Web Services Payment Cryptography defaults it to zero.

        • PaddingType — (String)

          The padding to be included with the data.

          Possible values include:
          • "PKCS1"
          • "OAEP_SHA1"
          • "OAEP_SHA256"
          • "OAEP_SHA512"
      • Dukpt — (map)

        Parameters that are required to encrypt plaintext data using DUKPT.

        • KeySerialNumberrequired — (String)

          The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

        • Mode — (String)

          The block cipher method to use for encryption.

          The default is CBC.

          Possible values include:
          • "ECB"
          • "CBC"
        • DukptKeyDerivationType — (String)

          The key type encrypted using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY

          Possible values include:
          • "TDES_2KEY"
          • "TDES_3KEY"
          • "AES_128"
          • "AES_192"
          • "AES_256"
        • DukptKeyVariant — (String)

          The type of use of DUKPT, which can be incoming data decryption, outgoing data encryption, or both.

          Possible values include:
          • "BIDIRECTIONAL"
          • "REQUEST"
          • "RESPONSE"
        • InitializationVector — (String)

          An input used to provide the intial state. If no value is provided, Amazon Web Services Payment Cryptography defaults it to zero.

    • OutgoingEncryptionAttributes — (map)

      The attributes and values for outgoing ciphertext data after encryption by Amazon Web Services Payment Cryptography.

      • Symmetric — (map)

        Parameters that are required to encrypt data using symmetric keys.

        • Moderequired — (String)

          The block cipher method to use for encryption.

          Possible values include:
          • "ECB"
          • "CBC"
          • "CFB"
          • "CFB1"
          • "CFB8"
          • "CFB64"
          • "CFB128"
          • "OFB"
        • InitializationVector — (String)

          An input used to provide the intial state. If no value is provided, Amazon Web Services Payment Cryptography defaults it to zero.

        • PaddingType — (String)

          The padding to be included with the data.

          Possible values include:
          • "PKCS1"
          • "OAEP_SHA1"
          • "OAEP_SHA256"
          • "OAEP_SHA512"
      • Dukpt — (map)

        Parameters that are required to encrypt plaintext data using DUKPT.

        • KeySerialNumberrequired — (String)

          The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

        • Mode — (String)

          The block cipher method to use for encryption.

          The default is CBC.

          Possible values include:
          • "ECB"
          • "CBC"
        • DukptKeyDerivationType — (String)

          The key type encrypted using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY

          Possible values include:
          • "TDES_2KEY"
          • "TDES_3KEY"
          • "AES_128"
          • "AES_192"
          • "AES_256"
        • DukptKeyVariant — (String)

          The type of use of DUKPT, which can be incoming data decryption, outgoing data encryption, or both.

          Possible values include:
          • "BIDIRECTIONAL"
          • "REQUEST"
          • "RESPONSE"
        • InitializationVector — (String)

          An input used to provide the intial state. If no value is provided, Amazon Web Services Payment Cryptography defaults it to zero.

    • IncomingWrappedKey — (map)

      The WrappedKeyBlock containing the encryption key of incoming ciphertext data.

      • WrappedKeyMaterialrequired — (map)

        Parameter information of a WrappedKeyBlock for encryption key exchange.

        • Tr31KeyBlock — (String)

          The TR-31 wrapped key block.

      • KeyCheckValueAlgorithm — (String)

        The algorithm that Amazon Web Services Payment Cryptography uses to calculate the key check value (KCV). It is used to validate the key integrity.

        For TDES keys, the KCV is computed by encrypting 8 bytes, each with value of zero, with the key to be checked and retaining the 3 highest order bytes of the encrypted result. For AES keys, the KCV is computed using a CMAC algorithm where the input data is 16 bytes of zero and retaining the 3 highest order bytes of the encrypted result.

        Possible values include:
        • "CMAC"
        • "ANSI_X9_24"
    • OutgoingWrappedKey — (map)

      The WrappedKeyBlock containing the encryption key of outgoing ciphertext data after encryption by Amazon Web Services Payment Cryptography.

      • WrappedKeyMaterialrequired — (map)

        Parameter information of a WrappedKeyBlock for encryption key exchange.

        • Tr31KeyBlock — (String)

          The TR-31 wrapped key block.

      • KeyCheckValueAlgorithm — (String)

        The algorithm that Amazon Web Services Payment Cryptography uses to calculate the key check value (KCV). It is used to validate the key integrity.

        For TDES keys, the KCV is computed by encrypting 8 bytes, each with value of zero, with the key to be checked and retaining the 3 highest order bytes of the encrypted result. For AES keys, the KCV is computed using a CMAC algorithm where the input data is 16 bytes of zero and retaining the 3 highest order bytes of the encrypted result.

        Possible values include:
        • "CMAC"
        • "ANSI_X9_24"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response)

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • KeyArn — (String)

        The keyARN (Amazon Resource Name) of the encryption key that Amazon Web Services Payment Cryptography uses for plaintext encryption.

      • KeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

      • CipherText — (String)

        The encrypted ciphertext.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

translatePinData(params = {}, callback) ⇒ AWS.Request

Translates encrypted PIN block from and to ISO 9564 formats 0,1,3,4. For more information, see Translate PIN data in the Amazon Web Services Payment Cryptography User Guide.

PIN block translation involves changing the encrytion of PIN block from one encryption key to another encryption key and changing PIN block format from one to another without PIN block data leaving Amazon Web Services Payment Cryptography. The encryption key transformation can be from PEK (Pin Encryption Key) to BDK (Base Derivation Key) for DUKPT or from BDK for DUKPT to PEK. Amazon Web Services Payment Cryptography supports TDES and AES key derivation type for DUKPT translations.

The allowed combinations of PIN block format translations are guided by PCI. It is important to note that not all encrypted PIN block formats (example, format 1) require PAN (Primary Account Number) as input. And as such, PIN block format that requires PAN (example, formats 0,3,4) cannot be translated to a format (format 1) that does not require a PAN for generation.

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.

Note: Amazon Web Services Payment Cryptography currently supports ISO PIN block 4 translation for PIN block built using legacy PAN length. That is, PAN is the right most 12 digits excluding the check digits.

Cross-account use: This operation can't be used across different Amazon Web Services accounts.

Related operations:

Service Reference:

Examples:

Calling the translatePinData operation

var params = {
  EncryptedPinBlock: 'STRING_VALUE', /* required */
  IncomingKeyIdentifier: 'STRING_VALUE', /* required */
  IncomingTranslationAttributes: { /* required */
    IsoFormat0: {
      PrimaryAccountNumber: 'STRING_VALUE' /* required */
    },
    IsoFormat1: {
    },
    IsoFormat3: {
      PrimaryAccountNumber: 'STRING_VALUE' /* required */
    },
    IsoFormat4: {
      PrimaryAccountNumber: 'STRING_VALUE' /* required */
    }
  },
  OutgoingKeyIdentifier: 'STRING_VALUE', /* required */
  OutgoingTranslationAttributes: { /* required */
    IsoFormat0: {
      PrimaryAccountNumber: 'STRING_VALUE' /* required */
    },
    IsoFormat1: {
    },
    IsoFormat3: {
      PrimaryAccountNumber: 'STRING_VALUE' /* required */
    },
    IsoFormat4: {
      PrimaryAccountNumber: 'STRING_VALUE' /* required */
    }
  },
  IncomingDukptAttributes: {
    KeySerialNumber: 'STRING_VALUE', /* required */
    DukptKeyDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256,
    DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE
  },
  IncomingWrappedKey: {
    WrappedKeyMaterial: { /* required */
      Tr31KeyBlock: 'STRING_VALUE'
    },
    KeyCheckValueAlgorithm: CMAC | ANSI_X9_24
  },
  OutgoingDukptAttributes: {
    KeySerialNumber: 'STRING_VALUE', /* required */
    DukptKeyDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256,
    DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE
  },
  OutgoingWrappedKey: {
    WrappedKeyMaterial: { /* required */
      Tr31KeyBlock: 'STRING_VALUE'
    },
    KeyCheckValueAlgorithm: CMAC | ANSI_X9_24
  }
};
paymentcryptographydata.translatePinData(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • IncomingKeyIdentifier — (String)

      The keyARN of the encryption key under which incoming PIN block data is encrypted. This key type can be PEK or BDK.

      When a WrappedKeyBlock is provided, this value will be the identifier to the key wrapping key for PIN block. Otherwise, it is the key identifier used to perform the operation.

    • OutgoingKeyIdentifier — (String)

      The keyARN of the encryption key for encrypting outgoing PIN block data. This key type can be PEK or BDK.

    • IncomingTranslationAttributes — (map)

      The format of the incoming PIN block data for translation within Amazon Web Services Payment Cryptography.

      • IsoFormat0 — (map)

        Parameters that are required for ISO9564 PIN format 0 tranlation.

        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

      • IsoFormat1 — (map)

        Parameters that are required for ISO9564 PIN format 1 tranlation.

      • IsoFormat3 — (map)

        Parameters that are required for ISO9564 PIN format 3 tranlation.

        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

      • IsoFormat4 — (map)

        Parameters that are required for ISO9564 PIN format 4 tranlation.

        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • OutgoingTranslationAttributes — (map)

      The format of the outgoing PIN block data after translation by Amazon Web Services Payment Cryptography.

      • IsoFormat0 — (map)

        Parameters that are required for ISO9564 PIN format 0 tranlation.

        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

      • IsoFormat1 — (map)

        Parameters that are required for ISO9564 PIN format 1 tranlation.

      • IsoFormat3 — (map)

        Parameters that are required for ISO9564 PIN format 3 tranlation.

        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

      • IsoFormat4 — (map)

        Parameters that are required for ISO9564 PIN format 4 tranlation.

        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

    • EncryptedPinBlock — (String)

      The encrypted PIN block data that Amazon Web Services Payment Cryptography translates.

    • IncomingDukptAttributes — (map)

      The attributes and values to use for incoming DUKPT encryption key for PIN block translation.

      • KeySerialNumberrequired — (String)

        The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

      • DukptKeyDerivationType — (String)

        The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY

        Possible values include:
        • "TDES_2KEY"
        • "TDES_3KEY"
        • "AES_128"
        • "AES_192"
        • "AES_256"
      • DukptKeyVariant — (String)

        The type of use of DUKPT, which can be for incoming data decryption, outgoing data encryption, or both.

        Possible values include:
        • "BIDIRECTIONAL"
        • "REQUEST"
        • "RESPONSE"
    • OutgoingDukptAttributes — (map)

      The attributes and values to use for outgoing DUKPT encryption key after PIN block translation.

      • KeySerialNumberrequired — (String)

        The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

      • DukptKeyDerivationType — (String)

        The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY

        Possible values include:
        • "TDES_2KEY"
        • "TDES_3KEY"
        • "AES_128"
        • "AES_192"
        • "AES_256"
      • DukptKeyVariant — (String)

        The type of use of DUKPT, which can be for incoming data decryption, outgoing data encryption, or both.

        Possible values include:
        • "BIDIRECTIONAL"
        • "REQUEST"
        • "RESPONSE"
    • IncomingWrappedKey — (map)

      The WrappedKeyBlock containing the encryption key under which incoming PIN block data is encrypted.

      • WrappedKeyMaterialrequired — (map)

        Parameter information of a WrappedKeyBlock for encryption key exchange.

        • Tr31KeyBlock — (String)

          The TR-31 wrapped key block.

      • KeyCheckValueAlgorithm — (String)

        The algorithm that Amazon Web Services Payment Cryptography uses to calculate the key check value (KCV). It is used to validate the key integrity.

        For TDES keys, the KCV is computed by encrypting 8 bytes, each with value of zero, with the key to be checked and retaining the 3 highest order bytes of the encrypted result. For AES keys, the KCV is computed using a CMAC algorithm where the input data is 16 bytes of zero and retaining the 3 highest order bytes of the encrypted result.

        Possible values include:
        • "CMAC"
        • "ANSI_X9_24"
    • OutgoingWrappedKey — (map)

      The WrappedKeyBlock containing the encryption key for encrypting outgoing PIN block data.

      • WrappedKeyMaterialrequired — (map)

        Parameter information of a WrappedKeyBlock for encryption key exchange.

        • Tr31KeyBlock — (String)

          The TR-31 wrapped key block.

      • KeyCheckValueAlgorithm — (String)

        The algorithm that Amazon Web Services Payment Cryptography uses to calculate the key check value (KCV). It is used to validate the key integrity.

        For TDES keys, the KCV is computed by encrypting 8 bytes, each with value of zero, with the key to be checked and retaining the 3 highest order bytes of the encrypted result. For AES keys, the KCV is computed using a CMAC algorithm where the input data is 16 bytes of zero and retaining the 3 highest order bytes of the encrypted result.

        Possible values include:
        • "CMAC"
        • "ANSI_X9_24"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response)

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • PinBlock — (String)

        The outgoing encrypted PIN block data after translation.

      • KeyArn — (String)

        The keyARN of the encryption key that Amazon Web Services Payment Cryptography uses to encrypt outgoing PIN block data after translation.

      • KeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

verifyAuthRequestCryptogram(params = {}, callback) ⇒ AWS.Request

Verifies Authorization Request Cryptogram (ARQC) for a EMV chip payment card authorization. For more information, see Verify auth request cryptogram in the Amazon Web Services Payment Cryptography User Guide.

ARQC generation is done outside of Amazon Web Services Payment Cryptography and is typically generated on a point of sale terminal for an EMV chip card to obtain payment authorization during transaction time. For ARQC verification, you must first import the ARQC generated outside of Amazon Web Services Payment Cryptography by calling ImportKey. This operation uses the imported ARQC and an major encryption key (DUKPT) created by calling CreateKey to either provide a boolean ARQC verification result or provide an APRC (Authorization Response Cryptogram) response using Method 1 or Method 2. The ARPC_METHOD_1 uses AuthResponseCode to generate ARPC and ARPC_METHOD_2 uses CardStatusUpdate to generate ARPC.

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:

Service Reference:

Examples:

Calling the verifyAuthRequestCryptogram operation

var params = {
  AuthRequestCryptogram: 'STRING_VALUE', /* required */
  KeyIdentifier: 'STRING_VALUE', /* required */
  MajorKeyDerivationMode: EMV_OPTION_A | EMV_OPTION_B, /* required */
  SessionKeyDerivationAttributes: { /* required */
    Amex: {
      PanSequenceNumber: 'STRING_VALUE', /* required */
      PrimaryAccountNumber: 'STRING_VALUE' /* required */
    },
    Emv2000: {
      ApplicationTransactionCounter: 'STRING_VALUE', /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      PrimaryAccountNumber: 'STRING_VALUE' /* required */
    },
    EmvCommon: {
      ApplicationTransactionCounter: 'STRING_VALUE', /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      PrimaryAccountNumber: 'STRING_VALUE' /* required */
    },
    Mastercard: {
      ApplicationTransactionCounter: 'STRING_VALUE', /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      PrimaryAccountNumber: 'STRING_VALUE', /* required */
      UnpredictableNumber: 'STRING_VALUE' /* required */
    },
    Visa: {
      PanSequenceNumber: 'STRING_VALUE', /* required */
      PrimaryAccountNumber: 'STRING_VALUE' /* required */
    }
  },
  TransactionData: 'STRING_VALUE', /* required */
  AuthResponseAttributes: {
    ArpcMethod1: {
      AuthResponseCode: 'STRING_VALUE' /* required */
    },
    ArpcMethod2: {
      CardStatusUpdate: 'STRING_VALUE', /* required */
      ProprietaryAuthenticationData: 'STRING_VALUE'
    }
  }
};
paymentcryptographydata.verifyAuthRequestCryptogram(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • KeyIdentifier — (String)

      The keyARN of the major encryption key that Amazon Web Services Payment Cryptography uses for ARQC verification.

    • TransactionData — (String)

      The transaction data that Amazon Web Services Payment Cryptography uses for ARQC verification. The same transaction is used for ARQC generation outside of Amazon Web Services Payment Cryptography.

    • AuthRequestCryptogram — (String)

      The auth request cryptogram imported into Amazon Web Services Payment Cryptography for ARQC verification using a major encryption key and transaction data.

    • MajorKeyDerivationMode — (String)

      The method to use when deriving the major encryption key for ARQC verification within Amazon Web Services Payment Cryptography. The same key derivation mode was used for ARQC generation outside of Amazon Web Services Payment Cryptography.

      Possible values include:
      • "EMV_OPTION_A"
      • "EMV_OPTION_B"
    • SessionKeyDerivationAttributes — (map)

      The attributes and values to use for deriving a session key for ARQC verification within Amazon Web Services Payment Cryptography. The same attributes were used for ARQC generation outside of Amazon Web Services Payment Cryptography.

      • EmvCommon — (map)

        Parameters to derive session key for an Emv common payment card for ARQC verification.

        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • ApplicationTransactionCounterrequired — (String)

          The transaction counter that is provided by the terminal during transaction processing.

      • Mastercard — (map)

        Parameters to derive session key for a Mastercard payment card for ARQC verification.

        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • ApplicationTransactionCounterrequired — (String)

          The transaction counter that is provided by the terminal during transaction processing.

        • UnpredictableNumberrequired — (String)

          A random number generated by the issuer.

      • Emv2000 — (map)

        Parameters to derive session key for an Emv2000 payment card for ARQC verification.

        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • ApplicationTransactionCounterrequired — (String)

          The transaction counter that is provided by the terminal during transaction processing.

      • Amex — (map)

        Parameters to derive session key for an Amex payment card for ARQC verification.

        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

      • Visa — (map)

        Parameters to derive session key for a Visa payment cardfor ARQC verification.

        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN) of the cardholder. A PAN is a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

    • AuthResponseAttributes — (map)

      The attributes and values for auth request cryptogram verification. These parameters are required in case using ARPC Method 1 or Method 2 for ARQC verification.

      • ArpcMethod1 — (map)

        Parameters that are required for ARPC response generation using method1 after ARQC verification is successful.

        • AuthResponseCoderequired — (String)

          The auth code used to calculate APRC after ARQC verification is successful. This is the same auth code used for ARQC generation outside of Amazon Web Services Payment Cryptography.

      • ArpcMethod2 — (map)

        Parameters that are required for ARPC response generation using method2 after ARQC verification is successful.

        • CardStatusUpdaterequired — (String)

          The data indicating whether the issuer approves or declines an online transaction using an EMV chip card.

        • ProprietaryAuthenticationData — (String)

          The proprietary authentication data used by issuer for communication during online transaction using an EMV chip card.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response)

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • KeyArn — (String)

        The keyARN of the major encryption key that Amazon Web Services Payment Cryptography uses for ARQC verification.

      • KeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

      • AuthResponseValue — (String)

        The result for ARQC verification or ARPC generation within Amazon Web Services Payment Cryptography.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

verifyCardValidationData(params = {}, callback) ⇒ AWS.Request

Verifies card-related validation data using algorithms such as Card Verification Values (CVV/CVV2), Dynamic Card Verification Values (dCVV/dCVV2) and Card Security Codes (CSC). For more information, see Verify card data in the Amazon Web Services Payment Cryptography User Guide.

This operation validates the CVV or CSC codes that is printed on a payment credit or debit card during card payment transaction. The input values are typically provided as part of an inbound transaction to an issuer or supporting platform partner. Amazon Web Services Payment Cryptography uses CVV or CSC, PAN (Primary Account Number) and expiration date of the card to check its validity during transaction processing. In this operation, the CVK (Card Verification Key) encryption key for use with card data verification is same as the one in used for GenerateCardValidationData.

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:

Service Reference:

Examples:

Calling the verifyCardValidationData operation

var params = {
  KeyIdentifier: 'STRING_VALUE', /* required */
  PrimaryAccountNumber: 'STRING_VALUE', /* required */
  ValidationData: 'STRING_VALUE', /* required */
  VerificationAttributes: { /* required */
    AmexCardSecurityCodeVersion1: {
      CardExpiryDate: 'STRING_VALUE' /* required */
    },
    AmexCardSecurityCodeVersion2: {
      CardExpiryDate: 'STRING_VALUE', /* required */
      ServiceCode: 'STRING_VALUE' /* required */
    },
    CardHolderVerificationValue: {
      ApplicationTransactionCounter: 'STRING_VALUE', /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      UnpredictableNumber: 'STRING_VALUE' /* required */
    },
    CardVerificationValue1: {
      CardExpiryDate: 'STRING_VALUE', /* required */
      ServiceCode: 'STRING_VALUE' /* required */
    },
    CardVerificationValue2: {
      CardExpiryDate: 'STRING_VALUE' /* required */
    },
    DiscoverDynamicCardVerificationCode: {
      ApplicationTransactionCounter: 'STRING_VALUE', /* required */
      CardExpiryDate: 'STRING_VALUE', /* required */
      UnpredictableNumber: 'STRING_VALUE' /* required */
    },
    DynamicCardVerificationCode: {
      ApplicationTransactionCounter: 'STRING_VALUE', /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      TrackData: 'STRING_VALUE', /* required */
      UnpredictableNumber: 'STRING_VALUE' /* required */
    },
    DynamicCardVerificationValue: {
      ApplicationTransactionCounter: 'STRING_VALUE', /* required */
      CardExpiryDate: 'STRING_VALUE', /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      ServiceCode: 'STRING_VALUE' /* required */
    }
  }
};
paymentcryptographydata.verifyCardValidationData(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • KeyIdentifier — (String)

      The keyARN of the CVK encryption key that Amazon Web Services Payment Cryptography uses to verify card data.

    • PrimaryAccountNumber — (String)

      The Primary Account Number (PAN), a unique identifier for a payment credit or debit card that associates the card with a specific account holder.

    • VerificationAttributes — (map)

      The algorithm to use for verification of card data within Amazon Web Services Payment Cryptography.

      • AmexCardSecurityCodeVersion1 — (map)

        Card data parameters that are required to generate a Card Security Code (CSC2) for an AMEX payment card.

        • CardExpiryDaterequired — (String)

          The expiry date of a payment card.

      • AmexCardSecurityCodeVersion2 — (map)

        Card data parameters that are required to verify a Card Security Code (CSC2) for an AMEX payment card.

        • CardExpiryDaterequired — (String)

          The expiry date of a payment card.

        • ServiceCoderequired — (String)

          The service code of the AMEX payment card. This is different from the Card Security Code (CSC).

      • CardVerificationValue1 — (map)

        Card data parameters that are required to verify Card Verification Value (CVV) for the payment card.

        • CardExpiryDaterequired — (String)

          The expiry date of a payment card.

        • ServiceCoderequired — (String)

          The service code of the payment card. This is different from Card Security Code (CSC).

      • CardVerificationValue2 — (map)

        Card data parameters that are required to verify Card Verification Value (CVV2) for the payment card.

        • CardExpiryDaterequired — (String)

          The expiry date of a payment card.

      • CardHolderVerificationValue — (map)

        Card data parameters that are required to verify a cardholder verification value for the payment card.

        • UnpredictableNumberrequired — (String)

          A random number generated by the issuer.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • ApplicationTransactionCounterrequired — (String)

          The transaction counter value that comes from a point of sale terminal.

      • DynamicCardVerificationCode — (map)

        Card data parameters that are required to verify CDynamic Card Verification Code (dCVC) for the payment card.

        • UnpredictableNumberrequired — (String)

          A random number generated by the issuer.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • ApplicationTransactionCounterrequired — (String)

          The transaction counter value that comes from the terminal.

        • TrackDatarequired — (String)

          The data on the two tracks of magnetic cards used for financial transactions. This includes the cardholder name, PAN, expiration date, bank ID (BIN) and several other numbers the issuing bank uses to validate the data received.

      • DynamicCardVerificationValue — (map)

        Card data parameters that are required to verify CDynamic Card Verification Value (dCVV) for the payment card.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • CardExpiryDaterequired — (String)

          The expiry date of a payment card.

        • ServiceCoderequired — (String)

          The service code of the payment card. This is different from Card Security Code (CSC).

        • ApplicationTransactionCounterrequired — (String)

          The transaction counter value that comes from the terminal.

      • DiscoverDynamicCardVerificationCode — (map)

        Card data parameters that are required to verify CDynamic Card Verification Code (dCVC) for the payment card.

        • CardExpiryDaterequired — (String)

          The expiry date of a payment card.

        • UnpredictableNumberrequired — (String)

          A random number that is generated by the issuer.

        • ApplicationTransactionCounterrequired — (String)

          The transaction counter value that comes from the terminal.

    • ValidationData — (String)

      The CVV or CSC value for use for card data verification within Amazon Web Services Payment Cryptography.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response)

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • KeyArn — (String)

        The keyARN of the CVK encryption key that Amazon Web Services Payment Cryptography uses to verify CVV or CSC.

      • KeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

verifyMac(params = {}, callback) ⇒ AWS.Request

Verifies a Message Authentication Code (MAC).

You can use this operation to verify MAC for message data authentication such as . In this operation, you must use the same message data, secret encryption key and MAC algorithm that was used to generate MAC. You can use this operation to verify a DUPKT, CMAC, HMAC or EMV MAC by setting generation attributes and algorithm to the associated values.

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:

Service Reference:

Examples:

Calling the verifyMac operation

var params = {
  KeyIdentifier: 'STRING_VALUE', /* required */
  Mac: 'STRING_VALUE', /* required */
  MessageData: 'STRING_VALUE', /* required */
  VerificationAttributes: { /* required */
    Algorithm: ISO9797_ALGORITHM1 | ISO9797_ALGORITHM3 | CMAC | HMAC_SHA224 | HMAC_SHA256 | HMAC_SHA384 | HMAC_SHA512,
    DukptCmac: {
      DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE, /* required */
      KeySerialNumber: 'STRING_VALUE', /* required */
      DukptDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256
    },
    DukptIso9797Algorithm1: {
      DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE, /* required */
      KeySerialNumber: 'STRING_VALUE', /* required */
      DukptDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256
    },
    DukptIso9797Algorithm3: {
      DukptKeyVariant: BIDIRECTIONAL | REQUEST | RESPONSE, /* required */
      KeySerialNumber: 'STRING_VALUE', /* required */
      DukptDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256
    },
    EmvMac: {
      MajorKeyDerivationMode: EMV_OPTION_A | EMV_OPTION_B, /* required */
      PanSequenceNumber: 'STRING_VALUE', /* required */
      PrimaryAccountNumber: 'STRING_VALUE', /* required */
      SessionKeyDerivationMode: EMV_COMMON_SESSION_KEY | EMV2000 | AMEX | MASTERCARD_SESSION_KEY | VISA, /* required */
      SessionKeyDerivationValue: { /* required */
        ApplicationCryptogram: 'STRING_VALUE',
        ApplicationTransactionCounter: 'STRING_VALUE'
      }
    }
  },
  MacLength: 'NUMBER_VALUE'
};
paymentcryptographydata.verifyMac(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • KeyIdentifier — (String)

      The keyARN of the encryption key that Amazon Web Services Payment Cryptography uses to verify MAC data.

    • MessageData — (String)

      The data on for which MAC is under verification. This value must be hexBinary.

    • Mac — (String)

      The MAC being verified.

    • VerificationAttributes — (map)

      The attributes and data values to use for MAC verification within Amazon Web Services Payment Cryptography.

      • Algorithm — (String)

        The encryption algorithm for MAC generation or verification.

        Possible values include:
        • "ISO9797_ALGORITHM1"
        • "ISO9797_ALGORITHM3"
        • "CMAC"
        • "HMAC_SHA224"
        • "HMAC_SHA256"
        • "HMAC_SHA384"
        • "HMAC_SHA512"
      • EmvMac — (map)

        Parameters that are required for MAC generation or verification using EMV MAC algorithm.

        • MajorKeyDerivationModerequired — (String)

          The method to use when deriving the master key for EMV MAC generation or verification.

          Possible values include:
          • "EMV_OPTION_A"
          • "EMV_OPTION_B"
        • PrimaryAccountNumberrequired — (String)

          The Primary Account Number (PAN), a unique identifier for a payment credit or debit card and associates the card to a specific account holder.

        • PanSequenceNumberrequired — (String)

          A number that identifies and differentiates payment cards with the same Primary Account Number (PAN).

        • SessionKeyDerivationModerequired — (String)

          The method of deriving a session key for EMV MAC generation or verification.

          Possible values include:
          • "EMV_COMMON_SESSION_KEY"
          • "EMV2000"
          • "AMEX"
          • "MASTERCARD_SESSION_KEY"
          • "VISA"
        • SessionKeyDerivationValuerequired — (map)

          Parameters that are required to generate session key for EMV generation and verification.

          • ApplicationCryptogram — (String)

            The cryptogram provided by the terminal during transaction processing.

          • ApplicationTransactionCounter — (String)

            The transaction counter that is provided by the terminal during transaction processing.

      • DukptIso9797Algorithm1 — (map)

        Parameters that are required for MAC generation or verification using DUKPT ISO 9797 algorithm1.

        • KeySerialNumberrequired — (String)

          The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

        • DukptKeyVariantrequired — (String)

          The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

          Possible values include:
          • "BIDIRECTIONAL"
          • "REQUEST"
          • "RESPONSE"
        • DukptDerivationType — (String)

          The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

          Possible values include:
          • "TDES_2KEY"
          • "TDES_3KEY"
          • "AES_128"
          • "AES_192"
          • "AES_256"
      • DukptIso9797Algorithm3 — (map)

        Parameters that are required for MAC generation or verification using DUKPT ISO 9797 algorithm3.

        • KeySerialNumberrequired — (String)

          The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

        • DukptKeyVariantrequired — (String)

          The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

          Possible values include:
          • "BIDIRECTIONAL"
          • "REQUEST"
          • "RESPONSE"
        • DukptDerivationType — (String)

          The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

          Possible values include:
          • "TDES_2KEY"
          • "TDES_3KEY"
          • "AES_128"
          • "AES_192"
          • "AES_256"
      • DukptCmac — (map)

        Parameters that are required for MAC generation or verification using DUKPT CMAC algorithm.

        • KeySerialNumberrequired — (String)

          The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

        • DukptKeyVariantrequired — (String)

          The type of use of DUKPT, which can be MAC generation, MAC verification, or both.

          Possible values include:
          • "BIDIRECTIONAL"
          • "REQUEST"
          • "RESPONSE"
        • DukptDerivationType — (String)

          The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

          Possible values include:
          • "TDES_2KEY"
          • "TDES_3KEY"
          • "AES_128"
          • "AES_192"
          • "AES_256"
    • MacLength — (Integer)

      The length of the MAC.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response)

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • KeyArn — (String)

        The keyARN of the encryption key that Amazon Web Services Payment Cryptography uses for MAC verification.

      • KeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

verifyPinData(params = {}, callback) ⇒ AWS.Request

Verifies pin-related data such as PIN and PIN Offset using algorithms including VISA PVV and IBM3624. For more information, see Verify PIN data in the Amazon Web Services Payment Cryptography User Guide.

This operation verifies PIN data for user payment card. A card holder PIN data is never transmitted in clear to or from Amazon Web Services Payment Cryptography. This operation uses PIN Verification Key (PVK) for PIN or PIN Offset generation and then encrypts it using PIN Encryption Key (PEK) to create an EncryptedPinBlock for transmission from Amazon Web Services Payment Cryptography.

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:

Service Reference:

Examples:

Calling the verifyPinData operation

var params = {
  EncryptedPinBlock: 'STRING_VALUE', /* required */
  EncryptionKeyIdentifier: 'STRING_VALUE', /* required */
  PinBlockFormat: ISO_FORMAT_0 | ISO_FORMAT_3, /* required */
  PrimaryAccountNumber: 'STRING_VALUE', /* required */
  VerificationAttributes: { /* required */
    Ibm3624Pin: {
      DecimalizationTable: 'STRING_VALUE', /* required */
      PinOffset: 'STRING_VALUE', /* required */
      PinValidationData: 'STRING_VALUE', /* required */
      PinValidationDataPadCharacter: 'STRING_VALUE' /* required */
    },
    VisaPin: {
      PinVerificationKeyIndex: 'NUMBER_VALUE', /* required */
      VerificationValue: 'STRING_VALUE' /* required */
    }
  },
  VerificationKeyIdentifier: 'STRING_VALUE', /* required */
  DukptAttributes: {
    DukptDerivationType: TDES_2KEY | TDES_3KEY | AES_128 | AES_192 | AES_256, /* required */
    KeySerialNumber: 'STRING_VALUE' /* required */
  },
  PinDataLength: 'NUMBER_VALUE'
};
paymentcryptographydata.verifyPinData(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) (defaults to: {})
    • VerificationKeyIdentifier — (String)

      The keyARN of the PIN verification key.

    • EncryptionKeyIdentifier — (String)

      The keyARN of the encryption key under which the PIN block data is encrypted. This key type can be PEK or BDK.

    • VerificationAttributes — (map)

      The attributes and values for PIN data verification.

      • VisaPin — (map)

        Parameters that are required to generate or verify Visa PIN.

        • PinVerificationKeyIndexrequired — (Integer)

          The value for PIN verification index. It is used in the Visa PIN algorithm to calculate the PVV (PIN Verification Value).

        • VerificationValuerequired — (String)

          Parameters that are required to generate or verify Visa PVV (PIN Verification Value).

      • Ibm3624Pin — (map)

        Parameters that are required to generate or verify Ibm3624 PIN.

        • DecimalizationTablerequired — (String)

          The decimalization table to use for IBM 3624 PIN algorithm. The table is used to convert the algorithm intermediate result from hexadecimal characters to decimal.

        • PinValidationDataPadCharacterrequired — (String)

          The padding character for validation data.

        • PinValidationDatarequired — (String)

          The unique data for cardholder identification.

        • PinOffsetrequired — (String)

          The PIN offset value.

    • EncryptedPinBlock — (String)

      The encrypted PIN block data that Amazon Web Services Payment Cryptography verifies.

    • PrimaryAccountNumber — (String)

      The Primary Account Number (PAN), a unique identifier for a payment credit or debit card that associates the card with a specific account holder.

    • PinBlockFormat — (String)

      The PIN encoding format for pin data generation as specified in ISO 9564. Amazon Web Services Payment Cryptography supports ISO_Format_0 and ISO_Format_3.

      The ISO_Format_0 PIN block format is equivalent to the ANSI X9.8, VISA-1, and ECI-1 PIN block formats. It is similar to a VISA-4 PIN block format. It supports a PIN from 4 to 12 digits in length.

      The ISO_Format_3 PIN block format is the same as ISO_Format_0 except that the fill digits are random values from 10 to 15.

      Possible values include:
      • "ISO_FORMAT_0"
      • "ISO_FORMAT_3"
    • PinDataLength — (Integer)

      The length of PIN being verified.

    • DukptAttributes — (map)

      The attributes and values for the DUKPT encrypted PIN block data.

      • KeySerialNumberrequired — (String)

        The unique identifier known as Key Serial Number (KSN) that comes from an encrypting device using DUKPT encryption method. The KSN is derived from the encrypting device unique identifier and an internal transaction counter.

      • DukptDerivationTyperequired — (String)

        The key type derived using DUKPT from a Base Derivation Key (BDK) and Key Serial Number (KSN). This must be less than or equal to the strength of the BDK. For example, you can't use AES_128 as a derivation type for a BDK of AES_128 or TDES_2KEY.

        Possible values include:
        • "TDES_2KEY"
        • "TDES_3KEY"
        • "AES_128"
        • "AES_192"
        • "AES_256"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response)

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error)

      the error object returned from the request. Set to null if the request is successful.

    • data (Object)

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • VerificationKeyArn — (String)

        The keyARN of the PIN encryption key that Amazon Web Services Payment Cryptography uses for PIN or PIN Offset verification.

      • VerificationKeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

      • EncryptionKeyArn — (String)

        The keyARN of the PEK that Amazon Web Services Payment Cryptography uses for encrypted pin block generation.

      • EncryptionKeyCheckValue — (String)

        The key check value (KCV) of the encryption key. The KCV is used to check if all parties holding a given key have the same key or to detect that a key has changed.

        Amazon Web Services Payment Cryptography computes the KCV according to the CMAC specification.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.

waitFor(state, params = {}, callback) ⇒ AWS.Request

Waits for a given PaymentCryptographyData resource. The final callback or 'complete' event will be fired only when the resource is either in its final state or the waiter has timed out and stopped polling for the final state.

Parameters:

  • state (String)

    the resource state to wait for. Available states for this service are listed in "Waiter Resource States" below.

  • params (map) (defaults to: {})

    a list of parameters for the given state. See each waiter resource state for required parameters.

Callback (callback):

  • function(err, data) { ... }

    Callback containing error and data information. See the respective resource state for the expected error or data information.

    If the waiter times out its requests, it will return a ResourceNotReady error.

Returns:

  • (AWS.Request)

    a handle to the operation request for subsequent event callback registration.