[Contents] [Index]

About This Document >>     Installing SSH Tectia Server for IBM z/OS >>     Getting Started with SSH Tectia Server for IBM z/OS >>     Configuring the Server >>     Configuring the Client >>     Authentication >>         Using the z/OS System Authorization Facility         Server Authentication with Public Keys in File >>         Server Authentication with Certificates >>         User Authentication with Passwords         User Authentication with Public Keys in File >>         User Authentication with Certificates >>             Client Configuration             Server Configuration         Host-Based User Authentication >>         User Authentication with Keyboard-Interactive >>         Distributing Public Keys Using the Key Distribution Tool >>     Transferring Files >>     Tunneling >>     Troubleshooting SSH Tectia Server for IBM z/OS >>     Advanced Information >>     Man Pages >>     Log Messages >>

Server Configuration

The server can be configured to allow or require certificate-based user authentication. To use SAF certificates, a trusted key provider must be configured. The users must be set up with digital certificates.

Certificates Stored in File

To configure the server to allow user authentication with certificates, perform the following tasks:

1. Acquire the CA certificate and copy it to the server machine. You can either copy the X.509 certificate(s) as such or you can copy a PKCS #7 package including the CA certificate(s). Certificates can be extracted from a PKCS #7 package by specifying the -7 flag with ssh-keygen2.
2. Certificate authentication is a part of the publickey authentication method. Make sure that you have enabled it in the /etc/ssh2/sshd2_config file:

   AllowedAuthentications publickey AuthPublicKey.Cert.Required no

   Setting the AuthPublicKey.Cert.Required option to yes defines that the user must authenticate with a certificate or else the authentication will fail.
3. Specify the trusted CA certificate and the mapping file(s) in the ssh_certd_config file:

   Pki <ca-cert-path> MapFile <map-file-path>

   You can define several CA certificates by using several Pki keywords.

   Pki test-ca1.crt MapFile cert-user-mapping1.txt Pki test-ca2.crt MapFile cert-user-mapping2a.txt MapFile cert-user-mapping2b.txt

   Note that multiple MapFile keywords are permitted per Pki keyword. Also, if no mapping file is defined, all connections are denied even if user certificates can be verified using the defined CA certificate. The server will accept only certificates issued by defined CA(s).
4. Also define 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.
5. Create the certificate user mapping file as described in Section Certificate User Mapping File.
6. 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.

Certificate User Mapping File

The map file specifies which certificates authorize logging into which accounts. The format of the file is as follows:

<account-id> <keyword> <argument>

The keyword can be either Email, Subject, SerialAndIssuer, EmailRegex, or SubjectRegex. The argument depends on the keyword.

• Email: The argument is the e-mail address which must be present in the certificate.
• Subject: The argument is the required subject name in LDAP DN (distinguished name) string format.
• SerialAndIssuer: The argument is the required serial number and issuer name in LDAP DN string format, separated by spaces or tabs.
• EmailRegex: The argument is the regular expression which must match an e-mail address in the certificate. If account-id contains the string %subst%, it is substituted with the first parenthesized part of the regular expression. The patterns are matched using the egrep syntax.
• SubjectRegex: The argument is the regular expression which must match a subject name in the certificate. If account-id contains the string %subst%, it is substituted with the first parenthesized part of the regular expression. The patterns are matched using the egrep syntax.

Examples

The following are examples of different map file definitions:

testuser email testuser@ssh.com testuser subject C=FI,O=SSH,CN=Secure Shell Tester testuser serialandissuer 1234 C=FI,O=SSH,CN=Secure Shell Tester %subst% subjectregex C=FI, O=SSH, CN=([a-z]+) %subst% emailregex ([a-z]+)@ssh\.com

The last line permits logging with any e-mail address with only letters in the username. For more information on the regular expression syntax, see Appendix sshregex.

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 /etc/ssh2/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 /etc/ssh2/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 alternative 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 /etc/ssh2/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 /etc/ssh2/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 /etc/ssh2/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.