spiffe/spire

The SPIFFE Runtime Environment

SPIRE (the SPIFFE Runtime Environment) is a toolchain of APIs for establishing trust between software systems across a wide variety of hosting platforms. SPIRE exposes the SPIFFE Workload API, which can attest running software systems and issue SPIFFE IDs and SVIDs to them. This in turn allows two workloads to establish trust between each other, for example by establishing an mTLS connection or by signing and verifying a JWT token. SPIRE can also enable workloads to securely authenticate to a secret store, a database, or a cloud provider service.

• Get SPIRE
• Learn about SPIRE
• Integrate with SPIRE
• Contribute to SPIRE
• Further Reading
• Security

SPIRE is a graduated project of the Cloud Native Computing Foundation (CNCF). If you are an organization that wants to help shape the evolution of technologies that are container-packaged, dynamically-scheduled and microservices-oriented, consider joining the CNCF.

Get SPIRE

• Pre-built releases of SPIRE can be found at https://github.com/spiffe/spire/releases. These releases contain both SPIRE Server and SPIRE Agent binaries.
• Container images are published for spire-server, spire-agent, and oidc-discovery-provider.
• Alternatively, you can build SPIRE from source.

Learn about SPIRE

• Before trying SPIRE, it's a good idea to learn about its architecture and design goals.
• Once ready to get started, see the Quickstart Guides for Kubernetes, Linux, and MacOS.
• There are several examples demonstrating SPIRE usage in the spire-examples and spire-tutorials repositories.
• Check ADOPTERS.md for a list of production SPIRE adopters, a view of the ecosystem, and use cases.
• See the SPIRE Roadmap for a list of planned features and enhancements.
• Join the SPIFFE community on Slack. If you have any questions about how SPIRE works, or how to get it up and running, the best places to ask questions are the SPIFFE Slack channels.
• Download the free book about SPIFFE and SPIRE, "Solving the Bottom Turtle."

Integrate with SPIRE

• See Extend SPIRE to learn about the highly extensible SPIRE plugin framework.
• Officially maintained client libraries for interacting with the SPIFFE Workload API are available in Go and Java. See SPIFFE Library Usage Examples for a full list of official and community libraries, as well as code samples.
• SPIRE provides an implementation of the Envoy Secret Discovery Service (SDS) for use with Envoy Proxy. SDS can be used to transparently install and rotate TLS certificates and trust bundles in Envoy. See Using SPIRE with Envoy for more information.

For supported integration versions, see Supported Integrations.

Contribute to SPIRE

The SPIFFE community maintains the SPIRE project. Information on the various SIGs and relevant standards can be found in https://github.com/spiffe/spiffe.

• See CONTRIBUTING to get started.
• Use GitHub Issues to request features or file bugs.
• See GOVERNANCE for SPIFFE and SPIRE governance policies.

Further Reading

• The Scaling SPIRE guide covers design guidelines, recommendations, and deployment models.
• For an explanation of how SPIRE compares to related systems such as secret stores, identity providers, authorization policy engines and service meshes see comparisons.

Security

Security Assessments

A third party security firm (Cure53) completed a security audit of SPIFFE and SPIRE in February of 2021. Additionally, the CNCF Technical Advisory Group for Security conducted two assessments on SPIFFE and SPIRE in 2018 and 2020. Please find the reports and supporting material, including the threat model exercise results, below.

• Cure53 Security Audit Report
• SIG-Security SPIFFE/SPIRE Security Assessment: summary
• SIG-Security SPIFFE/SPIRE Security Assessment: full assessment
• Scrutinizing SPIRE to Sensibly Strengthen SPIFFE Security

Reporting Security Vulnerabilities

If you've found a vulnerability or a potential vulnerability in SPIRE please let us know at [email protected]. We'll send a confirmation email to acknowledge your report, and we'll send an additional email when we've identified the issue positively or negatively.

spire's Issues

Implement token-based Node Attestor

From @evan2645 on August 7, 2017 21:17

Implement a node attestor plugin which support join tokens. See https://github.com/spiffe/node-agent/issues/37

Copied from original issue: spiffe/control-plane#42

Implement Control Plane CA in Memory

Should use GO PKI libs. Need to define what will be configured. Trust domain should be passed in as a configuration argument. we need to define what the config parameters for the Plugin will be. Part of the README. How do we translate those to the CP HCL config file

Library to parse SPIFFE ID out of a cert

From @evan2645 on July 18, 2017 19:32

In order to do any of the authentication we want, we need to be able to pull a SPIFFE ID out of a certificate. In practice, this is poorly supported due to the use of the URI SAN type. Additionally, this action will be performed in many places, by us and by others, so it makes sense to build a shared library.

We can use the go-spiffe repo for this. The lib should provide at least two helper methods:

1. Given a cert or TLS connection, give me the SPIFFE ID of the client
2. Given a cert or TLS connection, assert that the client matches SPIFFE ID foo

Copied from original issue: spiffe/node-agent#3

Data Store Plugin: Handle schema changes

We need to handle changes in the schema. Figure out a way to update the schema so when the plugin is updated it can persist the information according with the new definitions.
Migration of the old data to the new schema must also be handled.

Add pre-commit hook to make sure all package names conform to standard

From @walmav on July 26, 2017 21:21

1. Identify rules for standard package naming format.
2. Add a pre-commit hook that enforces these rules.

Copied from original issue: spiffe/control-plane#15

Add support to Federated Bundles in CP Data Store SQLite plugin

Support Federated Bundles in the Control Plane Data Store SQLite plugin.

CLI authentication

The CLI utility exposes some sensitive operations. "Regular" users on the system shouldn't be able to invoke such actions, so we need to control access to these functions. If we use a socket, we can apply filesystem permissions there, so that only root or the CP/NA user can access it

Make sure we have testing for all proto buffer interfaces

From @kunzimariano on August 7, 2017 21:11

NodeAgent
Plugins

• Workload Attester
• Key Manager
• Node Attester

API

• Workload API

Copied from original issue: spiffe/node-agent#36

Implement Workload API

From @kunzimariano on August 7, 2017 20:51

GRPC (Service side).

Copied from original issue: spiffe/node-agent#31

Basic CLI for GRPC/REST (Registration)

From @kunzimariano on August 7, 2017 20:57

Demo will have to call CLI to do Registration. Or should we use REST for registration. First phase will just load data into SQLite (Look into hashicorp cli).

Copied from original issue: spiffe/control-plane#39

move example configs to central location

out of the .conf/ directories, into the light

Make sure we have testing for all protobuf and plugin interfaces

Protobuf and go-plugins define interfaces which are used to call the actual service and plugin implementations. The code path of the caller can be easily tested using mocked objects for these interfaces using mockgen. This ticket is to implement unit test by injecting the mocked objects in code path that uses the interfaces.

Control Plane
API

• Node API
• Registration

Plugins

• Node Attester
• CA CP
• CA Up stream
• Data Store
• Node Selector

Copied from original issue: spiffe/control-plane#40

Implement CP DataStore Sqlite plugin

From @walmav on August 7, 2017 20:58

Seed initial testing with a CSV data file that is loaded into SQLite

Copied from original issue: spiffe/node-agent#34

• CreateFederatedEntry()
• ListFederatedEntry()
• UpdateFederatedEntry()
• DeleteFederatedEntry()
• CreateAttestedNodeEntry()
• FetchAttestedNodeEntry()
• FetchStaleNodeEntries()
• UpdateAttestedNodeEntry()
• DeleteAttestedNodeEntry()
• CreateNodeResolverMapEntry()
• FetchNodeResolverMapEntry()
• DeleteNodeResolverMapEntry()
• RectifyNodeResolverMapEntries()
• CreateRegistrationEntry()
• FetchRegistrationEntry()
• UpdateRegistrationEntry()
• DeleteRegistrationEntry()
• ListParentIDEntries()
• ListSelectorEntries()
• ListSpiffeEntries()
• Configure()
• GetPluginInfo() (minimal stub exists)

Having built and started the control_plane binary, I get strange errors

I've built and started the control plane binary, and set the CP_CONFIG_PATH environment variable to point to /root/go/src/github.com/spiffe/sri/control_plane/.conf/default_cp_config.hcl.

When I try and run the control plane binary, I get the following output:

• When I run ./control_plane/control_plane

  I get Usage: sri/control_plane... (ie. the expected output)

• When I run ./control_plane/control_plane plugin-info

  I get 2017/08/24 14:02:33 error: rpc error: code = Unavailable desc = grpc: the connection is unavailable

  I find this error confusing as there's no text that describes what the control_plane binary was trying to do, or what I should be doing to fix it. It would be nice if the error message included details about what CP was trying to connect to, and what configuration it was using to do so.

• When I run ./control_plane/control_plane server

  I get no output.

  This is a little confusing, since now I'm not sure if the command worked or not. Ideally I'd see a line confirming success if it worked (and perhaps some extra detail, like the PID of the server). I would definitely expect to see something if it failed. But running ps aux shows now new processes running, so I guess it failed.

• When I run ./control_plane/control_plane stop

  I get 2017/08/24 14:02:33 error: rpc error: code = Unavailable desc = grpc: the connection is unavailable

  I find this error confusing for the same reasons as for when I ran plugin-info.

Build was from source, commit 65830d7996ffab21862ded6c4889980f441ac2e0

Add Pre commit hook for running go fmt

From @walmav on July 26, 2017 21:15

A pre-commit hook that would run go fmt would enforce coding style.

Copied from original issue: spiffe/control-plane#14

CA plugins: validate configuration values in Configure()

Add validation logic to ensure that the configuration values parsed are valid for the plugin.

Implement ProtoBuf data validation

We need to implement validation of data in ProtoBuf messages.
We may use this: https://github.com/mwitkow/go-proto-validators

Extract plugin and endpoint initialization from the server command.

NA and CP configuration

From @walmav on August 7, 2017 20:51

How do we parse and send stanzas to configured plugins. Using HCL parsing. Even if we go with the one binary option, will want to have the ability to configure each different "plugin"

Copied from original issue: spiffe/node-agent#32

TBD:

• Identify configurable properties and create section in Arch for NA

• Identify configurable properties and create section in Arch for CP

• Create default config for NA

• Create default config for CP

• Update the configs

• Update Readme for configurations

Add an evict method to the registration API

We have a mechanism which allows a Base SVID to be used in order to authenticate a request for a new Base SVID of the same ID once and only once. This is meant to mitigate the theft of a Base SVID private key, as the real node will get to know that something is wrong when it can't rotate its certificate.

This, however, does not take into account the situation in which the node has been decommissioned or otherwise. It is possible to steal the SVID key and destroy the host, renewing the key forever. For this and other reasons, we need a way to evict or "de-attest" nodes which have already been attested.

Add a method to evict/de-attest an already-attested node. This can be done by removing the entry in the Attested Nodes store, since we consult this store for the serial number when validating Base SVID renewal. Renewal should be rejected if there is no entry for the SVID being renewed.

Update README for Control Plane

From @y2bishop2y on August 9, 2017 19:17

Have to explain how to build, run and configure the ControlPlane.

• Configuration
• How to build
• How to deploy
• How to run in a typical configuration
• What the Control Plane does
• Interactions between different components in a SPIFFE deployment
• Description of the plugins
• Registration API Protobuf and Readme.md

Copied from original issue: spiffe/control-plane#45

Implement Node API

• FetchBaseSVID
• FetchSVID
• FetchCPBundle
• FetchFederatedBundle

From @kunzimariano on August 7, 2017 20:54

Copied from original issue: spiffe/control-plane#38

Implement unix workload attestor

From @evan2645 on August 7, 2017 21:15

Create a unix workload attestor. Support user ID attestation at a minimum.

Copied from original issue: spiffe/node-agent#38

Implement Consumer of Node API (Control Plane)

From @kunzimariano on August 7, 2017 20:54

Copied from original issue: spiffe/node-agent#33

Basic CLI for HTTP REST (Registration)

From @kunzimariano on August 7, 2017 20:57

Demo will have to call CLI to do Registration. Or should we use REST for registration. First phase will just load data into SQLite (Look into hashicorp cli).

Copied from original issue: spiffe/control-plane#39

plugin processes do not die when the server process does

$ ps ax | egrep '(spire-agent|attestor)' | grep -v grep
23694 pts/0    Sl+    0:00 spire-agent start
23698 pts/0    Sl+    0:00 workloadattestor-secretfile
$ kill 23694
$ ps ax | egrep '(spire-agent|attestor)' | grep -v grep
23698 pts/0    Sl     0:00 workloadattestor-secretfile

basic run-time startup tests

some classes of coding errors only some up at runtime, add a quick integration test

move /helpers into common

Logging Middleware

From @walmav on August 14, 2017 19:9

Create common Middleware to be used across

• Create common library
• Create middleware for plugins
• Create middleware for api (gokit)

Copied from original issue: spiffe/node-agent#50

rename this repo "spire"

and update all the imports

build.sh: compile, run tests in parallel

go test a b will compile and test packages a and b at the same time. build.sh is compiling/testing each package at a time.

On my system, running go test $(glide novendor) is roughly 4 times faster than running each package in sequence. I don't know if the impact would be the same on travis, but I'm sure it'd help.

/usr/bin/time /bin/sh -c 'go test $(glide novendor)
...
       31.83 real        49.61 user         4.29 sys

/usr/bin/time /bin/sh -c 'for i in $(go list ./... | grep -v -e'/vendor' -e'/proto$'); do go test $i; done'
...
      117.44 real       211.93 user        27.63 sys

run tests with `-race`

To detect possible race conditions.

edit: i usually have two modes - one quick without -race for edit-test cycle, one with -race for CI and occasionally running by hand.

Implement Control Plane upstream CA in Memory

From @amartinezfayo on August 7, 2017 21:22

Copied from original issue: spiffe/control-plane#43

Server CA plugin: revisit validation logic in LoadCertificate()

Instead of doing a complete validation to ensure that the certificate being loaded is a valid signing certificate, we may just validate that the certificate being loaded was created based on a CSR generated by the plugin.

Add localization support

We should have localized strings. This includes logging.

migrate /services/registration.go to /cmd/spire-server

Implement token-based Node Attestor

From @evan2645 on August 7, 2017 21:12

Implement a node attestor for token-based joins. Should take a join token via CLI flag and/or by reading a file.

Copied from original issue: spiffe/node-agent#37

Implement Key Manager in memory

From @amartinezfayo on August 7, 2017 21:5

Copied from original issue: spiffe/node-agent#35

simplify spire-agent and spire-server

• remove "service" API interfaces
• turn both binaries into foreground processes
• add command-line flag for configuration file location

Stop the plugins once we stop the service.

We are creating the plugin clients with Managed: true. Find out how to call plugin.CleanupClients() properly.

registration.proto and data_store.proto common messages

registration.proto and data_store.proto have messages in common (see RegisteredEntry and Selector).
Extract them into a separated proto file and consume them with import.

Plugin Lifecycle Management

From @walmav on August 7, 2017 20:45

Plugins how do they work. How do we handle and call out to the plugin. What are the default interfaces for all plugins to implement. Documentation for Plugins. Also, if we cannot get them to work, how do we build with just interfaces and create 1 binary (we need to know our escape options)

Copied from original issue: spiffe/node-agent#30

Update automated testing to use docker

We have a docker-based runtime environment for developers, it makes sense to test and build there too.

Cleanup the Workload API

From @y2bishop2y on August 10, 2017 0:0

Collapse the API and just have one endpoint. Do we need a different call set for Federated trust bundles? The API should just pull down all the SVID's it needs, should not matter if they are federated or not.

Copied from original issue: spiffe/node-agent#42

rename server api to admin

Implement Registration API

• CreateEntry
• FetchEntry
• ListByParentID
• ListBySelector
• ListBySpiffeID
• DeleteEntry
• UpdateEntry
• CreateFederatedBundle
• ListFederatedBundles
• UpdateFederatedBundle
• DeleteFederatedBundle

Update README.md

From @y2bishop2y on August 9, 2017 17:38

Have to explain how to build, run and configure the NodeAgent.

• Configuration
• How to build
• How to deploy
• How to run in a typical configuration
• What the NodeAgent does
• Description of the plugins

Copied from original issue: spiffe/node-agent#41

Consider calling the SPIFFE Control Plane CLI `spirectl`

There's a convention with some projects to postfix the CLI for the control plane of a project with *ctl (for "control"), examples include:

• Kubernetes kubectl - https://kubernetes.io/docs/user-guide/kubectl-overview/
• Istio istioctl - https://istio.io/docs/reference/commands/istioctl.html

Following this convention helps a new developer easily distinguish the server binary from the CLI binary, which can help when getting started. Since this CLI is the main mechanism folks will use to interact with SPIRE, consider spirectl.

Implement logic to poll for expiring Workload certs

From @walmav on August 7, 2017 21:27

The Node Agent polls for expiring certs and requests the control plane to reissue the certs.

Copied from original issue: spiffe/node-agent#40

Add swagger spec to Registration API