Chapter 5. Converting certificate formats to work with IdM
Chapter 5. 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: You are loading an external certificate into a user profile. For details, see Converting an external certificate to load into an IdM user account . You are using an external CA certificate when configuring the IdM server for smart card authentication or configuring the IdM client for smart card authentication so that users can authenticate to IdM using smart cards with certificates on them that have been issued by the external certificate authority. You are exporting a certificate from an NSS database into a pkcs #12 format that includes both the certificate and the private key. For details, see Exporting a certificate and private key from an NSS database into a PKCS #12 file . 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 format Human-readable Common filename extensions Sample 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: 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: Useful certificate commands To view the certificate data, such as the subject and the issuer: To compare in which lines two certificates differ: To compare in which lines two certificates differ with the output displayed in two columns: 5.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. 5.2.1. 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. 5.2.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 Convert the certificate to the PEM format: If your certificate is in the DER format: 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: Obtain the administrator's credentials: 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: 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: 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-----): This command results in the "ipa: ERROR: Base64 decoding failed: Incorrect padding" error message. To check if the certificate was accepted by the system: 5.2.3. Converting an external certificate in the IdM web UI for loading into an IdM user account Follow this procedure to convert an external certificate to PEM format and add it to an IdM user account in the IdM web UI. Procedure Using the CLI , convert the certificate to the PEM format: If your certificate is in the DER format: 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: 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. In the IdM web UI, log in as security officer. Go to Identity Users some_user . Click Add to Certificates . Paste the PEM-formatted contents of the certificate into the window that opens. Click Add . If the certificate was accepted by the system, you can see it listed among the Certificates in the user profile. 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: The certificate is located in an NSS database. For details how to proceed in this situation, see Exporting a certificate and private key from an NSS database into a PKCS #12 file . The certificate and the private key are in two separate PEM files. For details how to proceed in this situation, see Combining certificate and private key PEM files into a PKCS #12 file . 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 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: Set appropriate permissions for the .p12 file: 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: 5.4. Certificate-related commands and formats in IdM The following table displays certificate-related commands in IdM with acceptable formats. Table 5.2. IdM certificate commands and formats Command Acceptable formats Notes 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.
kinit -X X509_user_identity='PKCS11:opensc-pkcs11.so' idm_user kinit -X X509_user_identity='FILE:`/path/to/cert.pem,/path/to/cert.key`' idm_user openssl x509 -noout -text -in ca.pem diff cert1.crt cert2.crt diff cert1.crt cert2.crt -y openssl x509 -in cert.crt -inform der -outform pem -out cert.pem openssl pkcs12 -in cert_and_key.p12 -clcerts -nokeys -out cert.pem Enter Import Password: kinit admin ipa user-add-cert some_user --certificate="USD(sed -e '/BEGIN CERTIFICATE/d;/END CERTIFICATE/d' cert.pem)" ipa user-add-cert some_user --certificate=MIIDlzCCAn+gAwIBAgIBATANBgkqhki ipa user-add-cert some_user --cert=some_user_cert.pem [idm_user@r8server]USD ipa user-show some_user openssl x509 -in cert.crt -inform der -outform pem -out cert.pem openssl pkcs12 -in cert_and_key.p12 -clcerts -nokeys -out cert.pem Enter Import Password: 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 chmod 600 ~/some_user.p12 openssl pkcs12 -export -in certfile.cer -inkey certfile.key -out certfile.p12