II_KEY_RCV
PHW DSHP D
PSO/PSG D
SHP Toolkit MK2 D
Card Issuance (SHP Toolkit EMV) D
Request Content Length Attribute Description
EE0403 3 h Function Code FM 1 h Function Modifier = x0 KIR-Spec Var K-Spec Key specifier for KIR
(Formats: 0 - 3, 10, 11, 13, 15) Key Flags 2 h Key Type indicator / Encryption
mode
1eKIRnvx(KS) Var h Encrypted Session Key Response Content Length Attribute Description
EE0403 3 h Function Code Rc 1 h Return Code
N 1 h Number of following key sets.
Mark II Programmers Guide Chapter 10 Interchange Functions
The key-types 10, 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See, section Function Modifier Values.
This function re-encrypts a received set of encrypted DES or 3DES keys for host storage. The key set may include any of the session keys, PPK, MPK and DPK, and may also include a new key-encrypting key, KIR.
As received from the sending interchange institution, the keys are encrypted under the
appropriate variant of the Interchange Receive Key (KIR) indicated by the 'KIR-Spec' field in the function request. Exceptionally, if a new KIR is included in the set, any session keys that are also included must be encrypted by that new KIR. For double-length keys, either ECB or CBC
encryption modes are supported.
The received keys are returned encrypted under the appropriate *KM variant for storage within the host. The function also returns the KVCs of the received keys.
The function request and response will contain one or more sets of encrypted key fields as shown:
one set for each appropriate bit set in the 'Key Flags' field. That field also indicates the encryption mode for any double-length keys that are received.
FM = x0
The Host Key Protection using Function Modifier can be in the range of x0, where x= 0, 1, or 2.
KIR-Spec A key specifier for an HSM-stored or host-stored, single-length or double-length KIR. Accepts key spec formats 0 - 3, 10, 11, 13 and 15.
Key Flags Indicates the received encrypted keys and the encryption mode. The bit positions are allocated as follows:
Bit: Indicates:
0 Single-length Data Key (DPK).
1 Single-length PIN encrypting key (PPK).
2 Single-length MAC key (MPK).
3 Single-length key-encrypting key (KIS).
8 Double-length Data Key (DPK).
9 Double-length PIN encrypting key (PPK).
10 Double-length MAC key (MPK).
11 Double-length key encrypting key (KIS).
12 Encryption mode for decipher of the inbound eKIRnvx(KS):
0 = ECB; 1 = CBC.
13-15 Reserved. Must be zero.
Bit 0 is the least significant (right most) bit.
eKIRvx(KS) Key encrypted by a variant of the Interchange Receive Key.
KS-Spec Key Specifier incorporating an encrypted key.
KVC Key Verification Code for the key
Example values of 'Key Flags' field
Value of 'Key Encryption Keys to be generated Flags' field mode
X’0004’ ECB Single-length MPK
X’0402’ ECB Single-length PPK; double-length MPK X'1600' CBC Double-length PPK; double-length MPK
Mark II Programmers Guide Chapter 10 Interchange Functions
X'1A00' CBC Double-length KIS; double-length PPK Details and Restrictions
1. The formats of the key specifiers in the response are dependent on the key type, and on the format of the KIR-Spec in the request.
2. If an HSM-stored KIR is provided in the request, its associated variant scheme will be used when decrypting an encrypted key using that KIR.
3. If a host stored KIR is provided in the request in a format 10, 11 or 13 key specifier, the default KIR variants used to decrypt the incoming session keys will be SafeNet variants. No variants will be used when the Use 'No Variants' with host stored KIS/KIR flag is set. Please refer to the section Configuration Control in Chapter 5 of the Mark II Console User Guide for further information on setting or clearing this flag.
4. When the AS2805 variant scheme is used (HSM-stored KIR or host-stored KIR in a Format 15 key specifier), a double-length session key encrypted under KIR is decrypted using CBC.
The encryption mode flag bit is ignored; i.e. a value of 0 (ECB) will not cause an error.
5. When the Key Flags indicate that a new KIR is included in the set:
• If the KIR keys are HSM stored (KIR-Spec formats 0 - 3), the key referenced must be set to
"no variants"
• If the KIR keys are host stored (KIR-Spec formats 10, 11 and 13) the keys are assumed to have no variants. This will only affect the incoming eKIRvx(KIR) field.
• If the KIR-Spec is a Format 15, then only when the attributes are set to "no variant scheme" will this key spec be accepted.
Failure caused due to any of the previous 3 occurrences will result in error 0x0C (Inconsistent request fields) being returning as the return code.
6. When the Key Flags specify that a new KIR is included in the set this new KIR is encrypted with the old KIR (KIR-Spec). The encryption mode depends upon the Key Flags mode bit.
Error conditions
The following settings for the 'Key Flags' field will result in a Return Code of 0C.
1. A request for a double-length key to be re-encrypted, though the KIR indicated in the request is a single-length key
2. A request to re-encrypt a DPK, though this is disabled for the (HSM-stored) KIR.
3. A request to re-encrypt a single- and double-length key of same type.
4. A reserved bit not set to zero.
NOTES
• The encryption mode for eKIRnvx(KS) and KS-Spec is ECB unless otherwise specified.
• This function will check the length of KIRn and use the appropriate encryption method.
• When there is no variant scheme chosen for the KIR, this function will automatically disable the ability to generate a DPK. This part of the function can be manually enabled from the console by selecting “Enable function for receiving of data keys” under the KIR Options dialog.
Mark II Programmers Guide Chapter 10 Interchange Functions
SHP Toolkit MK2
int EFT_EE0403_ReceiveInitialSessionKey (
IN UCHAR FM,
IN KEYSPEC *KIR,
IN UCHAR KeyFlags[2],
IN EFTBUFFER *eKIR_KS1,
_IN EFTBUFFER *eKIR_KS2, _IN EFTBUFFER *eKIR_KS3, _IN EFTBUFFER *eKIR_KS4,
OUT UCHAR *numKeys,
OUT KEYSPEC *KS1,
OUT UCHAR KVC1[3],
_OUT KEYSPEC *KS2,
_OUT UCHAR KVC2[3],
_OUT KEYSPEC *KS3,
_OUT UCHAR KVC3[3],
_OUT KEYSPEC *KS4,
_OUT UCHAR KVC4[3]);
Mark II Programmers Guide Chapter 10 Interchange Functions
Rollover Session Key Generation
NI-KEY-GEN
PHW DSHP D
PSO/PSG D
SHP Toolkit MK2 D
Card Issuance (SHP Toolkit EMV) D
Length Description
Request Content Attribute
EE0404 3 h Function Code FM 1 h Function Modifier = x0
Key Flags 2 h Key Type indicator / Encryption mode
1KSn Spec Var K-Spec Key Specifier for Session Key (Formats: 10, 11, 13)
Length Description
Response Content Attribute
EE0404 3 h Function Code
rc 1 h Return Code
n 1 h Number of following key sets
1eKSn(KSn+1) Var h Encrypted Session Key
1KSn+1 Spec Var K-Spec Key Specifier for Session Key (Formats: 10, 11, 13)
1KVC 3 h Key Verification Code
1This set of fields will occur ‘n’ times.
Notes:
The key-types 10, 11 under the Response Content, are generated when using the Legacy option.
The key-types 10, 11, 13 under the Response Content, are generated based on the chosen operation on console and FM. See, section Function Modifier Values.
This function generates a set of new random DES or 3DES Session Keys (KSn+1-Spec) for an Interchange. For transmitting to the receiving node, the generated keys are returned encrypted under the supplied previous Session Key (KSn). For double-length keys, either ECB or CBC encryption modes may be selected.
The generated keys are also returned encrypted under the appropriate variant of the Domain Master Key (*KM), for storage within the host system. This function also returns the KVCs of the session keys.
The function response will contain one or more sets of encrypted key fields as shown: one set for each appropriate bit set in the 'Key Flags' field. That field also indicates the encryption mode for
Mark II Programmers Guide Chapter 10 Interchange Functions
FM = x0
The Host Key Protection using Function Modifier can be in the range of x0, where x= 0, 1, or 2.
Key Flags Indicates the keys to generate and the encryption mode. The bit positions are allocated as follows:
Bit: Indicates:
0 Single-length Data Key (DPK).
1 Single-length PIN encrypting key (PPK).
2 Single-length MAC key (MPK).
3 Reserved. Must be zero.
8 Double-length Data Key (DPK).
9 Double-length PIN encrypting key (PPK).
10 Double-length MAC key (MPK).
11 Reserved. Must be zero.
12 Encryption mode for the response encipher:
0 = ECB; 1 = CBC.
13-15 Reserved. Must be zero.
Bit 0 is the least significant (right most) bit.
KSn-Spec A key specifier incorporating a session key encrypted by a variant of the Domain master key
EKSn(KSn+1) The new session key encrypted by the supplied session key KSn+1-Spec A key specifier to the new session key
KVC Key Verification Code for the new session key
Note
• This function returns error code 03 when a = 00 of 01 is utilized.
• The encryption mode for eKSn(KSn+1) and KSn spec is ECB unless otherwise specified.
• This function supercedes functions 57, 58, 59.
• Bit 3, Bit 7, Bit 11 and Bits 13-15 of the key flags are reserved.
Mark II Programmers Guide Chapter 10 Interchange Functions