certs/README.md

# Go TLS Certificate Helper

[![Build Status](https://drone.yoorie.de/api/badges/go-lib/certs/status.svg)](https://drone.yoorie.de/go-lib/certs)

Small helper library to generate a self-signed TLS certificate and return it
as a ready-to-use `*tls.Config`.

## 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 © 2026 yoorie.de