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 send 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:
|
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. 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:
|
|
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.
|
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.
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.
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.
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 This is an EJBCA Enterprise feature.
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 ModeAllow RA Verify Proof-of-Possession : checkCMP Response Protection : pbeCMP Authentication Module : HMACCMP Authentication Parameters : passwordRA Name Generation Scheme : DNRA Name Generation Parameters : UIDRA Name Generation Prefix : cmpRA End Entity Profile : CMP_ENTITYRA Certificate Profile : CMP_CERTRA CA Name : ManagementCAUsing 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 (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:
|
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). |
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 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().
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.
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.
Related Content
Page:CMP Proxy
Page:CMP Interoperability
Page:CMP Error Messages
Page:Using CMP with 3GPP