Skip to content

Certificate

The DSH uses a public-key infrastructure (PKI) to make sure that all the communication on and with the DSH is secure. The DSH itself creates and manages most of these certificates automatically, but you can also add your own:

  • It’s recommended that you add your own certificates for vhosts, and the DSH requires certificates of your own if you want to deploy a Kafka Proxy and a Schema Store.
  • You can store the server certificate and the private key as secrets on the DSH, in the PEM format. You can also store the optional passphrase for the private key as a secret.
  • If a certificate is about to expire, then the DSH creates a warning on the “Notifications” page.
  • In order to renew an existing certificate, you only need to replace the values of its secrets.

Limits

The DSH imposes the following limits on certificates:

  • Maximum number of certificates: The maximum number of certificates that your DSH tenant can contain. This only applies to certificates that you create yourself, and the limit doesn’t count the certificates that the DSH creates automatically.

You can request a new limit:

  1. Click “Resources” > “Overview” in the menu bar of the DSH Console.
  2. Click the “Request” button next to “Certificates”.
  3. Fill out the desired value and click “Request”. A platform administrator will process your request, which appears as a ticket in the Support Portal.

Types of certificates

The Transport Layer Security (TLS) protocol requires the server to present a digital certificate to the client, to prove the server’s identity. The client then verifies that the subject of the certificate matches the hostname of the server, and that a trusted certificate authority has signed the certificate.

Certificates come in different types, depending on the strictness that a certificate authority exerts when it validates the hostname:

  • Domain Validated (DV) certificate
  • Organization Validated (OV) certificate
  • Extended Validation (EV) certificate

If you create a vhost on the DSH, then it doesn’t receive a certificate automatically. For that reason, it’s highly recommended that you add a strict certificate of your own, such as an OV certificate or an EV certificate.

Tip

KPN also acts as a certificate authority for certificates that can be used in specific services. See KPN Certificaten for more information.

Domain Validated certificate

For a Domain Validated (DV) certificate, the certificate authority checks whether the applicant has some control over the domain that the certificate protects, for example via the DNS records, whois records, or the public administrative contact of the domain. This is the lowest level of strictness in the validation, and a DV certificate doesn’t prove that a legal entity is actually connected to the certificate itself.

If the domain name of your DSH platform is in the “.com” top-level domain (TLD), then it contains DV certificates for TLS, in the Automatic Certificate Management Environment (ACME) protocol from Let’s Encrypt:

  • These certificates only secure domain names that are 1 or 2 levels deeper than the domain name of the platform in question.
  • However, you may request a vhost with a domain name that is at least 3 levels deeper than the domain name of the platform. In that case, it isn’t secured by a Let’s Encrypt certificate from the DSH.

For example:

  • ‘example.kpn-dsh.com’ is a platform under the “.com” top-level domain:
    • ‘yourtenant.example.kpn-dsh.com’ is 1 level deeper than your platform’s domain name. It’s secured by a DV certificate from the DSH.
    • ‘yourservice.yourtenant.example.kpn-dsh.com’ is 2 levels deeper than your platform’s domain name. It’s secured by a DV certificate from the DSH.
    • ‘subservice.yourservice.yourtenant.example.kpn-dsh.com’ is 3 levels deeper than your platform’s domain name. It isn’t secured by a DV certificate from the DSH, and you can only secure it with your own certificate.
  • ‘example.kpn-dsh.org’ is a platform under the “.org” top-level domain.
    • In this case, you can only secure subdomains with your own certificate.

Note

It’s strongly recommended that you use OV or EV certificates, and some platforms require certificates signed by KPN as a certificate authority. See KPN Certificaten for more information about such certificates.

Organization Validated certificate

For an Organization Validated (OV) certificate, the certificate authority also checks the legal and physical existence of the organization in the certificate’s subject. This validation is more strict, and the certificate proves that a legal entity is actually connected to the certificate.

Extended Validation certificate

For an Extended Validation (EV) certificate, the certificate authority checks the legal and physical existence of the organization in the certificate’s subject. This validation is the most strict one, and it includes additional manual checks of all the domain names in the certificate, checks against official government sources, checks against independent information sources, and phone calls to the company to confirm the position of the applicant. For these reasons, an EV certificate is the most trustworthy.

Public key, private key and passphrase

The client and the server can establish an encrypted TLS connection once the client has ascertained the identity of the server via the certificate. The public key and the private key play a crucial part when establishing this TLS connection:

  • You can only decrypt a message that was encrypted using a public key if you have the associated private key, and vice versa.
  • The public key is part of the server’s certificate and is thus shared publicly.
  • The private key is stored on the server and you should never share it. If you share a private key, then you compromize all TLS connections.
  • You can use a key passphrase to encrypt the private key. This adds an extra layer of security: if an encrypted private key does become public, then one still needs the passphrase to decrypt it.

In order to add a certificate to the DSH, you first need to add the certificate and the private key as secrets to the DSH, in the PEM format. Optionally, you can also add the key passphrase as a secret.

Managing certificates

You can manage your certificates in the DSH Console.

Tip

You can also use endpoints in the Tenant Management API to manage certificates.

Adding a certificate

When you create a certificate, then you need to link it to the DSH secrets that contain the certificate itself, the private key, and optionally the key passphrase. You can do this in two ways:

  • Add the necessary secrets to the DSH first, and then select them when you create the certificate. See Adding a secret for more information.
  • Create a certificate, and add the necessary secrets in the process.

Take the following steps to add a certificate:

  1. Click “Resources” > “Certificates” in the menu bar of the DSH Console.
  2. Click the “+ Certificate” button.
  3. Fill out the following fields:
    • Name: Enter an name that’s unique in your tenant.
    • Certificate secret: In the dropdown list, select the DSH secret that contains the certificate, or click the “+” button to create a new secret.
    • Certificate key secret: In the dropdown list, select the DSH secret that contains the private key, or click the “+” button to create a new secret.
    • Certificate key passphrase secret: In the dropdown list, select the DSH secret that contains the passphrase of the private key, or click the “+” button to create a new one. Using a passphrase is optional, but it adds an extra layer of security.
  4. Click “Create certificate” to add the certificate.

Once you’ve added the certificate, it will immediately secure all domain names listed as Subject Alternative Names (SANs) in the certificate. The DSH Console also marks any vhosts for these domain names with a “Certificate” label. Click this label to inspect the certificate in question.

Inspecting a certificate

Take the following steps to inspect an existing certificate:

  1. Click “Resources” > “Certificates” in the menu bar of the DSH Console.
  2. Click the “Configure” button for the certificate that you want to inspect.

The details page displays the following properties of the certificate:

  • Distinguished Name: The information in a certificate that identifies the owner of the certificate, and the certificate authority that issued the certificate.
  • Serial Number: A unique ID that identifies the certificate in a certificate authority’s systems.
  • Not Before: The earliest date and time when the certificate is valid.
  • Not After: The latest date and time when the certificate is valid.
  • DNS Names: The domains that the certificate secures.
  • Secrets: The DSH secrets that the certificate uses, namely for the certificate itself, the private key, and optionally the passphrase for the private key.

Updating a certificate

In order to update a certificate, you only need to update its secrets, see Editing a secret for more information. You can reach these secrets in different ways:

  • Click “Resources” > “Certificates” in the menu bar of the DSH Console, and click the “Inspect” button for the certificate in question. You can reach the secrets by clicking the buttons under “Secrets”.
  • Click “Resources” > “Secrets” in the menu bar of the DSH Console. Click the “Configure” button for the secrets in question.

If a certificate is only valid for 20 days or less, then the DSH displays a notification of type “User action required” in different places:

  • The status bar of the DSH Console
  • The “Notifications” page
  • The overview page at “Resources” > “Certificates”
  • The details page of the certificate in question
  • Under the “Certificate” field in configuration pages (e.g. for a Kafka Proxy)

If you receive this notification, then you need to request a new certificate from you certificate authority:

  • Once you receive the new certificate, you need to update the value of the DSH secret that holds the certificate, following the steps above.
  • If the private key and its passphrase also need an update, then you need to replace the values of these secrets, too.
  • Once you update the certificate, the DSH will stop displaying the notification.

Tip

The notification contains direct links to the DSH secrets for the certificate and the private key.

Deleting a certificate

Take the following steps to delete a certificate:

  • Click “Resources” > “Certificates” in the menu bar of the DSH Console.
  • Click the “Delete” button for the certificate that you want to delete, and click “Yes, delete” to confirm.

Note

The DSH doesn’t delete the linked DSH secrets automatically, so you need to delete these separately. See Deleting a secret for more information.

Creating a self-signed certificate

For testing purposes, it can be useful to create your own certificates before you request them from an official certificate authority (CA). This section shows you how to create your own CA, and how to use it to generate and sign a server certificate.

The certstrap tool allows you to create and sign certificates easily. Certstrap requires the “Go” programming language, see the Go releases page for more information.

If you installed Go, then you can take the following steps in a Terminal window on your computer:

Build certstrap
1
2
3
git clone https://github.com/square/certstrap.git
cd certstrap
go build

Navigate into the “certstrap” directory that you just created and initialize a new CA:

Create CA
1
2
cd certstrap
./certstrap init --common-name "my-own-ca.com"

Enter and confirm a passphrase for your CA. In the out folder, certstrap creates a certificate (.crt), private key (.key), and certificate revocation list (.crl).

Next, request a server certificate. In the example, make sure to replace the value for the domain with the correct domain that you need a certificate for:

Request server certificate for one domain
1
./certstrap request-cert --common-name "test-my-service" --domain "yourservice-1.yourtenant.example.kpn-dsh.com"
Request server certificate for multiple domains
1
./certstrap request-cert --common-name "test-my-service" --domain "yourservice-1.yourtenant.example.kpn-dsh.com", "yourservice-2.yourtenant.example.kpn-dsh.com"

Enter and confirm a passphrase for your private key. In the out folder, certstrap creates a private key (.key) and a certificate signing request (.csr).

Finally, use your CA to sign the certificate:

Sign the server certificate
1
./certstrap sign "test-my-service" --CA "my-own-ca.com"

Enter the passphrase that you created for your CA. In the out folder, certstrap creates a certificate (.crt). You now have all the information to create a certificate in the DSH:

  • Paste the contents of “test-my-service.crt” in the DSH secret for the certificate.
  • Paste the contents of “test-my-service.key” in the DSH secret for the private key.
  • In the DSH secret for the passphrase of the private key, enter the passphrase that you created when you requested a server certificate with certstrap.

See Adding a certificate or Updating a certificate for more information.