Versions Compared

Old Version 4

changes.mady.by.user Josefin Klang (Deactivated)

Saved on

compared with

New Version Current

changes.mady.by.user Ylva Andersson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Minor
Info

This article is valid for Smart ID 20.11 and later.

 This article describes how to connect to the EJBCA certificate authority from Smart ID Identity Manager. For the supported certificate authorities, see Identity Manager requirements IDM 23.10.3 - Requirements and interoperability. 

Prerequisites

Expand
titlePrerequisites

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

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

    Note

    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

Step-by-step instruction

Expand
titlePreparations

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

      Code Block
      titleejbca.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:

      Code Block
      titleejbca.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)

...

Expand
titleTroubleshooting

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

    Code Block
    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:

        Code Block
        titleC:\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.

...

Additional information

Expand
titleUseful links

...