Sorry, you need to enable JavaScript to visit this website.

Authentication

 

On this page

Introduction

The TomTom Intermediate Traffic Service (hereafter called “Service”) is a secure service 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 is explained how the certificate needs to be used with the Service.

▲ Return to top

How do you request a client certificate?

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

Step 1: A certificate signing request file (CSR) needs to be created.

The CSR contains information that will be included in the certificate to identify the requester and it contains the public key that will be included in the certificate. A private key is usually generated when the CSR is created, making a key pair.

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. It is assumed that OpenSSL is installed on your system to use this command:

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

The following information will be requested during CSR creation with OpenSSL:

Country Name (2 letter code) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (eg, fully qualified host name) []:
Email Address []:
A 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, an email address, or the name of your company. 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 also the previous example with OpenSSL) always stays with you and must never be sent to TomTom or be shared with any other 3rd party.

Step 2: The CSR file needs to be mailed to noc@tomtom.com.

In addition to the CSR the mail needs to contain the following information:

  • Email subject: “Client certificate request for Intermediate traffic service for XYZ”
    Replace XYZ with the name of your company.
  • The name of your account manager at TomTom (alternatively: put them CC).
  • Requester details:
    1. First name of the requester.
    2. Last name of the requester.
    3. Preferred group email. This mail will receive all communications from HydrantID. Since HydrantID will also send expiration notifications to that email address it should be ensured that the email address doesn't expire!
    4. Primary phone number.

Step 3: The client certificate will be issued.

Once TomTom receives the CSR, the next steps are:

  1. TomTom validates the CSR.
  2. You receive an email from noreply@trustlink.net with a HydrantID link. HydrantID is TomTom’s chosen certificate tool.
  3. You receive a separate email from TomTom which contains a ‘secret answer’ so you can sign in to HydrantID. You use the email address where you received the invitation (in the previous step) as your username and the secret answer as your one-time password.
  4. Once you are connected to HydrantID, you will be asked to create a new password for future logins.

Important

To make sure you receive e-mails from Hydrant ID, the email address noreply@trustlink.net should be trusted on your side. If you don’t have this set as a trusted sender, the emails may end up in your junk folder.

Step 4: Download the certificate from Hydrant ID portal.

Once you have created your password, you can sign in to HydrantID, download and manage your certificate(s).

On the certificate downloads page, three certificates are offered. It is sufficient to download only the first certificate offered (end-entity certificate). The intermediate and the root CA certificate 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 is going to register the certificate in your account.

▲ Return to top

How can I know when the client certificate is expired?

The client certificate is only valid up to 3 years. The HydrantID system will send an email notification from noreply@trustlink.net to you 30 days prior to the expiration date of the certificate.

It is your responsibility to apply for the renewal of the certificate in due time. To ensure your certificate remains valid and operational, we strongly recommend that you actively monitor the validity of the client certificate. It is not possible to access the Service 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 -text -noout –in <certificate>

▲ Return to top

How do you renew a client certificate?

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

To start the renewal process, a new CSR with a new CN is required.

A mail with the following information needs to be sent to noc@tomtom.com:

  • Email subject: “Renewal of client certificate for Intermediate traffic service”
  • The new CSR.
  • The CN and serial number of the expiring client certificate. The serial number can be found in the expiration notification email from HydrantID, or the HydrantID portal itself.
  • Requester details as explained in Step 2 under How do you request a client certificate?.

Complete Step 3 and Step 4 as in the How do you request a client certificate? section.

▲ Return to top

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

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

Example using curl:

curl --cert <certificate> --key <privateKey> https://cert-traffic.tomtom.com/tsq/<feed-url-suffix>

Example using wget:

wget --certificate=<certificate> --private-key=<privateKey> https://cert-traffic.tomtom.com/tsq/<feed-url-suffix>

▲ Return to top

Server Certificate

Server certificates used by the Service 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 Service, you can retrieve it from the Service’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> --key <privateKey> https://cert-traffic.tomtom.com/tsq/<feed-url suffix>

▲ Return to top