From b24393286dc33a0ffba274d7bdd6833f7e407870 Mon Sep 17 00:00:00 2001 From: Max Lambrecht Date: Thu, 8 Jun 2023 09:50:37 -0500 Subject: [PATCH] Add Comprehensive Getting Started Guide and Configuration References (#217) Signed-off-by: Max Lambrecht --- README.md | 11 +- doc/galadriel_harvester.md | 213 +++++++++++++++++++++++++++++++++ doc/galadriel_server.md | 234 +++++++++++++++++++++++++++++++++++++ doc/getting_started.md | 207 ++++++++++++++++++++++++++++++++ 4 files changed, 663 insertions(+), 2 deletions(-) create mode 100644 doc/galadriel_harvester.md create mode 100644 doc/galadriel_server.md create mode 100644 doc/getting_started.md diff --git a/README.md b/README.md index 5ee548a4..5939406e 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,16 @@ functions as a central hub for the management and auditing of these Federation r --- -## Getting Started +## Quick start -- **TBD** +1. Download the appropriate binary from our [releases page](https://github.com/HewlettPackard/galadriel/releases). +2. Follow the instructions in our [Getting Started Guide](./doc/getting_started.md). + +## Documentation + +- [Getting Started Guide](./doc/getting_started.md) +- [Galadriel Server Configuration Reference](./doc/galadriel_server.md) +- [Harvester Configuration Reference](./doc/galadriel_harvester.md) ## Contributing diff --git a/doc/galadriel_harvester.md b/doc/galadriel_harvester.md new file mode 100644 index 00000000..6f73f385 --- /dev/null +++ b/doc/galadriel_harvester.md @@ -0,0 +1,213 @@ +# Galadriel Harvester Configuration and CLI Reference + +This document provides a comprehensive reference for both the Galadriel Harvester configuration file and its +command-line interface (CLI). It details each section of the configuration file and explains various CLI commands to +assist with the harvester's setup, customization, and management. + +## Configuration File + +The Galadriel Harvester configuration file contains various sections that let you customize the Harvester's behaviour, +enhancing your control over its functions and operations. + +### `harvester` + +This section lists the options available for configuring the main behavior of the Galadriel Harvester. + +| Option | Description | Default | +|-----------------------------------|--------------------------------------------------------------------------------------------------------------------|--------------------------------------| +| `trust_domain` | Specifies the trust domain of the SPIRE Server instance that the Harvester runs alongside. | | +| `harvester_socket_path` | Specifies the path to the UNIX Domain Socket that the Galadriel Harvester will listen on. | `/tmp/galadriel-harvester/api.sock` | +| `spire_socket_path` | Specifies the path to the UNIX Domain Socket of the SPIRE Server that the Harvester will connect to. | `/tmp/spire-server/private/api.sock` | +| `galadriel_server_address` | Specifies the DNS name or IP address and port of the upstream Galadriel Server that the Harvester will connect to. | | +| `server_trust_bundle_path` | Path to the Galadriel Server CA bundle that will be used to verify the Server's certificate. | | +| `federated_bundles_poll_interval` | Configure how often the harvester will poll federated bundles from the Galadriel Server. | `2m` | +| `spire_bundle_poll_interval` | Configure how often the harvester will poll the bundle from SPIRE. | `1m` | +| `log_level` | Sets the logging level. Options are `DEBUG`, `WARN`, `INFO`, `ERROR` | `INFO` | +| `data_dir` | Directory to store persistent data. | | + +### `providers` + +This section describes the configuration options for the `BundleSigner` and `BundleVerifier` providers in the Galadriel +Harvester. + +| Provider | Description | +|------------------|--------------------------------------------------------------------------------------------------------| +| `BundleSigner` | Enables the signing of bundles using a selected implementation. Can be `noop` or `disk`. | +| `BundleVerifier` | Enables the verification of bundle signatures using selected implementations. Can be `noop` or `disk`. | + +#### BundleSigner + +This subsection illustrates options available for the `BundleSigner`. + +| Option | Description | +|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `noop` | No-op signing (doesn't sign bundles). | +| `disk` | Enables the signing of bundles using a disk-based key pair. The `ca_cert_path` is the path to the CA certificate file. The `ca_private_key_path` is the path to the CA private key file. | + +#### Example: + +```hcl +providers { + BundleSigner "disk" { + ca_cert_path = "conf/harvester/dummy_root_ca.crt" + ca_private_key_path = "conf/harvester/dummy_root_ca.key" + } +} +``` + +#### BundleVerifier + +This subsection explains the `BundleVerifier` options. + +| Option | Description | +|--------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `noop` | If this verifier is enabled, all bundles will pass the verification process without actually validating the signatures. | +| `disk` | Enables the verification of bundle signatures using a disk-based trust bundle. The `trust_bundle_path` is the path to the trust bundle file. | + +#### Example: + +```hcl +providers { + BundleVerifier "disk" { + trust_bundle_path = "conf/harvester/dummy_root_ca.crt" + } +} +``` + +## Galadriel Harvester CLI Reference + +The Galadriel Harvester provides a command-line interface (CLI) for operating the Harvester and managing +relationships for the trust domain overseen by the corresponding SPIRE Server. + +To access the CLI, you can use the `galadriel-harvester` command: + +```bash +./galadriel-harvester +``` + +### Available Commands + +This section describes the available commands and their usage. + +#### `run` + +This command starts the Galadriel Harvester. + +```bash +./galadriel-harvester run [flags] +``` + +| Flag | Description | Default | +|-------------------|-------------------------------------------------------------------------------------------|---------------------------------| +| `-c, --config` | Path to the Galadriel Harvester config file. | `conf/harvester/harvester.conf` | +| `-t, --joinToken` | A join token generated by Galadriel Server used to introduce the Harvester to the Server. | | + +#### `relationship` + +The 'relationship' command assists you in managing relationships within the trust domain regulated by the SPIRE Server +that the Harvester operates with. + +```bash +./galadriel-harvester relationship [command] +``` + +#### Available subcommands: + +- `approve` - Authorize participation in the Federation relationship. +- `deny` - Refuse participation in the Federation relationship. +- `list` - List all relationships for the trust domain managed by the SPIRE Server that the Harvester operates with. + +##### `relationship approve` + +The `approve` command is for approving a relationship for the trust domain of the SPIRE Server that the Harvester +operates with. + +Syntax: + +```bash +./galadriel-harvester relationship approve [flags] +``` + +Example Usage: + +```bash +./galadriel-harvester relationship approve --relationshipID +``` + +| Flag | Description | Default | +|-------------------------------|--------------------------------------------------------|---------| +| `-r, --relationshipID string` | The specific Relationship ID that you wish to approve. | | + +##### `relationship deny` + +The `deny` command enables you to reject a relationship within the trust domain managed by the SPIRE Server that the +Harvester operates with. + +Syntax: + +```bash +./galadriel-harvester relationship deny [flags] +``` + +Example Usage: + +```bash +./galadriel-harvester relationship deny --relationshipID +``` + +| Flag | Description | Default | +|-------------------------------|-----------------------------------------------------|---------| +| `-r, --relationshipID string` | The specific Relationship ID that you wish to deny. | | + +##### `relationship list` + +The `list` command allows you to view all relationships within the trust domain managed by the SPIRE Server where the +Harvester operates. + +```bash +./galadriel-harvester relationship list [flags] +``` + +Example Usage: + +```bash +./galadriel-harvester relationship list +``` + +### Global Flags + +These flags can be used across all commands. + +| Flag | Description | Default | +|----------------|---------------------------------------------|-------------------------------------| +| `--socketPath` | Path to the Galadriel Harvester API socket. | `/tmp/galadriel-harvester/api.sock` | + +## Sample Configuration File + +Provided below is a sample configuration file for the Galadriel Harvester. It demonstrates how to configure the +Harvester, providers, and other available options. + +```hcl +harvester { + trust_domain = "example.org" + harvester_socket_path = "/tmp/galadriel-harvester/api.sock" + spire_socket_path = "/tmp/spire-server/private/api.sock" + galadriel_server_address = "localhost:8085" + server_trust_bundle_path = "./conf/harvester/dummy_root_ca.crt" + federated_bundles_poll_interval = "10s" + spire_bundle_poll_interval = "10s" + log_level = "DEBUG" + data_dir = "./.data" +} + +providers { + BundleSigner "disk" { + ca_cert_path = "conf/harvester/dummy_root_ca.crt" + ca_private_key_path = "conf/harvester/dummy_root_ca.key" + } + + BundleVerifier "disk" { + trust_bundle_path = "conf/harvester/dummy_root_ca.crt" + } +} +``` diff --git a/doc/galadriel_server.md b/doc/galadriel_server.md new file mode 100644 index 00000000..84bd0cb7 --- /dev/null +++ b/doc/galadriel_server.md @@ -0,0 +1,234 @@ +# Galadriel Server Configuration Reference + +This document provides a comprehensive reference for both the Galadriel Server configuration file and its command-line +interface (CLI). It details each section of the configuration file and explains various CLI commands to assist with the +server's setup, customization, and management. + +## Introduction to the Configuration File + +The Galadriel Server configuration file is instrumental in tailoring the behavior of the Galadriel Server. It's divided +into multiple sections, primarily `server` and `providers`, with `providers` further containing `Datastore`, `X509CA`, +and `KeyManager`. + +### Server Configuration (`server`) + +This section facilitates the configuration of the server's fundamental characteristics. It includes properties such +as `listen_address`, `listen_port`, `socket_path`, and `log_level`. Below is the detailed description for each property +along with their default values: + +| Property | Description | Default | +|------------------|-----------------------------------------------------------------------------------------------------------------------------|----------------------------------| +| `listen_address` | Specifies the IP address or DNS name that the Galadriel server will bind to for accepting network connections. | `0.0.0.0` | +| `listen_port` | Specifies the HTTP port number that the Galadriel server will listen on for incoming connections. | `8085` | +| `socket_path` | Specifies the path to the UNIX Domain Socket that the Galadriel Server API will bind to for communication on the same host. | `/tmp/galadriel-server/api.sock` | +| `log_level` | Sets the logging level. Options are `DEBUG`, `INFO`, `WARN`, `ERROR`. | `INFO` | + +#### Example: + +```hcl +server { + listen_address = "localhost" + listen_port = "8085" + socket_path = "/tmp/galadriel-server/api.sock" + log_level = "DEBUG" +} +``` + +### Provider Configuration (`providers`) + +The `providers` section allows you to configure the Datastore, X509CA, and KeyManager providers. Each provider is +detailed below: + +| Provider | Description | +|--------------|------------------------------------------------------------------------------| +| `Datastore` | Configures the datastore provider. | +| `X509CA` | Configures the X509CA provider for signing TLS X.509 certificates. | +| `KeyManager` | Configures the KeyManager for providing private keys for signing JWT tokens. | + +The following subsections provide detailed configurations for each provider: + +#### Datastore Configuration + +The Datastore section covers the configuration details for SQLite3 and PostgreSQL datastores: + +| Option | Description | +|------------|----------------------------------------------------------------------------------------------| +| `sqlite3` | Uses SQLite3 as the datastore. The `connection_string` is the database connection string. | +| `postgres` | Uses PostgreSQL as the datastore. The `connection_string` is the database connection string. | + +#### Example: + +```hcl +providers { + Datastore "sqlite3" { + connection_string = "./datastore.sqlite3" + } +} +``` + +#### X509CA Configuration + +The X509CA section provides configuration details for X.509 CA providers: + +| Option | Description | +|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `disk` | Uses a ROOT CA and private key loaded from disk to issue X.509 certificates. The `key_file_path` is the path to the root CA private key file in PEM format. The `cert_file_path` is the path to the root CA certificate file in PEM format. | + +#### Example: + +```hcl +providers { + X509CA "disk" { + key_file_path = "./conf/server/dummy_root_ca.key" + cert_file_path = "./conf/server/dummy_root_ca.crt" + } +} +``` + +#### KeyManager Configuration + +The KeyManager section discusses the configuration details for key managers: + +| Option | Description | +|----------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| `memory` | A key manager for generating keys and signing certificates that stores keys in memory. | +| `disk` | A key manager for generating keys that stores keys on disk. The `keys_file_path` is the path to the file where the key manager will store keys. | + +#### Example: + +```hcl +providers { + KeyManager "disk" { + keys_file_path = "./keys.json" + } +} +``` + +Sure, here is the improved "Galadriel Server CLI Reference" section: + +## Galadriel Server CLI Reference + +The Galadriel server provides a command-line interface (CLI) for operating the server, managing federation +relationships, creating join tokens, and managing SPIFFE trust domains. + +To access the CLI, use the `galadriel-server` command: + +```bash +./galadriel-server +``` + +### CLI Commands + +Below are the primary commands available in the CLI, along with their associated flags. + +#### `run` Command + +This command initiates the Galadriel server. + +```bash +./galadriel-server run [flags] +``` + +| Flag | Description | Default | +|----------------|-------------------------------------------|---------------------------| +| `-c, --config` | Path to the Galadriel Server config file. | `conf/server/server.conf` | + +#### `token generate` Command + +This 'generate' command enables the generation of a join token bound to the provided trust domain. The join token acts +as a secure authentication mechanism to establish the requisite trust relationship between the Harvester and the +Galadriel Server. + +```bash +./galadriel-server token generate [flags] +``` + +| Flag | Description | Default | +|---------------------|---------------------------------------------------------|---------| +| `-t, --trustDomain` | The trust domain to which the join token will be bound. | | +| `--ttl` | Token TTL in seconds. | `600` | + +#### `trustdomain` Command + +The 'trustdomain' command facilitates the management of SPIFFE trust domains in the Galadriel Server. This +command allows for the registration, listing, updating, and deletion of trust domains. + +```bash +./galadriel-server trustdomain [command] +``` + +Subcommands: + +- `create`: Register a new trust domain in Galadriel Server. + +##### `trustdomain create` Subcommand + +This 'create' command registers a new trust domain in the Galadriel Server. + +```bash +./galadriel-server trustdomain create [flags] +``` + +| Flag | Description | Default | +|---------------------|-------------------------------------------|---------| +| `-t, --trustDomain` | The name of the trust domain to register. | | + +#### `relationship` Command + +The 'relationship' command manages federation relationships between SPIFFE trust domains. Federation relationships in +SPIFFE enable secure communication between workloads across different trust domains. + +```bash +./galadriel-server relationship [command] +``` + +Subcommands: + +- `create`: Register a new federation relationship in Galadriel Server. + +##### `relationship create` Subcommand + +This 'create' command registers a new federation relationship in the Galadriel Server. + +```bash +./galadriel-server relationship create [flags] +``` + +| Flag | Description | Default | +|----------------------|----------------------------------------------------------------|---------| +| `-a, --trustDomainA` | The name of a trust domain to participate in the relationship. | | +| `-b, --trustDomainB` | The name of a trust domain to participate in the relationship. | | + +### Global Flags + +These flags can be used across all commands. + +| Flag | Description | Default | +|----------------|------------------------------------------|----------------------------------| +| `--socketPath` | Path to the Galadriel Server API socket. | `/tmp/galadriel-server/api.sock` | + +## Sample Configuration File + +The following is a sample configuration file for the Galadriel server: + +```hcl +server { + listen_address = "localhost" + listen_port = "8085" + socket_path = "/tmp/galadriel-server/api.sock" + log_level = "DEBUG" +} + +providers { + Datastore "sqlite3" { + connection_string = "./datastore.sqlite3" + } + + X509CA "disk" { + key_file_path = "./conf/server/dummy_root_ca.key" + cert_file_path = "./conf/server/dummy_root_ca.crt" + } + + KeyManager "memory" {} +} +``` diff --git a/doc/getting_started.md b/doc/getting_started.md new file mode 100644 index 00000000..1713a3f2 --- /dev/null +++ b/doc/getting_started.md @@ -0,0 +1,207 @@ +# Getting Started with Galadriel + +This guide will walk you through the process of setting up Galadriel, a tool that streamlines the configuration of +Federation relationships among SPIRE Servers and manages the secure exchange of Trust Bundles. + +## Prerequisites + +Before you begin, you need to have two SPIRE Servers running in two different trust domains: `trust-domain-a` +and `trust-domain-b`. Each SPIRE Server should bind the local API to a unique UNIX Domain Socket (UDS). For more +information on how to set up a SPIRE Server, refer to +the [SPIRE Server Getting Started Guide](https://spiffe.io/docs/latest/try/getting-started-linux-macos-x/). + +For example: + +- SPIRE Server for `trust-domain-a` should bind to `/tmp/spire-server-a/private/api.sock` +- SPIRE Server for `trust-domain-b` should bind to `/tmp/spire-server-b/private/api.sock` + +## Installing Galadriel + +You can either download the pre-compiled binaries for Linux or build Galadriel from source for MacOS. + +### Downloading Galadriel for Linux + +You can download the Galadriel binaries for `amd64` and `arm64` architectures using the following commands: + +For `amd64` architecture: + +```bash +curl -s -N -L https://github.com/HewlettPackard/galadriel/releases/download/v0.2.1/galadriel-0.2.1-linux-amd64-glibc.tar.gz | tar xz +``` + +For `arm64` architecture: + +```bash +curl -s -N -L https://github.com/HewlettPackard/galadriel/releases/download/v0.2.1/galadriel-0.2.1-linux-arm64-glibc.tar.gz | tar xz +``` + +These commands will download and extract the Galadriel binaries `galadriel-server` and `galadriel-harvester` into a +directory named `galadriel-0.2.1`. The binaries can be found in the `bin` directory. + +### Building Galadriel from Source for MacOS + +To build Galadriel from source, clone the Galadriel repository and build the binaries using `make`: + +```bash +git clone https://github.com/HewlettPackard/galadriel.git +cd galadriel +make build +``` + +This will create the Galadriel binaries `galadriel-server` and `galadriel-harvester` in the `bin` directory. + +## Starting the Galadriel Server + +The Galadriel Server is responsible for managing relationships between trust domains and for storing and distributing +the trust bundles to the Harvesters. + +To start the Galadriel Server, navigate to the root directory of the Galadriel release artifact and run the following +command: + +```bash +./bin/galadriel-server run --config conf/server/server.conf +``` + +This command will start the Galadriel Server using the configuration file located at `conf/server/server.conf`. + +## Registering Trust Domains in Galadriel Server + +You need to register the trust domains `trust-domain-a` and `trust-domain-b` in the Galadriel Server. You can do this +using the following commands: + +```bash +./galadriel-server trustdomain create --trustDomain trust-domain-a +``` + +```bash +./galadriel-server trustdomain create --trustDomain trust-domain-b +``` + +These commands will register the trust domains and output a confirmation message. + +## Creating a Relationship Between Trust Domains + +To create a relationship between the trust domains `trust-domain-a` and `trust-domain-b`, use the following command: + +```bash +./galadriel-server relationship create --trustDomainA trust-domain-a --trustDomainB trust-domain-b +``` + +This command creates a relationship between the trust domains + +`trust-domain-a` and `trust-domain-b` that is initially in the `PENDING` state. This relationship needs to be approved +by the Harvesters administrators. + +## Generating a Join Token to Onboard a Harvester + +A join token is required to onboard a Harvester. To generate a join token bound to trust domain `trust-domain-a`, run +the following command: + +```bash +./galadriel-server token generate --trustDomain trust-domain-a +``` + +This command will output a token string. + +## Starting the First Harvester + +The Harvester is responsible for fetching and uploading trust bundles from/to the Galadriel Server and setting them to +the SPIRE Server. + +### Harvester Config File + +First, copy the sample Harvester config file `conf/harvester/harvester.conf` to `conf/harvester/harvester-a.conf` and +edit the following properties: + +```hcl +harvester { + trust_domain = "trust-domain-a" + harvester_socket_path = "/tmp/galadriel-harvester-a/api.sock" + spire_socket_path = "/tmp/spire-server-a/private/api.sock" +} +``` + +To start the Harvester, run the following command, replacing `` with the token generated in the previous +step: + +```bash +./galadriel-harvester run --joinToken --config conf/harvester/harvester-a.conf +``` + +## Starting the Second Harvester + +To start a second Harvester, you need to generate a join token bound to trust domain `trust-domain-b`: + +```bash +./galadriel-server token generate --trustDomain trust-domain-b +``` + +Next, copy the sample Harvester config file `conf/harvester/harvester.conf` to `conf/harvester/harvester-b.conf` and +edit the following properties: + +```hcl +harvester { + trust_domain = "trust-domain-b" + harvester_socket_path = "/tmp/galadriel-harvester-b/api.sock" + spire_socket_path = "/tmp/spire-server-b/private/api.sock" +} +``` + +Start the second Harvester by running the following command, replacing `` with the token generated in the +previous step: + +```bash +./galadriel-harvester run --joinToken --config conf/harvester/harvester-b.conf +``` + +## Approving the Relationship Between Trust Domains + +To list the relationships, run the following command: + +```bash +./galadriel-harvester relationship list --socketPath /tmp/galadriel-harvester-a/api.sock +``` + +This command will output the details of the relationship, including its ID and the consent status of each trust domain. + +To approve the relationship, run the following command, replacing `` with the relationship ID: + +```bash +./galadriel-harvester relationship approve --socketPath /tmp/galadriel-harvester-a/api.sock --relationshipID +``` + +This command will approve the relationship from the perspective of `trust-domain-a`. Now, the trust bundles +from `trust-domain-b` will be fetched from the Galadriel Server and set into the SPIRE Server. + +Repeat the approval process for the `trust-domain-b` Harvester: + +```bash +./galadriel-harvester relationship approve --socketPath /tmp/galadriel-harvester-b/api.sock --relationshipID +``` + +Now the relationship is approved by both Harvesters, which means that the trust bundles from one trust domain will be +fetched from the Galadriel Server and set into the SPIRE Server in the other trust domain. + +## Verifying the Bundles Were Set in the SPIRE Servers + +In the SPIRE Servers, you should see a log line similar to the following: + +```bash +INFO[0082] Bundle set successfully authorized_as=local authorized_via=transport method=BatchSetFederatedBundle trust_domain_id=trust_domain_a +``` + +This indicates that the trust bundles have been successfully set. + +To verify the Federated bundles in the SPIRE Servers, use the following commands: + +```bash +./spire-server bundle list -socketPath /tmp/spire-server-a/private/api.sock +``` + +```bash +./spire-server bundle list -socketPath /tmp/spire-server-b/private/api.sock +``` + +These commands will display the Federated bundles for each trust domain. + +Congratulations! You have now set up Galadriel and established a Federation relationship between two trust domains. \ No newline at end of file