Bifrost

A simple mTLS authentication toolkit.

Read an introduction to Bifrost.

Bifrost consists of a Certificate Authority (CA) server that issues X.509 certificates, a Go package to fetch such certificates, and a Go package with HTTP middleware to identify and authenticate clients using such TLS certificates in requests.

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 for Windows, MacOS, and Linux on the releases page.

Container images are available at 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())

Gauntlet Plugins

Bifrost Certificate Authority supports plugins that validate certificate signing requests.

A plugin is a Go package that exports a function named Gauntlet that implements the tinyca.Gauntlet interface.

For example, here's a plugin that checks the ID of the public key from the certificate signing request against a list of allowed IDs:

package main

import (
    "crypto/x509"
    "encoding/pem"
    "errors"
    "fmt"
    "io/ioutil"

    "github.com/RealImage/bifrost/pkg/tinyca"
)

func Gauntlet(ctx context.Context, csr *bifrost.CertificateRequest) (*x509.Certificate, error) {
    // Check the public key ID against a list of allowed IDs
    if !isAllowed(csr.UUID) {
        return nil, errors.New("public key ID not allowed")
    }

    tmpl := tinyca.TLSClientCertTemplate()
    tmpl.Subject.OrganizationalUnit = []string{"my-app")}

    return tmpl, nil
}

func isAllowed(id uuid.UUID) bool {
    // Implement your logic here
    return true
}

The bf ca command loads a gauntlet plugin from the path specified in the GAUNTLET_PLUGIN environment variable or in the --gauntlet-plugin flag.

Build

Native

Install Node.js & Go. Build static binaries on your machine for all supported platforms.

./build.sh

Container

Build an image with ko.

ko build --local ./cmd/bf

Take Bifrost out for a spin

Here's what you need to get started.

1. Install all bifrost binaries by running go install ./....
2. Generate a new namespace UUID using export NS=$(bf new ns).
3. Ensure that python, curl, and openssl are available in your environment.

Start CA server and mTLS reverse proxy

Set up server key material and start the CA and TLS reverse-proxy.

1. Create Bifrost ECDSA private key:

   bf new id -o key.pem

2. Create self-signed CA root certificate:

   bf new ca -o cert.pem

3. Start the CA issuer, reverse proxy, and the target web server.

   bf ca &
   bf proxy &
   python -m http.server 8080 &

Request a client certificate

1. Generate a new client identity key:

   bf new key -o clientkey.pem

2. Fetch signed certificate from the CA:

   bf request -o clientcrt.pem

3. Make a request through the mTLS proxy to the python web server:

   curl --cert clientcrt.pem --key clientkey.pem -k https://localhost:8443

4. Admire your shiny new client certificate (optional):

   $ openssl x509 -in clientcrt.pem -noout -text
    Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 6573843113666499538 (0x5b3afb7b6f3d53d2)
        Signature Algorithm: ecdsa-with-SHA256
            Issuer: O=01881c8c-e2e1-4950-9dee-3a9558c6c741, CN=033fc353-f618-5c18-acd1-f9d4313cc052
            Validity
                Not Before: Jun 12 15:08:54 2024 GMT
                Not After : Jun 12 16:08:54 2024 GMT
            Subject: O=01881c8c-e2e1-4950-9dee-3a9558c6c741, CN=f6057aa6-6553-586a-9fda-319faa78958f
            Subject Public Key Info:
                Public Key Algorithm: id-ecPublicKey
                    Public-Key: (256 bit)
                    pub:
                        04:7a:88:ce:51:88:ac:8e:75:a4:17:79:0b:fe:6c:
                        ab:0c:89:be:fb:66:d7:e0:b2:b3:ec:e3:5d:02:4a:
                        cc:04:24:36:1f:33:64:8f:4d:61:aa:0a:ef:44:c3:
                        7b:60:7b:7d:48:ab:89:36:eb:d0:90:6e:d6:c1:78:
                        e7:52:82:9e:7f
                    ASN1 OID: prime256v1
                    NIST CURVE: P-256
            X509v3 extensions:
                X509v3 Key Usage: critical
                    Digital Signature, Key Encipherment
                X509v3 Extended Key Usage:
                    TLS Web Client Authentication
                X509v3 Basic Constraints: critical
                    CA:FALSE
                X509v3 Authority Key Identifier:
                    keyid:BD:BE:8A:D6:16:0A:08:46:01:27:71:25:42:04:60:DE:8C:23:8E:B3
   
        Signature Algorithm: ecdsa-with-SHA256
             30:45:02:21:00:f7:dd:97:18:ef:ec:95:e0:88:6e:d7:93:66:
             74:ca:4f:96:fe:34:b1:f8:0b:90:65:c0:bc:08:a3:49:fc:8f:
             37:02:20:6d:6a:fe:b5:d1:ab:77:59:3a:d1:94:6c:4c:f7:a2:
             3d:7f:69:a8:5e:85:52:aa:6b:7e:35:c4:9f:7e:11:92:d2

Fishy Benchmarks

A toy benchmark for your favourite toy CA.

Bifrost CA issued 10,000 certificates on my Macbook Pro M1 Pro in ~41s. Your results may vary.

LICENSE

Bifrost is available under the terms of the MIT License.

Qube Cinema © 2023, 2024