diff options
Diffstat (limited to 'roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/admin/pkinit.rst')
| -rw-r--r-- | roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/admin/pkinit.rst | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/admin/pkinit.rst b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/admin/pkinit.rst new file mode 100644 index 000000000..bec4fc800 --- /dev/null +++ b/roms/edk2/CryptoPkg/Library/OpensslLib/openssl/krb5/doc/admin/pkinit.rst @@ -0,0 +1,354 @@ +.. _pkinit: + +PKINIT configuration +==================== + +PKINIT is a preauthentication mechanism for Kerberos 5 which uses +X.509 certificates to authenticate the KDC to clients and vice versa. +PKINIT can also be used to enable anonymity support, allowing clients +to communicate securely with the KDC or with application servers +without authenticating as a particular client principal. + + +Creating certificates +--------------------- + +PKINIT requires an X.509 certificate for the KDC and one for each +client principal which will authenticate using PKINIT. For anonymous +PKINIT, a KDC certificate is required, but client certificates are +not. A commercially issued server certificate can be used for the KDC +certificate, but generally cannot be used for client certificates. + +The instruction in this section describe how to establish a +certificate authority and create standard PKINIT certificates. Skip +this section if you are using a commercially issued server certificate +as the KDC certificate for anonymous PKINIT, or if you are configuring +a client to use an Active Directory KDC. + + +Generating a certificate authority certificate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can establish a new certificate authority (CA) for use with a +PKINIT deployment with the commands:: + + openssl genrsa -out cakey.pem 2048 + openssl req -key cakey.pem -new -x509 -out cacert.pem -days 3650 + +The second command will ask for the values of several certificate +fields. These fields can be set to any values. You can adjust the +expiration time of the CA certificate by changing the number after +``-days``. Since the CA certificate must be deployed to client +machines each time it changes, it should normally have an expiration +time far in the future; however, expiration times after 2037 may cause +interoperability issues in rare circumstances. + +The result of these commands will be two files, cakey.pem and +cacert.pem. cakey.pem will contain a 2048-bit RSA private key, which +must be carefully protected. cacert.pem will contain the CA +certificate, which must be placed in the filesytems of the KDC and +each client host. cakey.pem will be required to create KDC and client +certificates. + + +Generating a KDC certificate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A KDC certificate for use with PKINIT is required to have some unusual +fields, which makes generating them with OpenSSL somewhat complicated. +First, you will need a file containing the following:: + + [kdc_cert] + basicConstraints=CA:FALSE + keyUsage=nonRepudiation,digitalSignature,keyEncipherment,keyAgreement + extendedKeyUsage=1.3.6.1.5.2.3.5 + subjectKeyIdentifier=hash + authorityKeyIdentifier=keyid,issuer + issuerAltName=issuer:copy + subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:kdc_princ_name + + [kdc_princ_name] + realm=EXP:0,GeneralString:${ENV::REALM} + principal_name=EXP:1,SEQUENCE:kdc_principal_seq + + [kdc_principal_seq] + name_type=EXP:0,INTEGER:1 + name_string=EXP:1,SEQUENCE:kdc_principals + + [kdc_principals] + princ1=GeneralString:krbtgt + princ2=GeneralString:${ENV::REALM} + +If the above contents are placed in extensions.kdc, you can generate +and sign a KDC certificate with the following commands:: + + openssl genrsa -out kdckey.pem 2048 + openssl req -new -out kdc.req -key kdckey.pem + env REALM=YOUR_REALMNAME openssl x509 -req -in kdc.req \ + -CAkey cakey.pem -CA cacert.pem -out kdc.pem -days 365 \ + -extfile extensions.kdc -extensions kdc_cert -CAcreateserial + rm kdc.req + +The second command will ask for the values of certificate fields, +which can be set to any values. In the third command, substitute your +KDC's realm name for YOUR_REALMNAME. You can adjust the certificate's +expiration date by changing the number after ``-days``. Remember to +create a new KDC certificate before the old one expires. + +The result of this operation will be in two files, kdckey.pem and +kdc.pem. Both files must be placed in the KDC's filesystem. +kdckey.pem, which contains the KDC's private key, must be carefully +protected. + +If you examine the KDC certificate with ``openssl x509 -in kdc.pem +-text -noout``, OpenSSL will not know how to display the KDC principal +name in the Subject Alternative Name extension, so it will appear as +``othername:<unsupported>``. This is normal and does not mean +anything is wrong with the KDC certificate. + + +Generating client certificates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PKINIT client certificates also must have some unusual certificate +fields. To generate a client certificate with OpenSSL for a +single-component principal name, you will need an extensions file +(different from the KDC extensions file above) containing:: + + [client_cert] + basicConstraints=CA:FALSE + keyUsage=digitalSignature,keyEncipherment,keyAgreement + extendedKeyUsage=1.3.6.1.5.2.3.4 + subjectKeyIdentifier=hash + authorityKeyIdentifier=keyid,issuer + issuerAltName=issuer:copy + subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name + + [princ_name] + realm=EXP:0,GeneralString:${ENV::REALM} + principal_name=EXP:1,SEQUENCE:principal_seq + + [principal_seq] + name_type=EXP:0,INTEGER:1 + name_string=EXP:1,SEQUENCE:principals + + [principals] + princ1=GeneralString:${ENV::CLIENT} + +If the above contents are placed in extensions.client, you can +generate and sign a client certificate with the following commands:: + + openssl genrsa -out clientkey.pem 2048 + openssl req -new -key clientkey.pem -out client.req + env REALM=YOUR_REALMNAME CLIENT=YOUR_PRINCNAME openssl x509 \ + -CAkey cakey.pem -CA cacert.pem -req -in client.req \ + -extensions client_cert -extfile extensions.client \ + -days 365 -out client.pem + rm client.req + +Normally, the first two commands should be run on the client host, and +the resulting client.req file transferred to the certificate authority +host for the third command. As in the previous steps, the second +command will ask for the values of certificate fields, which can be +set to any values. In the third command, substitute your realm's name +for YOUR_REALMNAME and the client's principal name (without realm) for +YOUR_PRINCNAME. You can adjust the certificate's expiration date by +changing the number after ``-days``. + +The result of this operation will be two files, clientkey.pem and +client.pem. Both files must be present on the client's host; +clientkey.pem, which contains the client's private key, must be +protected from access by others. + +As in the KDC certificate, OpenSSL will display the client principal +name as ``othername:<unsupported>`` in the Subject Alternative Name +extension of a PKINIT client certificate. + +If the client principal name contains more than one component +(e.g. ``host/example.com@REALM``), the ``[principals]`` section of +``extensions.client`` must be altered to contain multiple entries. +(Simply setting ``CLIENT`` to ``host/example.com`` would generate a +certificate for ``host\/example.com@REALM`` which would not match the +multi-component principal name.) For a two-component principal, the +section should read:: + + [principals] + princ1=GeneralString:${ENV::CLIENT1} + princ2=GeneralString:${ENV::CLIENT2} + +The environment variables ``CLIENT1`` and ``CLIENT2`` must then be set +to the first and second components when running ``openssl x509``. + + +Configuring the KDC +------------------- + +The KDC must have filesystem access to the KDC certificate (kdc.pem) +and the KDC private key (kdckey.pem). Configure the following +relation in the KDC's :ref:`kdc.conf(5)` file, either in the +:ref:`kdcdefaults` section or in a :ref:`kdc_realms` subsection (with +appropriate pathnames):: + + pkinit_identity = FILE:/var/lib/krb5kdc/kdc.pem,/var/lib/krb5kdc/kdckey.pem + +If any clients will authenticate using regular (as opposed to +anonymous) PKINIT, the KDC must also have filesystem access to the CA +certificate (cacert.pem), and the following configuration (with the +appropriate pathname):: + + pkinit_anchors = FILE:/var/lib/krb5kdc/cacert.pem + +Because of the larger size of requests and responses using PKINIT, you +may also need to allow TCP access to the KDC:: + + kdc_tcp_listen = 88 + +Restart the :ref:`krb5kdc(8)` daemon to pick up the configuration +changes. + +The principal entry for each PKINIT-using client must be configured to +require preauthentication. Ensure this with the command:: + + kadmin -q 'modprinc +requires_preauth YOUR_PRINCNAME' + +Starting with release 1.12, it is possible to remove the long-term +keys of a principal entry, which can save some space in the database +and help to clarify some PKINIT-related error conditions by not asking +for a password:: + + kadmin -q 'purgekeys -all YOUR_PRINCNAME' + +These principal options can also be specified at principal creation +time as follows:: + + kadmin -q 'add_principal +requires_preauth -nokey YOUR_PRINCNAME' + +By default, the KDC requires PKINIT client certificates to have the +standard Extended Key Usage and Subject Alternative Name attributes +for PKINIT. Starting in release 1.16, it is possible to authorize +client certificates based on the subject or other criteria instead of +the standard PKINIT Subject Alternative Name, by setting the +**pkinit_cert_match** string attribute on each client principal entry. +For example:: + + kadmin set_string user@REALM pkinit_cert_match "<SUBJECT>CN=user@REALM$" + +The **pkinit_cert_match** string attribute follows the syntax used by +the :ref:`krb5.conf(5)` **pkinit_cert_match** relation. To allow the +use of non-PKINIT client certificates, it will also be necessary to +disable key usage checking using the **pkinit_eku_checking** relation; +for example:: + + [kdcdefaults] + pkinit_eku_checking = none + + + +Configuring the clients +----------------------- + +Client hosts must be configured to trust the issuing authority for the +KDC certificate. For a newly established certificate authority, the +client host must have filesystem access to the CA certificate +(cacert.pem) and the following relation in :ref:`krb5.conf(5)` in the +appropriate :ref:`realms` subsection (with appropriate pathnames):: + + pkinit_anchors = FILE:/etc/krb5/cacert.pem + +If the KDC certificate is a commercially issued server certificate, +the issuing certificate is most likely included in a system directory. +You can specify it by filename as above, or specify the whole +directory like so:: + + pkinit_anchors = DIR:/etc/ssl/certs + +A commercially issued server certificate will usually not have the +standard PKINIT principal name or Extended Key Usage extensions, so +the following additional configuration is required:: + + pkinit_eku_checking = kpServerAuth + pkinit_kdc_hostname = hostname.of.kdc.certificate + +Multiple **pkinit_kdc_hostname** relations can be configured to +recognize multiple KDC certificates. If the KDC is an Active +Directory domain controller, setting **pkinit_kdc_hostname** is +necessary, but it should not be necessary to set +**pkinit_eku_checking**. + +To perform regular (as opposed to anonymous) PKINIT authentication, a +client host must have filesystem access to a client certificate +(client.pem), and the corresponding private key (clientkey.pem). +Configure the following relations in the client host's +:ref:`krb5.conf(5)` file in the appropriate :ref:`realms` subsection +(with appropriate pathnames):: + + pkinit_identities = FILE:/etc/krb5/client.pem,/etc/krb5/clientkey.pem + +If the KDC and client are properly configured, it should now be +possible to run ``kinit username`` without entering a password. + + +.. _anonymous_pkinit: + +Anonymous PKINIT +---------------- + +Anonymity support in Kerberos allows a client to obtain a ticket +without authenticating as any particular principal. Such a ticket can +be used as a FAST armor ticket, or to securely communicate with an +application server anonymously. + +To configure anonymity support, you must generate or otherwise procure +a KDC certificate and configure the KDC host, but you do not need to +generate any client certificates. On the KDC, you must set the +**pkinit_identity** variable to provide the KDC certificate, but do +not need to set the **pkinit_anchors** variable or store the issuing +certificate if you won't have any client certificates to verify. On +client hosts, you must set the **pkinit_anchors** variable (and +possibly **pkinit_kdc_hostname** and **pkinit_eku_checking**) in order +to trust the issuing authority for the KDC certificate, but do not +need to set the **pkinit_identities** variable. + +Anonymity support is not enabled by default. To enable it, you must +create the principal ``WELLKNOWN/ANONYMOUS`` using the command:: + + kadmin -q 'addprinc -randkey WELLKNOWN/ANONYMOUS' + +Some Kerberos deployments include application servers which lack +proper access control, and grant some level of access to any user who +can authenticate. In such an environment, enabling anonymity support +on the KDC would present a security issue. If you need to enable +anonymity support for TGTs (for use as FAST armor tickets) without +enabling anonymous authentication to application servers, you can set +the variable **restrict_anonymous_to_tgt** to ``true`` in the +appropriate :ref:`kdc_realms` subsection of the KDC's +:ref:`kdc.conf(5)` file. + +To obtain anonymous credentials on a client, run ``kinit -n``, or +``kinit -n @REALMNAME`` to specify a realm. The resulting tickets +will have the client name ``WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS``. + + +Freshness tokens +---------------- + +Freshness tokens can ensure that the client has recently had access to +its certificate private key. If freshness tokens are not required by +the KDC, a client program with temporary possession of the private key +can compose requests for future timestamps and use them later. + +In release 1.17 and later, freshness tokens are supported by the +client and are sent by the KDC when the client indicates support for +them. Because not all clients support freshness tokens yet, they are +not required by default. To check if freshness tokens are supported +by a realm's clients, look in the KDC logs for the lines:: + + PKINIT: freshness token received from <client principal> + PKINIT: no freshness token received from <client principal> + +To require freshness tokens for all clients in a realm (except for +clients authenticating anonymously), set the +**pkinit_require_freshness** variable to ``true`` in the appropriate +:ref:`kdc_realms` subsection of the KDC's :ref:`kdc.conf(5)` file. To +test that this option is in effect, run ``kinit -X disable_freshness`` +and verify that authentication is unsuccessful. |