Certificates Stored in SAF

To configure the server to allow user authentication with SAF certificates, perform the following tasks. Replace the names and IDs with those appropriate to your system:

Certificate authentication is a part of the publickey authentication method. Make sure that you have enabled it in the /opt/tectia/etc/sshd2_config file:
```
AllowedAuthentications        publickey
AuthPublicKey.Cert.Required   yes 
```
Setting the AuthPublicKey.Cert.Required option to yes defines that the user must authenticate with a certificate or else the authentication will fail.

Define the certificate validation method in the /opt/tectia/etc/sshd2_config file. The validation method can be either saf, tectia, or both (saf,tectia).

AuthPublicKey.Cert.ValidationMethods   tectia|saf|saf,tectia

If saf is specified, RACF/SAF is used for validating user certificates. The user certificates must be found in a trusted key ring defined by the AuthorizationEkProvider keyword. Note that when only SAF validation is used, the certificate validity period and revocation status are not checked.

If tectia is specified (or the keyword is missing from the configuration), the Tectia Certificate Validator (ssh-certd) is used for validating the user certificate. The user certificates must be issued by a trusted certification authority defined in the Pki or PkiEkProvider keyword of ssh_certd_config.

If both values are specified, RACF/SAF determines the user name based on the certificate contents. After that the Tectia validation is performed. The CA certificate of the issuing certification authority must be found in a trusted key ring defined by the PkiEkProvider keyword of ssh_certd_config.

	Note
	Several of the following steps are marked either as SAF validation, SAF validation only, Tectia validation, or Tectia validation only. These steps are alternatives depending on the value of `AuthPublicKey.Cert.ValidationMethods`. If `saf,tectia` is selected, both the steps marked as SAF validation and Tectia validation need to be completed.

(SAF validation only) Get the user certificate and store it to a data set, for example 'USER.CRT'.

(SAF validation only) To add the user certificate into SAF, give the following TSO commands:

RACDCERT ID(USER) ADD('USER.CRT')TRUST WITHLABEL('USER')
RACDCERT ID(USER) ADDRING(USER)
RACDCERT ID(USER) CONNECT(ID(USER) LABEL('USER') RING(USER) 
  USAGE(PERSONAL))
RACDCERT ID(USER) LISTRING(USER)

(SAF validation only) For the settings to take effect, give the following TSO command:
```
SETROPTS RACLIST(DIGTCERT) REFRESH
```
(Tectia validation) Get the CA certificate and store it to a data set, for example 'PKICA.CRT'.

(Tectia validation) To add the CA certificate into SAF, give the following TSO commands:

RACDCERT CERTAUTH ADD('PKICA.CRT') TRUST WITHLABEL('PKICA')
RACDCERT ID(SSHD2) ADDRING(SSH-PKI)
RACDCERT ID(SSHD2) CONNECT(CERTAUTH LABEL('PKICA') RING(SSH-PKI) 
  USAGE(CERTAUTH))
RACDCERT ID(SSHD2) LISTRING(SSH-PKI)

(Tectia validation) For the settings to take effect, give the following TSO command:
```
SETROPTS RACLIST(DIGTCERT) REFRESH
```
(SAF validation) The IdentityDispatchUsers keyword in the /opt/tectia/etc/sshd2_config file can be used to define user name patterns for which the login name given by the user is not used but the real user name is taken from the user certificate.
```
IdentityDispatchUsers username-pattern
```
(SAF validation) A user certificate might contain a HostIdMapping extension field. That field is used by SAF to determine the local user name of the user. If the user certificate has the correct host name in the HostIdMapping host name field, the user name associated with that host name (specified in the certificate) is used. To use the HostIdMapping extension in user certificates, give the CA certificate the HIGHTRUST status and give the SSHD2 user READ access to the resource IRR.HOST.hostname in the SERVAUTH class, where hostname is the character string used in the certificate extension. Often the DNS name of the server is used as the host name. To allow SAF to use the HostIdMapping extension, give the following commands:
```
RACDCERT CERTAUTH ALTER(LABEL('PKICA')) HIGHTRUST
RDEFINE SERVAUTH IRR.HOST.LPAR2.EXAMPLE.COM UACC(NONE) 
PERMIT IRR.HOST.LPAR2.EXAMPLE.COM CLASS(SERVAUTH) ID(SSHD2) ACCESS(READ) 
SETROPTS RACLIST(SERVAUTH) REFRESH
RLIST SERVAUTH IRR.HOST.LPAR2.EXAMPLE.COM ALL
```
(SAF and Tectia validation) As an alternative to the previous step, when both SAF and Tectia validation are used, the HostIdMappingHostnames keyword in the /opt/tectia/etc/sshd2_config file can be used to define a list of host names that the server recognizes. If the user certificate has a matching host name in the HostIdMapping host name field, the user name associated with that host name (specified in the certificate) is used.
```
HostIdMappingHostnames         lpar2.example.com
```
(SAF validation only) If only SAF validation is used, define the z/OS SAF external key provider that contains the user certificates with the AuthorizationEkProvider keyword in the /opt/tectia/etc/sshd2_config file:
```
AuthorizationEkProvider        "zos-saf:KEYS(ID(%U) RING(%U))"
```
The AuthorizationEkProvider keyword can contain special strings in the key specification that are mapped according to the following list:
- %U = user name
- %IU = user ID
- %IG = user group ID
(Tectia validation) If Tectia validation is used, define the z/OS SAF external key provider that contains the CA certificates with the PkiEkProvider keyword in the ssh_certd_config file:
```
PkiEkProvider                  "zos-saf:KEYS(ID(SSHD2) RING(SSH-PKI))"
```

(Tectia validation only) If only Tectia validation is used, define also the mapping file(s) in the ssh_certd_config file:

PkiEkProvider                  "zos-saf:KEYS(ID(SSHD2)RING(SSH-PKI))"
MapFile                        cert-user-mapping.txt

(Tectia validation) If Tectia validation is used, define also the LDAP server(s) used for CRL checks in the ssh_certd_config file. If the CA services (OCSP, CRLs) are located behind a firewall, define also the SOCKS server.
```
LdapServers                    ldap://ldap.example.com:389
SocksServer                    socks://fw.example.com:1080
```
Defining the LDAP server is not necessary if the CA certificate contains a CRL Distribution Point or an Authority Info Access extension.
(Tectia validation only) If only Tectia validation is used, create the certificate user mapping file as described in Certificate User Mapping File.
(Tectia validation) Restart ssh-certd as instructed in Restarting and Stopping ssh-certd.

For more information on the configuration file options, see sshd2_config and ssh_certd_config. For information on the format of the external key initialization string, see ssh-externalkeys.