When a PainChek integration communicates with the API for a Residential Care System (RCS), the data is secured and so requires a valid TLS certificate be installed on the RCS API server.
When installing the certificate onto the RCS API server, installing just the domain certificate issued to the RCS organisation is typically not enough. There is also a requirement to install the intermediate certificates using an intermediate certificate bundle.
The simplest way to see if the certificate installed is to use either cURL or Wget to call the API endpoint. See those utilities for more details on how to use them. If the response indicates there a certificate issue, it may well be because there is no intermediate installed - e.g.:
wget https://painchek.com:4443 --2020-03-17 12:58:46-- https://painchek.com:4443/ Resolving painchek.com (painchek.com)... 1.1.1.1 Connecting to painchek.com (painchek.com)|1.1.1.1|:4443... connected. ERROR: cannot verify painchek.com's certificate, issued by ‘CN=AlphaSSL CA - SHA256 - G2,O=GlobalSign nv-sa,C=BE’: Unable to locally verify the issuer's authority. To connect to painchek.com insecurely, use `--no-check-certificate'.
An intermediate certificate is a certificate issued by the Trusted Root Certificate Authority (CA) that is then used by another (intermediate) CA to issue certificates to end-users.
In the screenshot below, you can see the certificate chain for the painchek.com domain. In it, you can see the intermediate certificate (Let's Encrypt Authority X3) that provides the link between the PainChek certificate and a trusted root certificate.
The following table summarises what each of the certificates are in the chain
|
Name |
Level in Chain |
Issued by |
Issued to |
Type |
|
DST Root CA X3 |
First |
Digital Signature Trust Co. |
Digital Signature Trust Co. |
Trusted root certificate |
|
Let's Encrypt Authority X3 |
Second |
Digital Signature Trust Co. |
Let's Encrypt |
Intermediate certificate |
|
painchek.com |
Third |
Let's Encrypt |
PainChek |
Final domain certificate |
It is possible to have multiple intermediate certificates, although the example about only has one.
A certificate chain is a collection of certificates that allow a domain certificate to be trusted.
Looking at the example above, the chain has three certificates.
The first one is "DST Root CA X3" which is the trusted root certificate. This root certificate is installed to the Trusted Root Certification Authorities store on PCs, servers and networking devices and is implicitly trusted by the systems they are installed on.
The second certificate in the chain is "Let's Encrypt Authority X3" which is an intermediate certificate. The Root CA has used its root certificate to issue this certificate and, as the root certificate is trusted, so too is the intermediate certificate.
The last certificate in the chain is painchek.com which is the actual certificate issued to PainChek. This is also known as a “domain certificate”. The intermediate CA has used its certificate to issue this certificate and, as the intermediate certificate is trusted, so too is the domain certificate.
A certificate bundle is a collection of two or certificates in a single file. An intermediate certificate bundle is a bundle with one or more intermediate certificates and a domain certificate.
Your CA may provide the bundle for you, but if not, they will provide the intermediate certificates. It’s easy enough to create a bundle – you just place the two certificates into the one file – e.g.:
-----BEGIN CERTIFICATE----- w5QwDQYJKoZIhvcNAQEFBQAwVzELMAkGw5QwDQYJKoZIhvcNAQEFBQAwVzELM A1UEBhMCQkUxGTAXBgNVBAoTEEdsb2JhA1UEBhMCQkUxGTAXBgNVBAoTEEdsb2 …… rest of the intermediate CA certificate… DKqC5JlR3XC321Y9YeRq4VzW9v493kHMB65jUr9TU/Qr6cf9tveCX4XSQRjbgbME p4A==HMUfpIBvFSDJ3gyICh3WZlXi/EjJKSZp4A==HMUfpIBvFSDJ3gyICh3WZlXio -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- RQwwDQYJKoZIhvcNAQEFBQAwVzELMAkGRQwwDQYJKoZIhvcNAQEFBQAwVzELgg A1UEBhMCQkUxGTAXBgNVBAoTEEdsJvA1UEBhMCQkUxGTAXBgNVBAoTEEdsJvsw …… rest of the domain Certificate… pOBWYdw9P91nbHZF2krqrhqkYE/Ho9aqp9nNgSvBZnWygI/1h01fwlr1kMbawb30 hag8IyrhFHvBN91i0ZJsumB9iOQct+R2UTjEqUdOqCsukNK1OFHrwZyKarXMsh3o -----END CERTIFICATE-----
Install this certificate on your server and it will allow PainChek to authenticate.