diff options
Diffstat (limited to 'crypto/krb5/doc/admin/pkinit.rst')
| -rw-r--r-- | crypto/krb5/doc/admin/pkinit.rst | 354 |
1 files changed, 0 insertions, 354 deletions
diff --git a/crypto/krb5/doc/admin/pkinit.rst b/crypto/krb5/doc/admin/pkinit.rst deleted file mode 100644 index 45817daca3a4..000000000000 --- a/crypto/krb5/doc/admin/pkinit.rst +++ /dev/null @@ -1,354 +0,0 @@ -.. _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 filesystems 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:2 - 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. |