linearregression / spiffe

Implementation of SPIFFE

Status

WARNING This is draft implementation. It will likely change based on the feedback! Use at own risk!!!

Description

SPIFFE is a draft implementation of SPIFFE.io

It includes:

• Certificate Authority management server backend by ETCD (with pluggable backends)
• GRPC API
• spiffectl - command line API tool

Notes for developers

Test everything:

make test

Test package that you need:

make test-package make test-package p=./lib/workload/api/

Test only function in the package that you need:

make test-package p=./lib/workload/api/ e=Workload

Glossary

SPIFFE

SPIFFE: Secure Production Identity Framework For Everyone. This is a draft spec and guidelines for x509-based mutual TLS identity framework. It adds special URN namespace spiffe and embeds SPIFFE URN inside x509 certificates

Trusted Root Bundle

Trusted Root Bundle is a collection of trusted root x509 certificates. SPIFFE service lets you control certificate root bundles and make sure infrastructure services get the right bundles installed

Certificate Authority

Certificate Authority is x509 certificate authority used to sign SPIFFE-powered certificates

Quickstart

Start local SPIFFE service:

make run

Trusted Root Bundles

Create Trusted Root Bundle from local directory with certificates

spiffectl bundle create --replace --id=web --dir=/etc/ssl/certs

You can now export the bundle inside any directory and watch for updates:

spiffectl bundle export --id=web --dir=/tmp/web --exec="/bin/echo updated" --debug --watch

You will see certificates populated to the directory.

ls -l /tmp/web

Every time you update the bundle, directory will be updated as well

Certificates and Certificate Authorities

Create self signed local certificate authority

 spiffectl ca create --replace --id=test --common-name=localhost --org=localhost --ttl=100000h

spiffectl ca ls

[Certificate Authorities]
-------------------------
* id: 'spiffe.localhost.localdomain', CN=spiffe.localhost.localdomain, expires: 2026-09-14 17:31:20 +0000 UTC
* id: 'test', CN=localhost, expires: 2028-02-15 11:39:00 +0000 UTC

You will see 2 Cert Authorities: 1 is a local CA used by SPIFFE itself, another is the one you've just created.

Import CA

You can also import CA:

spiffectl ca import --id=existing --in-key-file=fixtures/certs/ca-key.pem --in-cert-file=fixtures/certs/ca.pem
id: 'existing', CN=Autogenerated CA, expires: 2021-09-08 18:01:00 +0000 UTC successfully created

You can now sign certificates with required SPIFFE IDs:

spiffectl ca sign --renew --ca=test --id=urn:spiffe:localhost:sasha --out-key-file=/tmp/out.pem --out-cert-file=/tmp/out.cert --common-name="*.localhost" --ttl=10s --exec="/bin/echo updated certificate hehe" --debug

You will see certificates and keys generated and certificate will be periodically renewed. Notice exec flag that will launch hook every time cert gets updated.

Trusted Root Bundles and Certificate authorities

You can combine trusted root bundles out of externeal certificates and certificates from certificate authorities:

spiffectl bundle create --replace --id=web --dir=/etc/ssl/certs --ca=test --ca=existing

Kubernetes integration

In K8s mode, SPIFFE is capable of mounting secrets directly to the Pods via special flex volume.

When launched in k8s mode, SPIFFE certificate authority service creates a special CA for signing in-cluster certificates and creates special secret file with credentials for in-cluster agents spiffe-creds, updating it from time to time.

spiffectl can pull credentials in-cluster directly from the secrets by using --k8s-secret and --k8s-namespace flags, and watches for credentials updates

Installation

To install SPIFFE with K8s mode against a working cluster, run the following command:

make dev-create

Now restart Kubelets on nodes, so they can load spiffe.io/flex volume plugin.

See resource definitions for more details.

Architecture

Every K8s node runs a trusted Node CA - special daemon responsible for managing and rotating certificates on every K8s node. Node CA agent communicates with certificate authority service to get certificates.

Flex volume plugin spiffe.io/flex communicates with Node CA using unix socket file, adding and removing mounts.

Example

The following flex volume is supported by the flex plugin:

          flexVolume:
            driver: "spiffe.io/flex"
            options:
              type: "cert"
              commonName: "nginx.default.svc.cluster.local"
              key:  nginx-key.pem
              ttl:  10h
              cert: nginx-cert.pem
              certAuthorityCert: ca-cert.pem

It will generate private key nginx-key.pem, certificate nginx-cert.pem and write certificate of ca-cert.pem to the target volume. It will also take care of the rotation, rotating the certificate every 10 hours.

See nginx.yaml for more details.