The replaceAnsiX9241Key (RDK) operation is used for persistent, secure storage of ANSI X-924.1 keys in SAKA. The web service receives a CCEncryptedAnsiX9241KeyType object (along with other parameters to authenticate and authorize the transaction) that contains all the metadata necessary to store the key. While behaving similarly to the storeAnsiX9241Key web service, this web service additionally marks another—previously stored—ANSI key as “retired,” so the newly stored ANSI key can replace it.
There are two methods for replacing a key on the appliance using the values from the CCEncryptedAnsiX9241KeyType element. The first involves assembling the key from a set of key components that were previously loaded through the loadKeyComponent web service. The second method is to decrypt an encrypted key using a previously stored key as the wrapping key.
The web service will automatically know which method of key replacement you are attempting based on whether the ParentToken value of the CCEncryptedAnsiX9241KeyType object is NULL or not.
The RDK web service operation requires four 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 Administrator privilege and the encryption privilege at minimum to execute this operation. If the ANSI key is a wrapped key, then the decryption privilege is also required to recover the wrapping key. |
|
password |
The password of the username to authenticate the credential of the requester. |
|
encansikey |
The CCEncryptedAnsiX9241KeyType object that contains the key component and metadata. |
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 replaceAnsiX9241Key service by verifying if they are a member of the KMAAuthorized and EncryptionAuthorized groups. 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 parses the CCEncryptedAnsiX9241KeyType object. Depending on what parameters are specified, the code will branch into one of two paths:
-
If a ParentToken is specified, the appliance will make an additional check to verify if the user is a member of the DecryptionAuthorized group. If authorized, the wrapping key will be recovered from secure storage for use in this transaction. The wrapping key is used to decrypt the provided EncryptedKey data.
-
If a ParentToken is not specified, the appliance will search it's internal maps for Key Components associated with the key specified by the KeyName. If the necessary key components are found, the key is assembled from these components (and the components are subsequently erased).
Once the appliance has assembled/decrypted the ANSI key, a KCV is calculated and compared with the provided KCV. If they do not match, the integrity of the key cannot be confirmed and the request will fail. If the integrity of the key is confirmed, the key is ready to be securely stored. Within a single transaction, the to-be-replaced token is marked as “retired.” The replacement key is then encrypted and stored by the appliance. If either action in this two-phase transaction fails, the entire transaction is rolled back.
Once the ANSI key is successfully stored, 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. |
|
Token |
The token reference to this encrypted ANSI key. |
|
KeyName |
The identifier used to reference this key in the request. |