SCEP

1. Introduction

MTG Certificate Lifecycle Manager Server includes an implementation of the SCEP server according to RFC 8894 [RFC8894].

2. MTG-CLM integration

To enable integration with MTG-CLM, SCEP uses the credentials of an API client as described in SCEP Administration Manual. Additionally, SCEP server uses a policy to handle certificate management. A policy in MTG-CLM specifies the methods and mechanisms on how certificates are created. It identifies the CA that will issue the certificate, the template which is used, and also it may contain additional restrictions and configurations for the certificate lifecycle.

2.1. Authorization

2.1.1. Certificate-based authorization

A SCEP client may request a certificate from the server if it already has a certificate from MTG-CLM. In this case it should sign the CMS container with the private key corresponding to a certificate issued by MTG-CLM.

2.1.2. Password-based authorization

A SCEP client should set the challengePassword attribute in the PKCS10 request. In order to be authorized to access the SCEP server, the challenge password should be the UUID of the end-entity, followed by the character :, followed by the password of the end-entity.

For example, the end-entity with UUID a4a0995-5fba-49c7-bc8a-55a61bd423d4 and password Vw1okwIDjt'|Lcr7 should use the following value as challengePassword: ba4a0995-5fba-49c7-bc8a-55a61bd423d4:Vw1okwIDjt'|Lcr7.

If the challengePassword attribute is set in the PKCS10 request then the certificate-based authorization for this request is deactivated.

2.1.3. Static-Password-based authorization

A SCEP client should set the challengePassword attribute in the PKCS10 request. This is the password which is configured at the application.properties of the SCEP server. When this option is activated all other authorization methods are not active. All SCEP clients must use this method.

Use this option with caution. All SCEP client are in position to create an arbitrary end-entity and request certificates for other end-entities.

2.2. Defining default policy

API clients are optionally associated with a default policy. MTG Certificate Lifecycle Manager Server by default, uses the default policy of the associated API client to handle certificate management. In case the API client is not associated with a default policy and the client does not specify a different policy in the request (see Section 3.1), the SCEP server responds with an invalid identifier error.

2.3. Defining different policy

The SCEP server supports specifying a different policy as the policy to be used instead of the API client’s default policy. The ID if this new policy has to be used in the requests towards SCEP server as described in Section 3.1.

2.4. Quickstart

Assuming there is a newly installed MTG-CLM and MTG Certificate Lifecycle Manager Server, to request a certificate over SCEP following steps must be performed:

  1. Create a realm R.

  2. Create a policy P in realm R.

  3. Create an API client A in realm R with policy P as default policy.

  4. Create an end-entity E in realm R.

  5. Create a certificate C for end-entity E using policy P.

  6. Download private key K corresponding to certificate C.

  7. Configure credentials of API client A to MTG Certificate Lifecycle Manager Server.

  8. Start MTG Certificate Lifecycle Manager Server.

  9. Send a RenewalReq (see Section 3.3.1 of [RFC8894]) with an SCEP client by signing the CMS container with private key K, placing certificate C in the CMS container, and creating a new PKCS10 request with a new key pair.

3. Custom features

3.1. Different policies endpoints

Per default the SCEP server offers the following endpoint:

  • SCEP_SERVER_BASE_URL/scep

Client requests to this endpoint use the default policy.

The SCEP server provides supplementary endpoints to support requests that require a different policy. Requests towards these endpoints specify a different policy to use, rather than the default policy of the associated API client. These are the endpoints for the different policy endpoints:

  • SCEP_SERVER_BASE_URL/<identifier>/scep

  • SCEP_SERVER_BASE_URL/scep/<identifier>

The <identifier> needs to be replaced with a valid policy ID. For example to request a certificate that is issued under the policy ffc0d281-f9df-45cd-a30d-1881cd67012a use the URL: SCEP_SERVER_BASE_URL/ffc0d281-f9df-45cd-a30d-1881cd67012a/scep.

3.2. Device type specific SCEP-Handling

The default SCEP-SuccessResponse which is generated after issuance of the EE-Cert, is not accepted by Juniper JunOS/ScreenOS devices resulting in a local processing failure, preventing the EE-Cert to be installed at the device. The reason for failure is not obvious and cannot be solved by the requesting entity. Tests showed that Juniper does not expect a full cert-chain in the SCEP-SuccessResponse and simply fails to verify the EE-Cert signature when it not an "EE-Cert-Only" SCEP-SuccessResponse.

To support Juniper devices, the scep.response.include.cachain flag (default true) has been added in the application.properties of the SCEP server. When this option is set to false, the CA-Chain is excluded and an "EE-Cert-Only" SCEP-SuccessResponse is generated.

The scep.response.include.cachain flag affects all SCEP-Clients.

To support devices that require only the CA certificate of the CA that signs the end-entity, the scep.getcacert.include.cachain.onmessage flag (default true) has been added in the application.properties of the SCEP server. When this option is set to false, the CA-Chain is excluded and only the signing CA certificate is placed in the GetCACert response.

The scep.getcacert.include.cachain.onmessage flag affects all SCEP-Clients.

4. Usage

The MTG SCEP Server can be used by all clients that are compliant to the RFC 8894 [RFC8894] protocol. An SCEP client connects to the IP address of the SCEP server and the port it is running

Listing 1 shows a request to get the capabilities of the SCEP server.

Listing 1. Get capabilities of the SCEP server
curl -X GET "https://<serverHost>:8507/scep?operation=GetCACaps"

Listing 2 shows a request to receive the CA certificate configured in the SCEP server.

Listing 2. Download of CA certificate
curl -X GET "https://<serverHost>:8507/scep?operation=GetCACert" -o cacert.pem

To receive the full CA certificate chain configured in the SCEP server, the SCEP message=<CaName> parameter must be added as shown in Listing 3.

Listing 3. Download of CA certificate chain
curl -X GET "https://<serverHost>:8507/scep?operation=GetCACert&message=MyCaName" -o cacertchain.p7

All other SCEP Operations are transfered as shown in Listing 4
Note: SCEP PKI-Operations may also use the HTTP POST operation.

Listing 4. SCEP PKI-Operations
curl -X GET "https://<serverHost>:8507/scep?operation=PKIOperation&message=<...pkiMessage.(Base64)...>" -o scep.resp.p7

The SCEP Server also supports the processing of a RenewalReq, which can be sent using for example the jscep [jscep] client.

References

  • [MTG_SCEP_Administration_Manual] MTG Certificate Lifecycle Manager Server — Administration Manual

  • [MTGClmUserManual] MTG-CLM — User Manual

  • [RFC8894] P. Gutmann. Simple Certificate Enrolment Protocol. RFC 8894. www.rfc-editor.org/rfc/rfc8894.txt.

  • [jscep] jscep. github.com/jscep/jscep.