[Freeipa-devel] [RFE] CA-less install

Fri Mar 22 12:10:29 UTC 2013

The design page for CA-less installation with user-provided SSL certs is 
available at http://freeipa.org/page/V3/CA-less_install. I've also 
copied it to this mail.

Does it answer all your questions?

-- 
Petr³

__NOTOC__

= Overview =

IPA will support installing without an embedded Certificate Authority,
with user-provided SSL certificates for the HTTP and Directory servers.

= Use Cases =

# User installs IPA using the --http_pkcs, --dirsrv_pkcs, --http_pin, 
--dirsrv_pin, --root-ca-file options, giving appropriate certificates.
# IPA installs and works normally, excluding the certificate management 
operaions
# User creates a replica using --http_pkcs, --dirsrv_pkcs, --http_pin, 
--dirsrv_pin options to ipa-replica-prepare
# Replica works normally, excluding certificate management operaions

= Design=

To install without a CA, the following options must be provided to 
ipa-server-install:
* --http_pkcs: a PKCS#12 file containing the HTTP server certificate
* --dirsrv_pkcs: a PKCS#12 file containing the Directory server certificate
* --http_pin: password for the file given in --http_pkcs
* --dirsrv_pin: password for the file given in --dirsrv_pkcs
* --root-ca-file: a PEM file containing the root CA certificate

Each of the PKCS#12 files must contain exactly one certificate with a 
private key.
This will be used as the server certificate.
It must also contain certificates of any intermediate CAs.
It may contain any number of other certificates without matching private 
keys.
The two PKCS#12 files may (and often will) be the same.
The certificates must be valid as server certs for the given host.

The PEM file given by --root-ca-file must contain exactly one certificate.
This cert will be trusted as a root CA on the IPA server and all clients.
Both server certs must be signed by this CA (possibly via a trust chain).
It will be available in <tt>/etc/ipa/ca.crt</tt> and in the cACertificate
attribute of cn=CACert,cn=ipa,cn=etc,$SUFFIX in LDAP, just like the IPA 
CA cert
in Dogtag-based installations.

These options are incompatible with --external-ca.

To install a replica, following options must be provided to 
ipa-replica-prepare:
* --http_pkcs
* --dirsrv_pkcs
* --http_pin
* --dirsrv_pin

The root CA is taken from the existing master.
All apply as in the ipa-server-install case.

== Why --root-ca-file? ==

IPA requires the user to specify the root CA to be trusted.
This done to ensure that all replicas and clients trust the IPA 
certificates,
no matter what their initial configuration is.

Theoretically the CA certificate could be extracted from PKCS#12 files,
but to ensure transparency and the administrator's control when it comes to
trusting a root CA, it must always be specified explicitly.

In the future it might be possible to trust more than one CA in this way.

= Certificate management FAQ =

== How to check what format files are? ==

Use the handy <tt>file</tt> command.

PEM files show up as such:

     $ file /etc/ipa/ca.crt
     /etc/ipa/ca.crt: PEM certificate

PKCS#12 files show up as just "data":

     $ file dirsrv.p12
     dirsrv.p12: data

To check a PKCS#12 file, you need to know the password:

     $ pk12util -l dirsrv.p12
     Enter password for PKCS12 file:
     Certificate(has private key):
         <...>
     Certificate:
         <...>
     Key(shrouded):
         <...>

== How many certs are there in a file? ==

For PKCS#12 files, use <tt>pk12util -l</tt> (see previous section).

For PEM files, simply open the file in a pager or text editor and count 
the number of blocks.
A certificate will look like this:

     $ cat /etc/ipa/ca.crt
     -----BEGIN CERTIFICATE-----
     MIIDuzCCAqOgAwIBAgIBATANBgkqhkiG9w0BAQsFADBFMSMwIQYDVQQKExpJRE0u
     TEFCLkVORy5CUlEuUkVESEFULkNPTTEeMBwGA1UEAxMVQ2VydGlmaWNhdGUgQXV0
     aG9yaXR5MB4XDTEzMDMyMDE3MDQxNFoXDTMzMDMyMDE3MDQxNFowRTEjMCEGA1UE
     ChMaSURNLkxBQi5FTkcuQlJRLlJFREhBVC5DT00xHjAcBgNVBAMTFUNlcnRpZmlj
     YXRlIEF1dGhvcml0eTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMZi
     pF9Dz5O1rVTRnwIdttHl0sKpHeRqzi/S7bnAFh3Jb2UxzFmHTpgQFKqq72mYatpL
     O0BPc47IGh9gwGZNLcEaNCf7zYCbqBJso8RV6SxbHSEdo+JuSYhMxVasKQcojqeY
     /wx11A4NSQAco6mBZz255llZqMQcJVMW4T8aioUd19Yh35CM9vr6l6dgUnvA9fAF
     TOl144yfF8AjvF1hIAePjLyl+Y/xxh1U2j5hF4z7ZeUGHKVZR9pQ62kbM7TgAR6Y
     YLGpis44JPfgRVkDGEkc7Vzpct1D4Iz7/oGMV+0kbJbz+9DSIHWY10QTtf9mNQNn
     xKGa3wCf5u8ctfmms8cCAwEAAaOBtTCBsjAfBgNVHSMEGDAWgBQCHF1DVeHg3kUG
     VRm/j0f9eji6nzAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBxjAdBgNV
     HQ4EFgQUAhxdQ1Xh4N5FBlUZv49H/Xo4up8wTwYIKwYBBQUHAQEEQzBBMD8GCCsG
     AQUFBzABhjNodHRwOi8vdm0tMDg0LmlkbS5sYWIuZW5nLmJycS5yZWRoYXQuY29t
     OjgwL2NhL29jc3AwDQYJKoZIhvcNAQELBQADggEBAB3+or2Q/aPO4ZMBE4Q6xCMV
     09ESAXXT/0DLakAt28ljy1wWKVR3d54TxZJ4DEcYgbxDa1A87DZW8sn+LM4Uwap9
     DUyHA0mhBjROe6NXgJQl9aZ7IeE1ht+pw/n+JR2sg3ccYHvQjRcEZj2OPQuavyPn
     hwokDc3FVarlsQcrtfePG3e8TQXAnpSxV+KAMBEp4yib5nrkNZZoU+nqMI0ftXrk
     rP5q0SaEBEjC4+AoYje4Bv3+8RKT1kwBMkTL8eRRuWZmKvOy9sCnnFfU4HMMkPTK
     NJg9Gt8a/xU6GK239M1keCKct87VqWN1unXaD51bgotK1UJWj1q8H262mSYzfRg=
     -----END CERTIFICATE-----

== How to extact certs or or combine certs into files? ==

=== PEM Files ===

PEM files are plain text; manipulate them using a text editor

=== Using a NSS database ===

NSS databases can be manipulated using <tt>certutil</tt> and 
<tt>pk12util</tt>.

In a NSS database, each certificate is identified using a "nickname".
The nickname can be set with -n option, or taken from the "Friendly name"
entry in a PKCS#12 file, or from the Subject of the certificate.
Note that nicknames and Friendly Names are *not* part of the cert itself.

Create a temporary NSS database using:

     certutil -N -d /path/to/nssdb

Remember to set appropriate permissions if you're working with sensitive 
data.

To list nicknames and trust flags in of the certs in the database, enter:

     certutil -L -d /path/to/nssdb/

To import a PKCS#12 file to a database:

     pk12util -i /path/to/pkcs12file.p12 -d /path/to/nssdb

To export a PKCS#12 file from a database
(this will export the certificate chain and private key(s), if available):

     pk12util -o /path/to/pkcs12file.p12 -d /path/to/nssdb -n <nickname>

To import a PEM file:

     certutil -A -d /path/to/nssdb -n <nickname> -a -t <flags> -i <file>

For an explicitly trusted (root) CA, use "CT,C,C" for flags. Otherwise 
use ",,"

To export a PEM file (to stdout):

     certutil -L -d /path/to/nssdb -n <nickname> -a

Note that PEM is referred to as "ASCII" in certutil documentation.

To create a self-signed root CA certificate and private key:

     certutil -S -d /path/to/nssdb -s "CN=$(hostname)" -m $RANDOM -n 
RootCA -t CT,C,C -x

You should substitute a unique serial number for $RANDOM.

To generate a Certificate Signing Request for a server:

     certutil -R -d /path/to/nssdb -s "CN=$(hostname)" -1 -a -o request.csr

Select Digital Signature, Non-Repudiation and Key Encipherment for the 
extension.

To sign the CSR, and get a PEM file with the cert:

     certutil -C -d /path/to/nssdb -m $RANDOM -a -i request.csr -c RootCA

Again, substitute a unique serial number for $RANDOM.

== How to check that my certificates will be usable? ==

To inspect PKCS#12 files, use <tt>pk12util -l</tt>.
For other files, import them in a NSS database and use <tt>certutil 
-L</tt>. See above for details.

For the servers, you will need certs with a private key.
These show up as "Certificate(has private key):" in <tt>pk12util</tt> 
output,
and with "u" flags in <tt>certutil -L</tt> without <tt>-n</tt>
The certs will need Digital Signature, Non-Repudiation and Key 
Encipherment in the
"Certificate Key Usage" extension (visible in <tt>pk12util -l</tt> and 
<tt>certutil -L -n</tt> output).
Also, server certs must have "CN=<hostname>" in the Subject.

The server certs will need a valid trust chain leading up to the CA 
certificate.
You can check the trust chain following the "Subject" and "Issuer" lines 
in the <tt>pk12util -l</tt> output.
CAs should have Certificate Signing and CRL Signing in their 
"Certificate Key Usage" extension.

= Implementation =

No additional requirements or changes discovered during the 
implementation phase.

= Feature Managment =

=== UI ===

N/A

=== CLI ===

The --http_pkcs, --dirsrv_pkcs, --http_pin, --dirsrv_pin options to
ipa-server-install and ipa-replica-prepare work again.
The --root-ca-file option was added to ipa-server-install.

= Major configuration options and enablement =

The feature can be installed as detailed above.
There is no supported way to enable a CA once a CA-less IPA is installed,
or to revert to CA-less from a Dogtag installation.

= Replication =

When creating a replica file, certificates for that replica must be 
specified.
These must be signed by the CA given as --root-ca-file to the original 
master
(a copy of this CA cert is in /etc/ipa/ca.crt).

= Updates and Upgrades =

Existing installs are not affected.

Upgrading CA-less instances should work normally.

= Dependencies =

None

= External Impact =

Tests will need to be written.

Documentation will need to be updated.