github.com/breml/rootcerts@v0.2.16/README.md (about)

     1  # rootcerts
     2  
     3  [![Go Reference](https://pkg.go.dev/badge/github.com/breml/rootcerts.svg)](https://pkg.go.dev/github.com/breml/rootcerts)
     4  [![Github Action Workflow - Update Mozilla Included CA Certificate List](https://github.com/breml/rootcerts/workflows/Update%20Mozilla%20Included%20CA%20Certificate%20List/badge.svg)](https://github.com/breml/rootcerts/actions?query=workflow%3A%22Update+Mozilla+Included+CA+Certificate+List%22)
     5  [![Go Report Card](https://goreportcard.com/badge/github.com/breml/rootcerts)](https://goreportcard.com/report/github.com/breml/rootcerts)
     6  
     7  Package rootcerts provides an embedded copy of the [Mozilla Included CA Certificate List],
     8  more specifically the [PEM of Root Certificates in Mozilla's Root Store with the Websites (TLS/SSL) Trust Bit Enabled].
     9  If this package is imported anywhere in the program and the [`crypto/x509`] package cannot find the system certificate
    10  pool, it will use this embedded information.
    11  
    12  This package should be used when one of the following conditions is met:
    13  
    14  1. the Go program is frequently updated (automated via CI) and distributed in a minimalistic form like a Docker
    15  container from scratch
    16  2. the Go program is run in an out of date environment like a poorly maintained or no longer updateable system (e.g.
    17  hardware appliances)
    18  
    19  **In all other cases, it is recommended to stick to the CA certificates maintained with the operating system.**
    20  
    21  Please consider the following advice if using this package:
    22  
    23  * Carefully read and understand the section [Words of Caution ‒ or why you should not use this package](#words-of-caution--or-why-you-should-not-use-this-package)
    24    * Without update of your Go Module depencies, rebuilding and redeploying of your programm, there is no update to the
    25    embedded root certificates.
    26  * Do not include this package in any library package. This package should only be included in package main of programs.
    27  
    28  The functionality of this package is proposed for inclusion into the Go standard library in [#43958](https://github.com/golang/go/issues/43958).
    29  
    30  ## Usage
    31  
    32  To use this package, simply import in your program.
    33  
    34  ```Go
    35  import (
    36      _ "github.com/breml/rootcerts"
    37  )
    38  ```
    39  
    40  If this package is imported anywhere in the program and the [`crypto/x509`]
    41  package cannot find the system certificate pool, it will use this embedded information.
    42  
    43  Additionally, the usage of this embedded information can be forced by setting the environment
    44  variable `GO_ROOTCERTS_ENABLE=1` while running a program which includes this package.
    45  
    46  Importing this package will increase the size of a program by about 250 KB.
    47  
    48  This package should normally be imported by a program's main package, not by a library. Libraries
    49  generally shouldn't decide whether to include the "Mozilla Included CA Certificate List" in a program.
    50  
    51  ## Use cases in detail
    52  
    53  ### Docker Containers from Scratch
    54  
    55  If one is building a Docker container from scratch, containing a Go program, there are usually two issues:
    56  
    57  1. Timezone data is missing
    58  2. CA certificates are missing
    59  
    60  The first issue can be addressed with the [`time/tzdata`] package, introduced into the Go standard library
    61  with version 1.15.
    62  The second case can now be mitigated by this package.
    63  
    64  ### Poorly maintained appliances
    65  
    66  I'm mainly thinking of hardware appliances like small NAS (network attached storage) systems from
    67  vendors like QNAP or Synology when I use the word appliance. These systems are based on Linux in most cases and offer
    68  SSH access. This allows the user to run custom tools on these systems. Unfortunately, whenever the vendor of these
    69  systems decides to stop shipping firmware updates, the system certificates are also no longer updated and it is often
    70  difficult or even impossible to update the system certificates manually.
    71  
    72  Therefore, it is a great advantage if a program like a tool built with Go embeds its own root certificates.
    73  
    74  The following two properties of Go make it a really good candidate for building programs for hardware appliances:
    75  
    76  1. Go programs are statically linked and can be distributed by simply copying the executable.
    77  2. Go provides greate support for cross compiling for multiple CPU architectures.
    78  
    79  ## Trustworthiness of the Mozilla Included CA Certificate List
    80  
    81  Most operating systems as well as web browsers include a list of certificate authorities and the corrosponding
    82  root certificates that are trusted by default. Some major software vendors operate their own [root programs] and
    83  so does the Mozilla Foundation for their well known products like the [Firefox] web browser or [Thunderbird] email
    84  client.
    85  
    86  In contrast to most of the other software vendors, Mozilla maintains its Included CA Certificate List publicly and
    87  distributes it under an open source license. This is also the reason why most of the Linux distributions, as well as
    88  other free unix derivates and wide spread tools, use this list of CA Certificates as part of their distribution.
    89  
    90  Here some examples:
    91  
    92  * Debian (and its derivates): [ca-certificates](https://packages.debian.org/en/sid/ca-certificates)
    93  * Red Hat / Fedora / CentOS: [ca-certificates](https://src.fedoraproject.org/rpms/ca-certificates) / [ca-certificates](https://centos.pkgs.org/7/centos-x86_64/ca-certificates-2020.2.41-70.0.el7_8.noarch.rpm.html)
    94  * Alpine Linux: [ca-certificates](https://pkgs.alpinelinux.org/package/v3.12/main/x86/ca-certificates)
    95  * FreeBSD: [ca_root_nss](https://www.freshports.org/security/ca_root_nss/)
    96  * NetBSD: [ca-certificates](https://pkgsrc.se/security/ca-certificates)
    97  * curl: [cacert.pem](https://curl.se/docs/caextract.html)
    98  
    99  Additionally, Mozilla operates the [Common CA Database] (used/supported by other major software vendors). The Common
   100  CA Database describes it self as:
   101  
   102  > The Common CA Database (CCADB) is a repository of information about externally operated Certificate Authorities (CAs)
   103  whose root and intermediate certificates are included within the products and services of CCADB root store members.
   104  
   105  To summarize: It is safe to say that the Mozilla Included CA Certificate List is well established and widely used.
   106  In fact, if your Go program is run on Linux or an other free Unix derivate, chances are high that the root
   107  certificates used by your program are already provided by the Mozilla Included CA Certificate List.
   108  
   109  ## Words of Caution ‒ or why you should not use this package
   110  
   111  The root certificates are the top-most certificates in the trust chain and used to ensure the trustworthiness of the
   112  certificates signed by them either directly (intermediate certificates) or indirectly (through intermediate
   113  certificates). As a user of this package, you have the obligation to double check the source as well as the integrity
   114  of the root certificates provided in this package. This is absolutely crucial and should not be taken lightly. All
   115  certificates that are validated by programs built upon this package, e.g. by using TLS for communication, rely
   116  on the trustworthiness of these root certificates.
   117  
   118  Beside the issue of the trust you put into the certificates included in this package, there is another topic to keep in
   119  mind and that is how the certificates get updated.
   120  
   121  In the "normal" case, where a Go program is run on a recent operating system, the certificates get updated whenever
   122  the operating system is updated (and a new version of the CA certificates is available).\
   123  With the use of this package, this stays true if both of the following conditions are met:
   124  
   125  * the [`crypto/x509`] package is able to find the CA certificates on the system.
   126  * the environment variable `GO_ROOTCERTS_ENABLE=1` is not set.
   127  
   128  It is worth mentioning that the [`crypto/x509`] package by default does not provide the necessary mechanics to detect
   129  and reload the CA certificates if they change. By default, a restart of the Go program is necessary to leverage the
   130  updated certificates. Additionally the [`crypto/x509`] package does not check the certificate revokation lists (CRL),
   131  when it is verifing the validity of certificates.
   132  
   133  If the above conditions are not met, the CA certificates from this package are used. These certificates are only
   134  updated if all of the following conditions are met:
   135  
   136  * An updated list of certificates is available from Mozilla.
   137  * An updated version of this package, containing the updated certificates, is available.
   138  * The dependencies of the Go program are updated (`go get -u github.com/breml/rootcerts`).
   139  * A rebuilt version of the Go program is used
   140  
   141  ## Inspiration
   142  
   143  This package is heavily inspired by the [`time/tzdata`] package from the Go standard library.
   144  
   145  ## Similar projects
   146  
   147  * [gwatts/rootcerts - Root CA Certificates for Go (`go generate`-able)](https://github.com/gwatts/rootcerts)
   148  
   149  ## License
   150  
   151  Software: [BSD 2-Clause “Simplified” License](LICENSE)\
   152  Embedded certificates: [MPL-2.0](LICENSE.certificates)
   153  
   154  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"\
   155  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\
   156  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\
   157  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\
   158  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\
   159  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\
   160  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\
   161  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\
   162  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\
   163  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   164  
   165  [`crypto/x509`]: https://golang.org/pkg/crypto/x509/
   166  [Mozilla Included CA Certificate List]: https://wiki.mozilla.org/CA/Included_Certificates
   167  [PEM of Root Certificates in Mozilla's Root Store with the Websites (TLS/SSL) Trust Bit Enabled]: https://ccadb-public.secure.force.com/mozilla/IncludedRootsPEMTxt?TrustBitsInclude=Websites
   168  [root programs]: https://en.wikipedia.org/wiki/Public_key_certificate#Root_programs
   169  [Firefox]: https://www.mozilla.org/en-US/firefox/
   170  [Thunderbird]: https://www.thunderbird.net/en-US/
   171  [Common CA Database]: https://www.ccadb.org/
   172  [`time/tzdata`]: https://golang.org/pkg/time/tzdata/