[Contents] [Index]

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:

1. 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.
2. 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 SSH 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 username based on the certificate contents. After that the SSH 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, SSH Tectia validation, or SSH 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 SSH Tectia validation need to be completed.
3. (SAF validation only) Get the user certificate and store it to a dataset, for example 'USER.CRT'.
4. (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)
   

5. (SAF validation only) For the settings to take effect, give the following TSO command:

   SETROPTS RACLIST(DIGTCERT) REFRESH
   

6. (SSH Tectia validation) Get the CA certificate and store it to a dataset, for example 'PKICA.CRT'.
7. (SSH 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)
   

8. (SSH Tectia validation) For the settings to take effect, give the following TSO command:

   SETROPTS RACLIST(DIGTCERT) REFRESH
   

9. (SAF validation) The IdentityDispatchUsers keyword in the /opt/tectia/etc/sshd2_config file can be used to define username patterns for which the login name given by the user is not used but the real username is taken from the user certificate.

   IdentityDispatchUsers username-pattern

10. (SAF validation) A user certificate might contain a HostIdMapping extension field. That field is used by SAF to determine the local username of the user. If the user certificate has the correct hostname in the HostIdMapping hostname field, the username associated with that hostname (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 hostname. 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
    

11. (SAF and SSH Tectia validation) As an alternative to the previous step, when both SAF and SSH Tectia validation are used, the HostIdMappingHostnames keyword in the /opt/tectia/etc/sshd2_config file can be used to define a list of hostnames that the server recognizes. If the user certificate has a matching hostname in the HostIdMapping hostname field, the username associated with that hostname (specified in the certificate) is used.

    HostIdMappingHostnames lpar2.example.com

12. (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 the following list:
    • %U = user name
    • %IU = user ID
    • %IG = user group ID
13. (SSH Tectia validation) If SSH 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))"

14. (SSH Tectia validation only) If only SSH 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

15. (SSH Tectia validation) If SSH 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.
16. (SSH Tectia validation only) If only SSH Tectia validation is used, create the certificate user mapping file as described in Section Certificate User Mapping File.
17. (SSH Tectia validation) Restart ssh-certd as instructed in Section Restarting 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.