# Certificate Enrollment With SCEP

Ability Public Key Infrastructure (PKI) is the primary identity provider for all ABB Ability devices. While engineering an Ability device or configuring your Ability Edge device, you need to obtain a device certificate to connect it to any cloud endpoints, like Azure IoT Hub or Device Provisioning Service (DPS).

This article explains the options for obtaining valid device certificates and configuring the device to obtain one.

To learn more about the Ability PKI consult the Ability PKI Overview article.

# Device Authentication

All Ability devices establish a persistent connection to the Azure IoT Hub in order to send and receive messages from the cloud. The transport is a mutually authenticated TLS (RFC-5246) connection, where the server (IoT Hub) authenticates to the client (Ability Device) using a certificate issued by a well-known trusted Certificate Authority and the client presents its device certificate issued by the certificate authority that is part of the Ability PKI. This process guarantees that both parties are authenticated, and no information is leaked to any untrusted third party. TLS also provides industry-grade encryption to ensure the secrecy of transferred data.

# Obtaining certificates

Devices obtain their own certificates as part of the PKI enrollment process using the PKI's Request Authority (RA) endpoint. This endpoint conforms to the SCEP - Simple Certificate Enrollment Protocol - that is currently considered an industrial standard in device self-enrollment for identity management purposes. SCEP is currently an RFC draft documented here.

In order to obtain a certificate, a device performs the following procedure:

Download an issuing CA certificate from the RA endpoint
Authenticate the issuing CA by comparing a fingerprint of the received certificate with a value stored on a device, or obtained using different, secure means.
Create an RSA key pair (private key material should be kept in secure storage to prevent identity theft and spoofing)
Create a Certificate Signing Request (CSR) in PKCS #10 form. The CSR must contain at least the following items:
- The subject Distinguished Name
- The subject public key
- a challengePassword attribute (see below)
Send CSR to the Request Authority (using SCEP protocol PKCSReq) and receive its device certificate.

All enrollment requests (PKCSReq) and certificate renewal requests (RenewalReq) are authenticated at the RA to prevent fraud and misuse of the PKI. For enrollment requests, a challengePassword (aka Enrollment Code) attribute of CSR is verified with the value known by the RA, while devices renewing their certificates use their former certificate to authenticate RenewalReq messages.

# Ability PKI Environments

Ability PKI provides 5 environments that you can use to obtain certificates.

Development - used by developers, devops and testers to obtain device certificates for all their development and test scenarios other than to test certificate management
Testing - used by QA/test teams to validate PKI-related software components and certificate management processes such as enrollment, renewal and revocation tests
Preproduction Generic - used by developers and QA engineers for final SCEP protocol compliance/compatibility validation. Only development teams creating their own SCEP client implementations should use this environment.
Preproduction For Renewal Check - used by developers and QA engineers for final SCEP protocol compliance/compatibility validation where short-lived certificates are required. Only development teams creating their own SCEP client implementations should use this environment.
Production - issuing certificates for production Ability devices

TIP

When developing an Ability solution and you are not sure which environment to use, always use the Development PKI Environment

All Ability PKI Environments issue certificates using different set of Certificate Authorities, provide separate RA/SCEP endpoints and follow different request authentication rules. You may consider them as separate PKIs. Learn more about configuration details on the Ability PKI Environments page.

Development, Testing and both Preproduction Environment are shared by all ABB Business Lines.

# Development Environment

Development Environment issues free, short-lived certificates for development purposes. Only development Ability Platform instances trust devices presenting those certificates. On the other hand, this environment allows you to automate the whole process, because - in contrast to Testing or Production Environments - CSRs are authenticated using a well known, static challengePassword (aka Enrollment Code).

# Testing Environment

Testing Environment reflects the configuration of the production environment, but issues certificates rooted in the ABB Ability TEST Root CA. Just like the production environment it uses device-specific enrollment codes for CSR authentication. You can submit those codes in CSV file. For details see Ability PKI Overview.

# Preproduction Environments

While testing a SCEP client or your certificate lifetime management solution, you may need to perform some limited final testing on an environment that is 100% identical to the production PKI environment. Here's when our preproduction environment comes handy giving you a 100% match in terms of implementation and configuration to what you'll see on production. The preproduction environment consists of a general profile that is configured with Ability PKI standard settings and an option to create a custom profile that reflects your production PKI configuration on demand. Business Lines may create up to 100 certificates on this environment per year.

Preproduction environment also features a special shared short-lived certificate profile for testing certificate renewal and handling of expired certificates. All the profile settings are equal to the Ability PKI production configuration, but the certificate validity period (set to 3 days) and renewal window (100% lifetime of the certificate).

TIP

If you think you may need some special non-standard PKI configuration for your development or testing needs, please consult your Ability Client Success Team representative.

# Configuring Ability Edge device

# DPCM

DPCM is a software component of the Ability Edge Framework that enrolls a device to the Ability PKI and maintains the certificate through the whole lifetime of the device.

In order to configure DPCM for a given PKI environment, you have to modify its configuration file (by default in /etc/dpcm.conf) setting environment-specific variables.

Variable	Description
`PKI_RA_SERVER_ADDRESS`	SCEP Endpoint URL
`PKI_CA_AUTH_HASH`	Issuing CA MD5 fingerprint
`PKI_CERTIFICTE_OU`	A value of the requested certificate's OU field
`PKI_ENROLL_PASWD`	CSR challengePassword field value (Enrollment Code)

CERTIFICATE OU FIELD

For the OU (Organization Unit) field in all CSRs to be signed by the Ability PKI you should use your business line product group code (ex. PG12345).
For development and testing use Digital's PG code: PG9964

For the development environment the PKI_ENROLL_PASWD would be a constant, well-known value (see above), while for the testing or production environments this needs to be a device specific enrollment code, previously sent to the Ability PKI team as part of the device pre-enrollment process. Password has to correspond to the DEVICE_ID specified in /var/ability/config/edge.env file.

Learn more about configuring the Ability Edge device

# Edge Proxy

Ability Edge Framework's Proxy component is making use of the certificate obtained by DPCM but doesn't need any environment-specific configuration.

# Requesting a Certificate in Bash

One of the simplest ways to obtain a certificate from Ability PKI is using readily available software tools (like OpenSSL and SSCEP). That allows you to create a CSR, send it to the RA and receive a certificate without a single line of code, for instance when you need to authenticate a PoC code that you are currently preparing on your computer.

In order to request a device certificate in bash shell you need to:

Create an RSA key pair and Certificate Signing Request (CSR) using ability-mkrequest script
Use any command-line SCEP client (like sscep) to send a request and receive a certificate.

# Device ID will become certificate's Common Name (CN)
# Make sure to replace it with a unique UUID created with uuid or uuidgen tool
DEVICE_ID='786c5db0-6930-11ea-a121-b20080352429'

# Create a CSR
./ability-mkrequest $DEVICE_ID 'PUT_CHALLENGE_PASSWORD_HERE'

# Download issuing CA certificate
sscep getca \
      -u 'PUT_SCEP_ENDPOINT_URL_HERE' \
      -c ca.pem      

# Send CSR to the SCEP RA
sscep enroll \
      -u 'PUT_SCEP_ENDPOINT_URL_HERE' \
      -c ca.pem \
      -k abilitydevice.key \
      -r abilitydevice.csr \
      -l abilitydevice.pem

# Inspect a certificate written to abilitydevice.pem
openssl x509 -in abilitydevice.pem -noout -text

# Renewing a Certificate

IoT devices should renew their identity certificates before it expires. The exact procedure for sending the renew request is described in the SCEP RFC but in general it's almost the same as sending a new certificate request. The main difference is how the request is authenticated - an already issued valid device certificate is used for authentication instead of the enrollment code.

TIP

Devices that spend most of their lifetime off-line may miss the timeslot for renewing the certificate and end up with an expired identity certificate. While Ability PKI allows such devices to authenticate the renewal request with the expired certificate for a certain period of time, keep in mind that it's not a standard SCEP procedure and your SCEP client implementation may need to be slightly modified for this to work.

Ability Edge Framework's DPCM supports this feature out-of-the-box.

# Renewal window

According to the SCEP specification, the certificate renewal request and the enrollment request look almost the same. The PKI Request Authority (SCEP server) assumes that all valid enrollment requests for the already enrolled certificate subject (technically the device ID) that are submitted within last N days preceding certificate expiration (renewal window) are considered as certificate renewal requests.

In the Ability PKI renewal window length is different for different profiles (environments). It's 30 days for the testing profile and usually 90 days for production profiles. Renewal window length for production profile can be adjusted on request by the Business Line concerned.

← Factory Proxy Apply Manual Production Process →