# Device Certificate Management
Each device utilizes an X.509 certificate for authentication between the device and the ABB Ability™ Platform. This certificate allows the device to establish a TLS tunnel, ensuring secure two-way communication between the device and the ABB Ability™ Platform.
# Overview
Each device needs to be trusted and prove that it is safe to connect to The ABB Ability™ Platform. To prove that your device is safe, the device must be configured with a unique device ID from the Global ID Service. Once the device ID is issued and configured, RSA Keys (min. 2048 bit) must be generated to establish a secure data transfer pathway. The keys should be generated in the (e.g. TPM 2.0).
# How to Request a Certificate
Using the device ID retrieved from the Global ID Service as the common name, request an X.509 certificate from the Ability PKI using the SCEP client. Refer to the code snippet here for obtaining a device certificate using Ability PKI.
Save the received X.509 certificate and ensure adequate protection for the certificate.
DANGER
Deleting the certificate makes it impossible to connect to the IoT Hub.
Periodically download the revocation lists and use the lists when establishing a connection.
Implement certificate renewal to ensure that the X.509 certificates are renewed before they expire.
# Communication Security
Directly connected devices are only allowed to initiate unsolicited secure connections to the CA Server, DPS, and IoT Hub. The device shall first register with DPS (using an X.509 certificate issued by the CA server) and using the IoT Hub URL received from DPS attempt to connect to IoT Hub. All further communication towards the cloud should be initiated by the device.
This means the device first sets up an outbound, mutually authenticated TLS tunnel to the IoT Hub, and uses this tunnel to negotiate various communication mechanisms (e.g., file upload, container image download). The device is allowed to connect to the CA Server to renew the certificates and to download revocation lists. Mutual authentication and TLS handshake are established via the ABB Ability™ CA-issued X.509 certificates.
# Supported and Unsupported Use Cases
Following is a list of use cases covering device certificate enrollment with explanations of how the same is managed in the Ability PKI (aka MPKI) and earlier Ability PKI (aka CertCentral).
WARNING
The information in the table below is presented with the assumption that your device uses the Ability Secure Components. These are part of the Ability Edge framework, but may also be used in custom device implementations.
# Device Certificate Enrollment
| Use Case | MPKI | Cert Central |
|---|---|---|
| Initialize | Preparing dpcm configuration | Preparing dpcm configuration |
| Device ID Duplication Check | If device ID is generated using third party device ID server, it requires the configuration flag DEVICEID_DUPLICATION_CHECK_REQUIRED to be set to '1' and in this case a duplication check is performed with GIG server. This flag is by default set to '0' and DPCM does not perform a duplication check. In the case where the device ID is generated using a GIG server, this flag should have the value = '0'. | In the case where the device ID is generated by the DPCM service, a duplication check is performed with the GIG server. There is no configuration flag to force performing a duplication check. |
| Key generation | Per the key length defined in the parameter of PKI_KEY_LENGTH = 2048 in dpcm.config file, TPM generates the key pair and stores it in "/var/ability/certs/edgedevice-key.pem". | Per the key length defined in the parameter of PKI_KEY_LENGTH = 2048 in dpcm.config file, TPM generates the key pair and stores it in "/var/ability/certs/edgedevice-key.pem". |
| CSR generation | A CSR (certificate signing request) is created and it contains the following Common name = Device ID PKI_CERTIFICTE_OU=DPS (configured in dpcm.config) PKI_CERTIFICTE_O=ABB Information System Ltd (configured in dpcm.config) PKI_KEY_LENGTH = 2048 (configured in dpcm.config) Asymmetric public key. | A CSR (certificate signing request) is created and it contains the following Common name = Device ID PKI_CERTIFICTE_OU=DPS (configured in dpcm.config) PKI_CERTIFICTE_O=ABB Ltd. (configured in dpcm.config) PKI_KEY_LENGTH = 2048 (configured in dpcm.config) Asymmetric public key. |
| CSR request with SCEP end point | A CSR request is sent to the SCEP endpoint. The following parameter should be populated in the dpcm.config file: PKI_RA_SERVER_ADDRESS = (MPKI BU profile scep endpoint) PKI_RA_SERVER_PORT = (port number) PKI_CA_AUTH_HASH = (MPKI BU profile hash) | A CSR request is sent to the SCEP endpoint. The following parameter should be populated in the dpcm.config file: PKI_RA_SERVER_ADDRESS = (Cert Central profile scep endpooint), PKI_RA_SERVER_PORT = (port number), PKI_CA_AUTH_HASH = (Cer Central profile hash). |
| Device Certificate decryption and storage | A response is received from the MPKI BU profile SCEP end point and the certificate is decrypted using a private key. After decryption is successful the certificate is stored in the following location: "/var/ability/certs/edgedevice-cert.key". | A response is received from the Cert Central profile SCEP end point and the certificate is decrypted using a private key. After decryption is successful the certificate is stored in the following location: "/var/ability/certs/edgedevice-cert.key". |
| Multiple enrollments with the same device ID. For example, during manufacturing, it is possible that after getting the cert, an issue causes the cert to be lost or deleted in the device. The device will then need to request again but with same device ID. | The device ID should be unique at each attempt. | Multiple enrollments with the same device ID can be done. |
| POST operation | If REGISTER_DEV_ID is set to '1', after device enrollment is successful, the DPCM application performs a POST operation with the GIG server. | If REGISTER_DEV_ID is set to '1', after device enrollment is successful, the DPCM application performs a POST operation with the GIG server. |
| Support for a preloaded list and individual device-based enrollment, i.e. the possibility of enrolling a device not in the list when the profile is configured for a preloaded list. | Device enrollment is supported only for a pre-loaded CSV list. Individual device-based enrollment will fail if the device ID is not in the pre-loaded CSV list. | N/A, since preloaded list-based enrollment is not supported. |
NOTE
Prior to certificate enrollment, the device ID and enrollment passcode should be uploaded in the MPKI profile (list). The MPKI profile provides an endpoint that should be configured with the respective device ID and enrollment passcode. By default, MPKI profiles are configured to accept certificate enrollment for a pre-registered deviceID, enrollmentcode pair. This list, once uploaded, is valid for 30 days. For more on configuring the MPKI endpoint, see Apply Manual Production Process.
# Profile Management
| Use Case | MPKI | Cert Central |
|---|---|---|
| Custom Profile | Ability PKI team will create a customized MPKI profile for each business line. | No profile customization is supported by CertCentral. It is common across all business lines. |
| Custom profile options | • Number of days that the enrollment code will remain valid: 30 days | No customization supported in Cert central. |
| • Certificate validity period: 3 years | ||
| • Renewal window: 60 days | ||
| SCEP service Endpoint URL | Each BL profile has a unique SCEP service endpoint URL. | SCEP service endpoint URL is common across all BLs. |
| Number of enrollments allowed | Can be -1 for no limit or anything more than 1 and less than 999999. | N/A or depends on ABB agreement |
| Basic profile control options | Hide, suspend, and delete profile. | N/A |
| Number of seats is more than uploaded ID's in CSV (i.e. device ID and password list) and device makes a request with device ID not in the CSV list. | Device ID is not in the preloaded CSV list and even if a number of seats are available, certificate enrollment will fail. | N/A |
# Certificate Renewal
| Use Case | MPKI | Cert Central |
|---|---|---|
| Renewal of expired certificate | Renewal of expired certificate is supported in MPKI. | Renewal of expired certificate is not supported in Cert Central. |
| Renewal of valid certificate | Renewal of valid certificate is supported in MPKI. | Renewal of valid certificate is supported in Cert Central. |
| Renewal Window Configuration (threshold for certificate renewal) | 60 days | The default PKI certificate expiration threshold is 30 days (fixed). |
# Enrollment Passcode/Password/Enrollment Code Management
| Use Case | MPKI | Cert Central |
|---|---|---|
| Preregistration of enrollment passcode for respective device ID | Single or bulk preregistration of device IDs and enrollment passcodes is supported in MPKI. | Preregistration of bulk device IDs and enrollment passcodes is not supported by Cert Central. |
| Enrollment passcode validity | Can be -1 (for never expire) or anything more than 1 and less than 365. | 1 day (fixed) |
| Shared Password | MPKI supports shared password. | Not supported. |
| Enrollment passcode generation | Can be generated from MPKI or User can generate desired enrollment passcodes using any other tool. | Should be generated from CertCentral only. |
| Enrollment passcode update to device | Enrollment passcode should be populated in PKI_ENROLL_PASWD of the dpcm.config file. | Enrollment passcode should be populated in PKI_ENROLL_PASWD of the dpcm.config file. |
# Certificate Validity
| Use Case | MPKI | Cert Central |
|---|---|---|
| Maximum certificate validity | 3 years | 3 years |
| Minimum certificate validity | 1 day | 3 years (fixed) |
| Certificate revocation | Certificate can be revoked in MPKI, by choosing the option (in the MPKI portal) Manage Users -> Enrolled in (profile name) -> Search by (Date, seat ID, Email Address). Then find the certificate and click on revoke certificate. | Certificate can be revoked in CertCenral. For details, see here |
# Certificate Visibility and Control
| Use Case | MPKI | Cert Central |
|---|---|---|
| Issued certificate details such as validity, requester, profile, issue date and other audit details | It is currently possible to be viewed only by users with PKI admin rights. Rest APIs are not yet available. For details, see here. | The certification details can be viewed only by users with PKI Admin rights. The certificate details viewable in Cert Central are: organization name, profile, status, creation date, expiration date, and other audit details. |
# Device Cerificate Renewal Failure
Device Certificates may occasionally fail, and logs may show "Early Renewal" (refer to the image below). In this case, check for the points mentioned below:
- "PKI_CERT_EXPIRE_THRESHOLD" in /etc/dpcm.config
- The value should be less than the "Renewal Window" value set in the Digicert MPKI Profile
- MPKI profile is accessible only to the Ability PKI Team
- If the renewal period is 30 days, set the PKI_CERT_EXPIRE_THRESHOLD to 29 or 28 or less, otherwise an "Early Renewal" error may occur
Also, sometimes a Renewal Certificate is issued from Digicert but is not present in the Edge Machine. In this case, we may also see renewal failure and "early renewal" logs. Then follow below steps:
- Contact the Ops Team or Ability PKI Team to revoke an existing certificate.
- When the certificate is revoked, restart the DPCM Service to obtain a new certificate.