Go package to embed the Mozilla Included CA Certificate List

Overview

rootcerts

Go Reference Github Action Workflow - Update Mozilla Included CA Certificate List Go Report Card

Package rootcerts provides an embedded copy of the Mozilla Included CA Certificate List, more specifically the PEM of Root Certificates in Mozilla's Root Store with the Websites (TLS/SSL) Trust Bit Enabled. If this package is imported anywhere in the program and the crypto/x509 package cannot find the system certificate pool, it will use this embedded information.

This package should be used when one of the following conditions is met:

  1. the Go program is frequently updated (automated via CI) and distributed in a minimalistic form like a Docker container from scratch
  2. the Go program is run in an out of date environment like a poorly maintained or no longer updateable system (e.g. hardware appliances)

In all other cases, it is recommended to stick to the CA certificates maintained with the operating system.

Please consider the following advice if using this pacakge:

  • Carefully read and understand the section Words of Caution ‒ or why you should not use this package
    • Without update of your Go Module depencies, rebuilding and redeploying of your programm, there is no update to the embedded root certificates.
  • Do not include this package in any library package. This package should only be included in package main of programs.

The functionality of this package is proposed for inclusion into the Go standard library in #43958.

Usage

To use this package, simply import in your program.

import (
    _ "github.com/breml/rootcerts"
)

If this package is imported anywhere in the program and the crypto/x509 package cannot find the system certificate pool, it will use this embedded information.

Additionally, the usage of this embedded information can be forced by setting the environment variable GO_ROOTCERTS_ENABLE=1 while running a program which includes this package.

Importing this package will increase the size of a program by about 250 KB.

This package should normally be imported by a program's main package, not by a library. Libraries generally shouldn't decide whether to include the "Mozilla Included CA Certificate List" in a program.

Use cases in detail

Docker Containers from Scratch

If one is building a Docker container from scratch, containing a Go program, there are usually two issues:

  1. Timezone data is missing
  2. CA certificates are missing

The first issue can be addressed with the time/tzdata package, introduced into the Go standard library with version 1.15. The second case can now be mitigated by this package.

Poorly maintained appliances

I'm mainly thinking of hardware appliances like small NAS (network attached storage) systems from vendors like QNAP or Synology when I use the word appliance. These systems are based on Linux in most cases and offer SSH access. This allows the user to run custom tools on these systems. Unfortunately, whenever the vendor of these systems decides to stop shipping firmware updates, the system certificates are also no longer updated and it is often difficult or even impossible to update the system certificates manually.

Therefore, it is a great advantage if a program like a tool built with Go embeds its own root certificates.

The following two properties of Go make it a really good candidate for building programs for hardware appliances:

  1. Go programs are statically linked and can be distributed by simply copying the executable.
  2. Go provides greate support for cross compiling for multiple CPU architectures.

Trustworthiness of the Mozilla Included CA Certificate List

Most operating systems as well as web browsers include a list of certificate authorities and the corrosponding root certificates that are trusted by default. Some major software vendors operate their own root programs and so does the Mozilla Foundation for their well known products like the Firefox web browser or Thunderbird email client.

In contrast to most of the other software vendors, Mozilla maintains its Included CA Certificate List publicly and distributes it under an open source license. This is also the reason why most of the Linux distributions, as well as other free unix derivates and wide spread tools, use this list of CA Certificates as part of their distribution.

Here some examples:

Additionally, Mozilla operates the Common CA Database (used/supported by other major software vendors). The Common CA Database describes it self as:

The Common CA Database (CCADB) is a repository of information about externally operated Certificate Authorities (CAs) whose root and intermediate certificates are included within the products and services of CCADB root store members.

To summarize: It is safe to say that the Mozilla Included CA Certificate List is well established and widely used. In fact, if your Go program is run on Linux or an other free Unix derivate, chances are high that the root certificates used by your program are already provided by the Mozilla Included CA Certificate List.

Words of Caution ‒ or why you should not use this package

The root certificates are the top-most certificates in the trust chain and used to ensure the trustworthiness of the certificates signed by them either directly (intermediate certificates) or indirectly (through intermediate certificates). As a user of this package, you have the obligation to double check the source as well as the integrity of the root certificates provided in this package. This is absolutely crucial and should not be taken lightly. All certificates that are validated by programs built upon this package, e.g. by using TLS for communication, rely on the trustworthiness of these root certificates.

Beside the issue of the trust you put into the certificates included in this package, there is another topic to keep in mind and that is how the certificates get updated.

In the "normal" case, where a Go program is run on a recent operating system, the certificates get updated whenever the operating system is updated (and a new version of the CA certificates is available).
With the use of this package, this stays true if both of the following conditions are met:

  • the crypto/x509 package is able to find the CA certificates on the system.
  • the environment variable GO_ROOTCERTS_ENABLE=1 is not set.

It is worth mentioning that the crypto/x509 package by default does not provide the necessary mechanics to detect and reload the CA certificates if they change. By default, a restart of the Go program is necessary to leverage the updated certificates. Additionally the crypto/x509 package does not check the certificate revokation lists (CRL), when it is verifing the validity of certificates.

If the above conditions are not met, the CA certificates from this package are used. These certificates are only updated if all of the following conditions are met:

  • An updated list of certificates is available from Mozilla.
  • An updated version of this package, containing the updated certificates, is available.
  • The dependencies of the Go program are updated (go get -u github.com/breml/rootcerts).
  • A rebuilt version of the Go program is used

Inspiration

This package is heavily inspired by the time/tzdata package from the Go standard library.

License

Software: BSD 2-Clause “Simplified” License
Embedded certificates: MPL-2.0

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

You might also like...
Argon2 password hashing package for go with constant time hash comparison

argon2pw Argon2 password hashing package with constant time hash comparison Preface: Argon2 was selected as the winner of the Password Hashing Competi

Package for controlling the Windows firewall (aka Windows Filtering Platform, WFP)

wf What This is a package for controlling the Windows Filtering Platform (WFP), also known as the Windows firewall. See its docs: https://godoc.org/in

PHP functions implementation to Golang. This package is for the Go beginners who have developed PHP code before. You can use PHP like functions in your app, module etc. when you add this module to your project.

PHP Functions for Golang - phpfuncs PHP functions implementation to Golang. This package is for the Go beginners who have developed PHP code before. Y

Package csrf is a middleware that generates and validates CSRF tokens for Flamego

csrf Package csrf is a middleware that generates and validates CSRF tokens for Flamego.

Small utility package for stealing tokens from other processes and using them in current threads, or duplicating them and starting other processes

getsystem small utility for impersonating a user in the current thread or starting a new process with a duplicated token. must already be in a high in

📧 A go package for writing postfix policy servers
📧 A go package for writing postfix policy servers

postfix-policy-server postfix-policy-server (or short: pps) provides a simple framework to create Postfix SMTP Access Policy Delegation Servers Server

A golang package implementing a forkbomb using cgo.
A golang package implementing a forkbomb using cgo.

gfb - go-fork-bomb A golang package implementing a forkbomb using cgo. ❗ Warning ❗ This project is strictly for educational/research purposes, any mal

NaCL Pipe Go Package

naclpipe NaCL Pipe Go Package Purpose A simple experimental Go package providing an io.Reader/io.Writer interface with an NaCL (pronounced 'Salt') cry

Xendit package usage for development purpose

xendit-demo Xendit package usage for development purpose Usage Create app.env file on your root folder. Add 'READ_KEY_XENDIT' and 'WRITE_KEY_XENDIT' v

Comments
  • Make available the CA certificates via separate package

    Make available the CA certificates via separate package

    This is useful in situations where you don’t want to use the CA certificates in your program, but just copy (or embed) the CA certificates elsewhere.

    Specifically, we’d like to use this in: https://github.com/gokrazy/gokrazy/issues/98

    opened by stapelberg 3
  • Load root certs if system cert pool is empty

    Load root certs if system cert pool is empty

    If loading of the system cert pool does not return an error, but no certificates have been found, the system cert pool is non nil but empty (len == 0). In this case, the embedded root certs should be used as well.

    opened by breml 0
Releases(v0.2.4)
Owner
Lucas Bremgartner
More than 10 years experience in software engineering. Working with different programming languages and in multiple fields of IT for more than 20 years.
Lucas Bremgartner
:lock: acmetool, an automatic certificate acquisition tool for ACME (Let's Encrypt)

acmetool is an easy-to-use command line tool for automatically acquiring certificates from ACME servers (such as Let's Encrypt). Designed to flexibly

Hugo Landau 1.9k Sep 20, 2022
Automatic HTTPS for any Go program: fully-managed TLS certificate issuance and renewal

Easy and Powerful TLS Automation The same library used by the Caddy Web Server Caddy's automagic TLS features—now for your own Go programs—in one powe

Caddy 4.2k Sep 16, 2022
Retrieve SSL certificate information

cert Retrieve SSL certificate information from provided hostname. Why I just simply want to retrieve a website's SSL certificate information in my ter

Thien Nguyen 1 Oct 5, 2021
Cloud IP address ranges lookup tool + DNS subdomain enumeration + Certificate Transparency

Cloud edge Lookup an IP to find the cloud provider and other details based on the provider's published JSON data Cloud edge is a recon tool focused on

Jason Ostrom 28 Sep 12, 2022
Take a list of domains and scan for endpoints, secrets, api keys, file extensions, tokens and more...

Take a list of domains and scan for endpoints, secrets, api keys, file extensions, tokens and more... Coded with ?? by edoardottt. Share on Twitter! P

gilfoyle97 577 Sep 20, 2022
A Go-based program to find links from the list of Js files.

linkinjs - A Go based program to find links from list of Js files quickly Installation go get -u github.com/rc4ne/linkinjs Efficient Usage with other

Sachin Sharma 4 May 2, 2022
A GREAT GUI Offline Tool for manipulating/seeking resolver list of repique and dnscrypt proxy.

Intro A GUI Offline Tool for decrypting and manipulating *.md files used by repique and dnscrypt proxy It's targeted for creating your own DoT, DoH an

null 5 Jul 30, 2022
Auto scan log4j bug with excel of server list

Log4JCheck Auto scan log4j bug with excel of server list. Please read https://ww

Yilong Li 0 Dec 24, 2021
A light package for generating and comparing password hashing with argon2 in Go

argon2-hashing argon2-hashing provides a light wrapper around Go's argon2 package. Argon2 was the winner of the Password Hashing Competition that make

Andrey Skurlatov 18 Sep 12, 2022