Chapter 5. Converting certificate formats to work with IdM


Learn how to use the correct formats of certificates with specific IdM commands. This is useful, for example, in the following situations:

5.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 5.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, …​

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
    Copy to Clipboard
  • 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
    Copy to Clipboard

Useful certificate commands

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

$ openssl x509 -noout -text -in ca.pem
Copy to Clipboard

To compare in which lines two certificates differ:

$ diff cert1.crt cert2.crt
Copy to Clipboard

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

$ diff cert1.crt cert2.crt -y
Copy to Clipboard

5.2. 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.

Follow this procedure to convert an external certificate to PEM format and add it to an IdM user account using the IdM CLI.

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
      Copy to Clipboard
    • 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:
      Copy to Clipboard
  2. Obtain the administrator’s credentials:

    $ kinit admin
    Copy to Clipboard
  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 to Clipboard
    • 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...
      Copy to Clipboard
      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
      Copy to Clipboard

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

  4. To check if the certificate was accepted by the system:

    $ ipa user-show some_user
    Copy to Clipboard

5.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 Configuring a browser to enable certificate authentication and Authenticating to the Identity Management Web UI with a Certificate as an Identity Management User.

5.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
    Copy to Clipboard
  2. Set appropriate permissions for the .p12 file:

    # chmod 600 ~/some_user.p12
    Copy to Clipboard

    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.

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

Follow this procedure 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
    Copy to Clipboard
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat