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.
Bifrost binaries are available for Windows, MacOS, and Linux on the releases page.
Container images are available at ghcr.io/realimage/bifrost.
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())
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.
Install Node.js & Go. Build static binaries on your machine for all supported platforms.
./build.sh
Build an image with ko
.
ko build --local ./cmd/bf
Here's what you need to get started.
- Install all bifrost binaries by running
go install ./...
. - Generate a new namespace UUID using
export NS=$(bf new ns)
. - Ensure that python, curl, and openssl are available in your environment.
Set up server key material and start the CA and TLS reverse-proxy.
-
Create Bifrost ECDSA private key:
bf new id -o key.pem
-
Create self-signed CA root certificate:
bf new ca -o cert.pem
-
Start the CA issuer, reverse proxy, and the target web server.
bf ca & bf proxy & python -m http.server 8080 &
-
Generate a new client identity key:
bf new key -o clientkey.pem
-
Fetch signed certificate from the CA:
bf request -o clientcrt.pem
-
Make a request through the mTLS proxy to the python web server:
curl --cert clientcrt.pem --key clientkey.pem -k https://localhost:8443
-
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
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.
Bifrost is available under the terms of the MIT License.
Qube Cinema © 2023, 2024