Chapter 36. Converting certificate formats to work with IdM

This user story describes how to make sure that you as an IdM system administrator are using the correct format of a certificate with specific IdM commands. This is useful, for example, in the following situations:

36.1. Certificate formats and encodings in IdM

Certificate authentication including smart card authentication in IdM proceeds by comparing the certificate that the user presents with the certificate, or certificate data, that are stored in the user’s IdM profile.

System configuration

What is stored in the IdM profile is only the certificate, not the corresponding private key. During authentication, the user must also show that he is in possession of the corresponding private key. The user does that by either presenting a PKCS #12 file that contains both the certificate and the private key or by presenting two files: one that contains the certificate and the other containing the private key.

Therefore, processes such as loading a certificate into a user profile only accept certificate files that do not contain the private key.

Similarly, when a system administrator provides you with an external CA certificate, he will provide only the public data: the certificate without the private key. The ipa-advise utility for configuring the IdM server or the IdM client for smart card authentication expects the input file to contain the certificate of the external CA but not the private key.

Certificate encodings

There are two common certificate encodings: Privacy-enhanced Electronic Mail (PEM) and Distinguished Encoding Rules (DER). The base64 format is almost identical to the PEM format but it does not contain the -----BEGIN CERTIFICATE-----/-----END CERTIFICATE----- header and footer.

A certificate that has been encoded using DER is a binary X509 digital certificate file. As a binary file, the certificate is not human-readable. DER files sometimes use the .der filename extension, but files with the .crt and .cer filename extensions also sometimes contain DER certificates. DER files containing keys can be named .key.

A certificate that has been encoded using PEM Base64 is a human-readable file. The file contains ASCII (Base64) armored data prefixed with a “-----BEGIN …” line. PEM files sometimes use the .pem filename extension, but files with the .crt and .cer filename extensions also sometimes contain PEM certificates. PEM files containing keys can be named .key.

Different ipa commands have different limitations regarding the types of certificates that they accept. For example, the ipa user-add-cert command only accepts certificates encoded in the base64 format but ipa-server-certinstall accepts PEM, DER, PKCS #7, PKCS #8 and PKCS #12 certificates.

Table 36.1. Certificate encodings

Encoding formatHuman-readableCommon filename extensionsSample IdM commands accepting the encoding format

PEM/base64

Yes

.pem, .crt, .cer

ipa user-add-cert, ipa-server-certinstall, …​

DER

No

.der, .crt, .cer

ipa-server-certinstall, …​

Section 36.4, “Certificate-related commands and formats in IdM” lists further ipa commands with the certificate formats that the commands accept.

User authentication

When using the web UI to access IdM, the user proves that he is in possession of the private key corresponding to the certificate by having both stored in the browser’s database.

When using the CLI to access IdM, the user proves that he is in possession of the private key corresponding to the certificate by one of the following methods:

  • The user adds, as the value of the X509_user_identity parameter of the kinit -X command, the path to the smart card module that is connected to the smart card that contains both the certificate and the key:

    $ kinit -X X509_user_identity='PKCS11:opensc-pkcs11.so' idm_user
  • The user adds two files as the values of the X509_user_identity parameter of the kinit -X command, one containing the certificate and the other the private key:

    $ kinit -X X509_user_identity='FILE:`/path/to/cert.pem,/path/to/cert.key`' idm_user

Useful certificate commands

To view the certificate data, such as the subject and the issuer:

$ openssl x509 -noout -text -in ca.pem

To compare in which lines two certificates differ:

$ diff cert1.crt cert2.crt

To compare in which lines two certificates differ with the output displayed in two columns:

$ diff cert1.crt cert2.crt -y

36.2. Converting an external certificate to load into an IdM user account

This section describes how to make sure that an external certificate is correctly encoded and formatted before adding it to a user entry.

Prerequisites

  • If your certificate was issued by an Active Directory certificate authority and uses the PEM encoding, make sure that the PEM file has been converted into the UNIX format. To convert a file, use the dos2unix utility provided by the eponymous package.

36.2.1. Converting an external certificate in the IdM CLI and loading it into an IdM user account

The IdM CLI only accepts a PEM certificate from which the first and last lines (-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----) have been removed.

Procedure

  1. Convert the certificate to the PEM format:

    • If your certificate is in the DER format:

      $ openssl x509 -in cert.crt -inform der -outform pem -out cert.pem
    • If your file is in the PKCS #12 format, whose common filename extensions are .pfx and .p12, and contains a certificate, a private key, and possibly other data, extract the certificate using the openssl pkcs12 utility. When prompted, enter the password protecting the private key stored in the file:

      $ openssl pkcs12 -in cert_and_key.p12 -clcerts -nokeys -out cert.pem
      Enter Import Password:
  2. Obtain the administrator’s credentials:

    $ kinit admin
  3. Add the certificate to the user account using the IdM CLI following one of the following methods:

    • Remove the first and last lines (-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----) of the PEM file using the sed utility before adding the string to the ipa user-add-cert command:

      $ ipa user-add-cert some_user --certificate="$(sed -e '/BEGIN CERTIFICATE/d;/END CERTIFICATE/d' cert.pem)"
    • Copy and paste the contents of the certificate file without the first and last lines (-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----) into the ipa user-add-cert command:

      $ ipa user-add-cert some_user --certificate=MIIDlzCCAn+gAwIBAgIBATANBgkqhki...
      Note

      You cannot pass a PEM file containing the certificate as input to the ipa user-add-cert command directly, without first removing the first and last lines (-----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----):

      $ ipa user-add-cert some_user --cert=some_user_cert.pem

      This command results in the "ipa: ERROR: Base64 decoding failed: Incorrect padding" error message.

  4. Optionally, to check if the certificate was accepted by the system:

    [idm_user@r8server]$ ipa user-show some_user

36.2.2. Converting an external certificate in the IdM web UI for loading into an IdM user account:

Procedure

  1. Using the CLI, convert the certificate to the PEM format:

    • If your certificate is in the DER format:

      $ openssl x509 -in cert.crt -inform der -outform pem -out cert.pem
    • If your file is in the PKCS #12 format, whose common filename extensions are .pfx and .p12, and contains a certificate, a private key, and possibly other data, extract the certificate using the openssl pkcs12 utility. When prompted, enter the password protecting the private key stored in the file:

      $ openssl pkcs12 -in cert_and_key.p12 -clcerts -nokeys -out cert.pem
      Enter Import Password:
  2. Open the certificate in an editor and copy the contents. You can include the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" header and footer lines but you do not have to, as both the PEM and base64 formats are accepted by the IdM web UI.
  3. In the IdM web UI, log in as security officer.
  4. Go to IdentityUserssome_user.
  5. Click Add next to Certificates.
  6. Paste the PEM-formatted contents of the certificate into the window that opens.
  7. Click Add.

If the certificate was accepted by the system, you can see it listed among the Certificates in the user profile.

36.3. Preparing to load a certificate into the browser

Before importing a user certificate into the browser, make sure that the certificate and the corresponding private key are in a PKCS #12 format. There are two common situations requiring extra preparatory work:

Afterwards, to import both the CA certificate in the PEM format and the user certificate in the PKCS #12 format into the browser, follow the procedures in Section 41.4, “Configuring a browser to enable certificate authentication” and Section 41.5, “Authenticating to the Identity Management Web UI with a Certificate as an Identity Management User”.

36.3.1. Exporting a certificate and private key from an NSS database into a PKCS #12 file

Procedure

  1. Use the pk12util command to export the certificate from the NSS database to the PKCS12 format. For example, to export the certificate with the some_user nickname from the NSS database stored in the ~/certdb directory into the ~/some_user.p12 file:

    $ pk12util -d ~/certdb -o ~/some_user.p12 -n some_user
    Enter Password or Pin for "NSS Certificate DB":
    Enter password for PKCS12 file:
    Re-enter password:
    pk12util: PKCS12 EXPORT SUCCESSFUL
  2. Set appropriate permissions for the .p12 file:

    # chmod 600 ~/some_user.p12

    Because the PKCS #12 file also contains the private key, it must be protected to prevent other users from using the file. Otherwise, they would be able to impersonate the user.

36.3.2. Combining certificate and private key PEM files into a PKCS #12 file

This section describes how to combine a certificate and the corresponding key stored in separate PEM files into a PKCS #12 file.

Procedure

  • To combine a certificate stored in certfile.cer and a key stored in certfile.key into a certfile.p12 file that contains both the certificate and the key:

    $ openssl pkcs12 -export -in certfile.cer -inkey certfile.key -out certfile.p12

36.4. Certificate-related commands and formats in IdM

Table IdM certificate commands and formats displays certificate-related commands in IdM with acceptable formats.

Table 36.2. IdM certificate commands and formats

CommandAcceptable formatsNotes

ipa user-add-cert some_user --certificate

base64 PEM certificate

 

ipa-server-certinstall

PEM and DER certificate; PKCS#7 certificate chain; PKCS#8 and raw private key; PKCS#12 certificate and private key

 

ipa-cacert-manage install

DER; PEM; PKCS#7

 

ipa-cacert-manage renew --external-cert-file

PEM and DER certificate; PKCS#7 certificate chain

 

ipa-ca-install --external-cert-file

PEM and DER certificate; PKCS#7 certificate chain

 

ipa cert-show <cert serial> --certificate-out /path/to/file.pem

N/A

Creates the PEM-encoded file.pem file with the certificate having the <cert_serial> serial number.

ipa cert-show <cert serial> --certificate-out /path/to/file.pem

N/A

Creates the PEM-encoded file.pem file with the certificate having the <cert_serial> serial number. If the --chain option is used, the PEM file contains the certificate including the certificate chain.

ipa cert-request --certificate-out=FILE /path/to/req.csr

N/A

Creates the req.csr file in the PEM format with the new certificate.

ipa cert-request --certificate-out=FILE /path/to/req.csr

N/A

Creates the req.csr file in the PEM format with the new certificate. If the --chain option is used, the PEM file contains the certificate including the certificate chain.