diff options
Diffstat (limited to 'src/plugins/preauth/pkinit/README')
| -rw-r--r-- | src/plugins/preauth/pkinit/README | 263 |
1 files changed, 263 insertions, 0 deletions
diff --git a/src/plugins/preauth/pkinit/README b/src/plugins/preauth/pkinit/README new file mode 100644 index 0000000000..90522a739e --- /dev/null +++ b/src/plugins/preauth/pkinit/README @@ -0,0 +1,263 @@ +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>] |