Configuration of Public Key Cryptography for initial authentication (PKINIT)
- Diffie-Hellman key exchange (DH) method
- Public Key Encryption (RSA) method
To support PKINIT there are new environment variables and configuration options for both the KDC and the client to use. The KDC and the client must also set up a key ring, key token, or key database with appropriate digital certificates.
The KDC reads the environment variables set up for this mechanism in /etc/skrb/home/kdc/envar. See the options that start with SKDC_PKINIT on Table 1 in topic Security server environment variables.
The client reads the krb5.conf for the configuration options in the appropriate realms section. See the options that start with pkinit in [realms] section.
If the keyword is repeated in the envar file or in the krb5.conf file, only the first occurrence takes effect.
The z/OS KDC requires clients to use one of two preauthentication mechanisms; PKINIT or an encrypted timestamp. The PKINIT preauthentication mechanism is the preferred mechanism when the KDC has been configured to use and support PKINIT. In addition, the KDC can be configured to require clients to use PKINIT by setting the SKDC_PKINIT_REQUIRED=1. Clients attempting to authenticate to the KDC without being configured to use PKINIT preauthentication but use the encrypted timestamp mechanism will fail with a preauthentication failure.When the KDC has been configured for PKINIT but does not require PKINIT preauthentication, the client may use either preauthentication mechanism. The z/OS kinit command will prefer the PKINIT preauthentication mechanism if there is sufficient client configuration to support PKINIT. If the KDC does not support PKINIT, and returns a preauthentication error, the z/OS kinit command will prompt for the password and fall back to use the encrypted timestamp mechanism.
If SKDC_PKINIT_REQUIRED=1, any invalid values of the SKDC_PKINIT keywords (except SKDC_PKINIT_DH_MIN_BITS) will prevent KDC from starting.
If SKDC_PKINIT_REQUIRED<>1, any invalid values are logged and KDC can be started. But the invalid values, except SKDC_PKINIT_DH_MIN_BITS and SKDC_PKINIT_REQUIRE_EKU, makes the KDC incapable of processing PKINIT requests.
For the z/OS client side, invalid values for pkinit_keyring, pkinit_keyring_stash in the krb5.conf file causes an error. Other invalid values cause the default values to be used.
Revocation checking
When the PKINIT preauthentication mechanism is in use, internal processing on both the KDC and client performs certificate validation. (KDC validates the clients certificate, and client validates the KDC certificate) Depending on if and how the issuing CA provides revocation information, your revocation checking configuration varies. The Network Authentication Service supports Online Certificate Status Protocol(OCSP) and Certificate Revocation Lists Distribution Points (CRL DPs). To configure revocation checking to be performed by the KDC on client certificates, see SKDC_PKINIT_REQUIRE_REVOCATION_CHECKING on Table 1. To configure revocation checking to be performed by the client on the KDC certificates, see pkinit_require_revocation_checking parameter for realm in the [realms] section.
Certificates needed in the KDC key ring, key token, or key database
- The CA certificate chains that signed the KDC certificates. If the KDC is contacted by different clients with different signing chains, multiple sets of client CA certificates are needed.
- The root CA certificate of the client chain is needed.
- The KDC certificates that meets the following requirement (There
can be multiple such KDC certificates for different clients.):
- Its private key is in the key ring / key token / key database.
- It has usage PERSONAL (for key ring and key token).
- If it has the keyUsage extension, it must assert the digitalSignature key usage bit.
- The following is required by the z/OS Kerberos client:
- It must contain OtherName form in the Subject Alternative Name
extension as follows:
where Realm is the KDC that issues the TGS ticket, PrincipalName indicates the target realm that the ticket is for, with name type value 2 - type 2 principal name contains a sequence of a hardcoded string 'krbtgt' and the realm name that accepts the ticket.OID:1.3.6.1.5.2.2 - id-pkinit-san Value: KRB5PrincipalName ::= SEQUENCE { realm [0] Realm, principalName [1] PrincipalName** }
When the client verifies the KDC certificate, it checks whether the PrincipalName** indicated in the certificate matches the PrincipalName in the server name field in the request.
- It must contain OtherName form in the Subject Alternative Name
extension as follows:
The KDC picks its certificate that was issued by the CA on the list of the trusted certifiers. It uses the first one found that satisfies the requirements.
If key ring or key token is set up through the RACDCERT CONNECT or BIND commands, the usage can be explicitly specified by using the USAGE keyword. If key database or key token is set up through System SSL's gskkyman, the certificate usage is implicitly set – if it is added with the private key, it has usage PERSONAL.
Certificates needed in the client key ring, key token, or key database
- The CA chain certificates that signed the client certificate.
- The CA root certificates of the KDC certificates.
- The client certificate that meets the following requirements:
- Its private key is in the key ring / key token / key database.
- Has usage PERSONAL (for key ring and key token).
- Marked as the default certificate.
- If it has the keyUsage extension, it must assert the digitalSignature key usage bit.
- Contain OtherName form in the Subject Alternative Name extension
as follows:
where Realm is the client's realm, PrincipalName indicates the client's principal name with name type 1,OID:1.3.6.1.5.2.2 id_pkinit-san Value: KRB5PrincipalName ::= SEQUENCE { realm [0] Realm, principalName [1] PrincipalName }
or
OID: 1.3.6.1.4.1.311.20.2.3 id-ms-san-sc-logon-upn Value: UserPrincipalName ::= UTF8STRING (principalName@Realm)
- If KDC requires extended keyusage extension (that is, the environment
variable SKDC_PKINIT_REQUIRE_EKU is set to 1), the client certificate
must contain,
- One of these extended keyusage, either
- id-pkinit-KPClientauth (1.3.6.1.5.2.3.4), or
- id-ms-kp-sc-logon (1.3.6.1.4.1.311.20.2.2)
- When an extended keyusage extension is included in the client certificate, a keyusage extension that asserts the digitalSignature key usage bit is required.
- One of these extended keyusage, either
The client builds the trusted certifiers from all the other certificates in its key ring / key token / key database.
Anonymous PKINIT
When using the Flexible Authentication Secure Tunneling (FAST) support for initial authentication requests, clients will need an armor ticket to successfully use FAST. The only supported method of obtaining an armor ticket is to use anonymous PKINIT. Anonymous PKINIT is similar to PKINIT pre-authentication, however, the client does not supply a certificate or any other information that would reveal the client identity to the receiving KDC. Anonymous PKINIT requests require the same KDC configuration as PKINIT, with the exception that the root CA certificates for validating client certificates are not required. The client key rings, key tokens, or key databases are only required to contain the certificates necessary to validate the KDC certificate, as a client certificate is not used in an anonymous PKINIT authentication request. Since the anonymous PKINIT authentication request does not use a client certificate, requests will only support the Diffie_Hellman key exchange method for obtaining an anonymous tickets from the KDC, the Public Key Encryption method is not allowed.