RACF and key rings

A key ring is a collection of certificates that identify a networking trust relationship (also called a trust policy). In a client-server network environment, entities identify themselves using digital certificates. Server applications on z/OS that want to establish network connections to other entities can use RACF® key rings and other related services to determine the trustworthiness of the client or peer entity.

A virtual key ring is the set of all certificates owned by a user ID. This set of certificates is used, like a real key ring, by a user or server application to determine the trustworthiness of a client or peer. Each RACF user ID is associated with a virtual key ring. In contrast to a real key ring, a virtual key ring is not added to RACF.

Each of the following commands list the contents of a virtual key ring:

Examples:

RACDCERT ID(userid) LIST
RACDCERT CERTAUTH LIST
RACDCERT SITE LIST

The most common type is the CERTAUTH virtual key ring, which is used when an application validates the certificates of others but has no need for its own certificate and private key. See Using a virtual key ring for an example.

System SSL and other security middleware use the R_datalib callable service (IRRSDL00 or IRRSDL64) to retrieve certificate information from RACF. In order for an application to retrieve certificates and private keys from RACF, both of the following conditions must be met:

The certificates must be connected to a RACF key ring (a real or virtual key ring) or a z/OS® PKCS #11 token. The key ring or token is the data store that R_datalib opens, reads, and closes as directed by the application.
The application must have appropriate access authority to the key ring or the token. For authorization details, see "Usage Notes®" for R_datalib (IRRSDL00 or IRRSDL64) in z/OS Security Server RACF Callable Services.

Applications can also use R_datalib callable service to manage keys rings (virtual key rings are not included). Authorized applications can create key rings and connect certificates to key rings. See R_datalib (IRRSDL00 or IRRSDL64) callable service for information about controlling applications that use this callable service.

The usage assigned to a certificate when it is connected to a key ring indicates its intended purpose. Personal certificates are to be used by the local server application to identify itself. Certificate-authority certificates are to be used to verify the peer entity's certificate. Peers with certificates issued by certificate authorities connected to the key ring are considered trusted network entities. There might be a few certificate validation applications that treat a certificate that is connected to a key ring with usage site as a valid certificate authority certificate to bypass the normal certificate verification tests; for example, an expired certificate can be considered trusted. The most popular exploiter of R_datalib, System SSL, does not make use of the site certificate.

Restriction: Certificates marked NOTRUST cannot be retrieved using the R_datalib callable service even if they are connected to a key ring. RACF hides them from the calling application and does not indicate that they are connected to the key ring.