gsk_open_keyring()

Opens a SAF digital certificate key ring or z/OS® PKCS #11 token.

Format

#include <gskcms.h>

gsk_status gsk_open_keyring (
                             const char *          ring_name,
                             gsk_handle *          db_handle,
                             int *                 num_records)

Parameters

ring_name: Specifies the SAF key ring or z/OS PKCS #11 token name in the local code page. When using a key ring owned by the current user, specify the ring name as "name". When using a key ring owned by another user, specify the ring name as "userid/name". The maximum user ID length is 8 and the maximum name length is 237. The z/OS PKCS #11 token name is specified as *TOKEN*/token-name. *TOKEN* indicates that the specified key ring is actually a token name.
db_handle: Returns the database handle. The application should call the gsk_close_database() routine when it no longer needs access to the key ring.
num_records: Returns the number of records in the key ring or token.

Results

The function return value will be 0 if no error is detected. Otherwise, it will be one of the return codes listed in the gskcms.h include file. These are some possible errors:

[CMSERR_ACCESS_DENIED]: The access permissions do not allow access.
[CMSERR_BAD_FILENAME]: The key ring or token name is not valid.
[CMSERR_BAD_RNG_OUTPUT]: In FIPS mode, random bytes generation produced duplicate output.
[CMSERR_FILE_NOT_FOUND]: The key ring or token does not exist
[CMSERR_ICSF_FIPS_DISABLED]: ICSF PKCS #11 services are disabled.
[CMSERR_IO_ERROR]: An error occurred while listing the key ring or token.
[CMSERR_NO_MEMORY]: Insufficient storage is available.

Usage

The gsk_open_keyring() routine will open a key ring maintained by the System Authorization Facility (SAF) and construct a read-only key database. Only trusted certificates connected to the specified key ring are included in the key database. The GSKDB_RECFLAG_DEFAULT flag will be set if the certificate is the default certificate for the key ring or token.

The user must have READ access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class when using a SAF key ring owned by the user. The user must have UPDATE access to the IRR.DIGTCERT.LISTRING resource in the FACILITY class when using a SAF key ring owned by another user.

Note:

Certificate private keys are not available when using a SAF key ring owned by another user, except for SITE certificates where CONTROL authority is given to IRR.DIGTCERT.GENCERT in the FACILITY class or for user certificates where READ or UPDATE authority is given to ringOwner.ringName.LST resource in the RDATALIB class.

The application user ID must have READ access to resource USER.tokenname in the CRYPTOZ class in order for the certificates and their private keys, if present, to be read from a z/OS PKCS #11 token.