Required files and details

• Address of the Certificate Management Protocol (CMP) alias' endpoint (for example, https://my.ejbca.server/ejbca/publicweb/cmp/myCmpAlias)
• Names of all the certificate profiles configured in EJBCA
• When using HMAC: Shared secret from CA config (if configured globally) or CMP config (if customized for alias)
• When using client auth: P12 file containing admin keypair and its password (for example, officer.p12)
• When using HTTPS endpoint (this is recommended and may require client cert auth): server certificate of EJBCA (for example, ejbcaserver.crt)

Plain requests

If you need plain requests, you must also configure Certificate Manager (CM) and the CM connector for key archival and recovery. The following details are required:

• Name of Identity Manager CA configuration for CM
• Name of CM recovery token procedure
• CM must have key archival token procedures with key generation supported by the the respective EJBCA profiles (for example, RSA 4096 bit)

• CM must have an import CA with configured P10 import token procedure for import of EJBCA certificates
  Set this in the CM connector configuration file nexus_cm.properties via

  caTokenProcedureImportCert=NameOfTheImportProcedure

  This import CA must have a dummy self-signed keypair and have the same subject DN as the EJBCA issuing CA.

Multiple different issuers

If there are multiple issuers, you need the following per issuer:

• Import CA config in CM

  You might have to create a new certificate format file for CM, which allows you to match the subject DN of the issuing EJBCA cert in attributes and order, in case the CM's default config does not fit. See "HTTPS works with client auth but fails with HMAC" under Troubleshooting below for details.

• CM connector configuration, specifying the import token procedure

• EJBCA connector configuration, referencing the CM configuration as key archive

1. Create a file called ejbca.properties. There are two options:

   1. In case of HMAC, specify like this (do not specify absolute or relative paths, just the filenames):
      

      ejbca.properties (with HMAC)

      useHmac = true
      # optional when using http
      #serverCert = ejbcaserver.crt
      # add profiles as needed
      certProfiles = SOME_KEY_ARCHIVAL_PROFILE,SOME_P10_PROFILE,ANOTHER_P10_PROFILE,EJBCA_Recovery
      # these are optional if we don't use key archival/recovery
      keyArchive=NameOfCMConfigInPrimeForEJBCAKeyArchivalAndRecovery
      ejbcaToCMCertTemplateMapping=EJBCA_Recovery=RecoveryTokenProcInCM;SOME_KEY_ARCHIVAL_PROFILE=KeyArchivalTokenProcInCM
      

   2. Or in case of client auth, specify like this:
      

      ejbca.properties (with client auth)

      # optional, as false is default
      # useHmac = false
      clientCert = officer.p12
      serverCert = ejbcaserver.crt
      # add profiles as needed
      certProfiles = SOME_KEY_ARCHIVAL_PROFILE,SOME_P10_PROFILE,ANOTHER_P10_PROFILE,EJBCA_Recovery
      # these are optional if we don't use key archival/recovery
      keyArchive=NameOfCMConfigInPrimeForEJBCAKeyArchivalAndRecovery
      ejbcaToCMCertTemplateMapping=EJBCA_Recovery=RecoveryTokenProcInCM;SOME_KEY_ARCHIVAL_PROFILE=KeyArchivalTokenProcInCM

      
      

2. Create a ZIP file containing in its root the following files:
   1. always:

      1. ejbca.properties (the name is fixed)
         

   2. if using HTTPS, then also:

      1. ejbcaserver.crt (this is an example, the name can vary)
         

   3. if using client auth, then also:

      1. officer.p12 (this is an example, the name can vary)
         

To configure the EJBCA connector into Identity Manager Admin:

1. Log in to Identity Manager Admin.
2. Go to Home > Certification Authorities (CA) and click New.

3. Enter Name of the EJBCA connector. Click Save+Edit.

4. Select Connection type EJBCA.

5. Click Upload and upload the zip file created under "Preparations" above.

6. Set the desired CMP endpoint as CA host, as mentioned under "Preparations" above.

7. Set the Signing password to:

   1. the shared secret, if you set useHmac=true

   2. otherwise set it to the client auth P12 password.

8. Click Save to save the configuration and go to the Details tab.
9. Click Search on the right hand side. All EJBCA CA certificate types are fetched and all configurable certificate types are shown. Click Apply.
   
10. Click Testing. All connections should be green.
11. Click Save.

The following certificate states for revocation requests are supported:

These are the limitations: 

• Verification of the PKCS#10 self-signature ("proof of possession") works only within the connector and for RSA keys only.
  • Make sure to allow skipping proof of possession validation in the CMP alias config.
• Let EJBCA provide the CA certs, that is, do not add external root certificates from a file, since this is deprecated.
• All credentials have to be configured in the CA config itself. There are no means to override them within the request.
• Nexus CM is used for key archival and recovery, since an externally hosted EJBCA service may not offer these.
• Certain certificate attributes do not work with EJBCA:
  
  • Avoid having multiple RDNs of the same type (for example, OU=this, OU=that) in the DNs of your certificate requests as EJBCA rejects these.
  • POSTALADDRESS is not compatible with EJBCA as it expect a different encoding format.
  • See https://doc.primekey.com/ejbca/ejbca-operations/ejbca-ca-concept-guide/end-entities-overview/end-entity-profiles-overview/end-entity-profiles-fields

I cannot view all EJBCA profiles to find out how they are configured

• Reason: You are likely using an older version of EJBCA which does not have the "View" option in addition to "Edit", which does not work on built-in profiles.
• Workaround: Clone the profile you are interested in into a temporary copy and click "Edit" on the clone to view its settings.
• Solution: Update to a newer version.

HTTPS works with client auth but fails with HMAC

• Reason: Your EJBCA instance might have its HTTPS endpoints configured to require client auth on the CMP endpoints (ejbca/publicweb/cmp/*) (this might have been done via application server and/or embedded Tomcat and/or reverse proxy) 
• Solution: You have the following options:
  1. Reconfigure EJBCA and its associated software to make client auth optional on the CMP endpoints
  2. Use client cert auth instead of HMAC
  3. Use HTTP (not recommended)

Failed import during key archival

• Reason: If key archival fails with a message like this...
  

  Aug 09, 2019 8:25:47 AM com.smarttrust.cm.sdk.Request logError
  SEVERE: ImportCertificateRequest Server error: 7, Certificate not issued by CA: cn=ManagementCA,o=EJBCA Sample,c=SE
  Aug 09, 2019 8:25:47 AM com.smarttrust.cm.sdk.Request logException
  SEVERE: ImportCertificateRequest.execute() Server error: 7, Certificate not issued by CA: cn=ManagementCA,o=EJBCA Sample,c=SE
  com.smarttrust.cm.sdk.RequestException: Certificate not issued by CA: cn=ManagementCA,o=EJBCA Sample,c=SE
      at com.smarttrust.cm.sdk.ProcedureRequest.createResponseError(ProcedureRequest.java:58)

  ... then most likely the DN attribute order of the key archival CA cert differs from the order in the issuing EJBCA cert.

• Solution: Either you:
  1. Configure EJBCA with a new (intermediate) cert that uses a compatible DN, OR
  2. Reconfigure CM as follows: (which is not always possible, as CM does not support certain attributes like UID) 

     1. First you have to create a new certificate format from which you are allowed to match the subject DN of the EJBCA cert properly (adjust SubjectNameSpaceOrder and IssuerNameSpaceOrder as needed), for example:
        

        C:\Program Files\Nexus\Certificate Manager\server\config\certformats\SELF-SIGNED CA-CERT EJBCA.conf

        [Info]
        FileFormatVersion=1
        Description=For EJBCA. Self signed CA certificate format. Creates a PKIX compatible CA certificate with the extensions BasicConstraints (critical, CA=true, no pathLength) and SubjectKeyIdentifier. The subject and issuer fields are encoded as either PrintableString or UTF8String. It's recommended to avoid national characters. A SubjectAltName extension with an email address is optionally created.
        Type=ca
        Visible=true
        include = rfc5280CA.conf
        [FormatDefinitionFields]
        SubjectNameSpaceOrder=cn,dmd,o,organisationidentifier,ou,c
        IssuerNameSpaceOrder=cn,dmd,o,organisationidentifier,ou,c

     2. Restart CM services for the new format to become available.
     3. Create EJBCA Key Archive CA in CM which uses the new format.
        

Using certificate templates EncHardCodedValues(P10) fail with EJBCA

• Reason: The cert attributes in these templates are partially incompatible with EJBCA. For example, the e-mail address is incorrectly formatted, multiple OU attributes are not supported, etc.
• Solution: Check the log messages and adjust the attributes accordingly.