Product Documentation

    The DukptDecrypt (DDEC) operation decrypts a hex-encoded ciphertext string using a key derived from the BDK and KSN. The algorithm and type of derived key are specified as parameters to determine the type of decryption to be performed. The web service operation requires eight (of a total of nine) parameters:

    DID

    The unique encryption domain identifier.

    username

    The username (service credential) within the encryption domain with the authorization to call this web service. The user requires the Decryption privilege to execute this operation.

    password

    The password of the username to authenticate the credential of the requester.

    bdktoken

    The token that references the BDK within the SAKA encryption domain. If this parameter is specified, the mfr parameter must be null.

    mfr

    The numerical identifier of the manufacturer for which this BDK is assigned. If this parameter is specified, the bdktoken parameter must be null.

    ksn

    The KSN to use to generate the derived key. This must be exactly 10 bytes sent to the web service, formatted as a hex-encoded string.

    ciphertext

    The ciphertext to be decrypted. The ciphertext must be sent to the web service as a hex-encoded string.

    algorithm

    The algorithm to use for this decryption. Valid choices are “TDES” and “AES.” Alternatively, a full transform can be specified in the form of “AES/CBC/ZeroBytePadding” if the default mode and padding of each derived key type needs to be overwritten. Continue reading the description of the web service mechanics for more details.

    derivedkeytype

    The type of key to be derived by the DUKPT process. Valid choices are:

    • “DEK” (Data Encryption Key, request or both ways)

    • “DEK_RESPONSE” (Data Encryption Key, response)

    • “PIN” (PIN Encryption Key)

    • “MAC” (Message Authentication Key, request or both ways)

    • “MAC_RESPONSE” (Message Authentication Key, response)

    When SAKA receives the request, it verifies the credentials presented against its internal database—or an optional LDAP directory server—and determines their authorization to request the DukptDecrypt service by verifying if they are a member of the DecryptionAuthorized group. If using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the installation process for SAKA; when using the internal database on SAKA, this group is created automatically.

    If the requester is authorized, SAKA proceeds to recover the BDK for this operation. If the manufacturer ID is provided in the web service call, the BDK associated with the manufacturer is recovered. If a BDK Token is provided, the BDK is recovered based on that token.

    Using the BDK and portions of the provided KSN, an IPEK is derived. Using the IPEK, the derived key (of the type requested for this transaction) is generated based on other portions of the KSN. Each type of derived key has a default encryption mode and padding associated with it.

    Those defaults are listed in the following table:

    Derived Key Type

    Encryption Mode

    Padding

    DEK

    CBC

    ZeroBytePadding

    DEK_RESPONSE

    CBC

    ZeroBytePadding

    PIN

    ECB

    NoPadding

    MAC

    ECB

    NoPadding

    MAC_RESPONSE

    ECB

    NoPadding

    If the default decryption mode and padding for your chosen type of derived key are correct, you will just need to select either “AES” or “TDES” as the algorithm in the web service request. You can override the default values, or explicitly state your preferred decryption mode and padding, by supplying the full cryptographic transform as the algorithm parameter in the web service. For instance, a TDES PIN key can be derived and decrypted in CBC mode with ZeroBytePadding if the algorithm web service parameter I s specified as “DESede/CBC/ZeroBytePadding.” Take notice that in this case, we specify Triple DES algorithm using Java's official name for the algorithm “DESede.”

    https://demo4.strongkey.com/getstarted/assets/documents/HTML/images/key_strong_cyan.pngNOTE: StrongKey has currently tested only the Electronic Code Book (ECB) and Cipher Block Chain (CBC) modes of encryption and, for the ANSI DUKPT processing module, only ZeroBytePadding and NoPadding mode of padding. Additionally, when using the CBC mode of encryption, the only currently supported Initialization Vector (IV) is an all-zero block. If other encryption modes, padding types, or IVs are desired, please contact support@strongkey.com.

    To learn more about Java cryptographic algorithms, modes of encryption and padding, please refer to the Java Cryptography Architecture (JCA) Reference Guide.

    Once the plaintext is encrypted, the result is hex-encoded and the following values will be returned, either as a JSON or XML string; in the case of SOAP, the JSON or XML string is embedded in the objectContent attribute of the CCReturnObject object.

    DID

    The unique encryption domain identifier for the domain that serviced this request.

    SRID

    A unique request identifier for this transaction.

    BDKToken

    The BDKToken used to service this request (or null if the BDK token was not specified as a web service parameter).

    MFR

    The manufacture ID used to service this request (or null if the manufacturer ID was not specified as a web service parameter).

    KSN

    The KSN used to service this request.

    Plaintext

    The plaintext generated from this request, formatted as a hex-encoded string. Be sure to hex decode the value to recover your desired plaintext value.