Signing a single file

OpenSSL can create digital signatures using a private key and verify them using the corresponding public key. These same steps can be used to sign the network manifest file as well as any single file artifacts referenced in the manifest.

The recommended algorithm is ES256 using an ECDSA P-256 keypair. EdDSA is a modern alternative, but ES256 is preferred here because it has better support in OPA's runtime verification path.

1. Prerequisites

OpenSSL Version

These commands require OpenSSL, not LibreSSL.

LibreSSL sometimes lacks support for certain signing commands or behaves differently from OpenSSL, so it is recommended to use openssl if you are following this guide.

Check your version:

openssl version

Expected output should look similar to:

OpenSSL 1.1.1x

or

OpenSSL 3.x.x

Recommended versions:

If the output contains:

LibreSSL

install OpenSSL instead.

Required Files

You need:

private.pem
artifact.yaml

private.pem must contain the private key used for signing. And assume artifact.yaml is the file you need to sign which may be a network manifest or a policy rego file or any other artifact that needs to be signed by you.

2. Generate a Key Pair (If You Don’t Already Have One)

If you already have the key pair, you can skip this step.

Generate a private key (ECDSA P-256 for ES256)

openssl ecparam -name prime256v1 -genkey -noout -out private.pem

Extract the public key

openssl pkey -in private.pem -pubout -out public.pem

Result:

private.pem
public.pem

3. Sign the File

Suppose you want to sign:

artifact.yaml

Run:

openssl dgst -sha256 -sign private.pem -out artifact.yaml.sig artifact.yaml

Generated file:

artifact.yaml.sig

4. Files to Publish

When publishing the signed artifact, provide:

artifact.yaml
artifact.yaml.sig

If the signed file is an artifact referenced in the network manifest, the links of the published files should be added to the network manifest at the appropriate section based on the type of artifact that is being signed.

If the signed file is the network manifest itself, it should be added as the manifestUrl in the metadata field of the NFO network registry this manifest is for.

5. Verifying the Signature

Anyone with the public key can verify the file.

Run:

openssl dgst -sha256 -verify public.pem -signature artifact.yaml.sig artifact.yaml

Expected output:

Verified OK

If the file has been modified, verification will fail:

Verification Failure

6. Security Best Practices

✔ Keep private.pem secret ✔ Store private keys securely ✔ Never upload private keys ✔ Rotate keys periodically

Recommended Naming Convention

Common pattern:

file.ext
file.ext.sig

Example:

artifact.yaml
artifact.yaml.sig