Certificates

Introduction

The application programming interface (API) enables the administration of security certificates, which may be utilised for a variety of purposes, including file signing validation, communication encryption, access control, and others.

Supported File Types

• type: PEM
• mime-type: x-pem-file
• file extension: .pem

How trustChains parameter works

The trustChains parameter represents an array of trust chains. The initial array comprises a series of string arrays, arranged from left to right, which collectively represent the path traversed by a certificate’s parents from the root or self-signed certificate to the certificate’s immediate parent.

To illustrate, if a certificate C is signed by a certificate B, which in turn is signed by a certificate A, the path will be A→B→C. The trustChain will contain the identifier of the certificate A in the initial position of the array, followed by the identifier of the certificate B in the subsequent position. Please refer to the example below, which assumes that:

• Identifier of A: 1427353136
• Identifier of B: 1427353426

trustChains parameter single path example “trustChains” : [ [ “1427353136”, “1427353426” ] ]

In the aforementioned example, if the same C certificate is present but with an alternative trust chain, namely A→B2→C,

• Identifier of B2: 1427353447

trustChains parameter multiple path example “trustChains” : [ [ “1427353136”, “1427353426” ], [ “1427353136”, “1427353447” ] ]

Comprehensive API actions

It is possible for devices to establish a connection with OpenGate through the utilisation of an authentication system based on a Public Key Infrastructure (PKI). The Certificate Provision API facilitates the administration of certificates.

Creating a certificate

In order to create new certificates, it is first necessary to be aware of the following tips:

• A user is permitted to upload a certificate to the platform, which may be in their own domain or in any of the domains with a low hierarchy that are managed by the user.
• A certificate can only be signed by a certificate uploaded to the platform with the usage code CERT_SIGN. Furthermore, the aforementioned certificate must be in the same domain or in a domain with a visible upper hierarchy.
• It is permissible to upload the same certificate to the platform on numerous occasions, provided that the identification data is different on each occasion.
• In the event of a change to the domain of a certificate, the trust chain will be updated in a manner that is consistent with the principle of least privilege. This entails the inclusion of only those certificates that are associated with visible domains within the new domain.

Reading a certificate

A user is only permitted to access the certificates in their possession.

Deleting a certificate

A user is only permitted to remove certificates in respect of which they are the owner.

Searching certificates

Fetch parameter

The fetch parameter in the URL request, /north/v80/search/certificates?fetch={value}, enables the retrieval of different response objects. The value of this parameter can be any of the following:

• 0: In the absence of the aforementioned parameter, the default value is as stated. The result is delineated in the section pertaining to the Certificate object structure.

• 1: A comprehensive account of the data pertaining to the certificates exhibited in the “trust chains” object, inclusive of the “entities” object.

Visibility parameter

The utilisation of the visibility parameter within the URL request, /north/v80/search/certificates?visibility={value}, enables the retrieval of disparate response objects. The value of the parameter, {value}, can be:

• assignable: In this instance, the relevant certificates will be issued, which can then be assigned to domains, channels and devices. It should be noted that these certificates are associated with the user’s domain or, where applicable, the user’s domain or domains with a visible upper hierarchy.

• administrable: In the absence of the parameter, the default value is returned. Consequently, the user will receive the certificates that can be administered, that is to say, the certificates that can be managed, including the option to update or delete them. The certificate in question belongs to the user’s domain or to domains with a low hierarchy managed by the user.

API specification