Important notes

Memory management

The memory management of all output parameters must be performed by the calling function.

Using a 64-bit platform

To compile an application with Authentication Suite Server SDK on a 64-bit platform, use the _64BIT pre-processor definition.

Null-termination of aat_ascii string buffers

To be handled correctly, all the aat_ascii string buffers passed in the parameters of a function must be null-terminated. This null character \0 allows Authentication Suite Server SDK to determine the aat_ascii string length.

aat_ascii string buffers which are not null-terminated may cause your system to crash.

In addition, all the aat_ascii string buffers a function fills and returns will be null-terminated. aat_byte buffers passed in the parameters of a function must not be null-terminated.

The null-termination rules outlined in this section apply to the C/C++ library only.

Cmd and InReply buffers allocation

Authentication Suite Server SDKhandles the host-side generation and processing of the messages sent to and from the HSM.

For each Authentication Suite Server SDK function performed on the HSM, Authentication Suite Server SDK on the host-side allows the following:

• Using AAL2GenxxxxCmd functions to generate an HSMcommand message to send from the host to the HSM. The minimum cmd buffer size to allocate for the command message varies for each function.

The recommended size for the cmd buffers is 8192 bytes.

• Using AAL2ProcxxxxRpl functions to process the HSM reply message returned by the HSM. The minimum InReply buffer size to allocate for the reply message varies for each function.

The recommended size for the InReply buffers is 8192 bytes.

PKCS#11-specific errors (Authentication Suite Server SDK for Thales ProtectServer HSM only)

With the Authentication Suite Server SDK for Thales ProtectServerHSM, the Authentication Suite Server SDK FM module (functionality module) performs internally some calls to the Thales ProtectServer/ProtectServer2 PKCS#11 APIs. As the HSM may return errors on the PKCS#11 internal function calls to the Authentication Suite Server SDK FM module, the Authentication Suite Server SDK for Thales ProtectServerHSM may have to return information regarding an unexpected PKCS#11 error. To distinguish PKCS#11 errors from Authentication Suite Server SDK ones, an offset is applied on each error code returned by PKCS#11 functions. This offset depends on the type of PKCS#11 error, Standard PKCS#11 error or vendor-defined PKCS#11 error:

• For vendor-defined PKCS#11 errors (above 0x80000000), an offset of 20000 is added on the PKCS#11 error (without the vendor-defined mask 0x80000000) for the resulting Authentication Suite Server SDK error.

PKCS#11 vendor-defined errors greater than 9999 in decimal (without the vendor-defined mask 0x80000000) are all returned as 20000 for the resulting Authentication Suite Server SDK error.

• For Standard PKCS#11 errors, an offset of 30000 is added on the PKCS#11 error for the resulting Authentication Suite Server SDK error.

PKCS#11 Standard errors greater than 1999 in decimal are all returned as 30000 for the resulting Authentication Suite Server SDK error.

Consequently, PKCS#11 errors are returned in these two ranges:

• From 20000 to 29999 for PKCS#11 vendor-defined errors,
• From 30000 to 31999 for PKCS#11 Standard errors.

Examples of Authentication Suite Server SDK return codes in case of a PKCS#11 internal error: