CMP

The following includes information about the Certificate Management Protocol (CMP) and how it works with EJBCA.

For guides, configurations and workflows using CMP, see the CMP Operations Guide.

Introduction

The Certificate Management Protocol (CMP) is an Internet protocol used for obtaining X.509 digital certificates in a public key infrastructure (PKI). It is described in RFC4210 and is one of two protocols to use the Certificate Request Message Format (CRMF), described in RFC4211.

EJBCA supports the following messages of the complex CMP protocol, as defined in RFC4210:

  • Initialization request (ir)

  • Certification request (cr)

  • Certification confirm (certConf)

  • Revocation request (rr)

  • NestedMessageContent (nested)

  • Key Update Request (kur)

Certificate requests are expected to use the Certificate Request Message Format as defined in RFC4211.

EJBCA does not support CMPv1 as defined in RFC2510

Aliases and Multitenancy

As with its other enrollment protocols, EJBCA provides multitenancy (the ability for several disjunct actors to use the same CA without being aware of each other) through a system of aliases.

images/download/attachments/141983997/Screenshot_2022-01-20_at_08.58.39.png

An alias provides a separate endpoint for enrollment by adding the alias name to the endpoint URL, e.g http://127.0.0.1:8080/ejbca/publicweb/cmp/cmpalias. Each alias also provides a separate configuration for each endpoint, allowing each alias to use its own certificate profiles, PoPo settings, etc.

images/download/attachments/141983997/Screenshot_2022-01-20_at_15.23.14.png

Client and RA Operational Modes

EJBCA can work in the following modes with CMP:

Client Mode

Client Mode assumes that the end entity has already been created, and that the enrolling client is purely submitting a key pair to be signed. When the request comes in, EJBCA verifies the request (see CMP Message Authentication) and issues a certificate to a user that has been previously registered in EJBCA. If the requested end entity does not exist, the request will fail.

RA Mode

RA Mode instead assumes that the CMP client is a trusted entity and thus allows it to enroll end entities in the same action as submitting the keys for signature. In RA mode, EJBCA supports several CAs and profiles based on the use of configuration alias specified in the URL used (see CMP over HTTP).


The EJBCA implementation of Certificate Confirm (certConf) only strictly adhere to RFC4210 if the certificate is not published to an external repository. RFC4210 section 4.2.2.2, with details in sections 5.3.18 and 5.2.8, specify certConf and that a certificate must be revoked if not accepted by the client through a certConf if it has been published or otherwise made available. EJBCA will not revoke certificates that are not accepted. In fact, certConf is mostly ignored, but a PKI Confirm message (RFC4210 section 5.3.17) is sent back to the client. The CA will never revoke a certificate based on a certConf message, or the lack thereof. Generally, CMP use cases would benefit from using the ImplicitConfirm method specified in section 5.1.1.1 of RFC4210.

Using CMP with EJBCA supports high transaction volumes with multiple concurrent transactions, enabling for high speed (hundreds of requests/second). However, if your CMP alias is configured for static/re-use of End Entities, making parallel requests to issue certificates for the same End Entity is not supported and will result in one of the transactions failing with database transaction error, indicating that the concurrent transactions tried to modify the same End Entity at the same time. This may be improved and implemented in a future version of EJBCA, but as of EJBCA 7.3.0, it is not a supported mode of operation.

CMP Message Authentication

EJBCA supports four modules for message authentication, configured in the CA UI under CMP Configuration.

The supported modules are either password extractors or PKIMessage verifiers:

Module

Description

Password extractors (client mode only)

RegTokenPwd

Extracts the password from the CMP request through the means of a regToken control (id-regCtrl-regToken) in the CRMF message. The regToken is a UTF8String containing the user password as registered in EJBCA. This module requires no parameters.

DnPartPwd

Extracts the password from the subjectDN of the user the request concerns. As a parameter, the DN part that contains the password should be specified. For example, if the subjectDN is "CN=name,C=se,UID=PASSWORD", the parameters should be set to "UID".

PKIMessage verifiers

HMAC

This module uses a shared secret to authenticate the CMP message:

  • In RA mode, the shared secret is set as a parameter to this module. If no parameter is specified, EJBCA uses the shared secret specified in the CA under CMP RA Authentication Secret.

  • In client mode, the pre-registered end entity will be looked up in the database, and if there was a clear text password there, this password will be used to authenticate the message. If there is no clear text password associated with that end entity, the authentication will fail.

EndEntityCertificate

When the EndEntityCertificate module is used, the request sender should attach his certificate in the extraCert field in the PKIMessage and then sign the message with his private key.

  • In client mode, a user may only send a CMP request regarding his/her own certificate. EJBCA will then check if the certificate in extraCert does exist in its database and verifies that it belongs to the sender before verifying the signature. No parameters should be specified for this module in client mode.

  • In RA mode, as a parameter, this module expects the name of the CA that has issued the certificate in the extraCert field. If a parameter is specified, EJBCA checks if the certificate in extraCert does exist in the database, that it was issued by the right CA (the CA specified as a parameter), and that it belongs to a registered administrator in EJBCA with the right authorizations to perform the operations required in the request. If no parameter is specified, none of the mentioned checks will be performed. However, EJBCA will expect the CMP request to have been previously authenticated by other ways, for example, by sending the request inside a signed NestedMessageContent.

You can specify more than one module in the CA UI CMP Configuration page by separating the modules with a semicolon ";". If specifying multiple modules, the first module is used for authentication testing. If the first module fails, the second module is used for authentication testing, and so on until a successful authentication is done or all alternatives fail.

CMP Response Messages

When a CMP request is successful, EJBCA returns a protected CMP response message. The protection type of the response message can also be configured in the CA UI under CMP Configuration. EJBCA supports the following types of response message protection: pbe and signature.

If a CMP request fails, EJBCA returns an unprotected, unencrypted CMP error message.

pbe

This type of protection of the response message can be used only when the request was authenticated using HMAC authentication module. The parameters used for the pbe protection are based on the parameters used in the received HMAC authentication.

signature

The CA used to handle the CMP request signs the CMP response message using the same protection algorithm specified in the CMP request. If a conflict occurs between the protection algorithm in the request and the CA's signature algorithm, the CA's key algorithm will be used in combination with a digest algorithm based on the protection algorithm in the CMP request. If a conflict occurs even on the digest algorithm level, a default digest algorithm will be used. For example, if the CMP request uses the protection algorithm ECDSA with SHA1 and the CA's signature algorithm is RSA with SHA256, the CMP response will be signed using RSA with SHA1.

The signature type of response protection can be used regardless of what authentication module was used to authenticate the CMP request.

CMP messages are signed using the CAs signature key. Verification of the signed CMP messages hence typically assumes that overly strict enforcement of Key Usage in CA certificate is not in place (similar to allow signing of OCSP responses under the CRLSign Key Usage).

The CA certificates returned with the CMP response message can be configured in the CMP configuration. For a list of CMP error codes, see CMP Error Messages.

CMP Response Additional CA Certificates

Additional CA certificates available in EJBCA can be added to the CMP response message (CertRepMessage.caPubs). Independent from the additional CA certificates configured, the signing CA certificate is returned at index 0 every time.

PKI Message Response Additional CA Certificates

Additional CA certificates available in EJBCA can be added to the CMP response wrapping PKI message (PKIMessage.extraCerts). Independent from the additional CA certificates configured, the response message signing CA certificate chain is included from index 0 every time.

Client Mode for CMP

Client mode is used when the CMP client will act as an End Entity to EJBCA. This means that the End Entity must be pre-registered in EJBCA and that the client request is authenticated with this pre-registered end entity before a certificate is issued. This is the same authentication model as for regular enrollment, i.e. browser enrollment, using a username/password combination.

  • The users DN is deducted from the request according to rules configured.

  • The username in EJBCA must be pre-registered.

  • The password for the user in EJBCA must be passed in the request (one-time password).

  • If the Certificate Profile allows it, keyUsage, validity and extensions are also taken from the CertTemplate in the request message.

  • Signature POPO is used.

After the user has been authenticated in EJBCA, a certificate is generated as usual and sent back to the client.

To use client mode, no particular configuration is needed, since this is the default mode.

User look-up

Initialization and certification requests uses the CRMF request message (RFC4211).

Users can be looked up from the request in different ways, as configured in the CA UI under CMP Configuration. By default the subject DN from the certTemplate in the request is used to look up the used in EJBCA. You can also configure EJBCA to use the CN or the UID from the subject DN as the username in EJBCA.

Vendor CA Authentication

ENTERPRISE This is an EJBCA Enterprise feature.

If the end entity has a Vendor certificate with which it should identify itself for initial enrollment, as specified in 3GPP for example, it can also do that. In this case the CA issuing the end entity certificate is not the same as the Vendor CA. The vendor CA must be imported in EJBCA as an External CA (CA UI → Import CA certificate). This is described in detail in the integration guide for 3GPP available with EJBCA Enterprise.

RA Mode for CMP

RA mode is used when the CMP client will act as an RA to EJBCA. When the RA sends a certificate request to EJBCA, no user needs to be pre-registered in EJBCA. When EJBCA receives the request, the message will be authenticated. After it has been authenticated, a user is created, and a certificate is issued.

  • The users DN is taken from the CertTemplate in the request message send from the RA (i.e. the DN requested by the RA).

  • The username in EJBCA is generated according to the options configured.

  • The password for the user in EJBCA is random.

  • If the Certificate Profile allows it, keyUsage, validity and extensions are also taken from the CertTemplate in the request message.

  • raVerify POPO is used.

  • Messages are authenticated using one of the configured authentication modules.

After the user has been created in EJBCA, a certificate is generated as usual and sent back to the RA, who will distribute it to the end-user.

If the same username is constructed (for example UID) as an already existing user, the existing user will be modified with new values for profile etc, and a new certificate will be issued for that user.

KeyID

Instead of specifying an RA End Entity Profile, RA Certificate Profile, and/or RA CA Name explicitly when creating a CMP alias, you can choose the KeyID option. When this option is selected, the value of the senderKID field in the CMP request is used instead of the corresponding entry in the CMP alias (which is set to KeyID). The client sending the CMP request must ensure the correctness of the CMP request, for example. that the CA and Certificate Profile is authorized by the End Entity profile.

Note that KeyID is only visible when the number of available options is at least two.

KeyID is useful when you want to issue different types of certificates using a single CMP alias. The EJBCA cmpclient tool allows you to set KeyID explicitly using the --keyid argument.

Multiprotection Support

In RA mode, it is also possible to send a CMP request with multiple signatures. EJBCA implements this feature following the specifications in RFC4210. In cases where an end entity sends a protected PKI message to an RA, the RA forwards that message to a CA, attaching its own signature for protection. This is accomplished by nesting the entire message sent by the end entity within a new PKI message. For a sample of what such a message might look like, see the CMP Operations Guide.

Sample Configuration

A sample configuration of EJBCA to allow an RA to request certificates for users. The RA uses password based mac (pbe) protection of CMP messages with password password. Users will be created using UID from the request DN and with a prefix, so the resulting username will be: cmp<UsersUID>. End entity profiles names CMP_ENTITY and CMP_CERT is created in EJBCA allowing the request DN.

CMP Operational Mode : RA Mode
Allow RA Verify Proof-of-Possession : check
CMP Response Protection : pbe
CMP Authentication Module : HMAC
CMP Authentication Parameters : password
RA Name Generation Scheme : DN
RA Name Generation Parameters : UID
RA Name Generation Prefix : cmp
RA End Entity Profile : CMP_ENTITY
RA Certificate Profile : CMP_CERT
RA CA Name : ManagementCA

Using one Authentication Secret per CA

Edit each CAs that should be used for CMP certificate issuance and enter new CMP RA Authentication Secret. There should be no parameter specified for the HMAC authentication module, otherwise, this parameter will override the CA specific configuration.

Key Update Request (kur)

Also known as the Certificate Update request. When a key pair is due to expire, the relevant end entity may request a key update. The CMP request is signed, and the sender attaches their certificate in the extraCert field in the CMP message.

In Client Mode

In client mode, the only end entity that is allowed to send a KeyUpdate request is the end entity that owns the certificate to be renewed. This end entity should be the one signing the request and attaching its "old" certificate (that has not been expired yet) to the CMP message. The CA will only look into the certificate in extraCert to find which certificate is to be updated.

In RA Mode

In RA mode, an administrator is allowed to send a KeyUpdate request on behalf of an end entity. The administrator should be the one signing the request and attaching his own certificate to the CMP message. Either only the subjectDN or both the subjectDN and the issuerDN of the certificate to be updated are specified in the CertificateTemplate field in the CMP message.

In order for this request to succeed, the administrator sending the update request has to be authorized to perform this operation. Also, EndEntityCertificate authentication module would have to be set among the configured authentication modules.

Neither CMP (RFC4210) nor 3GPP 33.310 mandate any specific times when key update can occur. Hence a client may send a Key Update Request (kur) at any time, as long as it is authenticated using the old certificate/key.

Proof of Possession

Proof of Possession (PoPo) is the act of proving that you control the private key of the public key you're attempting to certify. EJBCA supports several PoPo methods through CMP:

Method

Description

raVerify

Delegates checking PoPo to an RA placed ahead of EJBCA, and will cause EJBCA to not perform any PoPo verification. Not recommended by the standards.

signature

PublicKey is in the CertTemplate and the signature is calculated over the CertReqMsg.certReq (the standard procedure when the CertTemplate contains the subject and publicKey values).

signature with POPOSigningKeyInput

PublicKey and subject DN is in POPOSigningKeyInput, possibly just copied from the CertTemplate. The signature is calculated over the POPOSigningKeyInput (if the values are also in the CertTemplate they must be identical).

Server Generated Keys

CMP allows clients to request server generated keys, using one of the following in the CRMF certificate request:

  • Leaving out the (optional) request public key in the CRMF request.

  • Adding a subjectPublicKeyInfo containing an AlgorithmIdentifier followed by a zero-length BIT STRING for the subjectPublicKey (RFC4210 Appendix D.4).

These options enable a large number of choices and taking into consideration that the server wants to restrict what type of keys the clients can request and certify, there are a number of rather strict rules and business logic used by EJBCA. The following list highlights these choices.

Note that the following only applies if server generated keys are enabled in the CMP alias configuration. Use of server generated keys are by default disabled, and the default behavior is thus that all request for server generated keys are denied.

  • If the request does not contain a request public key, key generation options are taken from the certificate profile that will be used to issue the certificate:

    • The certificate profile must contain only one allowed key algorithm and one allowed key specification, for example RSA 1024 or ECDSA secp256r1.

    • If there is not a single distinct choice, the request will be denied, and an error returned to the client.

  • If the certificate profile contains a subjectPublicKeyInfo with the RSA algorithmId (rsaEncryption = 1.2.840.113549.1.1.1) the certificate profile must contain a single choice of key sizes allowed.

    • If there is not a single distinct choice, the request will be denied

  • If the certificate profile contains a subjectPublicKeyInfo with the ECDSA algorithmId (id_ecPublicKey = 1.2.840.10045.2.1), the subjectPublicKeyInfo must contain parameters where two choices are allowed:

    • implicitlyCA: The certificate profile must contain a single choice of curves allowed, otherwise the request will be denied.

    • namedCurve: With the OID of a supported named curve, which is among the allowed curves in the certificate profile.

These rules allow the CA administrator to control what server generated keys the CA will generate and return to the client, and can be summarized as:

  • A distinct choice of a single key algorithm and key size/curve, defined in the certificate profile.

  • A choice of a single RSA key size and a set of EC curves, defined in the certificate profile and selected by the client in the request.

Currently, RSA and EC keys are supported.

In order to support server generated, the client must include a id_regCtrl_protocolEncrKey in the request, containing a public key that the server will use to encrypt the private key returned in the response.

Server generated keys are returned in the CertifiedKeyPair.privateKey field in the response, as defined in the RFC4210 sections 5.3.4 and D.4. The EncryptedValue will contain the private key, encrypted using AES256 with a random symmetric key, in turn wrapped using the public key in id_regCtrl_protocolEncrKey (RFC4211 Appendix B have more details on the EncryptedValue).

Code example in Java for requesting server generated keys can be found in the test method CrmfRequestTest.test12ServerGeneratedKeys().

Certificate Validity

Generally, the validity period of issued certificates is controlled by the certificate profile. If you enable Allow validity override in the certificate profile, and the CMP initialization- or certification request contains a validity time in the CRMF request template, this validity period will be used.

Certificate Key Usage

Generally, the key usage extension of issued certificates are controlled by the certificate profile. If you enable Allow Key Usage Override in the certificate profile, and the CMP initialization- or certification request contains a key usage in the CRMF request template, this key usage will be used.

Interoperability with 3GPP/4G/LTE

To read more about using CMP with 3GPP in EJBCA, see Using CMP with 3GPP.

Interoperability / Tested Libraries and Devices

To read more about EJBCA's interoperability with various clients, devices and libraries, see CMP Interoperability.

CMP Error Messages

If issues occur during CMP processing, different CMP error messages or HTTP error codes are returned depending on issue type and when it is encountered. For a complete list of all CMP error codes, see CMP Error Messages.

CMP Proxy

ENTERPRISE This is an EJBCA Enterprise feature.

In some installations it may be desirable to terminate the client connection in a DMZ before connecting further to the CA. In this case the client never has a direct network connection to the CA machine. In such a scenario you can use the CMP Proxy module.