RSA Security 5.2.2 manual Using Cryptographic Hardware

Using Cryptographic Hardware

In this example, we passed 0 for sessionHandle and NULL_PTR for cryptokiFunctions. This means we want Crypto-C to load up the library (whose shared library name, p11DLLName, is given in the libraryName field), do the necessary initializations, find the appropriate token (if installed) using the given tokenLabel, then log on using the given passPhrase and create a session. After the call to B_CreateHardwareChooser, if we examined p11Session.sessionHandle, it would have a non-zero number there. Likewise, p11Session.cryptokiFunctions would have an address there. Crypto-C created a session and collected the function list. If you want to examine them now, you can, if not, ignore them.

The token label is defined by the manufacturer, the user, or both. A manufacturer would probably give each token a unique label. Most likely, there will also be tools that accompany the token that allow you to find the label and possibly change it. If you can label your token, the label can be up to 32 characters in length. Use unique names for all your tokens. Incidentally, Cryptoki says a label is 32 characters, no more no less. If the name is not 32 characters, then the rest of the label is blank spaces. NULL-terminating characters (such as 0) are not allowed. If you pass to Crypto-C a label that is not 32 characters or contains zeroes (as in the example above), the Crypto- C code will strip the zeroes and pad with the blank spaces.

Crypto-C will try to find the token with the same label you pass in. If you pass

NULL_PTR for tokenLabel.data, Crypto-C will use the first token it finds. Upon return, the tokenLabel.data field will point to the label of the token Crypto-C found. The len field will be its length. If you have only one token, this could save you a tremendous amount of time normally spent typing the token label.

The function list, by the way, is a way to isolate hardware dependencies. Different operating systems have different ways of accessing functions in a shared library. For instance, with Windows, you must call the routine GetProcAddress to get the address of the routine, then "invoke that address." Every time you want to call a PKCS #11 function then, it would seem, you have to write platform-specific code. This makes porting a little more difficult.

But with PKCS #11, you can make one platform-specific call to get the address of the routine C_GetFunctionList, then use that routine to get the list of function addresses. Now all future PKCS #11 calls are made from this list, so you have no more platform- specific calls to make.

The last field in the data struct is the surrender context. If you want your operations later on to use a surrender context, you must pass it in at this time. PKCS #11 associates a surrender context with a session (Crypto-C alternatively associates a surrender context with an individual function call). So we must register the surrender context right at the beginning. If you do not want the operation later on to use a

1 3 6 R S A B S A F E C r y p t o - C D e v e l o p e r ’s G u i d e