Certificate requirements and examples

To gain access to Ons API, we require requests to be signed using an SSL client certificate signed by our own Certificate Authority. These certificates identify the connector and the environment of the healthcare organisation on which the requests are made.

Certificate Linking Process
For an explanation of the request and linking process, refer to the article: Managing and using certificates.

CSR Requirements

Every CSR submitted for signing must meet these requirements:

• Key-length of at least 4096 bits.
• CN, OU, O, L, ST, C and email address are filled.
• CN is structured according to the convention; {technical_name_connector}-{customer_code}-{identification}
  • Technical_name_connector
    Technical name of the connector. Can differ from the displayed name of the connector. Only lowercase characters: a-z, 0-9 and _.
  • Customer_code
    The customer code applicable to that environment. For development purposes, this is: TE1002. See also: Managing and using certificates.
  • Identification
    Free text field, such as staging, production, id2431. Only the following characters: a-z, A-Z, 0-9, and _.
  • Valid examples:
    • hr_integration-TE1002-free_text
    • finance_integration-DF0000-production

Technical Details

TLS

• The minimum TLS version is 1.2.
• The framework you are using must send an SNI extension along with the TLS handshake.

Valid ciphers
Any of the following ciphers can be used:

• ECDHE-ECDSA-AES256-GCM-SHA384
• ECDHE-ECDSA-AES128-GCM-SHA256
• ECDHE-ECDSA-CHACHA20-POLY1305
• ECDHE-RSA-AES256-GCM-SHA384
• ECDHE-RSA-AES128-GCM-SHA256
• ECDHE-RSA-CHACHA20-POLY1305
• DHE-RSA-AES256-GCM-SHA384
• DHE-RSA-AES128-GCM-SHA256

CA Chain
If your framework, platform, or development language requires the full CA chain, it can be obtained here:

• Production CA chain
• Staging CA chain
• Development CA chain

Generating CSR

We recommend using OpenSSL. With OpenSSL, you can generate a CSR with the following command:

openssl req -out my_connector-TE1002-example.csr -new -newkey rsa:4096 -nodes -keyout my_connector-TE1002-example.key

OpenSSL will prompt for additional information.

Use a CN that meets the requirements described earlier in this article.

This will generate a CSR and KEY file. It is very important to securely store the KEY file and not share it! Do not share this file with Nedap. If the file is inadvertently shared at any time, disable the certificate in the Ons API Dashboard and inform Nedap.

The CSR file must be uploaded to the Ons API Dashboard Managing and using certificates. You will then receive a PEM file from us, which you can use to make calls.

If you use a tool other than OpenSSL (for example, BouncyCastle library), make sure to use the most recent version of that tool. Older versions may generate invalid CSRs that cannot be signed by us.

Certificate Testing

You can test the certificate by making a GET request to the /ping endpoint on Ons API. Use the URL corresponding to the environment for which the certificate is intended; see also: API properties.

• Example: GET https://api-development.ons.io/ping
• Result:
  • 200: The certificate works.
  • 403: The certificate does not work in combination with the provided URL.

If you are testing with curl on Windows, make sure to use a recent version of curl. Often version 7.55.1 is installed, which does not handle client certificates well.

---