Product Documentation

    The DukptEncrypt (DENC) operation encrypts a hex-encoded plaintext using a key derived from the BDK and Key Serial Number (KSN). The cryptographic algorithm and type of cryptographic key to be derived from the BDK+KSN combination are specified as parameters to determine the type of encryption 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 credential requires the Encryption privilege at a minimum, but may also require Decryption privileges if the BDK is recovered through a token parameter in the web service.

    password

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

    bdktoken

    The token that references the escrowed BDK. If this parameter is specified, the mfr parameter must be null. Also, by specifying this parameter, the user making the web service must also have Decryption privilege.

    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 key serial number (KSN) to use to generate a derived key. This must be exactly 10 bytes and must be formatted as a hex-encoded string.

    plaintext

    The plaintext to be encrypted. The plaintext must be sent to the web service as a hex-encoded string. Even if the plaintext is only alphanumeric characters, it is expected that the plaintext value is hex-encoded for transport to the web service.

    algorithm

    The algorithm to use for this encryption. Valid choices are TDES and AES. Alternately, a full transform can be specified in format, “AES/CBC/ZeroBytePadding” if the default mode and padding of each derivedkeytype 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 DukptEncrypt service by verifying if they are a member of the EncryptionAuthorized group. Note that if using LDAP, this group and its members must be created in the LDAP directory as a distinct task of the installation process of SAKA; when using the SAKA internal database, 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. In this case, the user must also be a member of the DecryptionAuthorized group.

    Using the BDK and portions of the provided KSN, an initial key (sometimes called the Initial PIN Encryption Key or 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:

    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 encryption mode and padding for your chosen type of derived key is correct, then you will just need to select either “AES” or “TDES” as the algorithm in the web service request. You can overwrite the default or explicitly state your preferred encryption 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 encrypted in CBC mode with ZeroBytePadding if the algorithm web service parameter is 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 This email address is being protected from spambots. You need JavaScript enabled to view it..

    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 manufacturer 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.

    Ciphertext

    The ciphertext generated from this request, formatted as a hex-encoded string.