Appendix

General information

What is happening?

Key Point: In late 2017 Google started a multi-year migration to its own root certificate
authority Google Trust Services. The root certificate authority is
to verify the security of all TLS/SSL connections to the Google Maps Platform. The vast
majority of clients will not be affected by this change but owners of some applications may need to
verify and update their client services to ensure a smooth transition through the entire migration
by following the recommendations in this document.

The big picture

Google is working on a multi-year plan to issue and use its own root
certificates, the cryptographic signatures which are the basis of
TLS/SSL internet security used by HTTPS.

Currently, the TLS security of the Google Maps Platform is guaranteed by a root
certificate issued by GeoTrust Global CA, a very well known and widely trusted
certificate authority (CA) which is owned by Symantec. Practically all TLS
clients (such as Web browsers, smartphones, and application servers) are aware
of this root certificate, and therefore can use it to ensure that they have a
secure connection to the Google Maps Platform servers.

By the early 2020s, Google plans to migrate all Google Maps Platform services to a
root certificate issued by Google's own certificate authority, Google Trust Services (GTS).

As an interim step, in early 2018 Google Maps Platform migrated to another
widely-trusted root certificate from GlobalSign (GS). Google has purchased the
use of this root certificate (and the CA that GlobalSign used to issue it) in
order to ease the certificate transition.

The vast majority of TLS clients already recognise the GlobalSign root
certificate, so their usage of the Google Maps Platform will not be affected by this
initial change.

However, especially in some specialist use cases such as embedded devices, or
users working with very outdated legacy browsers or operating systems, it is
possible that some clients will lack the GlobalSign root certificate. These
clients will need to be updated with the certificate in order to be able to
secure their Google Maps Platform connections. It is not possible for Google to
identify these clients, so application owners must carry out any necessary
verification on their own applications. Google Trust Services provides HTTPS
test endpoints at GTS site to help with
this. See below for more technical details.

The same will likely apply to most systems by the time the migration to GTS root certificates
begins, but following the recommendations in this document should generally ensure a smooth
migration even for specialist systems.

Technical summary

Key Point: The Google Maps Platform frontends transitioned to using the "GlobalSign
Root R2" certificate authority in early 2018. Application developers should
expect that their Google Maps Platform clients will authenticate against this
root CA. In the long term, developers should anticipate that clients will
authenticate against root certificates from Google Trust Services, and possibly for an
interim period at least against the "GlobalSign Root R3" CA.

As announced in the Google Maps Platform Premium Plan customer support portal on
March 16 2017, and earlier on the Google
Security Blog, Google has created its own root CA, GTS. Along with other Google services, the Google
Google Maps Platform will gradually transition to TLS certificates signed by GTS root CAs.

As an interim step, Google has purchased the existing, widely-trusted GS Root R2
CA. The Google Maps Platform started migrating from the GeoTrust root certificate to this
certificate in late 2017, finishing the migration in early 2018.

Almost all TLS clients are preconfigured with the GS Root R2 certificate or
receive it via normal software updates, but, if an application connects to the
Google Maps Platform from clients that may not recognize this certificate, the
application developers should ensure that the clients are tested and if
necessary updated with the certificate.

The GS Root R2 certificate and all GTS root certificates are available via the
GTS site. For testing
purposes, the GTS site also provides endpoints with TLS certificates signed by
each CA. In particular, if your client can establish a TLS connection to GS Root R2 test endpoint then
it trusts the GS Root R2 certificate and should not be affected by the upcoming
change.

Google will rely on GS Root R2 CA at least through the end of 2018. After that,
the Google Maps Platform may transition directly to the GTS CA, or may on occasion
fall back to third-party root CAs including GS
Root R3 CA.

Key point:To completely future-proof your application, we recommend
your applications trust all root certificates listed in the Google sample PEM file. This file includes
all CAs that may plausibly be used by Google services in the foreseeable future.

How do I get updates on this migration process?

Star public issue 67842936 for updates. This
FAQ is also updated throughout the migration process, whenever we encounter topics that may be of
general interest.

We use multiple Google services. Will the root CA migration affect all of them?

Yes, the root CA migration will happen across all Google services and APIs, but the timeline may
vary per service. However, once you have verified that your application trusts the recommended set
of root certificates listed in the Google sample PEM file,
your application should be future proof during the root certificate migration, no matter which
Google API or service it might call. See question Should I install
all root certificates from the Google sample PEM file? for further details.

Caution: We may in the coming years on occasion fall back to
third-party root CAs, including GS
Root R3 (verifiable using the GS Root R3 test endpoint), so
unless you already are able to connect to all of the below test
endpoints, you will still have to update your certificate store within the
next few years:

Therefore, we strongly recommend that you install now all certificates from the
Google sample PEM file to future proof
your system, unless you are certain that you will always manage to keep your
production environment completely up to date and patched up.

How will the migration proceed?

When will the migration occur?

The first migration phase, switching over to certificates issued by intermediate CAs anchored in
GS Root R2, started in late 2017 and finished in the first half of 2018.

Warning:
Google services may switch certificates at any time, without warning. This may also happen to
intermediate CA certificates, and services might even migrate from one intermediate CA
to another. Therefore, developers should never directly trust server
certificates, or even individual intermediate CAs. It is always
recommended to only rely on the root CA certificate to verify the trustworthiness
of the entire server certificate chain.

The schedules of later migration phases will be announced in the coming years,
but well in advance of the GS Root R2 2021 certificate expiration.

General rollout plan for each Google service

The staged rollout starts in a single data center.

The rollout is gradually extended to more data centers until there is global
coverage.

If serious issues are detected at any stage, the tests can be rolled back
temporarily while the issues are addressed.

Based on input from previous iterations, further Google services are
included in the rollout until gradually all Google services have migrated to the
new certificates.

Who will be affected, when, and where?

Increasing numbers of Google Maps Platform developers will start to receive the
new certificates as new data centers are migrated over. The changes will be
somewhat localized, as client requests tend to be forwarded to servers in
geographically nearby data centers. As we cannot with certainty in advance say
who will be affected, when and where, we recommend all our customers already
verify their systems are future proof, well in advance of the next phases of the
Google Root CA migration.

What to look out for

Clients that are not configured with the necessary root certificate will not be
able to verify their TLS connection to the Google Maps Platform. In this situation,
clients will typically issue a warning that certificate validation has failed.
Depending on their TLS configuration, clients may continue to issue a Google Maps Platform
request, or they may refuse to continue with the request.
Note: In case of systematic failures, see question
What to do in a production outage?.

What are the minimum requirements for a TLS client to communicate with Google Maps Platform?

Please refer to section What are the recommended minimum requirements for a Transport Layer
Security (TLS) client to communicate with Google? in the
GTS FAQ.

Google Maps Platform does not impose any additional requirements.

Which kinds of applications are at risk of breaking?

The application uses the system certificate store without any developer
imposed restrictions

Google Maps Platform web service applications

If you are using a mainstream OS, e.g., Ubuntu, Red Hat, Windows 7+ or Server
2008+, OS X) that is still maintained and receives regular updates, your default
certificate store should already include the GS Root R2 certificate.

If you are using a legacy OS version that no longer receives updates, you may or
may not have the GS Root R2 certificate. For example, Windows XP SP2 includes
the certificate, but Windows XP SP1 does not. Legacy devices should be tested to
ensure that they trust the certificate.

If you are pinning certificates or public keys for the Google domains your
application connects to, you should add the certificates and public keys to the
list of trusted entities in your application.

For further information about certificate or public key pinning, refer to the
external resources listed under question Need more info?.

Should I install all root certificates from the Google sample PEM file?

If you wish to future proof your system now in one go, we recommend that you
install all certificates from the Google sample PEM file, especially if you do not
regularly and routinely apply operating system updates to your system, or if you
for example maintain your own certificate bundles for your application.

Why should I not install any intermediate CA certificates?

Warning:
You should never configure your services to explicitly trust any intermediate CA! Doing so
will risk breaking your application at any point we enroll a new intermediate
certificate, which may happen at any time and without any prior notice.

You should only install the root certificates from the Google sample PEM file, and rely on the root certificate to
verify the authenticity of the entire certificate chain anchored to it. This applies equally
to individual server certificates (e.g. those served by the host maps.googleapis.com), as well as
any of our intermediate CAs (e.g. GIAG3, GTS CA 1O1 or GIAG4).

Any modern TLS library implementation should be able to automatically verify such chains of trust,
as long as the root certificate authority is trusted.

Are Google Maps JavaScript API applications at risk of breaking?

The GlobalSign R2 root CA is well embedded, and trusted by most modern browsers.
Therefore, it is likely that these browsers will continue to be able to connect
to Google services for some time. If the browser is actively maintained, it is
also almost certain that it will at some point also support all other Google
root CAs.

However, the Google Maps JavaScript API itself is only guaranteed to work on supported
browsers, so we recommend using one of the listed browsers and keeping the
browser up to date to ensure problem free use.

Note: Your browser might not yet trust the newly-created GTS
Root CAs, so make sure to keep your browser updated to avoid any root CA
migration related service interruptions in the future. Every modern browser
should allow end users to verify which certificates it trusts. Although the
exact location differs with each browser, the list of certificates can typically
be found somewhere under Settings.

Are mobile applications at risk of breaking?

Android and Apple devices still receiving regular updates from the device
manufacturer are also expected to be future proof. Most older Android phone
models already include at least both the GS Root R2 and GS Root R3 certificates,
although the list of trusted certificates may vary per handset manufacturer,
device model and Android version. Newer Android Open Source Project (AOSP)
versions used on Google Nexus and Pixel branded devices also trust GS Root R4
by default. Support for the GTS Root CAs is still minimal in any of the released
Android versions.

Caution:
As individual handset manufacturers may have chosen to include different sets of
trusted root certificates, the most reliable way to verify which root certificates are
available on an Android device is for the end user to verify this themselves. All Android
versions starting from Android Ice Cream Sandwich (4.0) should offer the list of
trusted root CAs under settings, although the actual path may vary.

For iOS devices, Apple maintains a list of trusted root CAs for each recent iOS
version on its support pages. However, all iOS versions 5 and up support GS
Root R2 and R3, versions 7 and up also GS Root R4. As with current Android versions,
GTS Root CAs are not yet supported at the time of writing.

When will my browser or operating system include the Google Trust Services root certificates?

Google is working with all major third parties maintaining widely used and
trusted root certificate bundles. Examples include operating system
manufacturers, such as Apple and Microsoft, but also Google's own Android and
ChromeOS teams; browser developers, such as Mozilla, Apple, Microsoft, but also
Google's own Chrome team; manufacturers of hardware, such as phones, set-top
boxes, TVs, game consoles, printers, just to name a few.

As third-party certificate inclusion timelines are largely beyond the control of
Google, the best general advice we can offer is to make sure you regularly apply
available system updates. Select third parties, such as Mozillaʼs CA
Certificate Program may have documented their own certificate
inclusion timelines.

Troubleshooting

Where can I get the tools I need?

Getting curl

If your OS distribution doesn't provide curl, you can download it
from https://curl.haxx.se/. You can either
download the source and compile the tool yourself or download a pre-compiled
binary, if one is available for your platform.

Getting Java keytool

The keytool command line tool should be shipped with every Java
Development Kit (JDK) or Java Runtime Environment (JRE) version. Install these
to get keytool. However, using keytool is unlikely
necessary for root certificate verification, unless your application is built
using Java.

What to do in a production outage?

The primary course of action for you is to install the required root
certificates from the Google sample PEM file into the
certificate trust store your application uses.
Note: This method varies per operating system, possibly even
the SSL/TLS library your application uses. Therefore, please always first refer
to your system documentation!
However, you may still find useful information in section Managing your trusted certificates.

Work together with your system administrators to upgrade your local certificate store.

Check this FAQ for pointers applicable to your system.

If you need further platform- or system-specific assistance, reach out to the technical support
channels offered by your system provider.

Filing a support case

When filing a support case, in addition to the data listed in section
Initial troubleshooting, please also provide the following:

What are your public IP addresses?

What is the public IP address of your DNS server?

If possible, a tcpdump or Wireshark packet capture of the failed TLS negotiation against
https://maps.googleapis.com/ (pcap format using a sufficiently large
snapshot length to capture the entire packet without truncating it)

Posting on public issue 67842936

Caution: As the issue tracker is a public forum, avoid posting any
personally identifiable or sensitive information, such as IP
addresses, email addresses, API keys or other credentials. If you need to share such information,
please always file a support case, as explained in section
Filing a support case.

Caution: There are multiple widely used SSL/TLS libraries (see
comparison table on
the curl site), which may all be configured to use different root certificate
bundles/certificate stores. If curl has been linked against a different SSL/TLS
library that your application, you might wish to double check that both point to
the same certificate store for the test results to be completely reliable.
Note: If you maintain your own certificate bundle for your
application or the application just uses a different store than
curland you wish to verify the one used by your
application, you can export the certificates from that store into a PEM file,
which you can pass to curl using the --cacert flag.
See section Managing your trusted certificates.

User agent

Outgoing requests contain the User-Agent header that may provide useful
information about curl and your system.

Failed TLS handshake

Lines, such as the ones below indicate the connection was terminated
mid-TLS-handshake because of an untrusted server certificate. The absence of
debug output starting with '>' or '<' are also
strong indicators of an unsuccessful connection attempt:

Successful TLS handshake

A successful TLS handshake is indicated by the presence of similar looking lines
to the ones below. The cipher suite used for the encrypted connection should be
listed, as should details of the accepted server certificate. Furthermore, the
presence of lines starting with '>' or '<' indicate
that payload HTTP traffic is being successfully transmitted over the TLS
encrypted connection:

Managing your trusted certificates

How can I check the trusted root certificates on my mobile phone?

Android trusted certificates

As mentioned under question Are mobile
applications at risk of breaking?, Android has since version 4.0 allowed handset users to verify
the list of trusted certificates under Settings. The table below shows the exact
Settings menu path:

The table below illustrates the likely availability of the most critical root
certificates per Android version, based on manual verification using currently available Android
Virtual Device (AVD) system images, falling back to the AOSP ca-certificates
Git repository version history whenever system images are no longer available:

Android version

GS Root R2

GS Root R3

GS Root R4

GTS

2.3, 3.2, 4.x, 5.0

5.1, 6.x, 7.x, 8.x, 9

10

Updating the Android system certificate store is generally not possible without a firmware update or
rooting the device. However, the current set of trusted root certificates on most still widely
used Android versions is likely to provide uninterrupted service for multiple years to
come, beyond the effective lifetime of most currently existing devices.

Beginning with version 7.0, Android offers application developers a secure method for
adding trusted certificates which are only trusted by their application. This is done by
bundling the certificates with the application and creating a custom network security configuration,
as described in the Android Best Practices for Security & Privacy Network Security
Configuration training document.

However, as third-party application developers will not be able to influence the network security
configuration of traffic originating from the Google
Play Services APK, such efforts would likely only provide a partial workaround.

On older legacy devices, your only available option would be to rely on user-added CAs, either
installed by a corporate group policy applied to the end user device, or by the end users
themselves.

However, any additional certificates installed on the iOS device should be
visible under Settings > General > Profile. If no additional
certificates are installed, the Profile menu item may not be displayed.

The table below illustrates the availability of the most critical root certificates per iOS
version, based on the above sources:

iOS version

GS Root R2

GS Root R3

GS Root R4

GTS

5, 6

7, 8, 9, 10, 11, 12.0

12.1.3+

Where is my system certificate store located and how can I update it?

The location of the default certificate store varies with operating system and
used SSL/TLS library. However, on most Linux distributions, the default root
certificates can be found under one of the following paths:
/usr/local/share/ca-certificates (Debian, Ubuntu, older RHEL and
CentOS versions) , /etc/pki/ca-trust/source/anchors and
/usr/share/pki/ca-trust-source (Fedora, newer RHEL and CentOS
versions) or /var/lib/ca-certificates (OpenSUSE). Other certificate
paths may include /etc/ssl/certs (Debian, Ubuntu) or
/etc/pki/tls/certs (RHEL, CentOS). Some of the certificates in
these directories are likely symbolic links to files in other directories.

Caution: Just adding a new certificate to these paths may not be
enough. To reconfigure your system to start using them, you will likely need to
run a separate command, such as /usr/sbin/update-ca-certificates
(Debian, Ubuntu) or /bin/update-ca-trust (Fedora, RHEL and
CentOS), which create the actual root certificate bundle that is used.
Note: Your application may also have been configured to use a
custom certificate store or root certificate bundle, so make sure you update the
correct one!

OpenSSL

For applications using OpenSSL, you can check the configured
location of its installed components including the default certificate store using the
following command:

openssl version -d

The command prints out OPENSSLDIR, which corresponds to the top level directory the
library and its configurations can be found under:

OPENSSLDIR: "/usr/lib/ssl"

The certificate store is located in the certs subdirectory.
Note: This directory may contain symbolic links that recursively point to
other locations, e.g. to the default system certificate store, as in the example below.

Mozilla NSS

Applications using Mozilla
NSS may by default also use a system-wide certificate database typically located under
/etc/pki/nssdb, or a user-specific default
store under ${HOME}/.pki/nssdb. For updating NSS, check out the
certutil tool documentation
for how to add new certificates, as well as the official OS documentation.

Microsoft .NET

Windows .NET developers may find at least the following Microsoft articles
useful for updating their certificate store:

Java

Java applications might use their own certificate store, which on Linux systems is
typically located at /etc/pki/java/cacerts or
/usr/share/ca-certificates-java. Please refer to the following
Stack Overflow and Oracle articles for help updating your Java certificate store
using the Oracle keytool command line tool:

What is a PEM file?

While the file format itself is human readable, the
Base64 encoded binary certificate data information
is not. However, the PEM specficiation permits emitting
explanatory text either before or
after the text encoded certificate body, and many tools use this feature to also provide a
clear-text summary of the most relevant data elements in a certificate.

What is a DER file?

What is a ".cer" file?

An exported file with a ".cer" suffix may contain a PEM-encoded certificate, but more
typically a binary, usually DER-encoded certificate. By
convention, ".cer" files generally only
contain a single certificate.

The PEM files issuer=….pem can then be imported individually, or further
converted into a file format your certificate store accepts.

How do I convert between a PEM file and a format supported by my system?

The OpenSSL toolkit command-line tool openssl
can be used to convert files between all commonly used certificate file formats. Instructions for
converting from a PEM file to most commonly used certificate file formats are listed below.

How do I see what certificates are installed in my certificate store?

This varies per operating system and SSL/TLS library. However, the tools that
allows importing and exporting certificates to and from the certificate store
typically also provide an option to list the installed certificates.

Also, if you have successfully exported the trusted root certificates into PEM
files, or your certificate store already contains stored PEM files, you can try
opening the files in any text editor, as it is a plain text file format.

The PEM file may be properly labeled, providing human readable information of
the associated certificate authority (example from the Google sample PEM file):

The file may also just contain the certificate part. In such cases, the name of
the file, such as GlobalSign_Root_CA_-_R2.pem may describe which CA
the certificate belongs to. The certificate string between the
-----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tokens
is guaranteed to be unique for each CA, and you can reliably compare these strings
between PEM files, if you cannot otherwise identify the CAs.

Therefore you can compare each of the certificates in the
Google sample PEM file against the
PEM files you extracted from your certificate store. As each certificate in the
Google root CA bundle is properly labeled, you can reliably verify which of the
certificates you already have in your certificate store and identify which of
them still need to be added, even if your certificate store PEM files were not
labeled.

Appendix

Need more info?

Always rely primarily on your operating system documentation, the documentation
of your application programming language(s), as well as the documentation from
any external libraries that your application is using.

For further details about advanced topics, such as certificate pinning, you may
find the Open Web Application Security Project (OWASP) article
and cheat
sheet informative. For Android specific instructions, please refer to the
official Android Best Practices for Security & Privacy Security
with HTTPS and SSL training document. For discussion about certificate v.s.
public key pinning on Android, you may find Matthew Dolan's blog post Android
Security: SSL Pinning useful.

For a comprehensive list of root CAs trusted by AOSP, refer to the ca-certificates
Git repository. For any versions based on inofficial Android forks, e.g. LineageOS, refer to the
appropriate repositories provided by the OS vendor.