Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 5. Converting certificate formats to work with IdM

Administrators format certificates correctly to ensure compatibility with IdM commands. Common tasks include loading external certificates into user profiles, configuring smart card authentication, and exporting credentials for browser compatibility.

5.1. Certificate formats and encodings in IdM
Copy link

IdM authentication verifies user identity by comparing the presented certificate against the stored profile data. While the profile stores only the public certificate, the user must prove possession of the corresponding private key during the authentication process.

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.

Expand
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

  • 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

The IdM CLI requires certificates in a specific stripped PEM format. Administrators use OpenSSL to convert binary DER or PKCS #12 files into PEM strings, removing the header and footer lines before adding them to user entries by using the ipa user-add-cert command.

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. To check if the certificate was accepted by the system: 

    $ ipa user-show some_user

The IdM Web UI simplifies certificate management by accepting standard PEM or Base64 formats with or without headers. Administrators convert source files by using OpenSSL and paste the resulting text directly into the user profile interface.

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 Identity Users <user_name>.
  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.

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.

The pk12util tool exports cryptographic pairs from the NSS database into a portable format. This command extracts the specified certificate and its private key into a password-protected .p12 file suitable for browser import.

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.

You can combine a certificate and the corresponding key stored in separate PEM files into a PKCS #12 file by using the openssl command.

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

© 2026 Red HatBack to top