Skip to content

Configuration file spec #76

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SteveLasker merged 10 commits into from
Sep 14, 2021
Merged

Configuration file spec #76

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
1db7a79
Notary v2 prototye process
Jun 20, 2020
bd6054b
Notary v2 prototye process
Jun 22, 2020
f1ea87a
Notary v2 prototye process updates
Jun 24, 2020
531a109
Rev of sketch, w/oci-index v3-index.config
Jun 25, 2020
9b64000
merge
SteveLasker Aug 25, 2021
321db15
Configuration file spec
SteveLasker Aug 27, 2021
0838141
move under the specs folder
SteveLasker Aug 27, 2021
fe46a2e
move under the specs folder
SteveLasker Aug 27, 2021
3f91b78
Incorporate feedback on table layout and naming
SteveLasker Aug 30, 2021
894e6c9
Updates to reflect the current release
SteveLasker Sep 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions specs/notation-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Notation Configuration

To enable persisted configuration, simplifying the execution of the `notation` cli, the following configuration file will be available

> Note: there will be a policy based configuration that will come at a later point.

## Location

The default location and file will be stored at: `~/.notation/config.json`. The `notation` cli and libraries will support alternate locations through a `config-location` parameters.

> TODO: Add Windows and Mac locations

## Properties

Property | Type | Value
------ | ------ | ---
`verificationCerts.certs`|_array_|collection of name/value pairs for a collection of public certs that are used for verification. These may be replaced with a future policy configuration.
`cert.name`|_string_|a named reference to the certificate
`cert.path`|_string_|a location by which the certificate can be found by the notation cli or notation libraries
`signing-keys.keys`|_array_|a collection of name/value pairs of signing keys.
`key.name`|_string_|a named reference to the key
`key.path`|_string_|a location by which the key can be found by the notation cli or notation libraries
`signing-keys.default`|_string_|the signing key to be used when `notation sign` is called without `--name`
`insecureRegistries`|_array_|a list of registries that may be used without https
Copy link
Contributor

@priteshbandi priteshbandi Sep 1, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How is insecureRegistries related to notary?

Copy link
Contributor Author

@SteveLasker SteveLasker Sep 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

notation pushes and pulls content to a registry using the oras-go libraries. insecureRegistires is a list of registries enables the flow, as an exception to the normal HTTPS required flag.
It's not just for local instances of distribution. Many IoT scenarios run non https scenarios.


## Samples

`~/.notary/notation-config.json`

```json
{
"verificationCerts": {
"certs": [
{
"name": "wabbit-networks.io",
"path": "~/./notary/keys/wabbit-networks.crt"
},
{
"name": "import.acme-rockets.io",
"path": "~/./notary/keys/import-acme-rockets.crt"
}
]
},
Comment on lines +32 to +43
Copy link
Contributor

@shizhMSFT shizhMSFT Aug 30, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we need certs inside of verificationCerts? It is redundant.

Copy link
Contributor Author

@SteveLasker SteveLasker Aug 30, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was trying to align with keys which has default nested, so it needed keys.
Suggestions?

Copy link
Contributor Author

@SteveLasker SteveLasker Aug 30, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Leaving for this PR, and lets address how we want to handle verificationCerts and signingKeys
Do we want to pull default out to a root node?

Copy link
Contributor

@sajayantony sajayantony Aug 31, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@SteveLasker - Moving this into the notary location exposes the notation CLI to need ACLs and policise that are present with notaryV1. My recommendatiaon is to have this under .notation for now and open an issue to unify the config location with notaryv1 if that is the requirement.
/cc @gokarnm

Copy link
Contributor

@priteshbandi priteshbandi Sep 1, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • How about naming it verification-identities and changing structure to something like this?
"verification-identities": [
    {
        "name": "wabbit-networks.io",
        "certificate-path": "~/./notary/keys/wabbit-networks.crt"
    },
    {
        "name": "import.acme-rockets.io",
        "certificate-path": "~/./notary/keys/import-acme-rockets.crt"
    }
]

If we are planning to support only referencing(using path) not inlining of certificate then we can rename certificate-path to certificate.

  • Also, are we thinking of supporting truststore and trustpolicy evaluation using this cli or its just that signature leads to a trusted certificate? If its former then we might not need verificationCerts instead we can refer trusstore+trustpolicy.

Copy link
Contributor

@gokarnm gokarnm Sep 2, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@SteveLasker - Moving this into the notary location exposes the notation CLI to need ACLs and policise that are present with notaryV1. My recommendatiaon is to have this under .notation for now and open an issue to unify the config location with notaryv1 if that is the requirement.
/cc @gokarnm

@sajayantony @SteveLasker would like to understand better if there is a requirement, and the motivation for unifying config with notary V1.

Copy link
Contributor Author

@SteveLasker SteveLasker Sep 2, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is a requirement, and the motivation for unifying config with notary V1.

It was more about reducing folder sprawl. I'm trying to avoid end users having to "feel the pain" of multiple folders being created as a result of using v1 and v2.
We don't have much usage of notary v1, so it's a minimal issue.
It's not the most pressing issue, so you could also argue, if most users don't have notary v1, is it really folder sprawl as they'll only have a single folder, "./notation".
I'll update to use notation and not be something to take more time for us to think about

Copy link
Contributor Author

@SteveLasker SteveLasker Sep 3, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

are we thinking of supporting truststore and trustpolicy evaluation

Yes, we should incorporate truststore policy. However, suggesting we add that as we iterate the details of the trust store policy. This will document the current state, so we can release a notation cli that we can iterate with.
As we complete the truststore policy design and implementation, we can update this config spec.

"signingKeys": {
"default": "wabbit-networks.io",
"keys": [
{
"name": "wabbit-networks.io",
"path": "~/./notary/keys/wabbit-networks.key"
},
{
"name": "import.acme-rockets.io",
"path": "~/./notary/keys/import-acme-rockets.key"
}
]
},
Comment on lines +44 to +56
Copy link
Contributor

@priteshbandi priteshbandi Sep 1, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Along with signingKey(private key) we will need signing certificate and certificate chain as signing certificate and certchain will be embedded in signature envelope.
  • Also, how about using default name for default identity? Although this works better with INI format.
"signing-identites": [
  {
      "name": "default",
      "signing-certificate": "~/./notary/keys/wabbit-networks.crt",
      "signing-certificate-chain": ""~/./notary/keys/wabbit-networks-chain.crt",
      "private-key": "~/./notary/keys/wabbit-networks.key"
  },
  {
      "name": "import-acme-rockets",
      "signing-certificate": "~/./notary/keys/import-acme-rockets.crt",
      "signing-certificate-chain": ""~/./notary/keys/import-acme-rockets-chain.crt",
      "private-key": "~/./notary/keys/import-acme-rockets.key"
  }
]

Copy link
Contributor

@gokarnm gokarnm Sep 2, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 on requiring signing certificate in addition to private key.

Copy link
Contributor

@priteshbandi priteshbandi Sep 10, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

opened issue: #89

"insecureRegistries": [
"registry.wabbit-networks.io"
]
}
```