diff options
Diffstat (limited to 'crypto/krb5/doc/html/_sources/admin/conf_files')
4 files changed, 0 insertions, 2442 deletions
diff --git a/crypto/krb5/doc/html/_sources/admin/conf_files/index.rst.txt b/crypto/krb5/doc/html/_sources/admin/conf_files/index.rst.txt deleted file mode 100644 index a04836ac742d..000000000000 --- a/crypto/krb5/doc/html/_sources/admin/conf_files/index.rst.txt +++ /dev/null @@ -1,20 +0,0 @@ -Configuration Files -=================== - -Kerberos uses configuration files to allow administrators to specify -settings on a per-machine basis. :ref:`krb5.conf(5)` applies to all -applications using the Kerboros library, on clients and servers. -For KDC-specific applications, additional settings can be specified in -:ref:`kdc.conf(5)`; the two files are merged into a configuration profile -used by applications accessing the KDC database directly. :ref:`kadm5.acl(5)` -is also only used on the KDC, it controls permissions for modifying the -KDC database. - -Contents --------- -.. toctree:: - :maxdepth: 1 - - krb5_conf - kdc_conf - kadm5_acl diff --git a/crypto/krb5/doc/html/_sources/admin/conf_files/kadm5_acl.rst.txt b/crypto/krb5/doc/html/_sources/admin/conf_files/kadm5_acl.rst.txt deleted file mode 100644 index 290bf0e037a7..000000000000 --- a/crypto/krb5/doc/html/_sources/admin/conf_files/kadm5_acl.rst.txt +++ /dev/null @@ -1,163 +0,0 @@ -.. _kadm5.acl(5): - -kadm5.acl -========= - -DESCRIPTION ------------ - -The Kerberos :ref:`kadmind(8)` daemon uses an Access Control List -(ACL) file to manage access rights to the Kerberos database. -For operations that affect principals, the ACL file also controls -which principals can operate on which other principals. - -The default location of the Kerberos ACL file is -|kdcdir|\ ``/kadm5.acl`` unless this is overridden by the *acl_file* -variable in :ref:`kdc.conf(5)`. - -SYNTAX ------- - -Empty lines and lines starting with the sharp sign (``#``) are -ignored. Lines containing ACL entries have the format:: - - principal permissions [target_principal [restrictions] ] - -.. note:: - - Line order in the ACL file is important. The first matching entry - will control access for an actor principal on a target principal. - -*principal* - (Partially or fully qualified Kerberos principal name.) Specifies - the principal whose permissions are to be set. - - Each component of the name may be wildcarded using the ``*`` - character. - -*permissions* - Specifies what operations may or may not be performed by a - *principal* matching a particular entry. This is a string of one or - more of the following list of characters or their upper-case - counterparts. If the character is *upper-case*, then the operation - is disallowed. If the character is *lower-case*, then the operation - is permitted. - - == ====================================================== - a [Dis]allows the addition of principals or policies - c [Dis]allows the changing of passwords for principals - d [Dis]allows the deletion of principals or policies - e [Dis]allows the extraction of principal keys - i [Dis]allows inquiries about principals or policies - l [Dis]allows the listing of all principals or policies - m [Dis]allows the modification of principals or policies - p [Dis]allows the propagation of the principal database (used in :ref:`incr_db_prop`) - s [Dis]allows the explicit setting of the key for a principal - x Short for admcilsp. All privileges (except ``e``) - \* Same as x. - == ====================================================== - -.. note:: - - The ``extract`` privilege is not included in the wildcard - privilege; it must be explicitly assigned. This privilege - allows the user to extract keys from the database, and must be - handled with great care to avoid disclosure of important keys - like those of the kadmin/* or krbtgt/* principals. The - **lockdown_keys** principal attribute can be used to prevent - key extraction from specific principals regardless of the - granted privilege. - -*target_principal* - (Optional. Partially or fully qualified Kerberos principal name.) - Specifies the principal on which *permissions* may be applied. - Each component of the name may be wildcarded using the ``*`` - character. - - *target_principal* can also include back-references to *principal*, - in which ``*number`` matches the corresponding wildcard in - *principal*. - -*restrictions* - (Optional) A string of flags. Allowed restrictions are: - - {+\|-}\ *flagname* - flag is forced to the indicated value. The permissible flags - are the same as those for the **default_principal_flags** - variable in :ref:`kdc.conf(5)`. - - *-clearpolicy* - policy is forced to be empty. - - *-policy pol* - policy is forced to be *pol*. - - -{*expire, pwexpire, maxlife, maxrenewlife*} *time* - (:ref:`getdate` string) associated value will be forced to - MIN(*time*, requested value). - - The above flags act as restrictions on any add or modify operation - which is allowed due to that ACL line. - -.. warning:: - - If the kadmind ACL file is modified, the kadmind daemon needs to be - restarted for changes to take effect. - -EXAMPLE -------- - -Here is an example of a kadm5.acl file:: - - */admin@ATHENA.MIT.EDU * # line 1 - joeadmin@ATHENA.MIT.EDU ADMCIL # line 2 - joeadmin/*@ATHENA.MIT.EDU i */root@ATHENA.MIT.EDU # line 3 - */root@ATHENA.MIT.EDU ci *1@ATHENA.MIT.EDU # line 4 - */root@ATHENA.MIT.EDU l * # line 5 - sms@ATHENA.MIT.EDU x * -maxlife 9h -postdateable # line 6 - -(line 1) Any principal in the ``ATHENA.MIT.EDU`` realm with an -``admin`` instance has all administrative privileges except extracting -keys. - -(lines 1-3) The user ``joeadmin`` has all permissions except -extracting keys with his ``admin`` instance, -``joeadmin/admin@ATHENA.MIT.EDU`` (matches line 1). He has no -permissions at all with his null instance, ``joeadmin@ATHENA.MIT.EDU`` -(matches line 2). His ``root`` and other non-``admin``, non-null -instances (e.g., ``extra`` or ``dbadmin``) have inquire permissions -with any principal that has the instance ``root`` (matches line 3). - -(line 4) Any ``root`` principal in ``ATHENA.MIT.EDU`` can inquire -or change the password of their null instance, but not any other -null instance. (Here, ``*1`` denotes a back-reference to the -component matching the first wildcard in the actor principal.) - -(line 5) Any ``root`` principal in ``ATHENA.MIT.EDU`` can generate -the list of principals in the database, and the list of policies -in the database. This line is separate from line 4, because list -permission can only be granted globally, not to specific target -principals. - -(line 6) Finally, the Service Management System principal -``sms@ATHENA.MIT.EDU`` has all permissions except extracting keys, but -any principal that it creates or modifies will not be able to get -postdateable tickets or tickets with a life of longer than 9 hours. - -MODULE BEHAVIOR ---------------- - -The ACL file can coexist with other authorization modules in release -1.16 and later, as configured in the :ref:`kadm5_auth` section of -:ref:`krb5.conf(5)`. The ACL file will positively authorize -operations according to the rules above, but will never -authoritatively deny an operation, so other modules can authorize -operations in addition to those authorized by the ACL file. - -To operate without an ACL file, set the *acl_file* variable in -:ref:`kdc.conf(5)` to the empty string with ``acl_file = ""``. - -SEE ALSO --------- - -:ref:`kdc.conf(5)`, :ref:`kadmind(8)` diff --git a/crypto/krb5/doc/html/_sources/admin/conf_files/kdc_conf.rst.txt b/crypto/krb5/doc/html/_sources/admin/conf_files/kdc_conf.rst.txt deleted file mode 100644 index 63bdb8d48c12..000000000000 --- a/crypto/krb5/doc/html/_sources/admin/conf_files/kdc_conf.rst.txt +++ /dev/null @@ -1,981 +0,0 @@ -.. _kdc.conf(5): - -kdc.conf -======== - -The kdc.conf file supplements :ref:`krb5.conf(5)` for programs which -are typically only used on a KDC, such as the :ref:`krb5kdc(8)` and -:ref:`kadmind(8)` daemons and the :ref:`kdb5_util(8)` program. -Relations documented here may also be specified in krb5.conf; for the -KDC programs mentioned, krb5.conf and kdc.conf will be merged into a -single configuration profile. - -Normally, the kdc.conf file is found in the KDC state directory, -|kdcdir|. You can override the default location by setting the -environment variable **KRB5_KDC_PROFILE**. - -Please note that you need to restart the KDC daemon for any configuration -changes to take effect. - -Structure ---------- - -The kdc.conf file is set up in the same format as the -:ref:`krb5.conf(5)` file. - - -Sections --------- - -The kdc.conf file may contain the following sections: - -==================== ================================================= -:ref:`kdcdefaults` Default values for KDC behavior -:ref:`kdc_realms` Realm-specific database configuration and settings -:ref:`dbdefaults` Default database settings -:ref:`dbmodules` Per-database settings -:ref:`logging` Controls how Kerberos daemons perform logging -==================== ================================================= - - -.. _kdcdefaults: - -[kdcdefaults] -~~~~~~~~~~~~~ - -Some relations in the [kdcdefaults] section specify default values for -realm variables, to be used if the [realms] subsection does not -contain a relation for the tag. See the :ref:`kdc_realms` section for -the definitions of these relations. - -* **host_based_services** -* **kdc_listen** -* **kdc_ports** -* **kdc_tcp_listen** -* **kdc_tcp_ports** -* **no_host_referral** -* **restrict_anonymous_to_tgt** - -The following [kdcdefaults] variables have no per-realm equivalent: - -**kdc_max_dgram_reply_size** - Specifies the maximum packet size that can be sent over UDP. The - default value is 4096 bytes. - -**kdc_tcp_listen_backlog** - (Integer.) Set the size of the listen queue length for the KDC - daemon. The value may be limited by OS settings. The default - value is 5. - -**spake_preauth_kdc_challenge** - (String.) Specifies the group for a SPAKE optimistic challenge. - See the **spake_preauth_groups** variable in :ref:`libdefaults` - for possible values. The default is not to issue an optimistic - challenge. (New in release 1.17.) - - -.. _kdc_realms: - -[realms] -~~~~~~~~ - -Each tag in the [realms] section is the name of a Kerberos realm. The -value of the tag is a subsection where the relations define KDC -parameters for that particular realm. The following example shows how -to define one parameter for the ATHENA.MIT.EDU realm:: - - [realms] - ATHENA.MIT.EDU = { - max_renewable_life = 7d 0h 0m 0s - } - -The following tags may be specified in a [realms] subsection: - -**acl_file** - (String.) Location of the access control list file that - :ref:`kadmind(8)` uses to determine which principals are allowed - which permissions on the Kerberos database. To operate without an - ACL file, set this relation to the empty string with ``acl_file = - ""``. The default value is |kdcdir|\ ``/kadm5.acl``. For more - information on Kerberos ACL file see :ref:`kadm5.acl(5)`. - -**database_module** - (String.) This relation indicates the name of the configuration - section under :ref:`dbmodules` for database-specific parameters - used by the loadable database library. The default value is the - realm name. If this configuration section does not exist, default - values will be used for all database parameters. - -**database_name** - (String, deprecated.) This relation specifies the location of the - Kerberos database for this realm, if the DB2 module is being used - and the :ref:`dbmodules` configuration section does not specify a - database name. The default value is |kdcdir|\ ``/principal``. - -**default_principal_expiration** - (:ref:`abstime` string.) Specifies the default expiration date of - principals created in this realm. The default value is 0, which - means no expiration date. - -**default_principal_flags** - (Flag string.) Specifies the default attributes of principals - created in this realm. The format for this string is a - comma-separated list of flags, with '+' before each flag that - should be enabled and '-' before each flag that should be - disabled. The **postdateable**, **forwardable**, **tgt-based**, - **renewable**, **proxiable**, **dup-skey**, **allow-tickets**, and - **service** flags default to enabled. - - There are a number of possible flags: - - **allow-tickets** - Enabling this flag means that the KDC will issue tickets for - this principal. Disabling this flag essentially deactivates - the principal within this realm. - - **dup-skey** - Enabling this flag allows the KDC to issue user-to-user - service tickets for this principal. - - **forwardable** - Enabling this flag allows the principal to obtain forwardable - tickets. - - **hwauth** - If this flag is enabled, then the principal is required to - preauthenticate using a hardware device before receiving any - tickets. - - **no-auth-data-required** - Enabling this flag prevents PAC or AD-SIGNEDPATH data from - being added to service tickets for the principal. - - **ok-as-delegate** - If this flag is enabled, it hints the client that credentials - can and should be delegated when authenticating to the - service. - - **ok-to-auth-as-delegate** - Enabling this flag allows the principal to use S4USelf tickets. - - **postdateable** - Enabling this flag allows the principal to obtain postdateable - tickets. - - **preauth** - If this flag is enabled on a client principal, then that - principal is required to preauthenticate to the KDC before - receiving any tickets. On a service principal, enabling this - flag means that service tickets for this principal will only - be issued to clients with a TGT that has the preauthenticated - bit set. - - **proxiable** - Enabling this flag allows the principal to obtain proxy - tickets. - - **pwchange** - Enabling this flag forces a password change for this - principal. - - **pwservice** - If this flag is enabled, it marks this principal as a password - change service. This should only be used in special cases, - for example, if a user's password has expired, then the user - has to get tickets for that principal without going through - the normal password authentication in order to be able to - change the password. - - **renewable** - Enabling this flag allows the principal to obtain renewable - tickets. - - **service** - Enabling this flag allows the the KDC to issue service tickets - for this principal. In release 1.17 and later, user-to-user - service tickets are still allowed if the **dup-skey** flag is - set. - - **tgt-based** - Enabling this flag allows a principal to obtain tickets based - on a ticket-granting-ticket, rather than repeating the - authentication process that was used to obtain the TGT. - -**dict_file** - (String.) Location of the dictionary file containing strings that - are not allowed as passwords. The file should contain one string - per line, with no additional whitespace. If none is specified or - if there is no policy assigned to the principal, no dictionary - checks of passwords will be performed. - -**disable_pac** - (Boolean value.) If true, the KDC will not issue PACs for this - realm, and S4U2Self and S4U2Proxy operations will be disabled. - The default is false, which will permit the KDC to issue PACs. - New in release 1.20. - -**encrypted_challenge_indicator** - (String.) Specifies the authentication indicator value that the KDC - asserts into tickets obtained using FAST encrypted challenge - pre-authentication. New in 1.16. - -**host_based_services** - (Whitespace- or comma-separated list.) Lists services which will - get host-based referral processing even if the server principal is - not marked as host-based by the client. - -**iprop_enable** - (Boolean value.) Specifies whether incremental database - propagation is enabled. The default value is false. - -**iprop_ulogsize** - (Integer.) Specifies the maximum number of log entries to be - retained for incremental propagation. The default value is 1000. - Prior to release 1.11, the maximum value was 2500. New in release - 1.19. - -**iprop_master_ulogsize** - The name for **iprop_ulogsize** prior to release 1.19. Its value is - used as a fallback if **iprop_ulogsize** is not specified. - -**iprop_replica_poll** - (Delta time string.) Specifies how often the replica KDC polls - for new updates from the primary. The default value is ``2m`` - (that is, two minutes). New in release 1.17. - -**iprop_slave_poll** - (Delta time string.) The name for **iprop_replica_poll** prior to - release 1.17. Its value is used as a fallback if - **iprop_replica_poll** is not specified. - -**iprop_listen** - (Whitespace- or comma-separated list.) Specifies the iprop RPC - listening addresses and/or ports for the :ref:`kadmind(8)` daemon. - Each entry may be an interface address, a port number, or an - address and port number separated by a colon. If the address - contains colons, enclose it in square brackets. If no address is - specified, the wildcard address is used. If kadmind fails to bind - to any of the specified addresses, it will fail to start. The - default (when **iprop_enable** is true) is to bind to the wildcard - address at the port specified in **iprop_port**. New in release - 1.15. - -**iprop_port** - (Port number.) Specifies the port number to be used for - incremental propagation. When **iprop_enable** is true, this - relation is required in the replica KDC configuration file, and - this relation or **iprop_listen** is required in the primary - configuration file, as there is no default port number. Port - numbers specified in **iprop_listen** entries will override this - port number for the :ref:`kadmind(8)` daemon. - -**iprop_resync_timeout** - (Delta time string.) Specifies the amount of time to wait for a - full propagation to complete. This is optional in configuration - files, and is used by replica KDCs only. The default value is 5 - minutes (``5m``). New in release 1.11. - -**iprop_logfile** - (File name.) Specifies where the update log file for the realm - database is to be stored. The default is to use the - **database_name** entry from the realms section of the krb5 config - file, with ``.ulog`` appended. (NOTE: If **database_name** isn't - specified in the realms section, perhaps because the LDAP database - back end is being used, or the file name is specified in the - [dbmodules] section, then the hard-coded default for - **database_name** is used. Determination of the **iprop_logfile** - default value will not use values from the [dbmodules] section.) - -**kadmind_listen** - (Whitespace- or comma-separated list.) Specifies the kadmin RPC - listening addresses and/or ports for the :ref:`kadmind(8)` daemon. - Each entry may be an interface address, a port number, an address - and port number separated by a colon, or a UNIX domain socket - pathname. If the address contains colons, enclose it in square - brackets. If no address is specified, the wildcard address is - used. To disable listening for kadmin RPC connections, set this - relation to the empty string with ``kadmind_listen = ""``. If - kadmind fails to bind to any of the specified addresses, it will - fail to start. The default is to bind to the wildcard address at - the port specified in **kadmind_port**, or the standard kadmin - port (749). New in release 1.15. - -**kadmind_port** - (Port number.) Specifies the port on which the :ref:`kadmind(8)` - daemon is to listen for this realm. Port numbers specified in - **kadmind_listen** entries will override this port number. The - assigned port for kadmind is 749, which is used by default. - -**key_stash_file** - (String.) Specifies the location where the master key has been - stored (via kdb5_util stash). The default is |kdcdir|\ - ``/.k5.REALM``, where *REALM* is the Kerberos realm. - -**kdc_listen** - (Whitespace- or comma-separated list.) Specifies the listening - addresses and/or ports for the :ref:`krb5kdc(8)` daemon. Each - entry may be an interface address, a port number, an address and - port number separated by a colon, or a UNIX domain socket - pathname. If the address contains colons, enclose it in square - brackets. If no address is specified, the wildcard address is - used. If no port is specified, the standard port (88) is used. - To disable listening on UDP, set this relation to the empty string - with ``kdc_listen = ""``. If the KDC daemon fails to bind to any - of the specified addresses, it will fail to start. The default is - to bind to the wildcard address on the standard port. New in - release 1.15. - -**kdc_ports** - (Whitespace- or comma-separated list, deprecated.) Prior to - release 1.15, this relation lists the ports for the - :ref:`krb5kdc(8)` daemon to listen on for UDP requests. In - release 1.15 and later, it has the same meaning as **kdc_listen** - if that relation is not defined. - -**kdc_tcp_listen** - (Whitespace- or comma-separated list.) Specifies the TCP - listening addresses and/or ports for the :ref:`krb5kdc(8)` daemon. - The syntax is identical to that of **kdc_listen**. To disable - listening on TCP, set this relation to the empty string with - ``kdc_tcp_listen = ""``. The default is to bind to the same - addresses and ports as for UDP. New in release 1.15. - -**kdc_tcp_ports** - (Whitespace- or comma-separated list, deprecated.) Prior to - release 1.15, this relation lists the ports for the - :ref:`krb5kdc(8)` daemon to listen on for UDP requests. In - release 1.15 and later, it has the same meaning as - **kdc_tcp_listen** if that relation is not defined. - -**kpasswd_listen** - (Comma-separated list.) Specifies the kpasswd listening - addresses and/or ports for the :ref:`kadmind(8)` daemon. Each - entry may be an interface address, a port number, an address and - port number separated by a colon, or a UNIX domain socket - pathname. If the address contains colons, enclose it in square - brackets. If no address is specified, the wildcard address is - used. To disable listening for kpasswd requests, set this - relation to the empty string with ``kpasswd_listen = ""``. If - kadmind fails to bind to any of the specified addresses, it will - fail to start. The default is to bind to the wildcard address at - the port specified in **kpasswd_port**, or the standard kpasswd - port (464). New in release 1.15. - -**kpasswd_port** - (Port number.) Specifies the port on which the :ref:`kadmind(8)` - daemon is to listen for password change requests for this realm. - Port numbers specified in **kpasswd_listen** entries will override - this port number. The assigned port for password change requests - is 464, which is used by default. - -**master_key_name** - (String.) Specifies the name of the principal associated with the - master key. The default is ``K/M``. - -**master_key_type** - (Key type string.) Specifies the master key's key type. The - default value for this is |defmkey|. For a list of all possible - values, see :ref:`Encryption_types`. - -**max_life** - (:ref:`duration` string.) Specifies the maximum time period for - which a ticket may be valid in this realm. The default value is - 24 hours. - -**max_renewable_life** - (:ref:`duration` string.) Specifies the maximum time period - during which a valid ticket may be renewed in this realm. - The default value is 0. - -**no_host_referral** - (Whitespace- or comma-separated list.) Lists services to block - from getting host-based referral processing, even if the client - marks the server principal as host-based or the service is also - listed in **host_based_services**. ``no_host_referral = *`` will - disable referral processing altogether. - -**reject_bad_transit** - (Boolean value.) If set to true, the KDC will check the list of - transited realms for cross-realm tickets against the transit path - computed from the realm names and the capaths section of its - :ref:`krb5.conf(5)` file; if the path in the ticket to be issued - contains any realms not in the computed path, the ticket will not - be issued, and an error will be returned to the client instead. - If this value is set to false, such tickets will be issued - anyways, and it will be left up to the application server to - validate the realm transit path. - - If the disable-transited-check flag is set in the incoming - request, this check is not performed at all. Having the - **reject_bad_transit** option will cause such ticket requests to - be rejected always. - - This transit path checking and config file option currently apply - only to TGS requests. - - The default value is true. - -**restrict_anonymous_to_tgt** - (Boolean value.) If set to true, the KDC will reject ticket - requests from anonymous principals to service principals other - than the realm's ticket-granting service. This option allows - anonymous PKINIT to be enabled for use as FAST armor tickets - without allowing anonymous authentication to services. The - default value is false. New in release 1.9. - -**spake_preauth_indicator** - (String.) Specifies an authentication indicator value that the - KDC asserts into tickets obtained using SPAKE pre-authentication. - The default is not to add any indicators. This option may be - specified multiple times. New in release 1.17. - -**supported_enctypes** - (List of *key*:*salt* strings.) Specifies the default key/salt - combinations of principals for this realm. Any principals created - through :ref:`kadmin(1)` will have keys of these types. The - default value for this tag is |defkeysalts|. For lists of - possible values, see :ref:`Keysalt_lists`. - - -.. _dbdefaults: - -[dbdefaults] -~~~~~~~~~~~~ - -The [dbdefaults] section specifies default values for some database -parameters, to be used if the [dbmodules] subsection does not contain -a relation for the tag. See the :ref:`dbmodules` section for the -definitions of these relations. - -* **ldap_kerberos_container_dn** -* **ldap_kdc_dn** -* **ldap_kdc_sasl_authcid** -* **ldap_kdc_sasl_authzid** -* **ldap_kdc_sasl_mech** -* **ldap_kdc_sasl_realm** -* **ldap_kadmind_dn** -* **ldap_kadmind_sasl_authcid** -* **ldap_kadmind_sasl_authzid** -* **ldap_kadmind_sasl_mech** -* **ldap_kadmind_sasl_realm** -* **ldap_service_password_file** -* **ldap_conns_per_server** - - -.. _dbmodules: - -[dbmodules] -~~~~~~~~~~~ - -The [dbmodules] section contains parameters used by the KDC database -library and database modules. Each tag in the [dbmodules] section is -the name of a Kerberos realm or a section name specified by a realm's -**database_module** parameter. The following example shows how to -define one database parameter for the ATHENA.MIT.EDU realm:: - - [dbmodules] - ATHENA.MIT.EDU = { - disable_last_success = true - } - -The following tags may be specified in a [dbmodules] subsection: - -**database_name** - This DB2-specific tag indicates the location of the database in - the filesystem. The default is |kdcdir|\ ``/principal``. - -**db_library** - This tag indicates the name of the loadable database module. The - value should be ``db2`` for the DB2 module, ``klmdb`` for the LMDB - module, or ``kldap`` for the LDAP module. - -**disable_last_success** - If set to ``true``, suppresses KDC updates to the "Last successful - authentication" field of principal entries requiring - preauthentication. Setting this flag may improve performance. - (Principal entries which do not require preauthentication never - update the "Last successful authentication" field.). First - introduced in release 1.9. - -**disable_lockout** - If set to ``true``, suppresses KDC updates to the "Last failed - authentication" and "Failed password attempts" fields of principal - entries requiring preauthentication. Setting this flag may - improve performance, but also disables account lockout. First - introduced in release 1.9. - -**ldap_conns_per_server** - This LDAP-specific tag indicates the number of connections to be - maintained per LDAP server. - -**ldap_kdc_dn** and **ldap_kadmind_dn** - These LDAP-specific tags indicate the default DN for binding to - the LDAP server. The :ref:`krb5kdc(8)` daemon uses - **ldap_kdc_dn**, while the :ref:`kadmind(8)` daemon and other - administrative programs use **ldap_kadmind_dn**. The kadmind DN - must have the rights to read and write the Kerberos data in the - LDAP database. The KDC DN must have the same rights, unless - **disable_lockout** and **disable_last_success** are true, in - which case it only needs to have rights to read the Kerberos data. - These tags are ignored if a SASL mechanism is set with - **ldap_kdc_sasl_mech** or **ldap_kadmind_sasl_mech**. - -**ldap_kdc_sasl_mech** and **ldap_kadmind_sasl_mech** - These LDAP-specific tags specify the SASL mechanism (such as - ``EXTERNAL``) to use when binding to the LDAP server. New in - release 1.13. - -**ldap_kdc_sasl_authcid** and **ldap_kadmind_sasl_authcid** - These LDAP-specific tags specify the SASL authentication identity - to use when binding to the LDAP server. Not all SASL mechanisms - require an authentication identity. If the SASL mechanism - requires a secret (such as the password for ``DIGEST-MD5``), these - tags also determine the name within the - **ldap_service_password_file** where the secret is stashed. New - in release 1.13. - -**ldap_kdc_sasl_authzid** and **ldap_kadmind_sasl_authzid** - These LDAP-specific tags specify the SASL authorization identity - to use when binding to the LDAP server. In most circumstances - they do not need to be specified. New in release 1.13. - -**ldap_kdc_sasl_realm** and **ldap_kadmind_sasl_realm** - These LDAP-specific tags specify the SASL realm to use when - binding to the LDAP server. In most circumstances they do not - need to be set. New in release 1.13. - -**ldap_kerberos_container_dn** - This LDAP-specific tag indicates the DN of the container object - where the realm objects will be located. - -**ldap_servers** - This LDAP-specific tag indicates the list of LDAP servers that the - Kerberos servers can connect to. The list of LDAP servers is - whitespace-separated. The LDAP server is specified by a LDAP URI. - It is recommended to use ``ldapi:`` or ``ldaps:`` URLs to connect - to the LDAP server. - -**ldap_service_password_file** - This LDAP-specific tag indicates the file containing the stashed - passwords (created by ``kdb5_ldap_util stashsrvpw``) for the - **ldap_kdc_dn** and **ldap_kadmind_dn** objects, or for the - **ldap_kdc_sasl_authcid** or **ldap_kadmind_sasl_authcid** names - for SASL authentication. This file must be kept secure. - -**mapsize** - This LMDB-specific tag indicates the maximum size of the two - database environments in megabytes. The default value is 128. - Increase this value to address "Environment mapsize limit reached" - errors. New in release 1.17. - -**max_readers** - This LMDB-specific tag indicates the maximum number of concurrent - reading processes for the databases. The default value is 128. - New in release 1.17. - -**nosync** - This LMDB-specific tag can be set to improve the throughput of - kadmind and other administrative agents, at the expense of - durability (recent database changes may not survive a power outage - or other sudden reboot). It does not affect the throughput of the - KDC. The default value is false. New in release 1.17. - -**unlockiter** - If set to ``true``, this DB2-specific tag causes iteration - operations to release the database lock while processing each - principal. Setting this flag to ``true`` can prevent extended - blocking of KDC or kadmin operations when dumps of large databases - are in progress. First introduced in release 1.13. - -The following tag may be specified directly in the [dbmodules] -section to control where database modules are loaded from: - -**db_module_dir** - This tag controls where the plugin system looks for database - modules. The value should be an absolute path. - -.. _logging: - -[logging] -~~~~~~~~~ - -The [logging] section indicates how :ref:`krb5kdc(8)` and -:ref:`kadmind(8)` perform logging. It may contain the following -relations: - -**admin_server** - Specifies how :ref:`kadmind(8)` performs logging. - -**kdc** - Specifies how :ref:`krb5kdc(8)` performs logging. - -**default** - Specifies how either daemon performs logging in the absence of - relations specific to the daemon. - -**debug** - (Boolean value.) Specifies whether debugging messages are - included in log outputs other than SYSLOG. Debugging messages are - always included in the system log output because syslog performs - its own priority filtering. The default value is false. New in - release 1.15. - -Logging specifications may have the following forms: - -**FILE=**\ *filename* or **FILE:**\ *filename* - This value causes the daemon's logging messages to go to the - *filename*. If the ``=`` form is used, the file is overwritten. - If the ``:`` form is used, the file is appended to. - -**STDERR** - This value causes the daemon's logging messages to go to its - standard error stream. - -**CONSOLE** - This value causes the daemon's logging messages to go to the - console, if the system supports it. - -**DEVICE=**\ *<devicename>* - This causes the daemon's logging messages to go to the specified - device. - -**SYSLOG**\ [\ **:**\ *severity*\ [\ **:**\ *facility*\ ]] - This causes the daemon's logging messages to go to the system log. - - For backward compatibility, a severity argument may be specified, - and must be specified in order to specify a facility. This - argument will be ignored. - - The facility argument specifies the facility under which the - messages are logged. This may be any of the following facilities - supported by the syslog(3) call minus the LOG\_ prefix: **KERN**, - **USER**, **MAIL**, **DAEMON**, **AUTH**, **LPR**, **NEWS**, - **UUCP**, **CRON**, and **LOCAL0** through **LOCAL7**. If no - facility is specified, the default is **AUTH**. - -In the following example, the logging messages from the KDC will go to -the console and to the system log under the facility LOG_DAEMON, and -the logging messages from the administrative server will be appended -to the file ``/var/adm/kadmin.log`` and sent to the device -``/dev/tty04``. :: - - [logging] - kdc = CONSOLE - kdc = SYSLOG:INFO:DAEMON - admin_server = FILE:/var/adm/kadmin.log - admin_server = DEVICE=/dev/tty04 - -If no logging specification is given, the default is to use syslog. -To disable logging entirely, specify ``default = DEVICE=/dev/null``. - - -.. _otp: - -[otp] -~~~~~ - -Each subsection of [otp] is the name of an OTP token type. The tags -within the subsection define the configuration required to forward a -One Time Password request to a RADIUS server. - -For each token type, the following tags may be specified: - -**server** - This is the server to send the RADIUS request to. It can be a - hostname with optional port, an ip address with optional port, or - a Unix domain socket address. The default is - |kdcdir|\ ``/<name>.socket``. - -**secret** - This tag indicates a filename (which may be relative to |kdcdir|) - containing the secret used to encrypt the RADIUS packets. The - secret should appear in the first line of the file by itself; - leading and trailing whitespace on the line will be removed. If - the value of **server** is a Unix domain socket address, this tag - is optional, and an empty secret will be used if it is not - specified. Otherwise, this tag is required. - -**timeout** - An integer which specifies the time in seconds during which the - KDC should attempt to contact the RADIUS server. This tag is the - total time across all retries and should be less than the time - which an OTP value remains valid for. The default is 5 seconds. - -**retries** - This tag specifies the number of retries to make to the RADIUS - server. The default is 3 retries (4 tries). - -**strip_realm** - If this tag is ``true``, the principal without the realm will be - passed to the RADIUS server. Otherwise, the realm will be - included. The default value is ``true``. - -**indicator** - This tag specifies an authentication indicator to be included in - the ticket if this token type is used to authenticate. This - option may be specified multiple times. (New in release 1.14.) - -In the following example, requests are sent to a remote server via UDP:: - - [otp] - MyRemoteTokenType = { - server = radius.mydomain.com:1812 - secret = SEmfiajf42$ - timeout = 15 - retries = 5 - strip_realm = true - } - -An implicit default token type named ``DEFAULT`` is defined for when -the per-principal configuration does not specify a token type. Its -configuration is shown below. You may override this token type to -something applicable for your situation:: - - [otp] - DEFAULT = { - strip_realm = false - } - -PKINIT options --------------- - -.. note:: - - The following are pkinit-specific options. These values may - be specified in [kdcdefaults] as global defaults, or within - a realm-specific subsection of [realms]. Also note that a - realm-specific value over-rides, does not add to, a generic - [kdcdefaults] specification. The search order is: - -1. realm-specific subsection of [realms]:: - - [realms] - EXAMPLE.COM = { - pkinit_anchors = FILE:/usr/local/example.com.crt - } - -2. generic value in the [kdcdefaults] section:: - - [kdcdefaults] - pkinit_anchors = DIR:/usr/local/generic_trusted_cas/ - -For information about the syntax of some of these options, see -:ref:`Specifying PKINIT identity information <pkinit_identity>` in -:ref:`krb5.conf(5)`. - -**pkinit_anchors** - Specifies the location of trusted anchor (root) certificates which - the KDC trusts to sign client certificates. This option is - required if pkinit is to be supported by the KDC. This option may - be specified multiple times. - -**pkinit_dh_min_bits** - Specifies the minimum strength of Diffie-Hellman group the KDC is - willing to accept for key exchange. Valid values in order of - increasing strength are 1024, 2048, P-256, 4096, P-384, and P-521. - The default is 2048. (P-256, P-384, and P-521 are new in release - 1.22.) - -**pkinit_allow_upn** - Specifies that the KDC is willing to accept client certificates - with the Microsoft UserPrincipalName (UPN) Subject Alternative - Name (SAN). This means the KDC accepts the binding of the UPN in - the certificate to the Kerberos principal name. The default value - is false. - - Without this option, the KDC will only accept certificates with - the id-pkinit-san as defined in :rfc:`4556`. There is currently - no option to disable SAN checking in the KDC. - -**pkinit_eku_checking** - This option specifies what Extended Key Usage (EKU) values the KDC - is willing to accept in client certificates. The values - recognized in the kdc.conf file are: - - **kpClientAuth** - This is the default value and specifies that client - certificates must have the id-pkinit-KPClientAuth EKU as - defined in :rfc:`4556`. - - **scLogin** - If scLogin is specified, client certificates with the - Microsoft Smart Card Login EKU (id-ms-kp-sc-logon) will be - accepted. - - **none** - If none is specified, then client certificates will not be - checked to verify they have an acceptable EKU. The use of - this option is not recommended. - -**pkinit_identity** - Specifies the location of the KDC's X.509 identity information. - This option is required if pkinit is to be supported by the KDC. - -**pkinit_indicator** - Specifies an authentication indicator to include in the ticket if - pkinit is used to authenticate. This option may be specified - multiple times. (New in release 1.14.) - -**pkinit_pool** - Specifies the location of intermediate certificates which may be - used by the KDC to complete the trust chain between a client's - certificate and a trusted anchor. This option may be specified - multiple times. - -**pkinit_revoke** - Specifies the location of Certificate Revocation List (CRL) - information to be used by the KDC when verifying the validity of - client certificates. This option may be specified multiple times. - -**pkinit_require_crl_checking** - The default certificate verification process will always check the - available revocation information to see if a certificate has been - revoked. If a match is found for the certificate in a CRL, - verification fails. If the certificate being verified is not - listed in a CRL, or there is no CRL present for its issuing CA, - and **pkinit_require_crl_checking** is false, then verification - succeeds. - - However, if **pkinit_require_crl_checking** is true and there is - no CRL information available for the issuing CA, then verification - fails. - - **pkinit_require_crl_checking** should be set to true if the - policy is such that up-to-date CRLs must be present for every CA. - -**pkinit_require_freshness** - Specifies whether to require clients to include a freshness token - in PKINIT requests. The default value is false. (New in release - 1.17.) - -.. _Encryption_types: - -Encryption types ----------------- - -Any tag in the configuration files which requires a list of encryption -types can be set to some combination of the following strings. -Encryption types marked as "weak" and "deprecated" are available for -compatibility but not recommended for use. - -==================================================== ========================================================= -des3-cbc-raw Triple DES cbc mode raw (weak) -des3-cbc-sha1 des3-hmac-sha1 des3-cbc-sha1-kd Triple DES cbc mode with HMAC/sha1 (deprecated) -aes256-cts-hmac-sha1-96 aes256-cts aes256-sha1 AES-256 CTS mode with 96-bit SHA-1 HMAC -aes128-cts-hmac-sha1-96 aes128-cts aes128-sha1 AES-128 CTS mode with 96-bit SHA-1 HMAC -aes256-cts-hmac-sha384-192 aes256-sha2 AES-256 CTS mode with 192-bit SHA-384 HMAC -aes128-cts-hmac-sha256-128 aes128-sha2 AES-128 CTS mode with 128-bit SHA-256 HMAC -arcfour-hmac rc4-hmac arcfour-hmac-md5 RC4 with HMAC/MD5 (deprecated) -arcfour-hmac-exp rc4-hmac-exp arcfour-hmac-md5-exp Exportable RC4 with HMAC/MD5 (weak) -camellia256-cts-cmac camellia256-cts Camellia-256 CTS mode with CMAC -camellia128-cts-cmac camellia128-cts Camellia-128 CTS mode with CMAC -des3 The triple DES family: des3-cbc-sha1 -aes The AES family: aes256-cts-hmac-sha1-96, aes128-cts-hmac-sha1-96, aes256-cts-hmac-sha384-192, and aes128-cts-hmac-sha256-128 -rc4 The RC4 family: arcfour-hmac -camellia The Camellia family: camellia256-cts-cmac and camellia128-cts-cmac -==================================================== ========================================================= - -The string **DEFAULT** can be used to refer to the default set of -types for the variable in question. Types or families can be removed -from the current list by prefixing them with a minus sign ("-"). -Types or families can be prefixed with a plus sign ("+") for symmetry; -it has the same meaning as just listing the type or family. For -example, "``DEFAULT -rc4``" would be the default set of encryption -types with RC4 types removed, and "``des3 DEFAULT``" would be the -default set of encryption types with triple DES types moved to the -front. - -While **aes128-cts** and **aes256-cts** are supported for all Kerberos -operations, they are not supported by very old versions of our GSSAPI -implementation (krb5-1.3.1 and earlier). Services running versions of -krb5 without AES support must not be given keys of these encryption -types in the KDC database. - -The **aes128-sha2** and **aes256-sha2** encryption types are new in -release 1.15. Services running versions of krb5 without support for -these newer encryption types must not be given keys of these -encryption types in the KDC database. - - -.. _Keysalt_lists: - -Keysalt lists -------------- - -Kerberos keys for users are usually derived from passwords. Kerberos -commands and configuration parameters that affect generation of keys -take lists of enctype-salttype ("keysalt") pairs, known as *keysalt -lists*. Each keysalt pair is an enctype name followed by a salttype -name, in the format *enc*:*salt*. Individual keysalt list members are -separated by comma (",") characters or space characters. For example:: - - kadmin -e aes256-cts:normal,aes128-cts:normal - -would start up kadmin so that by default it would generate -password-derived keys for the **aes256-cts** and **aes128-cts** -encryption types, using a **normal** salt. - -To ensure that people who happen to pick the same password do not have -the same key, Kerberos 5 incorporates more information into the key -using something called a salt. The supported salt types are as -follows: - -================= ============================================ -normal default for Kerberos Version 5 -norealm same as the default, without using realm information -onlyrealm uses only realm information as the salt -special generate a random salt -================= ============================================ - - -Sample kdc.conf File --------------------- - -Here's an example of a kdc.conf file:: - - [kdcdefaults] - kdc_listen = 88 - kdc_tcp_listen = 88 - [realms] - ATHENA.MIT.EDU = { - kadmind_port = 749 - max_life = 12h 0m 0s - max_renewable_life = 7d 0h 0m 0s - master_key_type = aes256-cts-hmac-sha1-96 - supported_enctypes = aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal - database_module = openldap_ldapconf - } - - [logging] - kdc = FILE:/usr/local/var/krb5kdc/kdc.log - admin_server = FILE:/usr/local/var/krb5kdc/kadmin.log - - [dbdefaults] - ldap_kerberos_container_dn = cn=krbcontainer,dc=mit,dc=edu - - [dbmodules] - openldap_ldapconf = { - db_library = kldap - disable_last_success = true - ldap_kdc_dn = "cn=krbadmin,dc=mit,dc=edu" - # this object needs to have read rights on - # the realm container and principal subtrees - ldap_kadmind_dn = "cn=krbadmin,dc=mit,dc=edu" - # this object needs to have read and write rights on - # the realm container and principal subtrees - ldap_service_password_file = /etc/kerberos/service.keyfile - ldap_servers = ldaps://kerberos.mit.edu - ldap_conns_per_server = 5 - } - - -FILES ------- - -|kdcdir|\ ``/kdc.conf`` - - -SEE ALSO ---------- - -:ref:`krb5.conf(5)`, :ref:`krb5kdc(8)`, :ref:`kadm5.acl(5)` diff --git a/crypto/krb5/doc/html/_sources/admin/conf_files/krb5_conf.rst.txt b/crypto/krb5/doc/html/_sources/admin/conf_files/krb5_conf.rst.txt deleted file mode 100644 index e0c7a633094e..000000000000 --- a/crypto/krb5/doc/html/_sources/admin/conf_files/krb5_conf.rst.txt +++ /dev/null @@ -1,1278 +0,0 @@ -.. _krb5.conf(5): - -krb5.conf -========= - -The krb5.conf file contains Kerberos configuration information, -including the locations of KDCs and admin servers for the Kerberos -realms of interest, defaults for the current realm and for Kerberos -applications, and mappings of hostnames onto Kerberos realms. -Normally, you should install your krb5.conf file in the directory -``/etc``. You can override the default location by setting the -environment variable **KRB5_CONFIG**. Multiple colon-separated -filenames may be specified in **KRB5_CONFIG**; all files which are -present will be read. Starting in release 1.14, directory names can -also be specified in **KRB5_CONFIG**; all files within the directory -whose names consist solely of alphanumeric characters, dashes, or -underscores will be read. - - -Structure ---------- - -The krb5.conf file is set up in the style of a Windows INI file. -Lines beginning with '#' or ';' (possibly after initial whitespace) -are ignored as comments. Sections are headed by the section name, in -square brackets. Each section may contain zero or more relations, of -the form:: - - foo = bar - -or:: - - fubar = { - foo = bar - baz = quux - } - -The krb5.conf file can include other files using either of the -following directives at the beginning of a line:: - - include FILENAME - includedir DIRNAME - -*FILENAME* or *DIRNAME* should be an absolute path. The named file or -directory must exist and be readable. Including a directory includes -all files within the directory whose names consist solely of -alphanumeric characters, dashes, or underscores. Starting in release -1.15, files with names ending in ".conf" are also included, unless the -name begins with ".". Included profile files are syntactically -independent of their parents, so each included file must begin with a -section header. Starting in release 1.17, files are read in -alphanumeric order; in previous releases, they may be read in any -order. - -Placing a '\*' after the closing bracket of a section name indicates -that the section is *final*, meaning that if the same section appears -again later, it will be ignored. A subsection can be marked as final -by placing a '\*' after either the tag name or the closing brace. A -relation can be marked as final by placing a '\*' after the tag name. -Prior to release 1.22, only sections and subsections can be marked as -final, and the flag only causes values to be ignored if they appear in -later files specified in **KRB5_CONFIG**, not if they appear later -within the same file or an included file. - -The krb5.conf file can specify that configuration should be obtained -from a loadable module, rather than the file itself, using the -following directive at the beginning of a line before any section -headers:: - - module MODULEPATH:RESIDUAL - -*MODULEPATH* may be relative to the library path of the krb5 -installation, or it may be an absolute path. *RESIDUAL* is provided -to the module at initialization time. If krb5.conf uses a module -directive, :ref:`kdc.conf(5)` should also use one if it exists. - - -Sections --------- - -The krb5.conf file may contain the following sections: - -=================== ======================================================= -:ref:`libdefaults` Settings used by the Kerberos V5 library -:ref:`realms` Realm-specific contact information and settings -:ref:`domain_realm` Maps server hostnames to Kerberos realms -:ref:`capaths` Authentication paths for non-hierarchical cross-realm -:ref:`appdefaults` Settings used by some Kerberos V5 applications -:ref:`plugins` Controls plugin module registration -=================== ======================================================= - -Additionally, krb5.conf may include any of the relations described in -:ref:`kdc.conf(5)`, but it is not a recommended practice. - -.. _libdefaults: - -[libdefaults] -~~~~~~~~~~~~~ - -The libdefaults section may contain any of the following relations: - -**allow_des3** - Permit the KDC to issue tickets with des3-cbc-sha1 session keys. - In future releases, this flag will allow des3-cbc-sha1 to be used - at all. The default value for this tag is false. (Added in - release 1.21.) - -**allow_rc4** - Permit the KDC to issue tickets with arcfour-hmac session keys. - In future releases, this flag will allow arcfour-hmac to be used - at all. The default value for this tag is false. (Added in - release 1.21.) - -**allow_weak_crypto** - If this flag is set to false, then weak encryption types (as noted - in :ref:`Encryption_types` in :ref:`kdc.conf(5)`) will be filtered - out of the lists **default_tgs_enctypes**, - **default_tkt_enctypes**, and **permitted_enctypes**. The default - value for this tag is false. - -**canonicalize** - If this flag is set to true, initial ticket requests to the KDC - will request canonicalization of the client principal name, and - answers with different client principals than the requested - principal will be accepted. The default value is false. - -**ccache_type** - This parameter determines the format of credential cache types - created by :ref:`kinit(1)` or other programs. The default value - is 4, which represents the most current format. Smaller values - can be used for compatibility with very old implementations of - Kerberos which interact with credential caches on the same host. - -**clockskew** - Sets the maximum allowable amount of clockskew in seconds that the - library will tolerate before assuming that a Kerberos message is - invalid. The default value is 300 seconds, or five minutes. - - The clockskew setting is also used when evaluating ticket start - and expiration times. For example, tickets that have reached - their expiration time can still be used (and renewed if they are - renewable tickets) if they have been expired for a shorter - duration than the **clockskew** setting. - -**default_ccache_name** - This relation specifies the name of the default credential cache. - The default is |ccache|. This relation is subject to parameter - expansion (see below). New in release 1.11. - -**default_client_keytab_name** - This relation specifies the name of the default keytab for - obtaining client credentials. The default is |ckeytab|. This - relation is subject to parameter expansion (see below). - New in release 1.11. - -**default_keytab_name** - This relation specifies the default keytab name to be used by - application servers such as sshd. The default is |keytab|. This - relation is subject to parameter expansion (see below). - -**default_rcache_name** - This relation specifies the name of the default replay cache. - The default is ``dfl:``. This relation is subject to parameter - expansion (see below). New in release 1.18. - -**default_realm** - Identifies the default Kerberos realm for the client. Set its - value to your Kerberos realm. If this value is not set, then a - realm must be specified with every Kerberos principal when - invoking programs such as :ref:`kinit(1)`. - -**default_tgs_enctypes** - Identifies the supported list of session key encryption types that - the client should request when making a TGS-REQ, in order of - preference from highest to lowest. The list may be delimited with - commas or whitespace. See :ref:`Encryption_types` in - :ref:`kdc.conf(5)` for a list of the accepted values for this tag. - Starting in release 1.18, the default value is the value of - **permitted_enctypes**. For previous releases or if - **permitted_enctypes** is not set, the default value is - |defetypes|. - - Do not set this unless required for specific backward - compatibility purposes; stale values of this setting can prevent - clients from taking advantage of new stronger enctypes when the - libraries are upgraded. - -**default_tkt_enctypes** - Identifies the supported list of session key encryption types that - the client should request when making an AS-REQ, in order of - preference from highest to lowest. The format is the same as for - default_tgs_enctypes. Starting in release 1.18, the default - value is the value of **permitted_enctypes**. For previous - releases or if **permitted_enctypes** is not set, the default - value is |defetypes|. - - Do not set this unless required for specific backward - compatibility purposes; stale values of this setting can prevent - clients from taking advantage of new stronger enctypes when the - libraries are upgraded. - -**dns_canonicalize_hostname** - Indicate whether name lookups will be used to canonicalize - hostnames for use in service principal names. Setting this flag - to false can improve security by reducing reliance on DNS, but - means that short hostnames will not be canonicalized to - fully-qualified hostnames. If this option is set to ``fallback`` (new - in release 1.18), DNS canonicalization will only be performed the - server hostname is not found with the original name when - requesting credentials. The default value is true. - -**dns_lookup_kdc** - Indicate whether DNS SRV records should be used to locate the KDCs - and other servers for a realm, if they are not listed in the - krb5.conf information for the realm. (Note that the admin_server - entry must be in the krb5.conf realm information in order to - contact kadmind, because the DNS implementation for kadmin is - incomplete.) - - Enabling this option does open up a type of denial-of-service - attack, if someone spoofs the DNS records and redirects you to - another server. However, it's no worse than a denial of service, - because that fake KDC will be unable to decode anything you send - it (besides the initial ticket request, which has no encrypted - data), and anything the fake KDC sends will not be trusted without - verification using some secret that it won't know. - -**dns_lookup_realm** - Indicate whether DNS TXT records should be used to map hostnames - to realm names for hostnames not listed in the [domain_realm] - section, and to determine the default realm if **default_realm** - is not set. The default value is false. - -**dns_uri_lookup** - Indicate whether DNS URI records should be used to locate the KDCs - and other servers for a realm, if they are not listed in the - krb5.conf information for the realm. SRV records are used as a - fallback if no URI records were found. The default value is true. - New in release 1.15. - -**enforce_ok_as_delegate** - If this flag to true, GSSAPI credential delegation will be - disabled when the ``ok-as-delegate`` flag is not set in the - service ticket. If this flag is false, the ``ok-as-delegate`` - ticket flag is only enforced when an application specifically - requests enforcement. The default value is false. - -**err_fmt** - This relation allows for custom error message formatting. If a - value is set, error messages will be formatted by substituting a - normal error message for %M and an error code for %C in the value. - -**extra_addresses** - This allows a computer to use multiple local addresses, in order - to allow Kerberos to work in a network that uses NATs while still - using address-restricted tickets. The addresses should be in a - comma-separated list. This option has no effect if - **noaddresses** is true. - -**forwardable** - If this flag is true, initial tickets will be forwardable by - default, if allowed by the KDC. The default value is false. - -**ignore_acceptor_hostname** - When accepting GSSAPI or krb5 security contexts for host-based - service principals, ignore any hostname passed by the calling - application, and allow clients to authenticate to any service - principal in the keytab matching the service name and realm name - (if given). This option can improve the administrative - flexibility of server applications on multihomed hosts, but could - compromise the security of virtual hosting environments. The - default value is false. New in release 1.10. - -**k5login_authoritative** - If this flag is true, principals must be listed in a local user's - k5login file to be granted login access, if a :ref:`.k5login(5)` - file exists. If this flag is false, a principal may still be - granted login access through other mechanisms even if a k5login - file exists but does not list the principal. The default value is - true. - -**k5login_directory** - If set, the library will look for a local user's k5login file - within the named directory, with a filename corresponding to the - local username. If not set, the library will look for k5login - files in the user's home directory, with the filename .k5login. - For security reasons, .k5login files must be owned by - the local user or by root. - -**kcm_mach_service** - On macOS only, determines the name of the bootstrap service used to - contact the KCM daemon for the KCM credential cache type. If the - value is ``-``, Mach RPC will not be used to contact the KCM - daemon. The default value is ``org.h5l.kcm``. - -**kcm_socket** - Determines the path to the Unix domain socket used to access the - KCM daemon for the KCM credential cache type. If the value is - ``-``, Unix domain sockets will not be used to contact the KCM - daemon. The default value is - ``/var/run/.heim_org.h5l.kcm-socket``. - -**kdc_default_options** - Default KDC options (Xored for multiple values) when requesting - initial tickets. By default it is set to 0x00000010 - (KDC_OPT_RENEWABLE_OK). - -**kdc_timesync** - Accepted values for this relation are 1 or 0. If it is nonzero, - client machines will compute the difference between their time and - the time returned by the KDC in the timestamps in the tickets and - use this value to correct for an inaccurate system clock when - requesting service tickets or authenticating to services. This - corrective factor is only used by the Kerberos library; it is not - used to change the system clock. The default value is 1. - -**noaddresses** - If this flag is true, requests for initial tickets will not be - made with address restrictions set, allowing the tickets to be - used across NATs. The default value is true. - -**permitted_enctypes** - Identifies the encryption types that servers will permit for - session keys and for ticket and authenticator encryption, ordered - by preference from highest to lowest. Starting in release 1.18, - this tag also acts as the default value for - **default_tgs_enctypes** and **default_tkt_enctypes**. The - default value for this tag is |defetypes|. - -**plugin_base_dir** - If set, determines the base directory where krb5 plugins are - located. The default value is the ``krb5/plugins`` subdirectory - of the krb5 library directory. This relation is subject to - parameter expansion (see below) in release 1.17 and later. - -**preferred_preauth_types** - This allows you to set the preferred preauthentication types which - the client will attempt before others which may be advertised by a - KDC. The default value for this setting is "17, 16, 15, 14", - which forces libkrb5 to attempt to use PKINIT if it is supported. - -**proxiable** - If this flag is true, initial tickets will be proxiable by - default, if allowed by the KDC. The default value is false. - -**qualify_shortname** - If this string is set, it determines the domain suffix for - single-component hostnames when DNS canonicalization is not used - (either because **dns_canonicalize_hostname** is false or because - forward canonicalization failed). The default value is the first - search domain of the system's DNS configuration. To disable - qualification of shortnames, set this relation to the empty string - with ``qualify_shortname = ""``. (New in release 1.18.) - -**rdns** - If this flag is true, reverse name lookup will be used in addition - to forward name lookup to canonicalizing hostnames for use in - service principal names. If **dns_canonicalize_hostname** is set - to false, this flag has no effect. The default value is true. - -**realm_try_domains** - Indicate whether a host's domain components should be used to - determine the Kerberos realm of the host. The value of this - variable is an integer: -1 means not to search, 0 means to try the - host's domain itself, 1 means to also try the domain's immediate - parent, and so forth. The library's usual mechanism for locating - Kerberos realms is used to determine whether a domain is a valid - realm, which may involve consulting DNS if **dns_lookup_kdc** is - set. The default is not to search domain components. - -**renew_lifetime** - (:ref:`duration` string.) Sets the default renewable lifetime - for initial ticket requests. The default value is 0. - -**request_timeout** - (:ref:`duration` string.) Sets the maximum total time for KDC and - password change requests. This timeout does not affect the - intervals between requests, so setting a low timeout may result in - fewer requests being attempted and/or some servers not being - contacted. A value of 0 indicates no specific maximum, in which - case requests will time out if no server responds after several - tries. The default value is 0. (New in release 1.22.) - -**spake_preauth_groups** - A whitespace or comma-separated list of words which specifies the - groups allowed for SPAKE preauthentication. The possible values - are: - - ============ ================================ - edwards25519 Edwards25519 curve (:rfc:`7748`) - P-256 NIST P-256 curve (:rfc:`5480`) - P-384 NIST P-384 curve (:rfc:`5480`) - P-521 NIST P-521 curve (:rfc:`5480`) - ============ ================================ - - The default value for the client is ``edwards25519``. The default - value for the KDC is empty. New in release 1.17. - -**ticket_lifetime** - (:ref:`duration` string.) Sets the default lifetime for initial - ticket requests. The default value is 1 day. - -**udp_preference_limit** - When sending a message to the KDC, the library will try using TCP - before UDP if the size of the message is above - **udp_preference_limit**. If the message is smaller than - **udp_preference_limit**, then UDP will be tried before TCP. - Regardless of the size, both protocols will be tried if the first - attempt fails. - -**verify_ap_req_nofail** - If this flag is true, then an attempt to verify initial - credentials will fail if the client machine does not have a - keytab. The default value is false. - -**client_aware_channel_bindings** - If this flag is true, then all application protocol authentication - requests will be flagged to indicate that the application supports - channel bindings when operating over a secure channel. The - default value is false. - -.. _realms: - -[realms] -~~~~~~~~ - -Each tag in the [realms] section of the file is the name of a Kerberos -realm. The value of the tag is a subsection with relations that -define the properties of that particular realm. For each realm, the -following tags may be specified in the realm's subsection: - -**admin_server** - Identifies the host where the administration server is running. - Typically, this is the primary Kerberos server. This tag must be - given a value in order to communicate with the :ref:`kadmind(8)` - server for the realm. - -**auth_to_local** - This tag allows you to set a general rule for mapping principal - names to local user names. It will be used if there is not an - explicit mapping for the principal name that is being - translated. The possible values are: - - **RULE:**\ *exp* - The local name will be formulated from *exp*. - - The format for *exp* is **[**\ *n*\ **:**\ *string*\ **](**\ - *regexp*\ **)s/**\ *pattern*\ **/**\ *replacement*\ **/g**. - The integer *n* indicates how many components the target - principal should have. If this matches, then a string will be - formed from *string*, substituting the realm of the principal - for ``$0`` and the *n*'th component of the principal for - ``$n`` (e.g., if the principal was ``johndoe/admin`` then - ``[2:$2$1foo]`` would result in the string - ``adminjohndoefoo``). If this string matches *regexp*, then - the ``s//[g]`` substitution command will be run over the - string. The optional **g** will cause the substitution to be - global over the *string*, instead of replacing only the first - match in the *string*. - - **DEFAULT** - The principal name will be used as the local user name. If - the principal has more than one component or is not in the - default realm, this rule is not applicable and the conversion - will fail. - - For example:: - - [realms] - ATHENA.MIT.EDU = { - auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/ - auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$// - auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/ - auth_to_local = DEFAULT - } - - would result in any principal without ``root`` or ``admin`` as the - second component to be translated with the default rule. A - principal with a second component of ``admin`` will become its - first component. ``root`` will be used as the local name for any - principal with a second component of ``root``. The exception to - these two rules are any principals ``johndoe/*``, which will - always get the local name ``guest``. - -**auth_to_local_names** - This subsection allows you to set explicit mappings from principal - names to local user names. The tag is the mapping name, and the - value is the corresponding local user name. - -**default_domain** - This tag specifies the domain used to expand hostnames when - translating Kerberos 4 service principals to Kerberos 5 principals - (for example, when converting ``rcmd.hostname`` to - ``host/hostname.domain``). - -**disable_encrypted_timestamp** - If this flag is true, the client will not perform encrypted - timestamp preauthentication if requested by the KDC. Setting this - flag can help to prevent dictionary attacks by active attackers, - if the realm's KDCs support SPAKE preauthentication or if initial - authentication always uses another mechanism or always uses FAST. - This flag persists across client referrals during initial - authentication. This flag does not prevent the KDC from offering - encrypted timestamp. New in release 1.17. - -**http_anchors** - When KDCs and kpasswd servers are accessed through HTTPS proxies, this tag - can be used to specify the location of the CA certificate which should be - trusted to issue the certificate for a proxy server. If left unspecified, - the system-wide default set of CA certificates is used. - - The syntax for values is similar to that of values for the - **pkinit_anchors** tag: - - **FILE:** *filename* - - *filename* is assumed to be the name of an OpenSSL-style ca-bundle file. - - **DIR:** *dirname* - - *dirname* is assumed to be an directory which contains CA certificates. - All files in the directory will be examined; if they contain certificates - (in PEM format), they will be used. - - **ENV:** *envvar* - - *envvar* specifies the name of an environment variable which has been set - to a value conforming to one of the previous values. For example, - ``ENV:X509_PROXY_CA``, where environment variable ``X509_PROXY_CA`` has - been set to ``FILE:/tmp/my_proxy.pem``. - -**kdc** - The name or address of a host running a KDC for the realm, or a - UNIX domain socket path of a locally running KDC. An optional - port number, separated from the hostname by a colon, may be - included. If the name or address contains colons (for example, if - it is an IPv6 address), enclose it in square brackets to - distinguish the colon from a port separator. For your computer to - be able to communicate with the KDC for each realm, this tag must - be given a value in each realm subsection in the configuration - file, or there must be DNS SRV records specifying the KDCs. - -**kpasswd_server** - The location of the password change server for the realm, using - the same syntax as **kdc**. If there is no such entry, DNS will - be queried (unless forbidden by **dns_lookup_kdc**). Finally, - port 464 on the **admin_server** host will be tried. - -**master_kdc** - The name for **primary_kdc** prior to release 1.19. Its value is - used as a fallback if **primary_kdc** is not specified. - -**primary_kdc** - Identifies the primary KDC(s). Currently, this tag is used in only - one case: If an attempt to get credentials fails because of an - invalid password, the client software will attempt to contact the - primary KDC, in case the user's password has just been changed, and - the updated database has not been propagated to the replica - servers yet. New in release 1.19. - -**sitename** - Specifies the name of the host's site for the purpose of DNS-based - KDC discovery for this realm. New in release 1.22. - -**v4_instance_convert** - This subsection allows the administrator to configure exceptions - to the **default_domain** mapping rule. It contains V4 instances - (the tag name) which should be translated to some specific - hostname (the tag value) as the second component in a Kerberos V5 - principal name. - -**v4_realm** - This relation is used by the krb524 library routines when - converting a V5 principal name to a V4 principal name. It is used - when the V4 realm name and the V5 realm name are not the same, but - still share the same principal names and passwords. The tag value - is the Kerberos V4 realm name. - - -.. _domain_realm: - -[domain_realm] -~~~~~~~~~~~~~~ - -The [domain_realm] section provides a translation from hostnames to -Kerberos realms. Each tag is a domain name, providing the mapping for -that domain and all subdomains. If the tag begins with a period -(``.``) then it applies only to subdomains. The Kerberos realm may be -identified either in the realms_ section or using DNS SRV records. -Tag names should be in lower case. For example:: - - [domain_realm] - crash.mit.edu = TEST.ATHENA.MIT.EDU - .dev.mit.edu = TEST.ATHENA.MIT.EDU - mit.edu = ATHENA.MIT.EDU - -maps the host with the name ``crash.mit.edu`` into the -``TEST.ATHENA.MIT.EDU`` realm. The second entry maps all hosts under the -domain ``dev.mit.edu`` into the ``TEST.ATHENA.MIT.EDU`` realm, but not -the host with the name ``dev.mit.edu``. That host is matched -by the third entry, which maps the host ``mit.edu`` and all hosts -under the domain ``mit.edu`` that do not match a preceding rule -into the realm ``ATHENA.MIT.EDU``. - -If no translation entry applies to a hostname used for a service -principal for a service ticket request, the library will try to get a -referral to the appropriate realm from the client realm's KDC. If -that does not succeed, the host's realm is considered to be the -hostname's domain portion converted to uppercase, unless the -**realm_try_domains** setting in [libdefaults] causes a different -parent domain to be used. - - -.. _capaths: - -[capaths] -~~~~~~~~~ - -In order to perform direct (non-hierarchical) cross-realm -authentication, configuration is needed to determine the -authentication paths between realms. - -A client will use this section to find the authentication path between -its realm and the realm of the server. The server will use this -section to verify the authentication path used by the client, by -checking the transited field of the received ticket. - -There is a tag for each participating client realm, and each tag has -subtags for each of the server realms. The value of the subtags is an -intermediate realm which may participate in the cross-realm -authentication. The subtags may be repeated if there is more then one -intermediate realm. A value of "." means that the two realms share -keys directly, and no intermediate realms should be allowed to -participate. - -Only those entries which will be needed on the client or the server -need to be present. A client needs a tag for its local realm with -subtags for all the realms of servers it will need to authenticate to. -A server needs a tag for each realm of the clients it will serve, with -a subtag of the server realm. - -For example, ``ANL.GOV``, ``PNL.GOV``, and ``NERSC.GOV`` all wish to -use the ``ES.NET`` realm as an intermediate realm. ANL has a sub -realm of ``TEST.ANL.GOV`` which will authenticate with ``NERSC.GOV`` -but not ``PNL.GOV``. The [capaths] section for ``ANL.GOV`` systems -would look like this:: - - [capaths] - ANL.GOV = { - TEST.ANL.GOV = . - PNL.GOV = ES.NET - NERSC.GOV = ES.NET - ES.NET = . - } - TEST.ANL.GOV = { - ANL.GOV = . - } - PNL.GOV = { - ANL.GOV = ES.NET - } - NERSC.GOV = { - ANL.GOV = ES.NET - } - ES.NET = { - ANL.GOV = . - } - -The [capaths] section of the configuration file used on ``NERSC.GOV`` -systems would look like this:: - - [capaths] - NERSC.GOV = { - ANL.GOV = ES.NET - TEST.ANL.GOV = ES.NET - TEST.ANL.GOV = ANL.GOV - PNL.GOV = ES.NET - ES.NET = . - } - ANL.GOV = { - NERSC.GOV = ES.NET - } - PNL.GOV = { - NERSC.GOV = ES.NET - } - ES.NET = { - NERSC.GOV = . - } - TEST.ANL.GOV = { - NERSC.GOV = ANL.GOV - NERSC.GOV = ES.NET - } - -When a subtag is used more than once within a tag, clients will use -the order of values to determine the path. The order of values is not -important to servers. - - -.. _appdefaults: - -[appdefaults] -~~~~~~~~~~~~~ - -Each tag in the [appdefaults] section names a Kerberos V5 application -or an option that is used by some Kerberos V5 application[s]. The -value of the tag defines the default behaviors for that application. - -For example:: - - [appdefaults] - telnet = { - ATHENA.MIT.EDU = { - option1 = false - } - } - telnet = { - option1 = true - option2 = true - } - ATHENA.MIT.EDU = { - option2 = false - } - option2 = true - -The above four ways of specifying the value of an option are shown in -order of decreasing precedence. In this example, if telnet is running -in the realm EXAMPLE.COM, it should, by default, have option1 and -option2 set to true. However, a telnet program in the realm -``ATHENA.MIT.EDU`` should have ``option1`` set to false and -``option2`` set to true. Any other programs in ATHENA.MIT.EDU should -have ``option2`` set to false by default. Any programs running in -other realms should have ``option2`` set to true. - -The list of specifiable options for each application may be found in -that application's man pages. The application defaults specified here -are overridden by those specified in the realms_ section. - - -.. _plugins: - -[plugins] -~~~~~~~~~ - - * pwqual_ interface - * kadm5_hook_ interface - * clpreauth_ and kdcpreauth_ interfaces - -Tags in the [plugins] section can be used to register dynamic plugin -modules and to turn modules on and off. Not every krb5 pluggable -interface uses the [plugins] section; the ones that do are documented -here. - -New in release 1.9. - -Each pluggable interface corresponds to a subsection of [plugins]. -All subsections support the same tags: - -**disable** - This tag may have multiple values. If there are values for this - tag, then the named modules will be disabled for the pluggable - interface. - -**enable_only** - This tag may have multiple values. If there are values for this - tag, then only the named modules will be enabled for the pluggable - interface. - -**module** - This tag may have multiple values. Each value is a string of the - form ``modulename:pathname``, which causes the shared object - located at *pathname* to be registered as a dynamic module named - *modulename* for the pluggable interface. If *pathname* is not an - absolute path, it will be treated as relative to the - **plugin_base_dir** value from :ref:`libdefaults`. - -For pluggable interfaces where module order matters, modules -registered with a **module** tag normally come first, in the order -they are registered, followed by built-in modules in the order they -are documented below. If **enable_only** tags are used, then the -order of those tags overrides the normal module order. - -The following subsections are currently supported within the [plugins] -section: - -.. _ccselect: - -ccselect interface -################## - -The ccselect subsection controls modules for credential cache -selection within a cache collection. In addition to any registered -dynamic modules, the following built-in modules exist (and may be -disabled with the disable tag): - -**k5identity** - Uses a .k5identity file in the user's home directory to select a - client principal - -**realm** - Uses the service realm to guess an appropriate cache from the - collection - -**hostname** - If the service principal is host-based, uses the service hostname - to guess an appropriate cache from the collection - -.. _pwqual: - -pwqual interface -################ - -The pwqual subsection controls modules for the password quality -interface, which is used to reject weak passwords when passwords are -changed. The following built-in modules exist for this interface: - -**dict** - Checks against the realm dictionary file - -**empty** - Rejects empty passwords - -**hesiod** - Checks against user information stored in Hesiod (only if Kerberos - was built with Hesiod support) - -**princ** - Checks against components of the principal name - -.. _kadm5_hook: - -kadm5_hook interface -#################### - -The kadm5_hook interface provides plugins with information on -principal creation, modification, password changes and deletion. This -interface can be used to write a plugin to synchronize MIT Kerberos -with another database such as Active Directory. No plugins are built -in for this interface. - -.. _kadm5_auth: - -kadm5_auth interface -#################### - -The kadm5_auth section (introduced in release 1.16) controls modules -for the kadmin authorization interface, which determines whether a -client principal is allowed to perform a kadmin operation. The -following built-in modules exist for this interface: - -**acl** - This module reads the :ref:`kadm5.acl(5)` file, and authorizes - operations which are allowed according to the rules in the file. - -**self** - This module authorizes self-service operations including password - changes, creation of new random keys, fetching the client's - principal record or string attributes, and fetching the policy - record associated with the client principal. - -.. _clpreauth: - -.. _kdcpreauth: - -clpreauth and kdcpreauth interfaces -################################### - -The clpreauth and kdcpreauth interfaces allow plugin modules to -provide client and KDC preauthentication mechanisms. The following -built-in modules exist for these interfaces: - -**pkinit** - This module implements the PKINIT preauthentication mechanism. - -**encrypted_challenge** - This module implements the encrypted challenge FAST factor. - -**encrypted_timestamp** - This module implements the encrypted timestamp mechanism. - -.. _hostrealm: - -hostrealm interface -################### - -The hostrealm section (introduced in release 1.12) controls modules -for the host-to-realm interface, which affects the local mapping of -hostnames to realm names and the choice of default realm. The following -built-in modules exist for this interface: - -**profile** - This module consults the [domain_realm] section of the profile for - authoritative host-to-realm mappings, and the **default_realm** - variable for the default realm. - -**dns** - This module looks for DNS records for fallback host-to-realm - mappings and the default realm. It only operates if the - **dns_lookup_realm** variable is set to true. - -**domain** - This module applies heuristics for fallback host-to-realm - mappings. It implements the **realm_try_domains** variable, and - uses the uppercased parent domain of the hostname if that does not - produce a result. - -.. _localauth: - -localauth interface -################### - -The localauth section (introduced in release 1.12) controls modules -for the local authorization interface, which affects the relationship -between Kerberos principals and local system accounts. The following -built-in modules exist for this interface: - -**default** - This module implements the **DEFAULT** type for **auth_to_local** - values. - -**rule** - This module implements the **RULE** type for **auth_to_local** - values. - -**names** - This module looks for an **auth_to_local_names** mapping for the - principal name. - -**auth_to_local** - This module processes **auth_to_local** values in the default - realm's section, and applies the default method if no - **auth_to_local** values exist. - -**k5login** - This module authorizes a principal to a local account according to - the account's :ref:`.k5login(5)` file. - -**an2ln** - This module authorizes a principal to a local account if the - principal name maps to the local account name. - -.. _certauth: - -certauth interface -################## - -The certauth section (introduced in release 1.16) controls modules for -the certificate authorization interface, which determines whether a -certificate is allowed to preauthenticate a user via PKINIT. The -following built-in modules exist for this interface: - -**pkinit_san** - This module authorizes the certificate if it contains a PKINIT - Subject Alternative Name for the requested client principal, or a - Microsoft UPN SAN matching the principal if **pkinit_allow_upn** - is set to true for the realm. - -**pkinit_eku** - This module rejects the certificate if it does not contain an - Extended Key Usage attribute consistent with the - **pkinit_eku_checking** value for the realm. - -**dbmatch** - This module authorizes or rejects the certificate according to - whether it matches the **pkinit_cert_match** string attribute on - the client principal, if that attribute is present. - - -PKINIT options --------------- - -.. note:: - - The following are PKINIT-specific options. These values may - be specified in [libdefaults] as global defaults, or within - a realm-specific subsection of [libdefaults], or may be - specified as realm-specific values in the [realms] section. - A realm-specific value overrides, not adds to, a generic - [libdefaults] specification. The search order is: - -1. realm-specific subsection of [libdefaults]:: - - [libdefaults] - EXAMPLE.COM = { - pkinit_anchors = FILE:/usr/local/example.com.crt - } - -2. realm-specific value in the [realms] section:: - - [realms] - OTHERREALM.ORG = { - pkinit_anchors = FILE:/usr/local/otherrealm.org.crt - } - -3. generic value in the [libdefaults] section:: - - [libdefaults] - pkinit_anchors = DIR:/usr/local/generic_trusted_cas/ - - -.. _pkinit_identity: - -Specifying PKINIT identity information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The syntax for specifying Public Key identity, trust, and revocation -information for PKINIT is as follows: - -**FILE:**\ *filename*\ [**,**\ *keyfilename*] - This option has context-specific behavior. - - In **pkinit_identity** or **pkinit_identities**, *filename* - specifies the name of a PEM-format file containing the user's - certificate. If *keyfilename* is not specified, the user's - private key is expected to be in *filename* as well. Otherwise, - *keyfilename* is the name of the file containing the private key. - - In **pkinit_anchors** or **pkinit_pool**, *filename* is assumed to - be the name of an OpenSSL-style ca-bundle file. - -**DIR:**\ *dirname* - This option has context-specific behavior. - - In **pkinit_identity** or **pkinit_identities**, *dirname* - specifies a directory with files named ``*.crt`` and ``*.key`` - where the first part of the file name is the same for matching - pairs of certificate and private key files. When a file with a - name ending with ``.crt`` is found, a matching file ending with - ``.key`` is assumed to contain the private key. If no such file - is found, then the certificate in the ``.crt`` is not used. - - In **pkinit_anchors** or **pkinit_pool**, *dirname* is assumed to - be an OpenSSL-style hashed CA directory where each CA cert is - stored in a file named ``hash-of-ca-cert.#``. This infrastructure - is encouraged, but all files in the directory will be examined and - if they contain certificates (in PEM format), they will be used. - - In **pkinit_revoke**, *dirname* is assumed to be an OpenSSL-style - hashed CA directory where each revocation list is stored in a file - named ``hash-of-ca-cert.r#``. This infrastructure is encouraged, - but all files in the directory will be examined and if they - contain a revocation list (in PEM format), they will be used. - -**PKCS12:**\ *filename* - *filename* is the name of a PKCS #12 format file, containing the - user's certificate and private key. - -**PKCS11:**\ [**module_name=**]\ *modname*\ [**:slotid=**\ *slot-id*][**:token=**\ *token-label*][**:certid=**\ *cert-id*][**:certlabel=**\ *cert-label*] - All keyword/values are optional. *modname* specifies the location - of a library implementing PKCS #11. If a value is encountered - with no keyword, it is assumed to be the *modname*. If no - module-name is specified, the default is |pkcs11_modname|. - ``slotid=`` and/or ``token=`` may be specified to force the use of - a particular smard card reader or token if there is more than one - available. ``certid=`` and/or ``certlabel=`` may be specified to - force the selection of a particular certificate on the device. - Specifier values must not contain colon characters, as colons are - always treated as separators. See the **pkinit_cert_match** - configuration option for more ways to select a particular - certificate to use for PKINIT. - -**ENV:**\ *envvar* - *envvar* specifies the name of an environment variable which has - been set to a value conforming to one of the previous values. For - example, ``ENV:X509_PROXY``, where environment variable - ``X509_PROXY`` has been set to ``FILE:/tmp/my_proxy.pem``. - - -PKINIT krb5.conf options -~~~~~~~~~~~~~~~~~~~~~~~~ - -**pkinit_anchors** - Specifies the location of trusted anchor (root) certificates which - the client trusts to sign KDC certificates. This option may be - specified multiple times. These values from the config file are - not used if the user specifies X509_anchors on the command line. - -**pkinit_cert_match** - Specifies matching rules that the client certificate must match - before it is used to attempt PKINIT authentication. If a user has - multiple certificates available (on a smart card, or via other - media), there must be exactly one certificate chosen before - attempting PKINIT authentication. This option may be specified - multiple times. All the available certificates are checked - against each rule in order until there is a match of exactly one - certificate. - - The Subject and Issuer comparison strings are the :rfc:`2253` - string representations from the certificate Subject DN and Issuer - DN values. - - The syntax of the matching rules is: - - [*relation-operator*\ ]\ *component-rule* ... - - where: - - *relation-operator* - can be either ``&&``, meaning all component rules must match, - or ``||``, meaning only one component rule must match. The - default is ``&&``. - - *component-rule* - can be one of the following. Note that there is no - punctuation or whitespace between component rules. - - | **<SUBJECT>**\ *regular-expression* - | **<ISSUER>**\ *regular-expression* - | **<SAN>**\ *regular-expression* - | **<EKU>**\ *extended-key-usage-list* - | **<KU>**\ *key-usage-list* - - *extended-key-usage-list* is a comma-separated list of - required Extended Key Usage values. All values in the list - must be present in the certificate. Extended Key Usage values - can be: - - * pkinit - * msScLogin - * clientAuth - * emailProtection - - *key-usage-list* is a comma-separated list of required Key - Usage values. All values in the list must be present in the - certificate. Key Usage values can be: - - * digitalSignature - * keyEncipherment - - Examples:: - - pkinit_cert_match = ||<SUBJECT>.*DoE.*<SAN>.*@EXAMPLE.COM - pkinit_cert_match = &&<EKU>msScLogin,clientAuth<ISSUER>.*DoE.* - pkinit_cert_match = <EKU>msScLogin,clientAuth<KU>digitalSignature - -**pkinit_eku_checking** - This option specifies what Extended Key Usage value the KDC - certificate presented to the client must contain. (Note that if - the KDC certificate has the pkinit SubjectAlternativeName encoded - as the Kerberos TGS name, EKU checking is not necessary since the - issuing CA has certified this as a KDC certificate.) The values - recognized in the krb5.conf file are: - - **kpKDC** - This is the default value and specifies that the KDC must have - the id-pkinit-KPKdc EKU as defined in :rfc:`4556`. - - **kpServerAuth** - If **kpServerAuth** is specified, a KDC certificate with the - id-kp-serverAuth EKU will be accepted. This key usage value - is used in most commercially issued server certificates. - - **none** - If **none** is specified, then the KDC certificate will not be - checked to verify it has an acceptable EKU. The use of this - option is not recommended. - -**pkinit_dh_min_bits** - Specifies the group of the Diffie-Hellman key the client will - attempt to use. The acceptable values are 1024, 2048, P-256, - 4096, P-384, and P-521. The default is 2048. (P-256, P-384, and - P-521 are new in release 1.22.) - -**pkinit_identities** - Specifies the location(s) to be used to find the user's X.509 - identity information. If this option is specified multiple times, - each value is attempted in order until certificates are found. - Note that these values are not used if the user specifies - **X509_user_identity** on the command line. - -**pkinit_kdc_hostname** - The presence of this option indicates that the client is willing - to accept a KDC certificate with a dNSName SAN (Subject - Alternative Name) rather than requiring the id-pkinit-san as - defined in :rfc:`4556`. This option may be specified multiple - times. Its value should contain the acceptable hostname for the - KDC (as contained in its certificate). - -**pkinit_pool** - Specifies the location of intermediate certificates which may be - used by the client to complete the trust chain between a KDC - certificate and a trusted anchor. This option may be specified - multiple times. - -**pkinit_require_crl_checking** - The default certificate verification process will always check the - available revocation information to see if a certificate has been - revoked. If a match is found for the certificate in a CRL, - verification fails. If the certificate being verified is not - listed in a CRL, or there is no CRL present for its issuing CA, - and **pkinit_require_crl_checking** is false, then verification - succeeds. - - However, if **pkinit_require_crl_checking** is true and there is - no CRL information available for the issuing CA, then verification - fails. - - **pkinit_require_crl_checking** should be set to true if the - policy is such that up-to-date CRLs must be present for every CA. - -**pkinit_revoke** - Specifies the location of Certificate Revocation List (CRL) - information to be used by the client when verifying the validity - of the KDC certificate presented. This option may be specified - multiple times. - - -.. _parameter_expansion: - -Parameter expansion -------------------- - -Starting with release 1.11, several variables, such as -**default_keytab_name**, allow parameters to be expanded. -Valid parameters are: - - ================= =================================================== - %{TEMP} Temporary directory - %{uid} Unix real UID or Windows SID - %{euid} Unix effective user ID or Windows SID - %{USERID} Same as %{uid} - %{null} Empty string - %{LIBDIR} Installation library directory - %{BINDIR} Installation binary directory - %{SBINDIR} Installation admin binary directory - %{username} (Unix) Username of effective user ID - %{APPDATA} (Windows) Roaming application data for current user - %{COMMON_APPDATA} (Windows) Application data for all users - %{LOCAL_APPDATA} (Windows) Local application data for current user - %{SYSTEM} (Windows) Windows system folder - %{WINDOWS} (Windows) Windows folder - %{USERCONFIG} (Windows) Per-user MIT krb5 config file directory - %{COMMONCONFIG} (Windows) Common MIT krb5 config file directory - ================= =================================================== - -Sample krb5.conf file ---------------------- - -Here is an example of a generic krb5.conf file:: - - [libdefaults] - default_realm = ATHENA.MIT.EDU - dns_lookup_kdc = true - dns_lookup_realm = false - - [realms] - ATHENA.MIT.EDU = { - kdc = kerberos.mit.edu - kdc = kerberos-1.mit.edu - kdc = kerberos-2.mit.edu - admin_server = kerberos.mit.edu - primary_kdc = kerberos.mit.edu - } - EXAMPLE.COM = { - kdc = kerberos.example.com - kdc = kerberos-1.example.com - admin_server = kerberos.example.com - } - - [domain_realm] - mit.edu = ATHENA.MIT.EDU - - [capaths] - ATHENA.MIT.EDU = { - EXAMPLE.COM = . - } - EXAMPLE.COM = { - ATHENA.MIT.EDU = . - } - -FILES ------ - -|krb5conf| - - -SEE ALSO --------- - -syslog(3) |