Importing Certificates

EJBCA supports importing certificates into the existing database. This can be used for migrating data from other systems, or for importing the external administration certificates into EJBCA. Certificates can be imported induvidually or in bulk.

Importing a Single Certificate

In order to import a single certificate, use the command:

BASH

bin/ejbca.sh ca importcert <username> <password> <caname> <status> --email <email> <certificate file> \[--eeprofile <endentityprofile>\] \[--certprofile <certificateprofile>\] \[--revocation-reason <reason>\] \[--revocation-time <time>\]

The following parameters are available:

username - Username of the end entity which should be owner of the certificate. If the end entity does not exist, it will be created automatically. If the end entity already exists, the imported certificate will be associated with it, and the end entity properties (subject, subject alternative names) will be updated.
password - Password that will be set for the end entity (often called enrollment code in the RA Web).
caname - The name of the CA which has issued the certificate. The certificate's issuer signature will be verified against this CA. If the signature does not match, the certificate will not be imported. The CA certificate must be present in the database (at least as an external CA).
status - Status that should be set for the imported certificate. Supported values are ACTIVE (for valid certificate), and REVOKED (for revoked certificate). The revocation reason for REVOKED certificate will be set to Unspecified.
email - E-mail that will be used for the end entity. If the e-mail is set to string null, it will be taken from the certificate itself.
certificate file - Path to BASE64-encoded PEM file containing the end entity certificate.
endentityprofile - End entity profile used for the certificate. The certificate will be verified against the constraints set forth by this end entity profile. If the constraints are violated by the certificate, it will not be imported. If no end entity profile is supplied, the default EMPTY profile will be used.
certificateprofile - Certificate profile used for the certificate. Once the certificate is imported, it will be marked as belonging to the specified certificate profile. If the certificate profile is not specified, the fixed ENDUSER certificate profile will be used instead.
revocation reason - Allows a revoked certificate to be imported with a specific revocation reason. Use the --help switch to see a list of valid revocation reasons. Will be set to UNSPECIFIED if not specified.
revocation time - Allows a revoked certificate to be imported with a specific revocation time in the format yyyy.MM.dd-HH:mm. Will be set to the current time if not supplied.

Running the command without any parameters will display basic usage help, and a list of acceptable parameter values (for caname, status, endentityprofile, and certificateprofile).

Here's an example usage of the importcert command:

BASH

bin/ejbca.sh ca importcert myuser mypassword SomeCAName ACTIVE --email mymail@example.com mycertificate.pem --eeprofile EMPTY --certprofile ENDUSER

This command would create a new end entity (or use the existing one) in EJBCA called myuser with the supplied password, and add a new active (non-revoked) certificate for this user under the end entity profile EMPTY, using the certificate profile ENDUSER.

Importing Certificates in Bulk

In order to import certificates in bulk, use the command:

BASH

bin/ejbca.sh ca importcertdir <username-source> <caname> <status> <certificate dir> --eeprofile <endentityprofile> --certprofile <certificateprofile> \[-resumeonerror\]  \[--revocation-reason <reason>\] \[--revocation-time <time>\]

The parameters are as follows:

username-source - Specifies how to derive the username of the end entity that will own the certificate. Supported values are CN, DN, and FILE. If set to CN, the username will be equal to the common name attribute present in the certificate subject. If set to DN, the username will be equal to the entire distinguished name (subject) of the certificate. If set to FILE, the username will be the same as the name of the file (extension included). If set to CN, and CN is not present in the subject, the import will first fall back to using DN, or if that is not available as well, to file name. If set to DN, and the subject is not present in the certificate, the import will fall back to using the file name as the username. The end entity will be automatically created if it does not exist already. If the end entity already exists, the imported certificate will be associated with it, and end entity properties will be updated.
caname - The name of the CA which has issued the certificates. The certificate issuer signature will be verified against this CA. If the signature does not match, the certificate will not be imported. The CA certificate must be present in the database (at least as an external CA).
status - Status that should be set for the imported certificates. Supported values are ACTIVE (for valid certificates), and REVOKED (for revoked certificates). The revocation reason for REVOKED certificates will be set to Unspecified.
certificate dir - Path to the directory containing the certificate files. Each file should contain a single certificate. The directory should not contain subdirectories, or non-certificates. The file extension does not matter - all the files will be processed.
endentityprofile - End entity profile used for the certificates. The certificates will be verified against the constraints set forth by the end entity profile. If the constraints are violated by the certificate, it will not be imported.
certificateprofile - Certificate profile used for the certificates. Once the certificate is imported, it will be marked as belonging to the specified certificate profile.
-resumeonerror - This optional switch can be used in order to force the import to proceed even if more serious errors are encountered. By default this option is not enabled. The errors that are covered by this switch, amongst others, are end entity profile constraint violations, problems with reading/parsing of certificate files etc.
revocation reason - Allows a revoked certificate to be imported with a specific revocation reason. Use the --help switch to see a list of valid revocation reasons. Will be set to UNSPECIFIED if not specified.
revocation time - Allows a revoked certificate to be imported with a specific revocation time in the format yyyy.MM.dd-HH:mm. Will be set to the current time if not supplied.

Running the command without any parameters will display basic usage help, and a list of acceptable parameter values (for username-source, status, endentityprofile, and certificateprofile).

Certificates that are already present in the database will be skipped during the import. Certificates that belong to a different CA than the one specified will be skipped as well. Any other discrepancy (like invalid file format, subdirectory, or violated end entity constraints) will stop the import operation, unless the -resumeonerror switch has been enabled. Certificates that have been imported up until the discrepancy will still remain in the database. For each certificate that has been skipped, the command will output its serial number and name of the file. The same information will be displayed for errors.

Once the import has finished, a short summary is displayed about the number of imported certificates, number of redundant (already present) certificates, and number of rejected certificates (that were not signed by the requested CA). No summary will be displayed if abnormal errors are encountered (i.e. anything besides the already present certificate or mismatched CA), unless the -resumeonerror switch has been enabled.

If the -resumeonerror switch has been enabled, the import will continue until all of the entries from the directory are processed. Errors will still be printed-out, and the summary will contain the following additional information:

Number of certificates that could not be read (because of malformed format or because they are directories).
Number of certificates that have violated the end entity constraints (invalid number of subject/subject alternative name fields, wrong values for non-modifiable fields etc).
Number of certificates that could not be read because of other errors.