bifrost

package module
v1.21.8 Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2024 License: MIT Imports: 19 Imported by: 0

README

Bifrost Bifrost

Go Reference

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())

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.

Fishy Benchmark

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

Documentation

Overview

Package bifrost contains an API client for the Bifrost CA service.

Package bifrost provides simple Public Key Infrastructure (PKI) services.

Bifrost identifies clients by their private keys. Keys are deterministically mapped to UUIDs by hashing them with the namespace UUID. The same key maps to different UUIDs in different namespaces. Clients can request certificates for their UUIDs. The certificates are signed by a root CA.

Index

Examples

Constants

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

Signature and Public Key Algorithms.

View Source 
const Version = `dev`

Variables

View Source 
var (
	// ErrCertificateInvalid is returned when an invalid certificate is parsed.
	ErrCertificateInvalid = errors.New("bifrost: certificate invalid")

	// ErrRequestDenied is returned when a certificate request is denied by the CA Gauntlet.
	ErrRequestDenied = errors.New("bifrost: certificate request denied")

	// ErrRequestInvalid is returned when an invalid certificate request is parsed.
	ErrRequestInvalid = errors.New("bifrost: certificate request invalid")

	// ErrRequestAborted is returned when the CA Gauntlet function times out or panics.
	ErrRequestAborted = errors.New("bifrost: certificate request aborted")
)

Errors.

View Source 
var StatsForNerds = metrics.NewSet()

StatsForNerds captures metrics from various bifrost processes.

Functions

func CertificateRequestTemplate added in v1.19.0 

func CertificateRequestTemplate(ns uuid.UUID, key *PublicKey) *x509.CertificateRequest

CertificateRequestTemplate returns a bifrost certificate request template for a namespace and public key.

func GetNamespace added in v1.20.1 

func GetNamespace(ctx context.Context, caUrl string) (uuid.UUID, error)

GetNamespace returns the namespace from the CA at url.

func HTTPClient added in v0.0.6 

func HTTPClient(
	caUrl string,
	ns uuid.UUID,
	privkey *PrivateKey,
	roots *x509.CertPool,
	ssllog io.Writer,
) (*http.Client, error)

HTTPClient returns a http.Client set up for TLS Client Authentication (mTLS). The client will request a new certificate from the bifrost caUrl when needed. 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 UUID 

func UUID(ns uuid.UUID, pubkey *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 X509ToTLSCertificate 

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

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

Types

type Certificate added in v1.11.0 

type Certificate struct {
	*x509.Certificate

	ID        uuid.UUID
	Namespace uuid.UUID
	PublicKey *PublicKey
}

Certificate is a bifrost certificate. It embeds the x509 certificate and adds the bifrost ID, namespace, and public key.

func NewCertificate added in v1.16.0 

func NewCertificate(cert *x509.Certificate) (*Certificate, error)

NewCertificate creates a bifrost certificate from an x509 certificate. It checks for the correct signature algorithm, identity namespace, and identity. On success, it sets the ID, Namespace, and PublicKey fields.

func ParseCertificate 

func ParseCertificate(asn1Data []byte) (*Certificate, error)

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

func RequestCertificate 

func RequestCertificate(
	ctx context.Context,
	caUrl string,
	namespace uuid.UUID,
	key *PrivateKey,
) (*Certificate, error)

RequestCertificate sends a certificate request over HTTP to url and returns the signed certificate. The returned error wraps ErrCertificateRequestInvalid or ErrCertificateRequestDenied if the request is invalid or denied.

Example 
const timeout = 5 * time.Second

exampleNS := uuid.MustParse("228b9676-998e-489a-8468-92d46a94a32d")
ctx, cancel := context.WithTimeout(context.Background(), timeout)
defer cancel()

key, err := NewPrivateKey()
if err != nil {
	panic(err)
}

cert, err := RequestCertificate(ctx, "https://bifrost-ca", exampleNS, key)
if errors.Is(err, ErrRequestInvalid) {
	// This error is returned when the wrong namespace is used in the CSR,
	// or if the CSR is invalid.
	fmt.Println("namespace mismatch or invalid csr")
} else if errors.Is(err, ErrRequestDenied) {
	// This error is returned when the request is denied by the CA gauntlet function.
	fmt.Println("csr denied")
}

// Success.
fmt.Println(cert.Subject)

Output:

func (Certificate) IsCA added in v1.16.7 

func (c Certificate) IsCA() bool

IsCA returns true if the certificate can be used as a certificate authority.

func (*Certificate) IssuedTo added in v1.16.0 

func (c *Certificate) IssuedTo(key *PublicKey) bool

IssuedTo returns true if the certificate was issued to the given public key.

func (Certificate) ToTLSCertificate added in v1.11.0 

func (c Certificate) ToTLSCertificate(key PrivateKey) (*tls.Certificate, error)

ToTLSCertificate returns a tls.Certificate from a bifrost certificate and private key.

type CertificateRequest added in v1.11.0 

type CertificateRequest struct {
	*x509.CertificateRequest

	ID        uuid.UUID
	Namespace uuid.UUID
	PublicKey *PublicKey
}

CertificateRequest is a bifrost certificate request. It embeds the x509 certificate request and adds the bifrost ID, namespace, and public key.

func NewCertificateRequest added in v1.16.0 

func NewCertificateRequest(cert *x509.CertificateRequest) (*CertificateRequest, error)

NewCertificateRequest creates a bifrost certificate request from an x509 certificate request. It checks for the correct signature algorithm, identity namespace, and identity. On success, it sets the ID, Namespace, and PublicKey fields.

func ParseCertificateRequest added in v1.5.2 

func ParseCertificateRequest(asn1Data []byte) (*CertificateRequest, error)

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

type Identity added in v1.16.6 

type Identity struct {
	Namespace uuid.UUID
	PublicKey *PublicKey
}

Identity represents a unique identity in the system.

func ParseIdentity added in v1.16.6 

func ParseIdentity(data []byte) (*Identity, error)

ParseIdentity parses a Bifrost identity from a PEM-encoded block. The block may contain a private key, public key, certificate, or certificate request.

If the block contains a private or a public key, the returned identity will contain the public key. If the block contains a certificate or certificate request, the returned identity will contain the public key and namespace.

func (Identity) String added in v1.16.6 

func (i Identity) String() string

func (Identity) UUID added in v1.16.6 

func (i Identity) UUID() uuid.UUID

type PrivateKey added in v1.15.3 

type PrivateKey struct {
	*ecdsa.PrivateKey
}

PrivateKey is a wrapper around an ECDSA private key. PrivateKey implements the Marshaler and Unmarshaler interfaces for binary, text, JSON, and DynamoDB. Keys are generated using the P-256 elliptic curve. Keys are serialised in PKCS #8, ASN.1 DER form.

func NewPrivateKey added in v1.15.0 

func NewPrivateKey() (*PrivateKey, error)

NewPrivateKey generates a new bifrost private key.

func (PrivateKey) MarshalBinary added in v1.18.0 

func (p PrivateKey) MarshalBinary() ([]byte, error)

MarshalBinary converts a private key to PKCS #8, ASN.1 DER form.

func (PrivateKey) MarshalDynamoDBAttributeValue added in v1.15.3 

func (p PrivateKey) MarshalDynamoDBAttributeValue() (types.AttributeValue, error)

MarshalDynamoDBAttributeValue marshals the private key to PKCS #8, ASN.1 DER form.

func (PrivateKey) MarshalJSON added in v1.15.3 

func (p PrivateKey) MarshalJSON() ([]byte, error)

MarshalJSON marshals the key to a JSON string containing PEM encoded PKCS #8, ASN.1 DER form.

func (PrivateKey) MarshalText added in v1.18.0 

func (p PrivateKey) MarshalText() ([]byte, error)

MarshalText marshals the key to a PEM encoded PKCS #8, ASN.1 DER form.

func (PrivateKey) PublicKey added in v1.15.3 

func (p PrivateKey) PublicKey() *PublicKey

PublicKey returns the public key corresponding to p.

func (PrivateKey) UUID added in v1.15.3 

func (p PrivateKey) UUID(ns uuid.UUID) uuid.UUID

UUID returns the bifrost identifier for p in the given namespace.

func (*PrivateKey) UnmarshalBinary added in v1.18.0 

func (p *PrivateKey) UnmarshalBinary(data []byte) error

UnmarshalBinary parses an unencrypted private key in PKCS #8, ASN.1 DER form. Unmarshal also supports private keys in SEC.1, ASN.1 DER form for backward compatibility.

func (*PrivateKey) UnmarshalDynamoDBAttributeValue added in v1.15.3 

func (p *PrivateKey) UnmarshalDynamoDBAttributeValue(av types.AttributeValue) error

UnmarshalDynamoDBAttributeValue unmarshals the private key from PKCS #8, ASN.1 DER form.

func (*PrivateKey) UnmarshalJSON added in v1.15.3 

func (p *PrivateKey) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the private key from PEM encoded PKCS #8, ASN.1 DER form.

func (*PrivateKey) UnmarshalText added in v1.18.0 

func (p *PrivateKey) UnmarshalText(text []byte) error

UnmarshalText unmarshals the private key from PEM encoded PKCS #8, ASN.1 DER form. Unmarshal also supports EC PRIVATE KEY PEM blocks for backward compatibility.

type PublicKey added in v1.15.0 

type PublicKey struct {
	*ecdsa.PublicKey
}

PublicKey is a wrapper around an ECDSA public key. It implements the Marshaler and Unmarshaler interfaces for binary, text, JSON, and DynamoDB. Keys are serialsed in PKIX, ASN.1 DER form.

func (*PublicKey) Equal added in v1.16.0 

func (p *PublicKey) Equal(other *PublicKey) bool

func (PublicKey) MarshalBinary added in v1.18.0 

func (p PublicKey) MarshalBinary() ([]byte, error)

MarshalBinary marshals a public key to PKIX, ASN.1 DER form.

func (PublicKey) MarshalDynamoDBAttributeValue added in v1.15.0 

func (p PublicKey) MarshalDynamoDBAttributeValue() (types.AttributeValue, error)

MarshalDynamoDBAttributeValue marshals the public key to PKIX, ASN.1 DER form.

func (PublicKey) MarshalJSON added in v1.15.0 

func (p PublicKey) MarshalJSON() ([]byte, error)

MarshalJSON marshals the public key to a JSON string containing PEM encoded PKIX, ASN.1 DER form.

func (PublicKey) MarshalText added in v1.18.0 

func (p PublicKey) MarshalText() ([]byte, error)

MarshalText marshals the public key to a PEM encoded PKIX Public Key in ASN.1 DER form.

func (PublicKey) UUID added in v1.15.0 

func (p PublicKey) UUID(ns uuid.UUID) uuid.UUID

UUID returns a unique identifier derived from the namespace and the client's public key.

func (*PublicKey) UnmarshalBinary added in v1.18.0 

func (p *PublicKey) UnmarshalBinary(data []byte) error

UnmarshalBinary unmarshals a public key from PKIX, ASN.1 DER form.

func (*PublicKey) UnmarshalDynamoDBAttributeValue added in v1.15.0 

func (p *PublicKey) UnmarshalDynamoDBAttributeValue(av types.AttributeValue) error

UnmarshalDynamoDBAttributeValue unmarshals the public key from PKIX, ASN.1 DER form.

func (*PublicKey) UnmarshalJSON added in v1.15.0 

func (p *PublicKey) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the public key as a JSON string containing PEM encoded PKIX Public Key, ASN.1 DER form.

func (*PublicKey) UnmarshalText added in v1.18.0 

func (p *PublicKey) UnmarshalText(text []byte) error

UnmarshalText unmarshals the public key from a PEM encoded PKIX Public Key in ASN.1 DER form.

Source Files

View all Source files

Directories

Path Synopsis
Package asgard provides middleware for use in HTTP API servers that require client certificate (mTLS) authentication.
 Package asgard provides middleware for use in HTTP API servers that require client certificate (mTLS) authentication.
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.
cmd
bf
internal
webapp
Package tinyca implements a small and flexible Certificate Authority.
 Package tinyca implements a small and flexible Certificate Authority.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.