Step 1. Construct the key ring

In this step, you will construct a key ring, if one is needed, generate certificates, connect them to the user's key ring, and set up permission to access the key ring.

Before you begin: You need to know the following facts:

Which protocol version you will be using. If you are using SSH protocol version 1, you cannot use key rings to hold your keys. You must use UNIX files to hold RSA keys used for SSH protocol version 1.
Whether you are working with real or virtual key rings because the setup steps vary depending on the type of key ring is being used. See z/OS Security Server RACF Security Administrator's Guide for more information about real and virtual key rings.

Create a real key ring if you do not yet have one for your keys. Omit this step if you plan to use a virtual key ring. If you already have a key ring or are using a virtual key ring, go to Step 2. Use the RACDCERT ADDRING command to create the new key ring, specifying the owning user ID and the key ring name. The ID keyword must specify the user ID that will be authenticating with the keys within it. The key ring name can be any unique name for this user ID.
Example: To define the SSHring key ring, issue:
```
RACDCERT ADDRING(SSHring) ID(userID)
```
On this command example, and all that follow, the ID() keyword can be omitted if the invoking user is the same as the authenticating user ID.
_______________________________________________________________
Using the RACDCERT GENCERT command, generate a certificate with public and private keys, based on the algorithms that are supported on the server (either RSA, DSA, or both.) For RSA keys, the minimum size is 768 bits, the maximum size is 32768 bits. Typically, 2048 bits is considered sufficient. DSA keys can be 1024 bits in both FIPS and non-FIPS mode. Since DSA 2048 is not supported by open group OpenSSH, z/OS OpenSSH may not communicate with open group OpenSSH if DSA 2048 key is used. It requires both client and server to be z/OS OpenSSH and run in FIPS mode if DSA 2048 is used. DSA keys larger than 2048 bits associated with certificates in a key ring are not supported by OpenSSH.
Do not use variant characters in the label name for the certificate.
Although the examples demonstrate how to create non-ICSF (Integrated Cryptographic Storage Facility) certificates in the RACF database, ICSF can also be used to store the certificate and associated keys for RSA only. These can be generated by software using ICSF or by hardware using a PCI Cryptographic Coprocessor (PCICC). For more information, refer to z/OS Cryptographic Services ICSF Administrator's Guide.
- To generate a certificate and an RSA public/private key pair, storing the private key in the RACF database as a non-ICSF key:
```
RACDCERT GENCERT SUBJECTSDN(CN('uniq-ssh-rsa-cn')) SIZE(2048) 
 WITHLABEL('uniq-ssh-rsa') ID(userID)
```
- To generate a certificate and a 1024 DSA public/private key pair, storing the private key in the RACF database as a non-ICSF key:
```
RACDCERT	GENCERT SUBJECTSDN(CN('uniq-ssh-dsa-cn')) SIZE(1024) DSA 
 WITHLABEL('uniq-ssh-dsa') ID(userID)
```
- To generate a certificate and a 2048 DSA public/private key pair, storing the private key in the RACF database as a non-ICSF key:
```
RDEFINE FACILITY IRR.DSA.SHA256 UACC(NONE)
SETROPTS RACLIST(FACILITY) REFRESH
RACDCERT	GENCERT SUBJECTSDN(CN('uniq-ssh-dsa-cn')) SIZE(2048) DSA 
 WITHLABEL('uniq-ssh-dsa') ID(userID)
```
The SUBJECTSDN parameter offers additional customizable keywords, which are not documented in this section, that can be included in the distinguished name. The label assigned to the certificate must be unique within the RACF database.

_______________________________________________________________
If real key rings are being used, use the RACDCERT CONNECT command to connect the certificate to the user's key ring. Omit this step if virtual key rings are being used. If you are not the certificate owner, you must identify the user ID that owns the certificate. If you are not the key ring owner, you must identify the user ID that owns the key ring. These will normally be the same for this connect command.
```
RACDCERT CONNECT(ID(userID) LABEL('uniq-ssh-type') RING(SSHring) 
 USAGE(PERSONAL)) ID(userID)
```
_______________________________________________________________
Update the user's z/OS-specific per-user client configuration file (~/.ssh/zos_user_ssh_config) to indicate the location of the user's keys when using key rings.
- If real key rings are being used, add the following line:
```
IdentityKeyRingLabel "userID/SSHring uniq-ssh-type"
```
- If virtual key rings are being used, add the following line:
```
IdentityKeyRingLabel "userID/* uniq-ssh-type"
```
_______________________________________________________________
Permit access to the key ring for the user, using either ring-specific profile checking or global profile checking. These are discussed in Managing key rings and restricting access to them.
For example:
- To define individual user access to the real key ring, SSHring, using ring-specific profile checking:
```
RDEFINE RDATALIB userID.SSHring.LST UACC(NONE)	
PERMIT userID.SSHring.LST CLASS(RDATALIB) ID(userID) ACCESS(READ) 
```
  If the RDATALIB class is not yet active and RACLISTed:
```
SETROPTS RACLIST(RDATALIB) CLASSACT(RDATALIB)
```
  Refresh the class:
```
SETROPTS RACLIST(RDATALIB) REFRESH
```
- To define individual user access to the virtual key ring, using ring-specific profile checking:
```
RDEFINE RDATALIB userID.IRR_VIRTUAL_KEYRING.LST UACC(NONE)	
PERMIT userID.IRR_VIRTUAL_LISTRING.LST CLASS(RDATALIB) ID(userID) ACCESS(READ)
```
  If the RDATALIB class is not yet active and RACLISTed:
```
SETROPTS RACLIST(RDATALIB) CLASSACT(RDATALIB)
```
  Refresh the class:
```
SETROPTS RACLIST(RDATALIB) REFRESH
```
- To define individual user access, using global profile checking:
```
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(READ)
```
  If the FACILITY class is not yet active and RACLISTed:
```
SETROPTS RACLIST(FACILITY) CLASSACT(FACILITY)
```
  Refresh the class:
```
SETROPTS RACLIST(FACILITY) REFRESH
```
_______________________________________________________________