The generateInitialKey (GIK) operation uses a previously loaded BDK and the supplied device serial number (DSN) to generate and return an Initial Key (sometimes called the Initial PIN Encryption Key or IPEK). The manner in which the Initial Key is returned to the calling application is determined by the returntype option.
The GIK web service operation requires seven 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 Key Management Custodian privilege to execute this operation. |
|
password |
The password of the username to authenticate the credential of the requester. |
|
mfr |
The numerical identifier of the manufacturer for which BDK will be used to derive the Initial Key. The BDK must have already been loaded by the loadBDK web service. |
|
DSN |
The DSN to use to generate a derived key. This must be either an 11-byte hex-encode string (43 bits of data) or 15-byte hex-encoded string (59 bits). Using the former, the server will automatically pad the DSN with the hex value “FFFF.” |
|
PublicKeyToken |
The token which identifies the public key that will be encrypting the Initial Key. Can be null when returntype equals KeyComponents. |
|
ReturnType |
The method in which to return the Initial Key. Currently the only accepted value is KeyComponents. |
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 generateInitialKey service by verifying if they are a member of the KMCAuthorized group. 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 the SAKA, this group is created automatically.
If the requester is authorized, SAKA proceeds to recover the BDK for this operation based on the Manufacturer ID. Using the BDK and portions of the provided DSN, an initial key is derived. This key is broken up into three key components. These key components are packaged in CCKeyComponentType objects along with their KCV and other metadata. A fourth CCKeyComponentType object is created that does not contain a key component but contains the KCV of the Initial Key.
Once the CCKeyComponentType objects are created—using SOAP—an array of these objects will be returned. Using REST, a JSON representation of the array is returned:
|
CCKeyComponentTypeArray[0] |
Contains the first key component with KCV and metadata. |
|
CCKeyComponentTypeArray[1] |
Contains the second key component with KCV and metadata. |
|
CCKeyComponentTypeArray[2] |
Contains the third key component with KCV and metadata. |
|
CCKeyComponentTypeArray[3] |
Contains only the KCV of the assembled BDK (does not include the assembled BDK itself). |
An example JSON array response for KMS Module's generateInitialKey service:
[{
"KeyName": "0",
"KeyComponent": "F540DF52C1E3957D0B69BE23E443C003",
"KeyCheckValue": "D35DF4",
"KeyAlgorithm": "AES",
"KeySize": "128",
"K": 1,
"N": 3
}, {
"KeyName": "0",
"KeyComponent": "EA60664815BF97F1692315842D331437",
"KeyCheckValue": "6A3D7F",
"KeyAlgorithm": "AES",
"KeySize": "128",
"K": 2,
"N": 3
}, {
"KeyName": "0",
"KeyComponent": "554548549AFB786036FFF422D9DEBC54",
"KeyCheckValue": "FB1843",
"KeyAlgorithm": "AES",
"KeySize": "128",
"K": 3,
"N": 3
}, {
"KeyCheckValue": "4B0333"
}]