Tokens

On most single-user systems, a token is a smart card or other plug-installed cryptographic device, accessed through a card reader or slot. The PKCS #11 specification assigns numbers to slots, known as slot IDs. An application identifies the token that it wants to access by specifying the appropriate slot ID. On systems that have multiple slots, it is the application's responsibility to determine which slot to access.

z/OS® must support multiple users, each potentially needing a unique key store. In this multiuser environment, the system does not give users direct access to the cryptographic cards installed as if they were personal smart cards. Instead, z/OS PKCS #11 tokens are virtual, conceptually similar to RACF® (SAF) key rings. An application can have one or more z/OS PKCS #11 tokens, depending on its needs.

Typically, PKCS #11 tokens are created in a factory and initialized either before they are installed or upon their first use. In contrast, z/OS PKCS #11 tokens can be created using system software such as RACF, the gskkyman utility, or by applications using the C API. Each token has a unique token name, or label, that is specified by the end user or application at the time that the token is created.

Rules: A token name must follow these rules:

Up to 32 characters in length
Permitted characters are:
- Alphanumeric
- National: @ (X'5B'), # (X'7B'), or $ (X'7C')
- Period: . (X'4B')
The first character must be alphabetic or national
Lowercase letters can be used, but are folded to uppercase
The IBM1047 code page is assumed

In addition to any tokens your installation may create, ICSF will also create a token that will be available to all applications. This "omnipresent" token is created by ICSF in order to enable PKCS #11 services when no other token has been created. This token supports session objects only. Session objects are objects that do not persist beyond the life of a PKCS #11 session. The omnipresent token is always mapped to slot ID #0, and its token label is SYSTOK-SESSION-ONLY.

Tip: To reference the omnipresent token by label, use the constant SESS_ONLY_TOK, which is defined in csnpdefs.h.

Because PKCS #11 tokens are typically physical hardware devices, the PKCS #11 specification provides no mechanism to delete tokens. However, because z/OS PKCS #11 tokens are virtual, z/OS must provide a way to delete them. For information on how to delete tokens using the C API, see Deleting z/OS PKCS #11 tokens.