{"id":19070742,"url":"https://github.com/powerdns/go-tlsconfig","last_synced_at":"2025-04-28T14:43:44.129Z","repository":{"id":57548148,"uuid":"303637319","full_name":"PowerDNS/go-tlsconfig","owner":"PowerDNS","description":"Go TLS configuration module","archived":false,"fork":false,"pushed_at":"2022-11-01T13:51:53.000Z","size":30,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-18T17:19:28.122Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PowerDNS.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}},"created_at":"2020-10-13T08:27:34.000Z","updated_at":"2024-12-11T01:11:54.000Z","dependencies_parsed_at":"2023-01-20T18:30:19.555Z","dependency_job_id":null,"html_url":"https://github.com/PowerDNS/go-tlsconfig","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerDNS%2Fgo-tlsconfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerDNS%2Fgo-tlsconfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerDNS%2Fgo-tlsconfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerDNS%2Fgo-tlsconfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PowerDNS","download_url":"https://codeload.github.com/PowerDNS/go-tlsconfig/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251332045,"owners_count":21572546,"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":[],"created_at":"2024-11-09T01:20:15.454Z","updated_at":"2025-04-28T14:43:44.104Z","avatar_url":"https://github.com/PowerDNS.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go TLS configuration module\n\n[![Go Doc](https://godoc.org/github.com/PowerDNS/go-tlsconfig?status.svg)](http://godoc.org/github.com/PowerDNS/go-tlsconfig)\n[![Build Status](https://travis-ci.com/PowerDNS/go-tlsconfig.svg?branch=master)](https://travis-ci.com/PowerDNS/go-tlsconfig)\n\nThis module eases configuration of TLS for clients and servers written in Go.\n\nFeatures:\n\n- The `Config` struct has YAML and JSON struct tags.\n- It can be used for both clients and servers.\n- A `Manager` can generate a corresponding `tls.Config`.\n- On-disk certificates can be automatically reloaded without downtime.\n\nThe main idea behind it is that you can integrate it in your code once and then\nautomatically gain support for any new certificate management features in the future.\n\n## YAML configuration examples\n\nNote that depending on the application, the configuration can also be in JSON or another format.\n\nThe examples below group all TLS options under a `tls` key, but this name depends on the name used in the program.\n\n### Servers\n\nLoad certificate from file:\n\n```yaml\ntls:\n  cert_file: path/to/cert.pem\n  key_file: path/to/key.pem\n```\n\nWith automatic reloading:\n\n```yaml\ntls:\n  cert_file: path/to/cert.pem\n  key_file: path/to/key.pem\n  watch_certs: true\n  watch_certs_poll_interval: 5s\n```\n\nSame with a custom CA and client certificate support:\n\n```yaml\ntls:\n  ca_file: path/to/ca.pem\n  cert_file: path/to/cert.pem\n  key_file: path/to/key.pem\n  watch_certs: true\n  watch_certs_poll_interval: 5s\n  require_client_cert: true\n```\n\n### Clients\n\nClients that just want to use OS provides CAs can leave the configuration empty.\n\nTo use custom CA certs to verify the connection:\n\n```yaml\ntls:\n  ca_file: path/to/ca.pem\n```\n\nTo allow both custom CA certs and system CA certs to verify the connection:\n\n```yaml\ntls:\n  ca_file: path/to/ca.pem\n  add_system_ca_pool: true\n```\n\nTo use a client certificate:\n\n```yaml\ntls:\n  ca_file: path/to/ca.pem\n  cert_file: path/to/cert.pem\n  key_file: path/to/key.pem\n```\n\nINSECURE - to disable certificate validation:\n\n\n```yaml\ntls:\n  insecure_skip_verify: true\n``` \n\n### General options\n\nThe `ca_file`, `cert_file` and `key_file` options have corresponding `ca`, `cert` and `key` options that allow\nyou to inline the PEM certificate into the config file:\n\n```yaml\ntls:\n  cert: |\n    -----BEGIN CERTIFICATE-----\n    ...\n```\n\nNote that there is no way to do automatic reloading this way.\n\nThe `insecure_key_log_file` option can be set to a log file path for the use of tools like Wireshark to decode encrypted traffic in development.\nSee [this Mozilla page](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format) for more information. \n\n\n## Usage in Go code\n\nYou can use the `Config` struct in you existing configuration structures:\n\n```go\nimport \"github.com/PowerDNS/go-tlsconfig\"\n\ntype MyConfig struct {\n\tServer Server `yaml:\"server\"`\n\t// ...\n}\n\ntype Server struct {\n\tTLS tlsconfig.Config `yaml:\"tls\"`\n}\n```\n\nAfter you have loaded your configration, you can the use a `Manager` to generate a `tls.Config` (error handling omitted):\n\n```go\nmanager, err := tlsconfig.NewManager(ctx, config.Server.TLS, tlsconfig.Options{\n\tIsServer: true,\n})\n\ntlsConfig, err := manager.TLSConfig()\n\nhs := http.Server{\n\tTLSConfig: tlsConfig,\n}\nerr = hs.ListenAndServeTLS(\"\", \"\") // Certificates are handled by the TLSConfig\n```\n\nExample of how to use a custom TLS config with an HTTP client:\n\n```go\nmanager, err := tlsconfig.NewManager(ctx, config.Client.TLS, tlsconfig.Options{\n\tIsClient: true,\n})\n\ntlsConfig, err := manager.TLSConfig()\n\ntransport := \u0026http.Transport{\n\tTLSClientConfig: tlsConfig,\n    ForceAttemptHTTP2: true, // not attempted by default when TLSClientConfig is set\n}\nclient := \u0026http.Client{Transport: transport}\nresp, err := client.Get(\"https://some.example/\")\n```\n\nOr you can use this convenience method for a more opinionated HTTP client with\nvarious timeouts set, but do read the source code for this method so that you\nunderstand the implications:\n\n```go\nmanager, err := tlsconfig.NewManager(ctx, config.Client.TLS, tlsconfig.Options{\n\tIsClient: true,\n})\n\nclient, err := manager.HTTPClient()\n\nresp, err := client.Get(\"https://some.example/\")\n```\n\nThe `testca/testca_test.go` file contains an example that uses client certificates.\n\nThe `Manager` performs certificate reloads in the background. To keep track of\nwhat it is doing and see error messages, you can provide a\n[`logr.Logger`](https://github.com/go-logr/logr) interface in `Options.Logr`.\nThe [genericr](https://github.com/wojas/genericr) module makes it easy to\nuse custom logging logic here.\n\n## Stability\n\nAt this point we do not guarantee any API and config file format stability between versions. If you want to use it in your own project,\npin it at a speciifc version. Once we are confident that our approach is sane, we will release a 1.0.0 version that will have these\nguarantees.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowerdns%2Fgo-tlsconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpowerdns%2Fgo-tlsconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowerdns%2Fgo-tlsconfig/lists"}