trdl secrets engine

The trdl secrets engine is a built-in Stronghold EE plugin for secure software release delivery following the trdl model. The plugin builds release artifacts from a Git tag, signs them, publishes them to S3 storage, and publishes update channels. Builds and publishing run only for commits that have the required number of verified PGP signatures (a quorum).

Key properties:

• the source code and the release configuration (trdl.yaml) are stored in a Git repository;
• the update channel configuration (trdl_channels.yaml) can be stored in a separate branch;
• trusted PGP public keys and the required number of signatures are set in the plugin configuration;
• release artifacts are signed with a PGP key managed by the plugin;
• macOS build signing and ELF binary signing via Delivery Kit are supported;
• builds run asynchronously as tasks whose status and log are available via the API.

The plugin is the server side of the trdl model (the github.com/werf/trdl/server module). Release configuration formats:

• trdl.yaml (the path is set by git_trdl_path): the required dockerImage field (builder image name with a digest) and the required commands list that runs in the container; the result must be placed in /result;
• trdl_channels.yaml (the path is set by git_trdl_channels_path): the groups list, where each group has a name and channels (name and version of each channel).

Signatures are not stored by the plugin: they are the PGP signatures embedded in Git objects. For an annotated tag, the tag signature is verified; for a lightweight tag, the signature of the commit it points to. The signatures are checked against the trusted public keys from the plugin configuration.

Setup

1. Enable the secrets engine:

   d8 stronghold secrets enable -path=trdl-myapp trdl

2. Configure the plugin: the Git repository, the S3 storage for publishing, and the required number of verified commit signatures:

   d8 stronghold write trdl-myapp/configure git_repo_url="https://git.example.com/org/myapp.git" required_number_of_verified_signatures_on_commit=2 s3_endpoint="https://s3.example.com" s3_region="ru-central1" s3_bucket_name="myapp-tuf" s3_access_key_id="<S3_ACCESS_KEY_ID>" s3_secret_access_key="<S3_SECRET_ACCESS_KEY>"

   Where <S3_ACCESS_KEY_ID> and <S3_SECRET_ACCESS_KEY> are the access key ID and the secret access key of the S3 storage.

   Required parameters:

   Parameter	Description
   git_repo_url	Git repository URL.
   required_number_of_verified_signatures_on_commit	Required number of verified commit signatures.
   s3_endpoint, s3_region, s3_bucket_name	S3 storage endpoint, region, and bucket name.
   s3_access_key_id, s3_secret_access_key	S3 storage access credentials.

   Optional parameters:

   Parameter	Description
   git_trdl_path	Path to the release configuration file in the repository. Defaults to trdl.yaml.
   git_trdl_channels_path	Path to the channel configuration file. Defaults to trdl_channels.yaml.
   git_trdl_channels_branch	Separate Git branch for the channel configuration file.
   initial_last_published_git_commit	Initial last successfully published commit.
   buildx_driver, buildx_driver_opts	buildx driver for builds (docker-container by default, or kubernetes) and its options.
   buildkitd_address	Address of a running buildkitd (unix://, tcp://, docker-container://, or kube-pod://).
   buildkitd_driver, buildkitd_driver_opts	Ephemeral buildkitd per build (for example, kubernetes) and its options.

   Build secrets are sent to the buildkitd daemon. A tcp:// channel is neither encrypted nor authenticated, so you are responsible for securing the channel and isolating the daemon.

3. Add trusted PGP public keys whose signatures count toward the quorum:

   d8 stronghold write trdl-myapp/configure/trusted_pgp_public_key name="developer-1" public_key=@developer-1.asc

   To list the added keys:

   d8 stronghold list trdl-myapp/configure/trusted_pgp_public_key

4. If the repository is private, configure Git credentials:

   d8 stronghold write trdl-myapp/configure/git_credential username="trdl-bot" password="<GIT_ACCESS_TOKEN>"

   Where <GIT_ACCESS_TOKEN> is the access token of the trdl-bot user in the Git server.

5. If needed, add build secrets available while building artifacts:

   d8 stronghold write trdl-myapp/configure/build/secrets id="npm-token" data="<SECRET_VALUE>"

   Where <SECRET_VALUE> is the value of the build secret.

6. If needed, configure the task manager:

   d8 stronghold write trdl-myapp/task/configure task_timeout=30m task_history_limit=10

Artifact signing

• The public part of the PGP key the plugin uses to sign release artifacts is available at configure/pgp_signing_key:

  d8 stronghold read trdl-myapp/configure/pgp_signing_key

  The signing key is generated automatically on first use (RSA, stored in the plugin storage). A read of configure/pgp_signing_key returns the public part in the public_key field. A delete of this path removes the current key; a new one is generated on demand.

• To sign macOS builds, set the certificate and Notary parameters in configure/build/mac_signing_identity (data, password, notary_issuer, notary_key, notary_key_id).

• To sign ELF binaries via Delivery Kit, set the certificate and private key in configure/delivery_kit_elf_signing. The key can be passed in base64 or as a hashivault://<KEY_NAME> reference to a Transit secrets engine key; in that case, set the vault_* parameters.

Usage

1. Perform a release for a signed Git tag:

   d8 stronghold write trdl-myapp/release git_tag="v1.2.3"

   The plugin verifies the signatures, then builds and publishes the artifacts. The operation is asynchronous: the response contains a task ID.

   The response contains the task UUID in the task_uuid field.

2. Publish update channels from trdl_channels.yaml:

   d8 stronghold write -force trdl-myapp/publish

3. Track tasks:

   d8 stronghold read trdl-myapp/task
   d8 stronghold read trdl-myapp/task/<TASK_UUID>
   d8 stronghold read trdl-myapp/task/<TASK_UUID>/log

   Where <TASK_UUID> is the task ID from the task list.

   To cancel a running task:

   d8 stronghold write -force trdl-myapp/task/<TASK_UUID>/cancel

The last published commit is stored at configure/last_published_git_commit; you can read or delete it.

For the full list of endpoints and parameters, see the secrets engines API reference.