Using Cryptographic Hardware
136 RSA BSAFE Crypto-C Developer’s Guide
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.cryptoki
Functions 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
