{"id":15648650,"url":"https://github.com/mdelapenya/tlscert","last_synced_at":"2025-04-30T14:41:25.728Z","repository":{"id":232794336,"uuid":"785173251","full_name":"mdelapenya/tlscert","owner":"mdelapenya","description":"Quickly generate customisable TLS certificates for Go apps. Ideal for testing and secure setups.","archived":false,"fork":false,"pushed_at":"2025-04-22T21:07:17.000Z","size":42,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-22T21:34:45.307Z","etag":null,"topics":["golang","self-signed-certificate","testing","tls"],"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/mdelapenya.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":"2024-04-11T10:50:02.000Z","updated_at":"2025-03-19T13:13:27.000Z","dependencies_parsed_at":"2024-06-19T13:24:55.945Z","dependency_job_id":"4298bee7-a545-4bb4-b82b-e0cb67735a2c","html_url":"https://github.com/mdelapenya/tlscert","commit_stats":null,"previous_names":["mdelapenya/tlscert"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdelapenya%2Ftlscert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdelapenya%2Ftlscert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdelapenya%2Ftlscert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdelapenya%2Ftlscert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mdelapenya","download_url":"https://codeload.github.com/mdelapenya/tlscert/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251722807,"owners_count":21633019,"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":["golang","self-signed-certificate","testing","tls"],"created_at":"2024-10-03T12:25:42.734Z","updated_at":"2025-04-30T14:41:25.705Z","avatar_url":"https://github.com/mdelapenya.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tlscert\n\nThis is a simple tool to generate self-signed certificates for testing purposes.\n\n## Motivation\n\nThis package is intended to be used in tests that require a self-signed certificate. It is not intended to be used in production code.\n\nI many times found myself needing to generate a self-signed certificate for testing purposes, and I always had to look up how to do it. This package is an attempt to make this process easier, providing a simple API to generate self-signed certificates and save them to disk, if needed.\n\n## Features\n\nThe package exposes the following types and functions:\n\n### Types\n\n- `Request`: A struct that contains the parameters for the certificate generation.\n- `Certificate`: A struct that contains the generated certificate and key, including the paths to the files on disk.\n\n### Functions\n\n- `SelfSigned`: A function that generates a self-signed certificate and returns it as a `Certificate` value. This function only receives the host name for the certificate, and it does not return an error, if it occurs.\n- `SelfSignedCA`: A function that generates a self-signed certificate for a Certificate Authority, and it does not return an error, if it occurs.\n- `SelfSignedFromRequest`: A function that generates a self-signed certificate based on the parameters in a `Request` value, and it does not return an error, if it occurs.\n\nAll three functions have an `E` version that returns an error, if it occurs:\n\n- `SelfSignedE`: A function that generates a self-signed certificate and returns it as a `Certificate` value. This function only receives the host name for the certificate, and it does return an error, if it occurs.\n- `SelfSignedCAE`: A function that generates a self-signed certificate for a Certificate Authority, and it does return an error, if it occurs.\n- `SelfSignedFromRequestE`: A function that generates a self-signed certificate based on the parameters in a `Request` value, and it does return an error, if it occurs.\n\nTherefore, it's possible to issue a self-signed certificate with a custom host name, and save it to disk, if needed, or to issue a certificate based on a parent certificate, which is useful for generating client certificates.\n\nThe `Request` struct also provides a `ParentDir` option that can be used to save the generated certificate to disk as a PEM file.\n\nThe `Certificate` struct provides a `Transport` method, which returns a pointer to a `http.Transport` that can be used to perform HTTP requests using the generated certificate; and a `TLSConfig` method, which returns a pointer to a `tls.Config`. The `Transport` method internally uses the `TLSConfig` method.\n\n## Example\n\nYou can find a simple example in the [example_test.go](example_test.go) file:\n\n```go\npackage tlscert_test\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"log\"\n\t\"net/http\"\n\t\"os\"\n\n\t\"github.com/mdelapenya/tlscert\"\n)\n\nfunc ExampleSelfSigned() {\n\ttmp := os.TempDir()\n\tcertsDir := tmp + \"/certs\"\n\tdefer os.RemoveAll(certsDir)\n\n\tif err := os.MkdirAll(certsDir, 0o755); err != nil {\n\t\tlog.Println(err)\n\t\treturn\n\t}\n\n\t// Generate a certificate for localhost and save it to disk.\n\tcaCert := tlscert.SelfSignedFromRequest(tlscert.Request{\n\t\tHost:      \"localhost\",\n\t\tName:      \"ca-cert\",\n\t\tParentDir: certsDir,\n\t})\n\tif caCert == nil {\n\t\tlog.Println(\"Failed to generate CA certificate\")\n\t\treturn\n\t}\n\n\tcert := tlscert.SelfSignedFromRequest(tlscert.Request{\n\t\tHost:      \"localhost\",\n\t\tName:      \"client-cert\",\n\t\tParent:    caCert,\n\t\tParentDir: certsDir,\n\t})\n\tif cert == nil {\n\t\tlog.Println(\"Failed to generate certificate\")\n\t\treturn\n\t}\n\n\t// create an http server that uses the generated certificate\n\t// and private key to serve requests over HTTPS\n\n\tserver := \u0026http.Server{\n\t\tAddr: \":8443\",\n\t}\n\n\tserver.Handler = http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {\n\t\tw.Header().Set(\"Content-Type\", \"text/plain\")\n\t\t//nolint:errcheck\n\t\tw.Write([]byte(\"TLS works!\\n\"))\n\t})\n\n\tgo func() {\n\t\tif err := server.ListenAndServeTLS(cert.CertPath, cert.KeyPath); err != nil {\n\t\t\tlog.Printf(\"Failed to start server: %v\", err)\n\t\t}\n\t}()\n\tdefer server.Close()\n\n\t// perform an HTTP request to the server, using the generated certificate\n\n\tconst url = \"https://localhost:8443/hello\"\n\n\tclient := \u0026http.Client{Transport: cert.Transport()}\n\tresp, err := client.Get(url)\n\tif err != nil {\n\t\tlog.Printf(\"Failed to get response: %v\", err)\n\t\treturn\n\t}\n\tdefer resp.Body.Close()\n\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\tlog.Printf(\"Failed to read response body: %v\", err)\n\t\treturn\n\t}\n\n\tfmt.Println(string(body))\n\n\t// Output:\n\t// TLS works!\n}\n```\n\nOr, if you prefer, you can use the `E` versions of the functions:\n\n```go\nfunc ExampleSelfSignedE() {\n\ttmp := os.TempDir()\n\tcertsDir := tmp + \"/certs\"\n\tdefer os.RemoveAll(certsDir)\n\n\tif err := os.MkdirAll(certsDir, 0o755); err != nil {\n\t\tlog.Println(err)\n\t\treturn\n\t}\n\n\t// Generate a certificate for localhost and save it to disk.\n\tcaCert, err := tlscert.SelfSignedFromRequestE(tlscert.Request{\n\t\tHost:      \"localhost\",\n\t\tName:      \"ca-cert\",\n\t\tParentDir: certsDir,\n\t})\n\tif err != nil {\n\t\tlog.Println(\"Failed to generate CA certificate\")\n\t\treturn\n\t}\n\tif caCert == nil {\n\t\tlog.Println(\"Failed to generate CA certificate\")\n\t\treturn\n\t}\n\n\tcert, err := tlscert.SelfSignedFromRequestE(tlscert.Request{\n\t\tHost:      \"localhost\",\n\t\tName:      \"client-cert\",\n\t\tParent:    caCert,\n\t\tParentDir: certsDir,\n\t})\n\tif err != nil {\n\t\tlog.Println(\"Failed to generate certificate\")\n\t\treturn\n\t}\n\tif cert == nil {\n\t\tlog.Println(\"Failed to generate certificate\")\n\t\treturn\n\t}\n\n\t// create an http server that uses the generated certificate\n\t// and private key to serve requests over HTTPS\n\n\tserver := \u0026http.Server{\n\t\tAddr: \":8443\",\n\t}\n\n\tserver.Handler = http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {\n\t\tw.Header().Set(\"Content-Type\", \"text/plain\")\n\t\t//nolint:errcheck\n\t\tw.Write([]byte(\"TLS works!\\n\"))\n\t})\n\n\tgo func() {\n\t\tif err := server.ListenAndServeTLS(cert.CertPath, cert.KeyPath); err != nil {\n\t\t\tlog.Printf(\"Failed to start server: %v\", err)\n\t\t}\n\t}()\n\tdefer server.Close()\n\n\t// perform an HTTP request to the server, using the generated certificate\n\n\tconst url = \"https://localhost:8443/hello\"\n\n\tclient := \u0026http.Client{Transport: cert.Transport()}\n\tresp, err := client.Get(url)\n\tif err != nil {\n\t\tlog.Printf(\"Failed to get response: %v\", err)\n\t\treturn\n\t}\n\tdefer resp.Body.Close()\n\n\tbody, err := io.ReadAll(resp.Body)\n\tif err != nil {\n\t\tlog.Printf(\"Failed to read response body: %v\", err)\n\t\treturn\n\t}\n\n\tfmt.Println(string(body))\n\n\t// Output:\n\t// TLS works!\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdelapenya%2Ftlscert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmdelapenya%2Ftlscert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdelapenya%2Ftlscert/lists"}