SCEP

This page describes EJBCA support of the SCEP protocol. For guides on how to use SCEP with EJBCA, see the SCEP Operations Guide.

SCEP is a protocol commonly used by network equipment to enroll for certificates. It is also used by MdM and EMM solutions to enroll certificates on behalf of devices such as mobiles. SCEP is specified in the IETF draft Simple Certificate Enrollment Protocol (draft-nourse-scep-23).

SCEP has in general use been supplanted by the similar EST protocol, which we recommend as an alternative.

There are some compatibility issues with SCEP, one being whether the CA certificate should be returned in a SCEP enrollment response or not. The CA certificate is optional (and configurable in EJBCA), and some clients such as the Cisco VPN client require it while others, such as Juniper's, prohibit it.

Supported Operations

EJBCA implements features as of (at least) draft 23 of the SCEP specification. The following SCEP messages are implemented:

  • PKCSReq including Client Certificate Renewal

  • GetCRL

  • GetCACert

  • GetCACertChain

  • GetCACaps

  • GetNextCACert

  • GetCertInitial

The following CA capabilities are supported:

  • POSTPKIOperation

  • SHA-512

  • SHA-256

  • SHA-1

  • DES3

  • Client Certificate Renewal (Enterprise Edition only)

Note that EJBCA returns proper SCEP error messages for the majority of failures, but not in all cases of failure.

Operational Modes

SCEP can be run in either CA Mode or RA Mode. In CA mode EJBCA acts in a basic CA capacity under the assumption that RA functions (i.e enrollment) are handled by an administrator directly in the RA UI or by a third party acting as RA. In RA mode EJBCA interfaces directly with the client, enrolling the end entity and then issuing the certificate all on its own.

CA Mode

In CA mode, EJBCA receives SCEP PKCSReq requests and sends back the certificate/CRL immediately in a proper SCEP reply message. The SCEP client will send messages directly to the CA, encrypted with the CAs certificate and the CA will authenticate/authorize the request based on username and enrollment code of an end entity pre-created in EJBCA. This mode does not support the 'polling' model, EJBCA uses the direct CA method, where a request is granted or denied immediately.

images/download/attachments/143736177/Screen_Shot_2018-08-02_at_08.59.47.png

  • The CN part of the DN in the PKCS#10 request, which is part of the SCEP request, will be used as the 'username' when authenticating the request in EJBCA. Create the SCEP request with a CN matching the username registered in EJBCA.

  • The challengePassword in the PKCS#10 request, which is part of the SCEP request, will be used as the 'password' when authenticating the request in EJBCA. Create the SCEP request with a challengePassword matching the password registered in EJBCA.

The CA used is either specified by the message or by the property scep.defaultca if no message is sent.

Configuration Values

Value Name

Description

Include CA Certificate in Response

Setting this value to true will cause the CA certificate to be included in the response, if applicable.

Allow Client Certificate Renewal

ENTERPRISE This is an EJBCA Enterprise feature.

This setting activates Client Certificate Renewal, as defined in IETF Simple Certificate Enrollment Protocol - Appendix D.

This mode allows the server to interpret enrollment requests as certificate renewal requests, only if the latest issued certificate for the end entity has passed half its validity. To be valid, the PKCS#7 wrapping the CSR must be signed by the old certificate's keypair.

Allow Client Certificate Renewal using Old Key

ENTERPRISE This is an EJBCA Enterprise feature.

The SCEP draft does not mandate if old keys may be reused for Client Certificate Renewal or not, so EJBCA includes this as a setting.

CA Certificate Rollover

EJBCA supports creating a rollover certificate for a CA and issuing certificates via SCEP with this new CA certificate. This is useful when changing the CA key during renewal. For more information, refer to IETF: Simple Certificate Enrollment Protocol - Appendix E.

Workflow Example

The following illustrates a workflow for running CA mode with or without renewal.

images/inline/3419fb0bb053a0805057333a1d925d86ab6af7599734e51ad7b8d1418a8a267c.png

RA Mode

ENTERPRISE This is an EJBCA Enterprise feature.

In RA Mode, EJBCA receives SCEP PKCSReq requests when a user is to be created (or edited). A certificate is returned immediately in a proper SCEP reply message. The RA is authenticated/authorized based on configuration.

images/download/attachments/143736177/Screen_Shot_2018-08-02_at_09.04.33.png

The RA Mode requires that the operational mode is set to RA. To specify the RA operational mode, either use the command line to set the property <alias>.operationmode or use the CA UI and go to System Functions → SCEP Configuration and select Operational mode as RA. All the parameters needed to create the new end entity should be set through the command line or the CA UI.

Configuration Values

Value Name

Description

Include CA Certificate in Response

Setting this value to true will cause the CA certificate to be included in the response, if applicable.

Return full chain in GetCACert responses

Setting this value will cause EJBCA to respond to GetCACert requests with a degenerate certificates-only CMS SignedData message when the CA is an intermediate CA (as specified in section 4.2.1.2 of RFC8894). If the CA is a root CA, or if this value is not selected, the response will be a single X509 certificate.

The Return full chain in GetCACert responses option can only be used by clients that support RFC8894. This does not apply to cases where the CA is the root CA.

RA End Entity Profile

The end entity profile being used when issuing certificates.

RA Certificate Profile

The certificate profile being used when issuing certificates.

RA CA Name

The CA to use when signing certificates. Also specifies the default CA to use when no message is provided for GetCACert , GetCACertChain , GetNextCACert and GetCACaps operations.

RA Authentication Password

A shared secret used to authenticate the SCEP client to the RA.

RA Name Generation Scheme

Specifies how the name of the end entity should be generated.

RA Name Generation Parameters

RA Name Generation Prefix

Specifies a prefix to prepend to the name of end entities.

RA Name Generation Postfix

Specifies a postfix to append to the name of end entities.

Return full chain in GetCACert responses option can be used only by clients that support RFC8894. (This doesn't apply to cases where the CA is the root CA)

Microsoft Intune Support

ENTERPRISE This is an EJBCA Enterprise feature.

EJBCA can be used to issue certificates to Microsoft Intune, which happens through SCEP in RA mode. See the SCEP Operations Guide for details of how to set up the alias, and our Intune Setup Guide for how to set up Microsoft Intune to work with EJBCA.

Using SCEP with Approvals

ENTERPRISE This is an EJBCA Enterprise feature.

EJBCA supports using SCEP with approvals only in RA mode due to the fact that EJBCA's approvals are run on enrollment (creating the end entity) and not on issuance (issuing the certificate). To enable approvals over SCEP, simply configure approvals to be used in the CA or Certificate Profile as usual, and they will be active for SCEP enrollment requests as well.

CA ↔ Client Workflow

In accordance with draft-nourse-scep-23, the workflow when using approvals is as follows:

images/inline/7811e69a62e3ff287b094d7aada9cccd6733d22a190ced9ce1563a0428bb1af5.png

Should enrollment succeed but issuance fail (for example the key not fulfilling certificate profile requirements), the client merely needs to send a PKCSREQ again without needing to pass the approvals process once more.

Internal Workflow

The following graphs document the internal workflow of EJBCA when processing SCEP requests. Worth noting is that sending a PKCSREQ message on an existing end entity with issued certificate will result in a request for renewal.

PKCSREQ

Note that the following PKCSREQ graph does not illustrate all fail states.

images/inline/3dfc09afaa747c1c600498512ee1b40b278b7a1f6a65b59a5c720b5332e06f4e.png

GetCertInitial

GetCertInital, as mentioned above, is the polling message used to check if a request has received approval.

Note that the following GetCertInital graph does not illustrate all fail states.

images/inline/76cde5e0a83ef9ba9c5f36bea48efcee6baabf3d6d8a439be054c4e449015c8d.png

Proxying SCEP Through an RA

Proxying SCEP through an EJBCA RA Using Peers

Like all other protocols in EJBCA, SCEP requests can be proxied to EJBCA over TLS through another EJBCA instance acting as RA in a DMZ. For more information on how to set this up, see the Peer Systems Operations page.

images/inline/7a38e5df190b3ec97a6228bd27eb9a3834d1c875affb538ad315d6e27143bbc5.png

Legacy External RA SCEP Server

ENTERPRISE This is an EJBCA Enterprise feature.


The External RA SCEP Server functionality is deprecated and will not be supported in the future. Instead, we recommend proxying SCEP requests synchronously through an RA using Peers.

EJBCA supports the SCEP 'polling' RA model using the External RA API. Using this, a SCEP client can send a request to the External RA, and then wait, polling the RA for updates. When the request is processed by the CA, which fetches the pkcs10 request from the External RA, the certificate is sent back to the External RA. When the certificate is complete on the External RA, the RA sends back the SCEP certificate response the next time the SCEP client polls the RA. This feature is very useful to securely insulate the CA from the SCEP clients throughout the network.

Interoperability / Tested Libraries and Devices

The following provides information on tested devices.

Cisco ISE

EJBCA SCEP, using RA mode, has been successfully integrated with Cisco ISE. Configuring EJBCA as a backend CA in Cisco ISE, devices can be enrolled with certificates from EJBCA, through the ISE enrollment interfaces. For more information, see EJBCA and Cisco ISE.

Cisco IOS

EJBCA SCEP, using CA mode, has been successfully integrated with Cisco IOS. Configuring EJBCA as a CA for Cisco IOS, devices can enroll certificates from EJBCA. For more information, see EJBCA and Cisco IOS.

OpenSCEP

Note that OpenSCEP only supports OpenSSL 0.9.6. Additionally, there is a know limitation that causes it to crash when receiving SCEP responses.

To use the OpenSCEP[External Link] client to request a certificate from this servlet, use the command:

$ scep -k test.key -r test.pemreq -c ejbca-ca.pem -q foo123 -u http://localhost:8080/ejbca/publicweb/apply/scep/ALIAS/pkiclient.exe

Where test.key is generated with:

$ openssl genrsa -out test.key

test.req is generated with:

$ openssl req -key test.key -new -days 30 -out test.req -outform DER -config ../openssl/openscep.cnf

and test.pemreq is generated with:

$ openssl req -key test.key -new -days 30 -out test.pemreq -outform PEM -config ../openssl/openscep.cnf

Simple Scep Client (sscep)

Simple Scep Client[External Link]. You should only use CN in the users DN (same as for PIX below).

jSCEP

jSCEP[External Link] uses EJBCA as one of the servers it is tested against.

There is a CLI for jSCEP[External Link] by Bruno Bonfils. Note that jSCEP and jSCEP CLI need a recent version from Git (jscep-cli 1.2 or later) to work properly in Java 11, otherwise Java 8 must be on the client-side when using the following command.

Test the CLI by creating a SCEP alias and issuing a SCEP request, for example:

$ cd ejbca
$ cat > scepalias-camode.properties
scep.operationmode = ca
uploaded.includeca = true
$ bin/ejbca.sh config scep uploadfile --alias scep --file scepalias-camode.properties
$ bin/ejbca.sh ra addendentity --username=user --password=foo123 --dn="CN=User Usersson" --caname=ManagementCA --type=1 --token=USERGENERATED
$ cd ../jscep-cli-jdk6
$ openssl genrsa -out test.key
$ openssl req -key test.key -new -days 30 -out test.pemreq -outform PEM
$ java -jar target/jscepcli-1.2-SNAPSHOT-exe.jar --ca-identifier ManagementCA --challenge foo123 --csr-file test.pemreq --dn "CN=user" --key-file test.key --url http://localhost:8080/ejbca/publicweb/apply/scep/pkiclient.exe

The following shows an example SCEP alias, using the default alias name scep, to work with the URL above:

images/download/thumbnails/143736177/scep-alias.png

If you use another SCEP alias name, for example myalias, the SCEP URL would be http://localhost:8080/ejbca/publicweb/apply/scep/myalias/pkiclient.exe.

MobileIron

EJBCA has been confirmed to work with the MobileIron MDM system.

Mobile Iron always uses the CA identifier 'MobileIronSCEP' in all SCEP request. SCEP request from MobileIron always start with "operation=GetCACaps&message=MobileIronSCEP". Therefore the CAs name has to be set to 'MobilIronSCEP' to make it work. When set, both RA and CA modes work with MobilIronMDM.

Juniper Networks NetScreen-25/NetScreen-50

To enroll using the Juniper box go to the Web GUI at https://<juniper-ip>/, then click your way to Objects > Certificates. To create a new certificate request:

  1. New - enter the DN that your box will receive:

    • Name=netscreen.foo.se

    • Organization=PrimeKey

    • Country=SE

    • IP Address=192.168.1.1

    • FQSN=netscreen.foo.se

    Click generate.

  2. Automatically enroll to > New CA Server settings. You have to configure if EJBCA should use the direct CA mode or the RA polling mode:

    • CGI URL: http://<ra-ip>:8080/scepraserver/scep/<config-alias>/pkiclient.exe

    • CA IDENT: The CA Name in EJBCA, for example ScepCA.

    • Challenge: A password for a pre-registered user in CA mode, or a random password used for polling RA mode.

    Click OK.

  3. You can now see the request in Objects > Certificates. If you are using polling RA mode, you can click 'Retrieve' after the request has been approved in the CA and the certificate has been generated.

Cryptlib

When using Cryptlib[External Link], the CA certificate must have KeyUsage 'Key Encipherment' in addition to the usual key usage flags. This is reasonable, since SCEP requires the CA to actually encrypt data (which generally is a bad thing, since a special encryption certificate should be used for that).

Key usage for a ScepCA should be: Certificate Sign, CRL Sign, Digital Signature, Key Encipherment

Use the complete path as for the Cisco VPN client below as server name.

Cisco VPN client

To enroll using the Cisco VPN client, use:

  • CA URL='http://127.0.0.1:8080/ejbca/publicweb/apply/scep/ALIAS/pkiclient.exe'

  • CA Domain=your CAs name in EJBCA

  • In the DN screen simply enter the username (as added in EJBCA) as 'Name \[CN\]'

When using an External RA to enroll with the Cisco VPN client, the RA certificate must have KeyUsage SigitalSignature and KeyEncipherment for the client to accept the CA certificates. However, to locate the RA encryption certificate, only KeyEncipherment can be set, which makes things quite complicated.

The conclusion is that RA enrollment does not work with Cisco VPN client.

AutoSscep

EJBCA has been tested successfully with AutoSscep for enrollment against the CA and the External RA SCEP service.

Instructions:

  1. Download and build AutoSscep (make).

  2. Create a configuration file, ejbca.conf, as the example below.

  3. Create a user in EJBCA with username (common name) and DN exactly as entered in the configuration file.

  4. Run 'autosscep ejbca.conf'.

Sample configuration file, ejbca.conf:

Verbose = "yes"
Debug = "no"
 
CADir="/home/autosscep/"
CertDir="/home/autosscep/"
KeyDir="/home/autosscep/"
 
[CA\]
DN="C=SE, O=EJBCA Sample, CN=ManagementCA"
URL="http://localhost:8080/ejbca/publicweb/apply/scep/pkiclient.exe"
CertFile="ManagementCA.cacert.pem"
EncCertFile="ManagementCA.cacert.pem"
[/CA\]
 
[Certificate\]
CertFile="mycert"
KeyFile="mykey"
CADN="C=SE, O=EJBCA Sample, CN=ManagementCA"
 
# Create a user with username "router4711" and password "foo123" in EJBCA
# to automatically enroll
# Note you need to add a user with exactly these fields in the DN in EJBCA
Email = "mymail@mydomain"
Country="SE"
State="BS"
Location="Stockholm"
Organization="PrimeKey"
CommonName="router4711"
 
ChallengePassword="foo123"
[/Certificate\]

AutoSscep also handles enrolling against an RA, where the RA first sends a PENDING response which the request is being processed. After processing (by the CA) you simply run the AutoSscep client again to pick up the generated certificate.

In order to enroll against the External RA SCEP Server in EJBCA, change the CA part of the configuration file to use the SCEP RA servers certificate for signing and encrypting the messages instead of the CAs, and to use the URL to the RA. The SCEP RA certificate is the end entity certificate issued to the External RA SCEP server (the keystore is usually called scepraserver.p12).

[CA\]
DN="C=SE, O=EJBCA Sample, CN=ManagementCA"
URL="http://localhost:8080/scepraserver/scep/pkiclient.exe"
CertFile="scepra.pem"
EncCertFile="scepra.pem"
[/CA\]