bifrost

README

Bifrost

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_ID" key.pem)/O=$BF_ID" \
    -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 clientkey.pem)/O=$BF_ID" \
     -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.

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

• Constants
• Variables
• func HTTPClient(h Hosts, clientCert *tls.Certificate, rootCAs *x509.CertPool, ssllog io.Writer) *http.Client
• func NewIdentity() (*ecdsa.PrivateKey, []byte, error)
• func ParseCertificate(der []byte) (uuid.UUID, *x509.Certificate, *ecdsa.PublicKey, error)
• func ParseCertificateRequest(der []byte) (uuid.UUID, *x509.CertificateRequest, *ecdsa.PublicKey, error)
• func RequestCertificate(ctx context.Context, url string, ns uuid.UUID, key *ecdsa.PrivateKey) (*x509.Certificate, error)
• func UUID(ns uuid.UUID, pubkey *ecdsa.PublicKey) uuid.UUID
• func ValidateCertificate(cert *x509.Certificate) (uuid.UUID, *ecdsa.PublicKey, error)
• func ValidateCertificateRequest(csr *x509.CertificateRequest) (uuid.UUID, *ecdsa.PublicKey, error)
• func X509ToTLSCertificate(crt *x509.Certificate, key *ecdsa.PrivateKey) *tls.Certificate
• type Hosts

Examples

• RequestCertificate

Constants

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

Signature and Public Key Algorithms

Variables

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

Errors.

Functions

func HTTPClient

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

HTTPClient returns a http.Client configured for mTLS with client authentication. The client will use the provided Hosts map to map hostnames to backend URLs. Client certificates are loaded from clientCert and rootCAs is used to validate the server certificate. If ssllog is not nil, the client will log TLS key material to it.

func NewIdentity

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

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)

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

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

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

type Hosts

type Hosts map[string]*url.URL

Hosts is a map of hostnames to backend URLs.