# Release process

## Preparing release

_TBD_

## Trusting TrueCloudLab code signing CA certificate

Verifying signatures (and signing) TrueCloudLab packages requires adding
[TrueCloudLab Code Signing CA](ca.cert) to the list of trusted roots.

On Linux this can be done by appending [release/ca.cert](ca.cert) to one of:

- `/etc/pki/ca-trust/extracted/pem/objsign-ca-bundle.pem`: compatible with
  [update-ca-trust] and originally proposed in [.NET design docs]
- `…/dotnet/sdk/X.Y.ZZZ/trustedroots/codesignctl.pem`: [fallback] codesigning certificate trust list for .NET

[update-ca-trust]: https://www.linux.org/docs/man8/update-ca-trust.html
[.NET design docs]: https://github.com/dotnet/designs/blob/main/accepted/2021/signed-package-verification/re-enable-signed-package-verification-technical.md#linux
[fallback]: https://github.com/dotnet/sdk/blob/11150c0ec9020625308edeec555a8b78dbfb2aa5/src/Layout/redist/trustedroots/README.md

## Signing Nuget packages

Repository maintainer places `maintainer.cert` and `maintainer.key` (see below
regarding obtaining these files) into `release/` directory and then
executes:

```console
$ make build sign
```

## Uploading packages to Nuget registry

**IMPORTANT: the following steps upload all `*.nupkg` files located under
`src/`. Maintainer MUST make sure that no unnecessary package versions will be
uploaded to the registry.**

Configure registry credentials (once per machine):

```console
$ make nuget-registry NUGET_REGISTRY_USER=username NUGET_REGISTRY_PASSWORD=token
```

Publish all locally built packages (implicitly clear existing `*.nupkg` and
rebuild current version only):

```console
$ make clean build sign publish
```


## Obtaining release signing certificate

Repository maintainer owns and keeps safe the release signing key
(`maintainer.key`). Private key should never leave maintainer's machine and
should be considered a highly sensitive secret.

- Generating new maintainer key and the corresponding CSR:

  ```console
  $ make maintainer.csr
  ...lines skipped...
  Enter PEM pass phrase:
  Verifying - Enter PEM pass phrase:
  -----
  IMPORTANT: Keep maintainer.key private!

  Certificate signing request is ready.
  Send maintainer.csr to CA administrator to obtain the certificate.
  ```

  Resulting CSR (`maintainer.csr`) does not contain any sensitive
  cryptographic material and may be passed to CA administrator through regular
  communication channels.

- CA administrator then issues the certificate (`make maintainer.cert`) and
  sends it back to the maintainer to be used in combination with
  `maintainer.key`

This procedure should be repeated once per machine per `maintainer.cert`
lifetime (1 year) - typically just once per year since we expect the
maintainer to use only a single computer to sign releases.