{"id":18822006,"url":"https://github.com/notaryproject/notation-hashicorp-vault","last_synced_at":"2025-07-20T06:33:12.260Z","repository":{"id":166498905,"uuid":"639326267","full_name":"notaryproject/notation-hashicorp-vault","owner":"notaryproject","description":"HashiCorp Vault provider for Notation","archived":false,"fork":false,"pushed_at":"2025-02-26T22:17:49.000Z","size":164,"stargazers_count":7,"open_issues_count":9,"forks_count":7,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-14T01:07:02.096Z","etag":null,"topics":["cncf","harshicorp","kms","notation","plugin","sign","vault"],"latest_commit_sha":null,"homepage":"https://notaryproject.dev/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/notaryproject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-11T08:39:50.000Z","updated_at":"2024-08-23T09:42:32.000Z","dependencies_parsed_at":"2024-06-21T20:23:13.891Z","dependency_job_id":"79055ab1-f10f-453b-b1ff-abe0a8d36bdb","html_url":"https://github.com/notaryproject/notation-hashicorp-vault","commit_stats":null,"previous_names":["notaryproject/notation-hashicorp-vault"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/notaryproject/notation-hashicorp-vault","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notaryproject%2Fnotation-hashicorp-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notaryproject%2Fnotation-hashicorp-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notaryproject%2Fnotation-hashicorp-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notaryproject%2Fnotation-hashicorp-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/notaryproject","download_url":"https://codeload.github.com/notaryproject/notation-hashicorp-vault/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notaryproject%2Fnotation-hashicorp-vault/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266076350,"owners_count":23872741,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cncf","harshicorp","kms","notation","plugin","sign","vault"],"created_at":"2024-11-08T00:47:03.245Z","updated_at":"2025-07-20T06:33:12.240Z","avatar_url":"https://github.com/notaryproject.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HashiCorp Vault plugin for Notation\n\nThis repository contains the implementation of the HashiCorp Vault signing plugin for [Notation](https://notaryproject.dev/). This project is still in early development status.\n\n\u003e **Note** The Notary Project documentation is available [here](https://notaryproject.dev/docs/). You can also find the Notary Project [README](https://github.com/notaryproject/.github/blob/main/README.md) to learn about the overall Notary Project.\n\n## Quick start\n\nThis document demonstrates how to sign and verify an OCI artifact with HashiCorp Vault plugin for Notation. \n\n## Setup\n\n1. There are two binaries in the release: `key-helper` and `notation-hc-vault`.\n2. Install the `notation-hc-vault` plugin to the notation path specified by [notation plugin spec](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#installation). On unix, the path is `$XDG_CONFIG_HOME/notation/plugins/hc-vault/notation-hc-vault`.\n3. `key-helper` is a standalone helper CLI used to configure Hashicorp Vault.\n\n## Install and Configure Hashicorp Vault Server\n1. [Install Hashicorp Vault](https://developer.hashicorp.com/vault/downloads)\n2. Create a Vault config file under your work directory. A minimal working example is shown below, more details about config can be found [here](https://developer.hashicorp.com/vault/tutorials/operations/configure-vault#configuration-files):\n    ```bash\n    $ cat \u003e vault-server.hcl \u003c\u003cEOF\n    disable_mlock = true\n    ui            = true\n\n    listener \"tcp\" {\n    address     = \"127.0.0.1:8200\"\n    tls_disable = \"true\"\n    }\n\n    storage \"raft\" {\n    path = \"/tmp/vault-data\"\n    }\n    EOF\n    ```\n3. Start a prod server \n    ```bash \n    vault server -config vault-server.hcl\n    ```   \n4. At this point, open `127.0.0.1:8200` in your browser to see the webpage of your Hashicorp Vault server.\n5. Initialize Vault (this is a one-time step, you do not need to do this step in the future). In this example, the root key is split into 3 key shares, and any two keys of the three will be sufficient to unseal Vault, [see details](https://developer.hashicorp.com/vault/docs/concepts/seal).\n    ![](./docs/root_keys.png)\n    ![](./docs/download_keys.png)\n    \n    \u003e **IMPORTANT** Remember to hit the `Download Keys` button before going forward. Both keys and the initial root token are downloaded. They are required to unseal Vault and sign in.\n    \n    Unseal Vault \u003cbr\u003e\n    Enter two of the three keys generated previously to unseal Vault.\n    ![](./docs/unseal_vault.png)\n    \n    Sign in \u003cbr\u003e\n    For test purpose, enter the root token in `Token`\n    ![](./docs/sign_in.png)\n    \n    By now, the Hashicorp Vault production server is ready to be used.\n    \n    Note: when Vault process is stopped/closed, Vault will be sealed again.\n6. Configure Vault client to talk to your server:\n    ```bash\n    export VAULT_ADDR='http://127.0.0.1:8200'\n    ```\n    Set the `VAULT_TOKEN` environment variable value to the downloaded Root Token value.\n    ```bash\n    export VAULT_TOKEN=\"hvs.**************\"\n    ```\n    Note: Do not use the root token for production usage of Notation and Vault.\n7. If this is your first time setting up Hashicorp vault, you need to enable the Transit Secrets Engine and the KV Secrets Engine. (You could do this in Vault's web UI as well.)\n    ```bash\n    vault secrets enable transit\n    vault secrets enable -path=secret kv-v2\n    ```\n    (Step 7 is a one-time setup, you do not need this step in the future.)\n\n## Generate Private Key and Certificate Chain\nNow you have an empty Hashicorp Vault. Let's put something in it.\n\nA user can bring their own private key and certificate. As a quick start, this tutorial is using openssl to generate a private key and a certificate chain of length 2.\n1. Generate CA root certificate\n   ```bash\n   openssl genrsa -out ca.key 2048\n   \n   openssl req -new -x509 -days 365 -key ca.key -subj \"/O=Notation/CN=Notation Root CA\" -out ca.crt -addext \"keyUsage=critical,keyCertSign\"\n   ```\n2. Generate private key and leaf certificate\n   ```bash\n   openssl genrsa -out leaf.key 2048\n   \n   openssl req -newkey rsa:2048 -nodes -keyout leaf.key -subj \"/CN=Notation.leaf\" -out leaf.csr\n   \n   openssl x509 -req -extfile \u003c(printf \"basicConstraints=critical,CA:FALSE\\nkeyUsage=critical,digitalSignature\") -days 365 -in leaf.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out leaf.crt\n   ```\n   (`leaf.key` is the private key used to sign)\n3. Create the certificate chain in a pem file (CA certificate after leaf certificate)\n   ```bash\n   cat leaf.crt ca.crt \u003e certificate_chain.pem\n   ```\n4. Import the certificate chain and private key into the Hashicorp Vault using `key-helper`\n    ```bash\n    ./key-helper import --cert_path \"{path-to}/certificate_chain.pem\" --key_name \"myNotationTestKey\" --key_path \"{path-to}/leaf.key\"\n    ```\n    `leaf.key` is saved in the Transit Secrets Engine, and `certificate_chain.pem` is saved in the KV Secrets Engine\n\n## Sign an artifact using Notation\nNow we've done all the configurations. Let's sign an artifact using Notation. (If you haven't done so, download notation from [here](https://github.com/notaryproject/notation/releases).)\n```bash\n./notation sign --id \"myNotationTestKey\" --plugin \"hc-vault\" \u003cmyRegistry\u003e/\u003cmyRepo\u003e@\u003cdigest\u003e\n```\nNote: the `--id` should be identical to your `--key_name` in the previous step.\n\n## Verify the artifact using Notation\n1. Configure trust store.\n    ```bash\n    ./notation cert add -t ca -s myStore \"{path-to-ca-cert}/ca.crt\"\n    ```\n    where `ca.crt` is the CA root cert generated in the previous step.\n2. Configure the trust policy.\n    ```bash \n    cat \u003c\u003cEOF \u003e ./trustpolicy.json\n    {\n        \"version\": \"1.0\",\n        \"trustPolicies\": [\n            {\n                \"name\": \"hc-vault-policy\",\n                \"registryScopes\": [ \"*\" ],\n                \"signatureVerification\": {\n                    \"level\" : \"strict\" \n                },\n                \"trustStores\": [ \"ca:myStore\" ],\n                \"trustedIdentities\": [\n                    \"*\"\n                ]\n            }\n        ]\n    }\n    EOF\n    ```\n    ```bash\n    ./notation policy import ./trustpolicy.json\n    ```\n3. Verify the artifact\n    ```bash\n    ./notation verify \u003cmyRegistry\u003e/\u003cmyRepo\u003e@\u003cdigest\u003e -v\n    ```\n\n## hc-vault plugin options (passed as `notation sign (...)` command options\n|Option name    |Usage                                   |Description                                                           |\n|---------------|----------------------------------------|-----------------------------------------------------------------------|\n|id             |`--id \u003ckeyName\u003e`                        |(required) default name for transit key and kv key                     |\n|kvName         |`--plugin-config kvName=\u003cname\u003e`         |(default: `secret`) custom name for key-value(KVv2) secret engine mount|\n|transitName    |`--plugin-config transitName=\u003cname\u003e`    |(default: `transit`) custom name for transit secret engine mount       |\n|transitKeyName |`--plugin-config transitKeyName=\u003cname\u003e` |custom name for transit key (overrides `id`)                           |\n\n## key-helper import options\nnotation-hashicorp-vault % ./cmd/key-helper/key-helper import --help\nimport private key to Vault Transit secrets engine and certificates to Vault KV secrets engine\n\nUsage:\n  key-helper import --key_path \u003cpath_to_private key file\u003e --cert_path \u003cpath_to__certificate_chain_file\u003e --key_name \u003cHashiCorp_Vault_key_name\u003e [flags]\n\nFlags:\n      --cert_path string          absolute path to the certificate chain file\n  -h, --help                      help for import\n      --key_name string           name of the key\n      --key_path string           absolute path to the private key file\n      --kv_name string            name of the KVv2 secret engine mount (default \"secret\")\n      --transit_key_name string   name of the key in transit engine\n      --transit_name string       name of the transit engine mount (default \"transit\")\nnotation-hashicorp-vault %\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotaryproject%2Fnotation-hashicorp-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnotaryproject%2Fnotation-hashicorp-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotaryproject%2Fnotation-hashicorp-vault/lists"}