{"id":16788649,"url":"https://github.com/breml/rootcerts","last_synced_at":"2025-04-08T07:33:00.938Z","repository":{"id":46017495,"uuid":"329433467","full_name":"breml/rootcerts","owner":"breml","description":"Go package to embed the Mozilla Included CA Certificate List","archived":false,"fork":false,"pushed_at":"2025-03-19T17:23:52.000Z","size":225,"stargazers_count":115,"open_issues_count":0,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-01T05:37:42.169Z","etag":null,"topics":["certificates","go","golang","golang-package","root-certificate"],"latest_commit_sha":null,"homepage":"https://breml.github.io/blog/2021/01/17/embed-ca-root-certificates-in-go-programs/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/breml.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-13T21:15:48.000Z","updated_at":"2025-03-19T17:23:57.000Z","dependencies_parsed_at":"2023-02-15T20:00:35.624Z","dependency_job_id":"5e7fd853-ae2a-49b5-96d5-a0c5383b2bc9","html_url":"https://github.com/breml/rootcerts","commit_stats":{"total_commits":41,"total_committers":4,"mean_commits":10.25,"dds":0.07317073170731703,"last_synced_commit":"ddabf2656c13df5bf7eb41fe02174d043441e9cc"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breml%2Frootcerts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breml%2Frootcerts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breml%2Frootcerts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breml%2Frootcerts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/breml","download_url":"https://codeload.github.com/breml/rootcerts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247796296,"owners_count":20997545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["certificates","go","golang","golang-package","root-certificate"],"created_at":"2024-10-13T08:18:36.264Z","updated_at":"2025-04-08T07:33:00.915Z","avatar_url":"https://github.com/breml.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rootcerts\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/breml/rootcerts.svg)](https://pkg.go.dev/github.com/breml/rootcerts)\n[![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)\n[![Go Report Card](https://goreportcard.com/badge/github.com/breml/rootcerts)](https://goreportcard.com/report/github.com/breml/rootcerts)\n\nPackage rootcerts provides an embedded copy of the [Mozilla Included CA Certificate List],\nmore specifically the [PEM of Root Certificates in Mozilla's Root Store with the Websites (TLS/SSL) Trust Bit Enabled].\nIf this package is imported anywhere in the program and the [`crypto/x509`] package cannot find the system certificate\npool, it will use this embedded information.\n\nThis package should be used when one of the following conditions is met:\n\n1. the Go program is frequently updated (automated via CI) and distributed in a minimalistic form like a Docker\ncontainer from scratch\n2. the Go program is run in an out of date environment like a poorly maintained or no longer updateable system (e.g.\nhardware appliances)\n\n**In all other cases, it is recommended to stick to the CA certificates maintained with the operating system.**\n\nPlease consider the following advice if using this package:\n\n* 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)\n  * Without update of your Go Module depencies, rebuilding and redeploying of your programm, there is no update to the\n  embedded root certificates.\n* Do not include this package in any library package. This package should only be included in package main of programs.\n\nThe functionality of this package is proposed for inclusion into the Go standard library in [#43958](https://github.com/golang/go/issues/43958).\n\n## Usage\n\nTo use this package, simply import in your program.\n\n```Go\nimport (\n    _ \"github.com/breml/rootcerts\"\n)\n```\n\nIf this package is imported anywhere in the program and the [`crypto/x509`]\npackage cannot find the system certificate pool, it will use this embedded information.\n\nAdditionally, the usage of this embedded information can be forced by setting the environment\nvariable `GO_ROOTCERTS_ENABLE=1` while running a program which includes this package.\n\nImporting this package will increase the size of a program by about 250 KB.\n\nThis package should normally be imported by a program's main package, not by a library. Libraries\ngenerally shouldn't decide whether to include the \"Mozilla Included CA Certificate List\" in a program.\n\n## Use cases in detail\n\n### Docker Containers from Scratch\n\nIf one is building a Docker container from scratch, containing a Go program, there are usually two issues:\n\n1. Timezone data is missing\n2. CA certificates are missing\n\nThe first issue can be addressed with the [`time/tzdata`] package, introduced into the Go standard library\nwith version 1.15.\nThe second case can now be mitigated by this package.\n\n### Poorly maintained appliances\n\nI'm mainly thinking of hardware appliances like small NAS (network attached storage) systems from\nvendors like QNAP or Synology when I use the word appliance. These systems are based on Linux in most cases and offer\nSSH access. This allows the user to run custom tools on these systems. Unfortunately, whenever the vendor of these\nsystems decides to stop shipping firmware updates, the system certificates are also no longer updated and it is often\ndifficult or even impossible to update the system certificates manually.\n\nTherefore, it is a great advantage if a program like a tool built with Go embeds its own root certificates.\n\nThe following two properties of Go make it a really good candidate for building programs for hardware appliances:\n\n1. Go programs are statically linked and can be distributed by simply copying the executable.\n2. Go provides greate support for cross compiling for multiple CPU architectures.\n\n## Trustworthiness of the Mozilla Included CA Certificate List\n\nMost operating systems as well as web browsers include a list of certificate authorities and the corrosponding\nroot certificates that are trusted by default. Some major software vendors operate their own [root programs] and\nso does the Mozilla Foundation for their well known products like the [Firefox] web browser or [Thunderbird] email\nclient.\n\nIn contrast to most of the other software vendors, Mozilla maintains its Included CA Certificate List publicly and\ndistributes it under an open source license. This is also the reason why most of the Linux distributions, as well as\nother free unix derivates and wide spread tools, use this list of CA Certificates as part of their distribution.\n\nHere some examples:\n\n* Debian (and its derivates): [ca-certificates](https://packages.debian.org/en/sid/ca-certificates)\n* 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)\n* Alpine Linux: [ca-certificates](https://pkgs.alpinelinux.org/package/v3.12/main/x86/ca-certificates)\n* FreeBSD: [ca_root_nss](https://www.freshports.org/security/ca_root_nss/)\n* NetBSD: [ca-certificates](https://pkgsrc.se/security/ca-certificates)\n* curl: [cacert.pem](https://curl.se/docs/caextract.html)\n\nAdditionally, Mozilla operates the [Common CA Database] (used/supported by other major software vendors). The Common\nCA Database describes it self as:\n\n\u003e The Common CA Database (CCADB) is a repository of information about externally operated Certificate Authorities (CAs)\nwhose root and intermediate certificates are included within the products and services of CCADB root store members.\n\nTo summarize: It is safe to say that the Mozilla Included CA Certificate List is well established and widely used.\nIn fact, if your Go program is run on Linux or an other free Unix derivate, chances are high that the root\ncertificates used by your program are already provided by the Mozilla Included CA Certificate List.\n\n## Words of Caution ‒ or why you should not use this package\n\nThe root certificates are the top-most certificates in the trust chain and used to ensure the trustworthiness of the\ncertificates signed by them either directly (intermediate certificates) or indirectly (through intermediate\ncertificates). As a user of this package, you have the obligation to double check the source as well as the integrity\nof the root certificates provided in this package. This is absolutely crucial and should not be taken lightly. All\ncertificates that are validated by programs built upon this package, e.g. by using TLS for communication, rely\non the trustworthiness of these root certificates.\n\nBeside the issue of the trust you put into the certificates included in this package, there is another topic to keep in\nmind and that is how the certificates get updated.\n\nIn the \"normal\" case, where a Go program is run on a recent operating system, the certificates get updated whenever\nthe operating system is updated (and a new version of the CA certificates is available).\\\nWith the use of this package, this stays true if both of the following conditions are met:\n\n* the [`crypto/x509`] package is able to find the CA certificates on the system.\n* the environment variable `GO_ROOTCERTS_ENABLE=1` is not set.\n\nIt is worth mentioning that the [`crypto/x509`] package by default does not provide the necessary mechanics to detect\nand reload the CA certificates if they change. By default, a restart of the Go program is necessary to leverage the\nupdated certificates. Additionally the [`crypto/x509`] package does not check the certificate revokation lists (CRL),\nwhen it is verifing the validity of certificates.\n\nIf the above conditions are not met, the CA certificates from this package are used. These certificates are only\nupdated if all of the following conditions are met:\n\n* An updated list of certificates is available from Mozilla.\n* An updated version of this package, containing the updated certificates, is available.\n* The dependencies of the Go program are updated (`go get -u github.com/breml/rootcerts`).\n* A rebuilt version of the Go program is used\n\n## Inspiration\n\nThis package is heavily inspired by the [`time/tzdata`] package from the Go standard library.\n\n## Similar projects\n\n* [gwatts/rootcerts - Root CA Certificates for Go (`go generate`-able)](https://github.com/gwatts/rootcerts)\n\n## License\n\nSoftware: [BSD 2-Clause “Simplified” License](LICENSE)\\\nEmbedded certificates: [MPL-2.0](LICENSE.certificates)\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\\\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\\\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\\\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\\\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\\\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\\\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\\\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\\\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\\\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n[`crypto/x509`]: https://golang.org/pkg/crypto/x509/\n[Mozilla Included CA Certificate List]: https://wiki.mozilla.org/CA/Included_Certificates\n[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\n[root programs]: https://en.wikipedia.org/wiki/Public_key_certificate#Root_programs\n[Firefox]: https://www.mozilla.org/en-US/firefox/\n[Thunderbird]: https://www.thunderbird.net/en-US/\n[Common CA Database]: https://www.ccadb.org/\n[`time/tzdata`]: https://golang.org/pkg/time/tzdata/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreml%2Frootcerts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbreml%2Frootcerts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreml%2Frootcerts/lists"}