Home >

SDK Reference Guide > Extensions to PKCS#11 > High Availability Indirect Login Functions

High Availability Indirect Login Functions

Note:  In order to implement High Availability Recovery, the primary and secondary tokens must exist on separate systems.

The following enhancements securely extend the indirect login capability to SafeNet CA3 tokens. SafeNet CA3 tokens to store sensitive information (encrypted) in flash memory, and must therefore be protected against attack by a man-in-the-middle who physically attacks the target token to expose the contents of flash memory, and employs that information against intercepted (or spuriously-generated) message traffic.

The SafeNet CA3 to SafeNet CA3 indirect login protocol also supports old-style MofN authentication between tokens that share an MofN secret.

Initialization functions

Initialization of tokens in a high-availability environment involves three steps:

1.The generation of an RSA login key pair (the public key of the pair may be discarded),

2.Cloning of the private key member to the User (and optionally to the SO) spaces of all tokens within that environment and,

3.Calling the CA_HAInit function on all tokens within that environment, in the context of the session owned by the User or SO.  

The first two steps are performed using ordinary key generate and cloning Cryptoki function calls. The CA_HAInit function is implemented as follows:

CA_HAInit()

CK_RV CK_ENTRY CA_HAInit(
CK_SESSION_HANDLE hSession, // Logged-in session of user
// who owns the Login key pair
CK_OBJECT_HANDLE hLoginPrivateKey // Handle to Login private key
);

Recovery Functions

The HA recovery mechanism requires the following commands and interface functions:

CA_HAGetMasterPublic()

Called on the primary token, CA_HAGetMasterPublic() retrieves the primary token's TWC (Token Wrapping Certificate) and returns it as a blob (octet string and length).  The format of this function is as follows:

CK_RV CK_ENTRY CA_HAGetMasterPublic(
CK_SLOT_ID slotId, // Slot number of the primary
// token
CK_BYTE_PTR pCertificate, // pointer to buffer to hold
//TWC certificate
CK_ULONG_PTR pulCertificateLen // pointer to value to hold
//TWC certificate length
);

CA_HAGetLoginChallenge()

Called on the secondary token, CA_HAGetLoginChallenge() accepts the TWC blob and returns the secondary token's login challenge blob.  The format of this command is as follows:

CK_RV CK_ENTRY CA_HAGetLoginChallenge(
CK_SESSION_HANDLE hSession, // Public session
CK_USER_TYPE userType, // User type - SO or USER
CK_BYTE_PTR pCertificate, // TWC certificate retrieved
// from primary
CK_ULONG ulCertificateLen, // TWC certificate length
CK_BYTE_PTR pChallengeBlob, // pointer to buffer to hold
// challenge blob
CK_ULONG_PTR pulChallengeBlobLen // pointer to value to hold
// challenge blob length
);

CA_HAAnswerLoginChallenge()

Called on the primary token, CA_HAAnswerLoginChallenge() accepts the login challenge blob and returns the encrypted SO or User PIN, as appropriate.

CK_RV CK_ENTRY CA_HAAnswerLoginChallenge(
CK_SESSION_HANDLE hSession, // Session of the Login Private
// key owner
CK_OBJECT_HANDLE hLoginPrivateKey, // object handle to login key
CK_BYTE_PTR pChallengeBlob, // pointer to buffer containing
// challenge blob
CK_ULONG ulChallengeBlobLen, // length of challenge blob
CK_BYTE_PTR pEncryptedPin, // pointer to buffer holding
// encrypted PIN
CK_ULONG_PTR pulEncryptedPinLen // pointer to value holding
// encrypted PIN length
);

CA_HALogin()

Called on the secondary token, CA_HALogin() accepts the encrypted PIN and logs the secondary token in. If the second-ary token requires MofN authentication, an MofN challenge blob is returned.  If no MofN authentication is required, a zero-length blob is returned. The format of this function is as follows:

CK_RV CK_ENTRY CA_HALogin(
CK_SESSION_HANDLE hSession, // Same public session opened
// in CA_HAGetLoginChallenge, 
//above
CK_BYTE_PTR pEncryptedPin, // pointer to buffer holding
// encrypted PIN
CK_ULONG ulEncryptedPinLen,  //  length of encrypted PIN
CK_BYTE_PTR pMofNBlob, // pointer to buffer to hold
// MofN blob
CK_ULONG_PTR pulMofNBlobLen // pointer to value to hold the
// length of MofN blob
);
 

If the call is successful, then the session now becomes a pri-vate session owned by the User or SO (as appropriate).

CA_HAAnswerMofNChallenge()

Called on the primary token, CA_AnswerMofNChallenge() accepts the MofN challenge blob and returns the primary token's masked MofN secret.  The format of this function is as follows:

CK_RV CK_ENTRY CA_HAAnswerMofNChallenge(
CK_SESSION_HANDLE hSession, // Private session
CK_BYTE_PTR pMofNBlob, // passed in MofN blob
CK_ULONG ulMofNBlobLen, // length of MofN blob
CK_BYTE_PTR pMofNSecretBlob, // pointer to buffer to hold
// MofN secret blob
CK_ULONG_PTR pulMofNSecretBlobLen//pointer to value that holds
// the MofN secret blob len
);

CA_HAActivateMofN()

Called on the secondary token, CA_HAActivateMofN() accepts the masked MofN secret and performs MofN authentication.  The resulting MofN secret is checked against the CRC stored in the MofN PARAM structure.

CK_RV CK_ENTRY CA_HAActivateMofN(
CK_SESSION_HANDLE hSession, // The now-private session from
// successful CA_HALogin call
CK_BYTE_PTR pMofNSecretBlob, // pointer to MofN secret 
// blob that is passed in
CK_ULONG ulMofNSecretBlobLen // length of MofN secret blob
);
 

It is expected that the recovery functions will be executed in the proper sequence and as part of an atomic operation.  Nonetheless, the recovery operation may be restarted at any time due to an error.  Restarting the recovery operation resets the state condition of the secondary token, and any data that has been stored or generated on the token is discarded.

Login Key Attributes

The login keys must possess the following attributes to function properly in a HA recovery scenario:

// Object
CKA_CLASS = CKO_PRIVATE_KEY,
// StorageClass
CKA_TOKEN = True,
CKA_PRIVATE = True,
CKA_MODIFIABLE = False,
// Key
CKA_KEY_TYPE = CKK_RSA,
CKA_DERIVE = False,
CKA_LOCAL = True,
// Private
CKA_SENSITIVE = True,
CKA_DECRYPT = False,
CKA_SIGN = False,
CKA_SIGN_RECOVER = False,
CKA_UNWRAP = False,
CKA_EXTRACTABLE = False

Control of HA Functionality

Refer to for the mechanisms by which the SO can control availability of the HA functionality.