Jump to: navigation, search

V3/CA-less install

Name: V3/CA-less install
Ticket: #3363
Target version: 3.2.0
Incomplete.png Pending review
Last updated: 2018-02-19 by Ab

Overview

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

Important.png
Changes to options
As part of Installer CA options usability improvements, some of the options mentioned in this article were changed:
  • --dirsrv_pkcs12 was replaced with --dirsrv-cert-file
  • --dirsrv_pin was replaced with --dirsrv-pin
  • --http_pkcs12 was replaced with --http-cert-file
  • --http_pin was replaced with --http-pin
  • --root-ca-file was replaced with --ca-cert-file

Use Cases

  1. User installs IPA using the --http_pkcs12, --dirsrv_pkcs12, --http_pin, --dirsrv_pin, --root-ca-file options, giving appropriate certificates.
  2. IPA installs and works normally, excluding the certificate management operations
  3. User creates a replica using --http_pkcs12, --dirsrv_pkcs12, --http_pin, --dirsrv_pin options to ipa-replica-prepare
  4. Replica works normally, excluding certificate management operaions

Design

To install without a CA, the following options must be provided to ipa-server-install:

  • --http_pkcs12: a PKCS#12 file containing the HTTP server certificate
  • --dirsrv_pkcs12: a PKCS#12 file containing the Directory server certificate
  • --http_pin: password for the file given in --http_pkcs12
  • --dirsrv_pin: password for the file given in --dirsrv_pkcs12
  • --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 /etc/ipa/ca.crt 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.

Note that --root-ca-file gives the root of trust, which may not necessarily be the root of a certificate chain. For example, if a user wishes to trust a company-wide certificate, but not an external the CA that signed it, --root-ca-file should give the company certificate.

These options are incompatible with --external-ca.

To install a replica, following options must be provided to ipa-replica-prepare:

  • --http_pkcs12
  • --dirsrv_pkcs12
  • --http_pin
  • --dirsrv_pin

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

Certificate rotation

Neither the Dogtag CA nor Certmonger are installed on IPA servers in this scenario. Before the server certificates expire, new ones must be issued and installed manually.

In this setup, no warnings are given about certs that are about to expire.

KDC pkinit considerations

In the future, another certificate will be needed for the KDC. It will be specified using the --pkinit_pkcs and --pkinit_pin options, similarly to the other two certs.

Currently KDC pkinit is disabled.

Affected commands

IPA's cert plugin and cert-* commands will not be available at all. Calling them will result in CommandError (code 905) No online help will be available on them, or on the "cert" topic.

Certificates removed from LDAP will not be automatically revoked. This affects the following commands:

  • host-del
  • host-mod
  • host-disable
  • service-del
  • service-mod
  • service-disable

Clients

Clients in a CA-less IPA installation will work normally, except host certificates will not be assigned automatically.

Older clients configure certmonger to obtain the host certificate, which will fail, with the following line appearing periodically in the system log:

   Server failed request, will retry: 905 (RPC failed at server.  unknown command 'cert_request').

The errors can be stopped by issuing:

   # getcert list  # to find out the certmonger request ID
   # getcert stop-tracking <ID of offending request>

If needed, machine certificates may be obtained from the external CA and added to the server with:

   ipa host-mod <hostname> --certificate <base64-encoded DER cert>

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 file 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 pk12util -l (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

Base64-encoded DER certificates

The letters and symbols between a PEM file's BEGIN CERTIFICATE and END CERTIFICATE markers are a base64-encoded DER-encoded X.509 certificate. To convert between PEM and base64-encoded DER, just add or remove the markers in a text editor.

Using a NSS database

NSS databases can be manipulated using certutil and pk12util.

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 pk12util -l. For other files, import them in a NSS database and use certutil -L. See above for details.

For the servers, you will need certs with a private key. These show up as "Certificate(has private key):" in pk12util output, and with "u" flags in certutil -L without -n The certs will need Digital Signature, Non-Repudiation and Key Encipherment in the "Certificate Key Usage" extension (visible in pk12util -l and certutil -L -n 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 pk12util -l output. CAs should have Certificate Signing and CRL Signing in their "Certificate Key Usage" extension.

Feature Managment

UI

N/A

CLI

The --http_pkcs12, --dirsrv_pkcs12, --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.

Configuration

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.

Test Plan

See dedicated test page.

RFE Author

pviktori