ePass1000 C/C++ API Reference Manual Version 2.0

epas_ChangeCode

The epas_ChangeCode function change current PIN value of the device to the given PIN. It can also be used to unlock the User PIN retry counter.

EPAS_STATUS EPAS_API
epas_ChangeCode(
    EPAS_HANDLE    hContextHandle,      // [in]
    unsigned long  ulFlags,           // [in]
    unsigned char* pucOldCode,       // [in]
    unsigned long  ulOldCodeLen,      // [in]
    unsigned char* pucNewCode,       // [in]
    unsigned long  ulNewCodeLen       // [in]
);

Requirement

epas_CreateContext, epas_OpenDevice

Parameters

hContextHandle
[in] Handle to device context.
ulFlags
[in] This parameter defines the PIN change to perform:
Flag Meaning
EPAS_CHANGE_USER_PIN Change the USER PIN. The pucOldCode is the current USER PIN. The pucNewCode is the new USER PIN to assign. Upon success, the current Security State will be switch to User State.
EPAS_UNBLOCK_UNSER_PIN Modify the USER PIN when token entered SO state. The pucOldCode parameter is the SO PIN of the device. The pucNewCode Parameter is the new USER PIN to be assigned. Upon success, the current security state will be switch to Security Officer State.
EPAS_CHANGE_SO_PIN Change the SO PIN. The pucOldCode is the current SO PIN of the device. The pucNewCode is the new SO PIN. Upon success, the current Security State will be switched to Security Officer State.
EPAS_CHANGE_NO_HASH Disables MD5 hashing of the SO PIN before sent it to the device. This flag can be combined with EPAS_CHANGE_SO_PIN and EPAS_UNBLOCK_USER_PIN.
EPAS_CHANGE_HASH_UPIN If this flag is set, User PIN is hashed before been sent to the device. This flag can be combined with EPAS_CHANGE_USER_PIN and EPAS_UNBLOCK_USER_PIN.
pucOldCode
[in] Points to the buffer containing the old PIN as follows:
Flag Meaning
EPAS_CHANGE_USER_PIN Points a buffer contains four bytes USER PIN.
EPAS_CHANGE_SO_PIN Points to a buffer contains the current SO PIN. If EPAS_CHANGE_NO_HASH is set, then the pucOldCode is a pointer to a buffer of 8 bytes long integer. Else the buffer can be any length.
EPAS_UNBLOCK_USER_PIN Points a buffer contains the current SO PIN. If EPAS_CHANGE_NO_HASH is set, then the pucOldCode is a pointer to a buffer of 8 bytes long integer. Else the buffer can be any length.
ulOldCodeLen
[in] Specifies the length of the pucOldCode buffer.
pucNewCode
[in] Points to the buffer containing the new PIN as follows:
Flag Meaning
EPAS_CHANGE_USER_PIN Points a buffer contains four bytes new USER PIN to assign.
EPAS_CHANGE_SO_PIN Points to a buffer contains the new SO PIN to assign. If EPAS_CHANGE_NO_HASH is set, then the pucNewCode is a pointer to a buffer of 8 bytes long integer. Else the buffer can be any length.
EPAS_UNBLOCK_USER_PIN Points a buffer contains four bytes new USER PIN to assign.
ulNewCodeLen
[in] Specifies the length of the pucNewCode buffer.

Remarks

To reset the security state, use epas_ResetSecurityState.

On an EPAS_CHANGE_USER_PIN, if the old USER PIN is invalid, the USER PIN retry counter is decremented.

Return Values

If the function succeeds, FT_SUCCESS returned.

If a invalid PIN is specified, FT_ACCESS_DENIED returned.

When no more USER PIN retries are allowed, FT_PIN_EXPIRED returned.

For a list of all return codes, see Status Return Values.

See Also

epas_Verify, epas_ResetSecurityState