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 (and the response messages such as cp and kup are constructed and sent back to clients):

• Initialization request (ir)
• Certification request (cr)
• Legacy PKCS #10 Certification Request (p10cr) 
• 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 (and for the p10cr message type the format should be as defined in RFC 2986).

EJBCA does not support CMPv1 as defined in RFC2510

Aliases and Multitenancy 

As with its other enrolment 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.

An alias provides a separate endpoint for enrolment 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.

Client and RA Operational Modes

EJBCA can work in the following modes with CMP:

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). Since EJBCA 8.0.0 it is possible to have concurrent requests involving the same end-entity, but it will still generate error messages in the server log (which are harmless), and the performance may be degraded. Therefore, it is recommended to use unique usernames if there could be concurrent requests.

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. This type of authentication is not supported for legacy p10cr requests.
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. In 7.11 support for PBMAC1 was added. PBMAC1 can be used as the protection type instead of the default passwordBasedMac that is described in the CMP RFC 4210. PBMAC1 support for CMP is currently in draft as part of the CMP Lightweight Profile. Using PBMAC1 does not require any configuration. It will automatically be detected if the incoming CMP message has PBMAC1 in its protection header and the MAC will be checked with the configured HMAC password. The difference between passwordBasedMac and PBMAC1 is that PBMAC1 makes it possible to define more detailed parameters, such as derived key length.
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 selecting multiple modules under CMP Authentication Module. 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: CMP#pbe and CMP#signature.

If a CMP request fails, EJBCA returns a CMP error message. In order to align with Lightweight CMP Profile (RFC 9483) as far as possible, EJBCA tries to sign the CMP error messages sent back to the client whenever possible. EJBCA first tries to determine the CA from the request in order to have it sign the message. If this is not possible, the default CA from the CMP alias will be used. In case this also fails, the message will be sent unprotected. EJBCA does not sign CMP error messages when the request is HMAC protected or when the error messages are sent during Extended Validation.

Note: pbe is only available in RA Mode. 

 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.
If the protection type of the incoming request is PBMAC1, the response will also be protected with PBMAC1, and the same goes for the default passwordBasedMac protection type.

 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 (in case of p10cr requests, validity is decided by issuing CA validity).
• Signature POPO is used.

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

After issuance in client mode, the End entity status is set to GENERATED and another certificate cannot be requested. This is a security function, i.e. making the enrollment code a one-time code, preventing an untrusted client from disrupting the service by issuing many certificates. RA mode allows for unlimited issuance from a trusted entity, i.e. the RA. If several certificates needed to be issued in client mode, a designated number of certificates can be set in "Number of allowed requests" configured in the End Entity Profile and the End Entity when added/edited.

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) or the legacy p10cr certification request format.

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 (this does not apply for p10cr certificate request massage type). 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

If the end entity has a Vendor certificate with which it should identify itself for initial enrolment, 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) (in case of p10cr request it is fetched from CSR).
• 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 (not applicable for p10cr type).
• raVerify POPO is used (not applicable for p10cr type).
• 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.

When using the CMP protocol in a RA-CA setup and utilizing the EndEntityCertificate authentication module, it is important to ensure that the admin role of the Peer Connection (on the CA side) has view rights to the profile of the end entity involved in the kur request sent to the CMP server. Failure to do so will result in errors like:
00:00:00,000 INFO [org.ejbca.core.protocol.cmp.CrmfKeyUpdateHandler] (EJB default - 1) Administrator 127.0.0.1 [via] CN=localhost,O=EJBCA RA,C=SE is not authorized to retrieve end entity

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 (applies in case of p10cr type) 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:

The above mentioned PoPo methods are only applicable for the CRMF certificate request message type! In case of p10cr message type proof of ownership is signature verification. Creating a PKCS10 request basically involves specifying the identity you want the final certificate to be associated with and then signing the structure containing that information. The idea being that if the enclosed public key can verify the signature when the certificate authority (CA) looks at the request later the structure must have been signed using the corresponding private key.

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 namedCurve must be 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().

Server generated keys are not applicable in case of p10cr request type, as there is always a public key must be present in the corresponding request which arrives at the CA.

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.

In case of p10cr request type, validity are imposed by the validity defined at the CA which handles the request. 

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. In order to align with Lightweight CMP Profile (RFC 9483) as far as possible, EJBCA tries to sign CMP error messages sent back to the client whenever possible. EJBCA first tries to determine the CA from the request in order to have it sign the message. If this is not possible, the default CA from the CMP alias will be used. In case this also fails the message will be sent unprotected. EJBCA does not sign CMP error messages when the request is HMAC protected or when the error messages are sent during Extended Validation. 

Extended Validation

ENTERPRISE

Extended Validation performs CMP message validation on RA nodes before they reach the CA. Those validations include message protection verification (HMAC/signature) as well as certificate validity and status validation. As of 7.11, HMAC validation is only performed in RA Mode. Extended validation is enabled in the CMP Alias configuration (System Configuration  CMP Configuration).