https://github.com/zowe/keyring-utilities
Various key ring utilities that interact with z/OS RACF key rings using R_datalib API
https://github.com/zowe/keyring-utilities
Last synced: 11 months ago
JSON representation
Various key ring utilities that interact with z/OS RACF key rings using R_datalib API
- Host: GitHub
- URL: https://github.com/zowe/keyring-utilities
- Owner: zowe
- License: epl-2.0
- Created: 2020-04-22T15:02:57.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2025-06-17T15:57:49.000Z (about 1 year ago)
- Last Synced: 2025-07-21T09:59:54.543Z (12 months ago)
- Language: C
- Homepage:
- Size: 102 KB
- Stars: 2
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# keyring-utilities
Various key ring utilities that interact with z/OS RACF key rings using R_datalib API and GSK APIs.
## keyring-util tool
The `keyring-util` tool is the primary artifact produced by this repository.
The keyring-util program leverages
[R_datalib callable service](https://www.ibm.com/docs/en/zos/2.5.0?topic=descriptions-r-datalib-irrsdl00-irrsdl64-certificate-data-library)
and [GSK CSM APIs](https://www.ibm.com/docs/en/zos/2.5.0?topic=programming-certificate-management-services-cms-api-reference) to perform various operations on digital certificates and RACF key rings. GSM CSM APIs are preferred when available, however, they don't always return complete metadata surrounding certificate definitions, which the R_datalib callable services will provide.
## Build
Enter the `build/` directory and execute the `build.sh` script
## Syntax
```bash
keyring-util function userid keyring label
```
**Parameters:**
1. `function` see [Functions](#Functions) section below
2. `userid` - an owner of the `keyring` and `label` certificate
3. `keyring` - a name of the keyring
4. **(Optional)** `-v`: verbose logging.
5. Command-specific arguments, see [Functions](#Functions) Supported Arguments.
## Functions
* `LISTRING` - lists keyring contents in a summarized format containing Label, Owner, Usage, Status, and Default.
- Supported Arguments:
* `-l `: Optional. Limits output to certificates with an alias matching `label`.
* `-u `: Optional. Limits output to certificates with USAGE matching ``. One of `CERTAUTH`, `PERSONAL`, `OTHER`.
* `--label-only`: Optional. Limits output to the label field only. Higher priority than `--owner-only`.
* `--owner-only`: Optional. Limits output to the owner field only.
- Examples:
* `keyring-util NEWRING USER01 RING02`
* `keyring-util NEWRING USER01 RING02 -l SOMELBL`
* `keyring-util NEWRING USER01 RING02 -u PERSONAL --label-only`
* `NEWRING` - creates a keyring
- Example: `keyring-util NEWRING USER01 RING02`
* `DELRING` - deletes a keyring
* Example: `keyring-util DELRING USER01 RING02`
* `DELCERT` - remove a certificate from a keyring or deletes a certificate from RACF database
- Supported Arguments:
* `-l `: Required. Specifies the certificate to be removed by label.
**Current Limitation:** The `DELCERT` function can only manipulate a certificate that is owned by the `userid`, i.e. it can't
work with certificates owned by the CERTAUTH, SITE or different userid.
The following example removes `CERT03` certificate owned by the `USER01` from the `RING02` keyring owned by the `USER01` userid
* Example: `keyring-util DELCERT USER01 RING02 -l CERT03`
The following example removes `CERT03` certificate owned by the `USER01` from the RACF database. The command fails if the certificate
is still connected to some keyring.
* Example: `keyring-util DELCERT USER01 '*' -l CERT03`
* `EXPORT` - exports a certificate in PEM format. The file is created in a `pwd` directory with a name of `.pem`
- Supported Arguments:
* `-l `: Required. Specifies the certificate to be exported by label.
- Example: `keyring-util EXPORT USER01 RING02 -l CERT03`
* Creates a file CERT03.pem.
* `IMPORT` - imports a certificate from the PKCS12 format. The certificate can be connected to a keyring as `PERSONAL` or `CERTAUTH`.
- Supported Arguments:
* `-l `: Required. Specifies the certificate label of the created keyring certificate.
* `-u `: Required. One of `CERTAUTH`, `PERSONAL`.
* `-f `: Required. Specifies the path to the PKCS12 certificate being imported.
* `-p `: Required. Specifies the password required to open the PKCS12 certificate specified by `-f`.
**Warning:** The scenario where a private key is also imported currently works only with RACF.
* Example: `keyring-util IMPORT USER01 RING02 -l CERT03 -u PERSONAL -f /path/to/file.p12 -p pkcs12_password`
* `REFRESH` - refreshes DIGTCERT class
* Example: `keyring-util REFRESH`
For any return and reason codes, check [R_datalib return and reason codes](https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.ichd100/ich2d100238.htm)
## Further development
There is room for improvement:
* command line argument processing and syntax (perhaps using the argp library from [ambitus project](https://github.com/ambitus/glibc/tree/zos/2.28/master/argp))
* an extension of functionality of the current R_datalib functions
* adding support for other [R_datalib functions](https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.ichd100/ich2d100226.htm)
Work with the following resource if you want to add support for other R_datalib functions [Data areas for R_datalib callable service](https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.ichc400/comx.htm)