Authentication

Purpose

The TomTom Intermediate Traffic API (hereafter called “API”) is a secure API that uses an API Key in combination with a TLS certificate. This document contains the steps required for setting up (and renewing) the security certification, and it explains how the certificate needs to be used with the API.

How do you request a client certificate?

Certificates are being created with the HydrantID ACM tool. It is a platform for managed PKI (public key infrastructure) that we use to manage certificates. In the following steps we describe how such a certificate can be requested and accessed from this tool.

Step 1: Request access to HydrantID ACM

Proceed directly to Step 2 if the certificate owner details have been provided in the feed request form.

TomTom grants you access to the HydrantID ACM tool. You will be able to request and renew certificates directly from the tool. To get access, send a mail with the following information to your TomTom account manager:

• Email subject: "HydrantID ACM access for Intermediate Traffic API customer XYZ”. Replace XYZ with the name of your company.
• Add the Requester details:
  1. Your first name.
  2. Your last name.
  3. Email address, preferably a group email. This address receives all communications from HydrantID. Since HydrantID will also send expiration notifications to that address, make sure it doesn't expire!

Step 2: Register at HydrantID ACM

The email address of the requester receives an invitation email from support@hydrantid.com (this may take up to three (3) business days). Please follow the instructions in that email.

The invitation link expires after 24 hours. If you don't accept the invitation in time, we ask you to contact your TomTom account manager and re-request the invitation.

Important

To make sure you receive e-mails from HydrantID ACM, the email address support@hydrantid.com should be set as "trusted" in your email software. If you have not set HydrantID ACM as a trusted sender, the emails may end up in your junk folder.

Step 3: Create a certificate signing request file (CSR)

The CSR contains information that is included in the certificate to identify the requester. It contains the public key that is included in the certificate. A private key is usually generated when the CSR is created, making a key pair. This CSR file is used later to request the certificate.

There are various tools to generate a CSR. This is an example using the OpenSSL tool to create a CSR along with a new private key that uses 2048 bits in length. If OpenSSL is installed on your system, use this command:

openssl req -out CSR.csr -new -newkey rsa:2048 -nodes -keyout privateKey.key

The CSR creation tool requests various information that it needs for your certificate request. The following is an example for the input form of the OpenSSL tool.

Example: For the organization unit "Traffic Unit" of the fictitious company "Traffic Company XYZ" with its registered office in the city of Maastricht in the Province Limburg in the Netherlands needs the following information for CSR creation.

1Country Name (2 letter code) []: NL
2State or Province Name (full name) []: Limburg
3Locality Name (eg, city) []: Maastricht
4Organization Name (eg, company) []: Traffic Company XYZ
5Organizational Unit Name (eg, section) []: Traffic Unit
6Common Name (eg, fully qualified host name) []: traffic-company-xyz.com
7Email Address []:
8A challenge password []:

The password field can be left empty.

Possible values for the common name (CN) can be:

• the Fully Qualified Domain Name (FQDN) of your service (in our example we used traffic-company-xyz.com),
• an email address (in our example this company could have created an email address like contact@traffic-company-xyz.com and used it as CN), or
• the name of your company (in our example this would have meant using the same content for the CN as for the organization name, i.e., "Traffic Company XYZ").

It is not allowed to use a name that contains “TomTom” or any of our server names.

Important

The private key that was either used to create the CSR or was created along with the CSR (see the previous example with OpenSSL) always stays with you and must never be sent to TomTom or be shared with any other third party.

Step 4: Request the certificate with the CSR at HydrantID ACM

Requesting the certificate in the HydrantID ACM portal is as follows:

1. Use the requester email address to log in to the portal: https://acm.hydrantid.com/login
2. Go to "Request".
3. Paste your CSR that you have created in Step 3 and press "PARSE CSR".
4. Check the content of the CSR and press "REQUEST CERTIFICATE" if everything is OK.
5. Now the certificate is waiting for approval. You can view the status under "Requests Queue".

Step 5: Download the certificate from HydrantID ACM

Once TomTom approves your certificate request, the certificate is ready for you to download under "View".

On the certificate downloads dialog, we offer different certificate formats. You can choose the one that best fits your setup. Check "Include Certificate Chain?" to include the intermediate and the root CA certificate. They only need to be installed if they are not trusted in your system.

Certificates are valid until the expiry date of the certificate.

After download TomTom registers the certificate in your account.

How can I know when the client certificate is expired?

The client certificate is only valid up to three (3) years. The HydrantID ACM system sends an email notification from no-reply@acm.mg.hydrantid.com to you 30 days prior to the certificate expiration date. It is your responsibility to apply for the renewal of the certificate in a timely manner. To ensure your certificate remains valid and operational, we strongly recommend that you actively monitor the validity of the client certificate. You cannot access the API with an expired client certificate. If your certificate is about to expire or if it is already expired, follow the instructions in How do you renew a client certificate?.

The following is an example of how to extract the expiry date from a certificate using OpenSSL:

openssl x509 -enddate -noout –in {client-certificate-file}

Important

To make sure you receive expiration notification emails from HydrantID ACM, the email address no-reply@acm.mg.hydrantid.com should be set as "trusted" in your email software. If you have not set HydrantID ACM set as a trusted sender, the emails may end up in your junk folder.

How do you renew a client certificate?

In How can I know when the client certificate is expired? we explain how to be informed about certificate expiration.

The renewal process is as follows:

1. Use the requester email address to log in to the portal: https://acm.hydrantid.com/login

2. Go to "View" and click on the row for your certificate.

3. Depending on the "Policy name" used to issue your certificate, different steps must be taken to renew the certificate:

   • TomTom-Business-to-Business-Client-Certificate-Signing CA 2 SSL Certificate Invitation: Process with Create a new certificate.
   • TomTom Managed B2B Client Certificate: Proceed with Renew the existing certificate.

Create a new certificate

Complete Step 3 through Step 5 under How do you request a client certificate?

Renew the existing certificate

1. Press "RENEW CERTIFICATE", paste a new CSR (we explain how to create a CSR in Step 3 under How do you request a client certificate?) and press "RENEW".
2. Now the certificate is waiting for approval. You can view the status under "Requests Queue".
3. Once TomTom approves your certificate request, the certificate is ready for you to download under "View".

Your old certificate does not become invalid when you renew it. This means that you can renew your certificate in the portal without this having any direct impact on your production environment or any other environment that uses your old certificate.

How can you use the client certificate to download a feed?

The client certificate and the private key must be used with every request made to download a feed.

curl --cert {client-certificate-file} --key {privateKey-file} https://cert-traffic.tomtom.com/tsq/{feed-url-suffix}

wget --certificate={client-certificate-file} --private-key={privateKey-file} https://cert-traffic.tomtom.com/tsq/{feed-url-suffix}

Server certificates

Server certificates used by the API are created by a publicly trusted authority. Thus, they are trusted by most systems by default.

For security reasons these server certificates are replaced once per year. We do not advise pinning or hardcoding the server certificate in your systems.

In case your system does not trust the server certificate of the API, you can retrieve it from the API's server via OpenSSL.

This is an example for our access hosts that requires a client certificate:

openssl s_client -connect cert-traffic.tomtom.com:443 –showcerts > TomTom-server-cert.pem

Then it can be used to verify the peer, for example with the --cacert option in curl:

curl -v –-cacert TomTom-server-cert.pem --cert {client-certificate-file} --key {privateKey-file} https://cert-traffic.tomtom.com/tsq/{feed-url suffix}