Skip to content

How the Broker Client Handles Certificate Validation

By default, the Broker Client API validates the certificate chain presented by a broker for each connection request against the Certificate Store of your operating system. If validation fails, one of the following errors is returned:

  • PCOIP_BROKER_ERROR_CERT_FAILED
  • PCOIP_BROKER_ERROR_CERTIFICATE_FAILED_BUT_WARNABLE

The details of the error are obtained by calling the pcoip_broker_get_server_certificate_error() function.

Retrieving Broker Certificates

The certificate chain presented by a broker can be obtained by calling the pcoip_broker_get_num_certificates() function, which returns the length of the chain along with a call to the pcoip_broker_get_broker_certificate() function. The pcoip_broker_get_broker_certificate() function presents the data in DER format.

Controlling the Certificate Validation

By default, the Broker Client API validates the certificate chain of the requesting broker. Validation of broker certificates can be disabled by calling the pcoip_broker_fail_if_unverified() function.

Standard Certificate Validation Modes

The 3 security levels of operation as described in the "PCoIP Connection Broker Protocol Specification", as well as in the specifications of other brokers are implemented using the following functions:

  • In the no security mode, the pcoip_broker_fail_if_unverified(false) functio is calledn, before calling any other requests.

  • In the full security mode, the Broker Client API validates the certificates for all broker requests. If validation fails, the error can be obtained by calling pcoip_broker_get_server_certificate_error() function, and optionally presenting information related to validation failure to the user.

  • In the warn but allow mode, the pcoip_broker_fail_if_unverified(true) function is called first. If the request fails with the PCOIP_BROKER_ERROR_CERT_FAILED error, the full security mode is implemented. If the request fails with the PCOIP_BROKER_ERROR_CERTIFICATE_FAILED_BUT_WARNABLE error, information related to the error and optionally, the certificate chain is presented to the user. Users can choose to continue with a non-secure connection, in which case, the pcoip_broker_fail_if_unverified(false) function is called, and the request for non-secure connection is processed.

Setting the Certificate Store

The Certificate Store that is used to validate the certificates presented by the broker during connection can be configured if required. By default, the Certificate Store of the Operating System is used, which means that all standard Certifying Authorities (CAs) are checked during validation.

However, for some high security applications, limiting the CAs to a subset of the standard CAs is essential. This set of CAs can be stored in an application folder. Before connecting to a broker, the path to this folder is provided to the Broker Client API via a call to the pcoip_broker_set_ca_store() function.

!!! note "Note: Additional Information Additional information on the use of the above mentioned functions is available in the broker_client.h file.