bifrost

package module
v1.8.7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 16, 2023 License: MPL-2.0 Imports: 15 Imported by: 0

README

Bifrost

CI

My First CA

Bifrost is a minimal Certificate Authority that issues X.509 certificates meant for mTLS client authentication. Bifrost CA does not authenticate certificate signing requests before issuance. You must authorise or control access to Bifrost CA as needed.

Bifrost CA issues certificates signed by a private key and a TLS X.509 certificate. A TLS reverse proxy can use the issuing certificate to authenticate clients and secure access to web applications. Bifrost identifies clients uniquely by ECDSA public keys. Client identity namespaces allow Bifrost to be natively multi-tenant.

Releases

Bifrost binaries are available on the releases page.

bifrost container image on ghcr.io contains all binaries.

podman pull ghcr.io/realimage/bifrost

Identity

Bifrost identities are UUID version 5 UUIDs, derived from ECDSA public keys. A client's identity is the sha1 hash of the namespace appended to the X and Y curve points (big-endian) of its ECDSA P256 public key.

In pseudo-code,

bifrostUUID = UUIDv5(sha1(NamespaceClientIdentity + PublicKey.X.Bytes() + PublicKey.Y.Bytes())

Components

bf (alpha)

bf is an interactive tool that generates Bifrost CA material. It uses Charm Cloud to store your key material securely in the cloud.

bfid

bfid prints the Bifrost UUID of a certificate, public key, or private key.

bouncer

bouncer is a simple mTLS reverse proxy suitable for local development. If client authentication succeeds, bouncer proxies the request to the backend url. The client's TLS certificate is available in the x-amzn-request-context header.

Bouncer will log TLS Pre-Master secrets to a file if the SSLKEYLOGFILE environment variable is present. Wireshark can use this file to decrypt traffic.

Sample Request Context containing Client Certificate:

"requestContext": {
    "authentication": {
        "clientCert": {
            "clientCertPem": "-----BEGIN CERTIFICATE-----\nMIIEZTCCAk0CAQEwDQ...",
            "issuerDN": "C=012d325d-6a4e-4076-b49a-a3e84e52bf79,O=765e4c02-b41a-4226-8522-2a52f4fbeebe",
            "serialNumber": "1",
            "subjectDN": "C=2ef463c4-cca9-4885-a8e2-d041c90d61fa,O=765e4c02-b41a-4226-8522-2a52f4fbeebe",
            "validity": {
                "notAfter": "Aug  5 00:28:21 2120 GMT",
                "notBefore": "Aug 29 00:28:21 2020 GMT"
            }
        }
    },
}

Run bouncer in front of a HTTP server listening on localhost port 5000:

env BACKEND_URL=http://127.0.0.1:5000 ./bouncer
issuer

OpenAPI schema

issuer signs certificates with the configured certificate and its private key. Clients must send certificate requests signed by an ECDSA P256 private key using the ECDSA SHA256 signature algorithm.

issuer can read its signing certificate and private key in PEM form, from a variety of sources. If unconfigured, it looks for crt.pem and key.pem in the current working directory.

issuer exposes prometheus format metrics at the /metrics path.

Build

Go toolchain

Build Go binaries on your machine:

mkdir build
go build -o build ./...
Container

Build all binaries:

podman build -t ghcr.io/realimage/bifrost .

Build the CA container with the AWS Lambda Web Adapter extension:

podman build -f ca.Containerfile -t bifrost-ca .

Run Issuer CA

  1. Generate a new namespace UUID

    export BF_NS=$(uuidgen)

  2. Create ECDSA P256 Private Key in PEM format:

    openssl ecparam -out key.pem -name prime256v1 -genkey -noout

  3. Create 10 year self-signed "CA" certificate:

    openssl req -new -key key.pem -x509 -nodes \
      -days 3650 \
      -subj "/CN=$(bfid -ns "$BF_NS" key.pem)/O=$BF_NS" \
     -addext "subjectAltName = DNS:localhost" \
     -out crt.pem
    
  4. Run the binary:

    ./issuer

  5. Generate a new client identity key:

    openssl ecparam -out clientkey.pem -name prime256v1 -genkey -noout

  6. Create a Certificate Signing Request with the client private key:

    openssl req -new -key clientkey.pem -sha256 \
      -subj "/CN=$(bfid -ns "$BF_NS" clientkey.pem)/O=$BF_NS" \
      -out csr.pem
    
  7. Fetch signed certificate from the CA:

    curl -X POST -H "Content-Type: text/plain" --data-binary "@csr.pem" \
      localhost:8888/issue >clientcrt.pem`
    
  8. Admire your shiny new client certificate (optional):

    $ openssl x509 -in clientcrt.pem -noout -text
    Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 871355257622038992 (0xc17acfd7bbb09d0)
            Signature Algorithm: ecdsa-with-SHA256
            Issuer: CN = 46d6516e-715f-5a8a-8523-c2924b2a53d7, O = 00000000-0000-0000-0000-000000000000
            Validity
                Not Before: Jul 12 23:09:46 2023 GMT
                Not After : Jul 13 00:09:46 2023 GMT
            Subject: O = 00000000-0000-0000-0000-000000000000, CN = 8b9fca79-13e0-5157-b754-ff2e4e985c30
            Subject Public Key Info:
                Public Key Algorithm: id-ecPublicKey
                    Public-Key: (256 bit)
                    pub:
                        04:84:4a:3b:fa:2e:dd:07:d5:a7:96:26:68:ac:81:
                        16:8a:cb:57:02:0a:c7:ae:d3:b3:da:b5:b4:2d:a5:
                        c8:65:c2:4d:88:45:00:5a:44:f3:30:52:ab:63:42:
                        59:3d:50:68:50:45:e0:60:61:e1:57:b8:5c:dc:87:
                        7f:f9:7e:07:f6
                    ASN1 OID: prime256v1
                    NIST CURVE: P-256
            X509v3 extensions:
                X509v3 Key Usage: critical
                    Digital Signature
                X509v3 Extended Key Usage: 
                    TLS Web Client Authentication
                X509v3 Authority Key Identifier: 
                    CA:2F:94:0D:43:FB:6D:00:66:09:50:4C:8C:1F:A3:BC:C1:EF:98:F4
        Signature Algorithm: ecdsa-with-SHA256
        Signature Value:
            30:45:02:21:00:a3:2a:99:6e:29:b6:97:61:55:ac:a5:96:9c:
            ab:c3:86:44:4e:86:f5:1f:56:34:49:a7:36:b5:6c:db:72:65:
            a6:02:20:14:a9:d2:07:d5:63:17:d5:e0:3b:e3:f7:ef:e7:d0:
            65:86:c3:74:5e:b4:61:87:cd:af:6a:71:af:cd:cf:45:8b
    

Fishy Benchmarks

A toy benchmark for your favourite toy CA.

my-first-benchmark.jpg

issuer issued 10,000 certificates on my Macbook Pro M1 Pro in ~41s. The slowest request completed in 12ms. With a mean response time of 4ms this is objectively the fastest CA on the planet. Statisticians hate this one weird trick.

LICENSE

Bifrost is available under the Mozilla Public License 2.0.

Qube Cinema © 2023

Documentation

Overview

Bifrost is an mTLS authentication toolkit.

Index

Examples

Constants

View Source
const (
	SignatureAlgorithm = x509.ECDSAWithSHA256
	PublicKeyAlgorithm = x509.ECDSA
)

Signature and Public Key Algorithms

Variables

View Source
var (
	ErrCertificateFormat        = errors.New("invalid certificate format")
	ErrCertificateRequestFormat = errors.New("invalid certificate request format")
	ErrWrongNamespace           = errors.New("wrong namespace")
)

Errors.

Functions

func HTTPClient added in v0.0.6

func HTTPClient(clientCert tls.Certificate, roots *x509.CertPool, ssllog io.Writer) *http.Client

HTTPClient returns a http.Client set up for TLS Client Authentication (mTLS). If roots is not nil, then only those Root CAs are used to authenticate server certs. If ssllog is not nil, the client will log TLS key material to it.

func NewIdentity added in v0.0.8

func NewIdentity() (*ecdsa.PrivateKey, []byte, error)

NewIdentity generates a new ECDSA private key. The private key is also returned as a PEM encoded DER bytes in the second return value.

func ParseCertificate

func ParseCertificate(der []byte) (uuid.UUID, *x509.Certificate, *ecdsa.PublicKey, error)

ParseCertificate parses a DER encoded certificate and validates it. On success, it returns the bifrost namespace, certificate public key, and the parsed certificate.

func ParseCertificateRequest added in v1.5.2

func ParseCertificateRequest(
	der []byte,
) (uuid.UUID, *x509.CertificateRequest, *ecdsa.PublicKey, error)

func RequestCertificate

func RequestCertificate(
	ctx context.Context,
	url string,
	ns uuid.UUID,
	key *ecdsa.PrivateKey,
) (*x509.Certificate, error)

RequestCertificate sends a certificate request to url and returns the signed certificate.

Example
exampleNS := uuid.MustParse("228b9676-998e-489a-8468-92d46a94a32d")
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
// TODO: handle errors
key, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
crt, _ := RequestCertificate(ctx, "https://bifrost-ca", exampleNS, key)
fmt.Println(crt.Subject)
Output:

func UUID

func UUID(ns uuid.UUID, pubkey *ecdsa.PublicKey) uuid.UUID

UUID returns a unique identifier derived from the namespace and the client's public key identity. The UUID is generated by SHA-1 hashing the namesapce UUID with the big endian bytes of the X and Y curve points from the public key.

func ValidateCertificate added in v1.4.0

func ValidateCertificate(cert *x509.Certificate) (uuid.UUID, *ecdsa.PublicKey, error)

ValidateCertificate validates a bifrost certificate. On success, it returns the bifrost namespace and certificate public key.

func ValidateCertificateRequest added in v1.5.2

func ValidateCertificateRequest(csr *x509.CertificateRequest) (uuid.UUID, *ecdsa.PublicKey, error)

func X509ToTLSCertificate

func X509ToTLSCertificate(crt *x509.Certificate, key *ecdsa.PrivateKey) *tls.Certificate

X509ToTLSCertificate puts an x509.Certificate inside a tls.Certificate.

Types

This section is empty.

Directories

Path Synopsis
cmd
bf
internal
cafiles
cafiles can fetch CA certificate and private key PEM files from many storage backends.
cafiles can fetch CA certificate and private key PEM files from many storage backends.
pkg
club
Package club provides middleware for use in HTTP API servers and gateways.
Package club provides middleware for use in HTTP API servers and gateways.
tinyca
Package tinyca implements a Certificate Authority that issues certificates for client authentication.
Package tinyca implements a Certificate Authority that issues certificates for client authentication.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL