From 51407fe36ff9a81a37e19a1db8b0dbd79d251825 Mon Sep 17 00:00:00 2001
From: Stefan <stefan.goppelt@yoorie.de>
Date: Sun, 29 Mar 2026 20:37:57 +0200
Subject: [PATCH] docs: update README with detailed usage instructions and API
 reference

---
 README.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 93 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 0056d30..c010506 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,103 @@
-# Go TLS Library
+# Go TLS Certificate Helper
 
 [![Build Status](https://drone.yoorie.de/api/badges/go-lib/certs/status.svg)](https://drone.yoorie.de/go-lib/certs)
 
-## Documentation
+Small helper library to generate a self-signed TLS certificate and return it
+as a ready-to-use `*tls.Config`.
 
-Available project documentation:
+## Overview
+
+The package builds an in-memory certificate and private key pair from a
+`GenerateCertificate` configuration and returns a TLS configuration with one
+certificate entry.
+
+Supported key options:
+
+- RSA (default when `EcdsaCurve` is empty and `Ed25519Key` is false)
+- Ed25519 (when `Ed25519Key` is true)
+- ECDSA curves: `P224`, `P256`, `P384`, `P521`
+
+## Installation
+
+```bash
+go get scm.yoorie.de/go-lib/certs
+```
+
+## Quick Start
+
+```go
+package main
+
+import (
+    "fmt"
+    "time"
+
+    "scm.yoorie.de/go-lib/certs"
+)
+
+func main() {
+    cfg := &certs.GenerateCertificate{
+        Organization: "example.org",
+        Host:         "127.0.0.1,localhost,api.example.org",
+        ValidFor:     365 * 24 * time.Hour,
+        RSABits:      2048,
+    }
+
+    tlsConfig, err := cfg.GenerateTLSConfig()
+    if err != nil {
+        panic(err)
+    }
+
+    fmt.Printf("certificates in config: %d\n", len(tlsConfig.Certificates))
+}
+```
+
+## API
+
+### Type: `GenerateCertificate`
+
+- `Organization string`: certificate subject organization
+- `Host string`: comma-separated DNS names and/or IPs for SAN
+- `ValidFrom string`: optional start date in format `Jan 2 15:04:05 2006`
+- `ValidFor time.Duration`: certificate validity duration
+- `IsCA bool`: whether to mark certificate as CA
+- `RSABits int`: RSA key size when RSA is used
+- `EcdsaCurve string`: one of `P224`, `P256`, `P384`, `P521`
+- `Ed25519Key bool`: generate Ed25519 key when true
+
+### Method
+
+- `GenerateTLSConfig() (*tls.Config, error)`
+
+Creates a self-signed certificate and returns a `*tls.Config` with that
+certificate.
+
+## Important Notes
+
+- The certificate is self-signed (issuer equals subject).
+- `Host` is split by comma and mapped into DNS or IP SAN entries.
+- Invalid `EcdsaCurve` values are not recoverable: the implementation uses
+  `log.Fatalf`.
+- Invalid `ValidFrom` values are not recoverable: the implementation uses
+  `log.Fatalf`.
+
+## Development
+
+Run quality checks locally:
+
+```bash
+go test ./...
+go test -coverprofile .build/coverage.out ./...
+go tool cover -func .build/coverage.out
+go vet ./...
+go run golang.org/x/vuln/cmd/govulncheck@latest ./...
+```
+
+## Documentation
 
 - [Changelog](CHANGELOG.md)
 - [Definition of Done](docs/DEFINITION_OF_DONE.md)
 - [Releasing](docs/RELEASING.md)
 
 ---
-Copyright &copy; 2023 yoorie.de
+Copyright &copy; 2026 yoorie.de