The DukptMac (DMAC) operation generates a message authentication code (MAC) for some hex-encoded plaintext bytes using a key derived from the BDK and KSN following the ANSI-defined MACing scheme. The type of derived key is specified as parameters.
The web service operation requires seven (of a total of eight) 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 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, and must be formatted as a hex-encoded string. |
|
plaintext |
The ciphertext to be decrypted. The ciphertext must be sent to the web service as a hex-encoded string. |
|
requesttype |
The type of MAC operation that must be performed by the DUKPT process. Valid choices are:
|
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 DukptMac 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 SAKA installation process; 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. In this case, the user must also be a member of the DecryptionAuthorized group.
Using the BDK and portions of the provided KSN, an IPEK is derived. Using the IPEK, the derived MAC key (of the type requested for this transaction) is generated based on other portions of the KSN. The derived MAC key is then used to generate a MAC for the decoded plaintext input using the ANSI-defined algorithm for generating message authentication codes.
This web service operation does two kinds of operations based on the value of the requesttype parameter. When a customer's application sends a DUKPT-encrypted message to SAKA for decryption, the ATM may have included a MAC with the DUKPT message. The customer's application may extract the MAC from the message sent by the ATM, use the DukptMac web service operation to regenerate a MAC for the specified plaintext. The application may then compare the regenerated MAC with the one sent by the ATM to determine if they are identical: if they are, it indicates that the message was decrypted correctly.
In the second operation, the customer's application may need to send a response to the ATM on a business transaction. In this case, the application may want to send a MAC of the plaintext message-response so the ATM may determine if the integrity of the message-response is intact. In such a situation, the application will call the DukptMac operation and specify MAC_RESPONSE in the requesttype parameter. This tells SAKA, how it should cryptographically process the input parameters to generate the right MAC response.
Once the MAC has been generated, 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. |
|
MAC |
The MAC generated from this request, formatted as a hex-encoded string. |