+++ /dev/null
-Building with pkinit enabled:
-=============================
-To build the code you will need OpenSSL headers. To build
-with smartcard support, OpenSC is required. The code can
-currently be built w/o smartcard support by defining
-WITHOUT_PKCS11 in the CFLAGS.
-
-Although you will need OpenSC to build the code, at run time you just need a
-pkcs11 module. It may be possible to build without having OpenSC installed
-by changing the path to the pkcs11 include file and the name of the default
-module. We have not tried this.
-
-Running with pkinit enabled:
-=============================
-In the following descriptions, options specified with "DIR:"
-are assumed to point to an OpenSSL-style hashed CA directory
-where each CA cert is stored in a file "<hash of CA cert>.0".
-We assume that a CRL directory (pkinit_revoke) will contain CRL files
-"<hash of CA cert>.r0". We encourage that users have such
-infrastructure but we will also allow files that contain
-certificates (or crls) in that directory that are not named
-in this style. Basically, for a given directory, the code
-will read each file in the directory and if the file contains
-a certificate (or crl), we will include it.
-
-Configuration for a pkinit-enabled KDC:
----------------------------------------
-The following pkinit-specific configuration parameters can be specified
-in kdc.conf in either the [kdcdefaults] stanza or the appropriate
-realm entry:
-
-"pkinit_identity"
- Specifies where to find the KDC's certificate and private key.
- It is REQUIRED, and can be defined only once. It takes the form:
-
- FILE:<cert-file-name>[,<key-file-name>]
-
- If <key-file-name> is not specified, the private key is assumed
- to be located in the same file with the certificate.
-
-"pkinit_anchors"
- Specifies where the KDC will find trusted root CA certficates
- to verify client certificates it receives. This parameter is
- REQUIRED and may be specified multiple times. It can take the
- forms:
-
- FILE:<ca-bundle-file-name>
- DIR:<openssl-style-hashed-directory>
-
-"pkinit_pool"
- Specifies where the KDC will find other (intermediate) CA
- certificates it can use to build trust paths to the trusted
- roots defined in "pkinit_anchors", while verifying client
- certificates. This parameter is OPTIONAL and may be specified
- multiple times. It can take the same forms as "pkinit_anchors".
-
-"pkinit_revoke"
- Specifies where CRL information can be found to be used when
- verifying client certificates. This parameter is OPTIONAL and
- may by specified multiple times. It can take the same forms
- as "pkinit_anchors". XXX???XXX
-
-"pkinit_dh_min_bits"
- Specifies the minimum number of bits the KDC is willing to accept
- for a client's Diffie-Hellman key. This is an OPTIONAL integer
- value. The default is 1024.
-
-
-Configuration for pkinit-enabled client:
-----------------------------------------
-The following pkinit-specific configuration parameters can be specified
-in krb5.conf in the [libdefaults] stanza. They may be specified as
-"global" libdefaults or specified by realm within the [libdefaults]
-stanza.
-
-i.e.
- [libdefaults]
- pkinit_anchors = DIR:/etc/ssl/trusted-anchors
- pkinit_win2k = false
-
- EXAMPLE.COM = {
- pkinit_win2k = true
- pkinit_win2k_require_binding = true
- pkinit_anchors = FILE:/etc/ssl/example.com.cas
- }
-
-"pkinit_identity"
- See the discussion for this option in the KDC description above.
- For the client, this is OPTIONAL. The client can use either
- of the following to specify its certificate and private key
- locations:
-
- FILE:<cert-file-name>[,<key-file-name>]
-
- PKCS11:[module_name=]<module-name>[:slotid=<slot-id>]
- [:token=<token-label>][:certid=<cert-id>]
- [:certlabel=<cert-label>]
-
-"pkinit_anchors"
- See the discussion for this option in the KDC description above.
- For the client, this option is considered OPTIONAL, however it
- is needed in practice to verify a KDC's certificate.
-
-"pkinit_pool"
- See the discussion for these options in the KDC descriptions above.
-
-"pkinit_revoke"
- See the discussion for these options in the KDC descriptions above.
-
-"pkinit_win2k"
- This BOOLEAN option specifies whether the target realm is assumed
- to support only the "old" version of the protocol. The default
- is false.
-
-"pkinit_win2k_require_binding"
- If this BOOLEAN option is set to true, it expects that the target
- KDC is patched to return a reply with a checksum rather than a
- nonce. The default is false.
-
-"pkinit_require_eku"
- This BOOLEAN specifies whether the client insists that the KDC
- certificate contain the appropriate Extended Key Usage value.
- The default is true.
-
-"pkinit_require_krbtgt_otherName"
- This BOOLEAN specifies whether the client insists that the KDC
- certificate contain the appropriate SubjectAlternativeName
- value. The default is true.
-
-"pkinit_require_hostname_match"
- This BOOLEAN specifies whether the client insists that the
- hostname within the SubjectAlternativeName must match the
- hostname the client believes it is talking to. The default
- is false.
-
-
-Command-line options for kinit:
--------------------------------
-Command-line options may be passed via the -X option to kinit.
-The following values are currently accepted:
-
-X509_user_identity=<value>
- Where <value> has the same format as the "pkinit_identity"
- config option described above.
-
-X509_anchors=<value>
- Where <value> has the same format as the "pkinit_anchors"
- config option described above.
-
-flag_RSA_PROTOCOL
- This boolean specifies that the RSA protocol (rather than
- the Diffie-Hellman protocol) should be used while authenticating
- with the KDC.
-
-
-For a pkinit-enabled client using smartcards:
----------------------------------------------
-1. Install a pkcs11 module (smartcard enabled or otherwise).
- We use OpenSC but any module that implements pkcs11 should work.
- There are some instructions for setting up OpenSC at
- http://www.citi.umich.edu/projects/pkinit/smartcard_setup.html
-2. set the location of your trusted cas either by setting the
- appropriate configuration file parameter or by specifying
- "-X X509_anchors=<value>" on the command line.
-3. Select a pkcs11 module. The default is opensc-pkcs11.so. To use a
- different one, use the "module_name=" option (see below).
-4. Select a pkcs11 slot/token. If you only have one with a token available,
- that one will be used. Otherwise use the "slotid=" option. Or you can
- specify a token label with the "token=" option and pkinit will attempt to
- locate that token.
-5. Select a client certificate to use. You can specify a certificate ID
- with "certid=" or a certificate label with "certlabel=". If multiple
- certs fit the selection criteria, the first one with the appropriate
- capabilities will be used.
-6. Options can be set either via the "pkcs11_identity" krb5.conf
- parameter or via the -X parameter to kinit.
- These two examples should produce the same result:
-
- pkinit_identity=PKCS11:module_name=/usr/local/VendorX/lib/libpkcs11.so:slotid=1:certid=4
-
- kinit -X X509_user_identity=PKCS11:module_name=/usr/local/VendorX/lib/libpkcs11.so:slotid=1:certid=4
-
-
-For a pkinit-enabled client using the filesystem for Cert and Key:
-------------------------------------------------------------------
-1. verify that the proper krb5.conf options are set
-2. Specify the certificate and private key locations either via the
- pkinit_identity config option, or via the "-X X509_user_identity="
- command line option.
- These two examples should produce the same result:
-
- pkinit_identity=FILE:/home/bubba/ssl/foo.crt,/home/bubba/ssl/foo.key
-
- kinit -X X509_user_identity=FILE:/home/bubba/ssl/foo.crt,/home/bubba/ssl/foo.key
-
-
-Testing
-=======
-We have tested the client code against our server, Heimdal server,
-and Windows 2003 servers, but not yet against a Vista/Longhorn server.
-
-We have not yet been able to test a Windows client against our server.
-
-Most of our smartcard testing has been with Cryptoflex.
-
-Known Issues
-============
-- The client principal must currently have the REQUIRES_PREAUTH attribute
- set to cause the use of pkinit
-- Some error reporting is incomplete
-
-
-Information about using CRLs
-============================
-N.B. The following describes a "pkinit_require_crl_checking" option
-which currently doesn't actually exist. The current behavior is
-as if this option were always set to false.
-
-We assume that the user will acquire needed CRLs and place them
-in a local directory (using OpenSSL style) or a single file. During
-verification of a certificate for each CA, the code looks for a CRL
-issued by that CA. 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 for the issuing CA, then verification fails.
-
-Basically, 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.
-
-
-===============
-NOT IMPLEMENTED
-===============
-The following KDC options allowed by Heimdal are NOT CURRENTLY IMPLEMENTED:
-
-"pkinit_kdc_ocsp"
- Specifies where the KDC will find information to use the Online
- Certificate Status Protocol while verifying client certificates.
- This parameter is OPTIONAL and there is no default.
-
-"pkinit_mappings_file"
- Specifies where the KDC will find information to use to map the
- DN information in a certificate to a KDC principal. This would
- be used when the client certificate does not contain the pkinit-SAN
- information defined by RFC 4556.
- This parameter is OPTIONAL and there is no default.
-
-"pkinit_allow_proxy_certificate"
- Specifies whether the KDC should accept proxy client certificates
- for authentication. This is an OPTIONAL boolean parameter. The
- default is false.
-
-"pkinit_principal_in_certificate"
- Specifies whether the KDC should obtain the client principal name
- from the SubjectAlternativeName in the certificate presented
- for authentication. This is an OPTIONAL boolean parameter. The
- default is true.
-
-pkinit_identity=PKCS11:[module_name=]<module-name>[:slotid=<slot-id>]
- [:token=<token-label>][:certid=<cert-id>]
- [:certlabel=<cert-label>]
projects / krb5.git / commitdiff