Digital signatures¶

All the qualification documents we send to the assessor have to be digitally signed by the responsible parties, to attest they were reviewed and to prevent accidental changes to the documents (which would require the assessor to review the documents again).

Signing documents¶

We developed a small wrapper around the “cosign” tool to make it easy to sign our qualification documents.

To sign a document, you need to run this command inside of ferrocene/ferrocene:

./x sign $path

For example:

./x sign ferrocene/doc/evaluation-report

Running the command will:

Build the document locally to calculate its document ID and the hash of the generated files.
Download the expected version of cosign, if it was not downloaded before.
Invoke cosign to digitally sign the document metadata gathered earlier.

When cosign is invoked, you will need to:

Agree to your company email address being published in the Rektor transparency log.
In the browser window that opened, select “Microsoft”.
Authenticate with your company email credentials.

This will generate an ephemeral code signing certificate for your company email address and sign the contents of the document with it. Once that’s done, commit the new files generated by the signing tool.

Verifying signatures¶

You can verify that all the present signatures are still valid with this command:

./x test ferrocene-check-document-signatures

Note

When running the command locally, you might get signature verification errors if some of the cached pages built locally are out of date. To fix them, remove the build/ directory.

It is also possible to inspect the ephemeral code signing certificate of a signature with this command:

jq .cert $path/signature/$role.cosign-bundle -r | base64 -d | openssl x509 -text