Spec to configure & persist signature envelope format for signing.

[FeynmanZhou]

As Notation will support both JWS and COSE signing envelop in RC.1, users need to add a tag --envelope-type cose using the notation sign to sign artifacts each time, see this step for details.

Is it more convenient to provide a system (global) configuration option to configure the signing envelope? In this way, users don't need to manually specify the signing envelope each time.

This suggestion was proposed by @SteveLasker initially. I think it is convenient for users who want to specify a commonly used signing envelope.

[JeyJeyGao]

I will work on this task.

[JeyJeyGao]

Related PR: https://github.com/notaryproject/notation/pull/329 https://github.com/notaryproject/notation-go/pull/126

The PRs will be merged to cose branch.

[dtzar]

Need to address plugin use case handling. @priteshbandi will copy over comment from PR here, per community call today.

[priteshbandi]

Reopening as spec work is pending and assigning it to @rgnote.

• [x] Define how default sig format will work
• [x] and how will it will be influenced by plugin

[rgnote]

Problem

Notation is designed in such a way that signing and verification is signature envelope format agnostic. That means, Notation can transparently work with multiple signature envelope formats at a time. Today, Notation supports two signature envelope formats.

1. JWS
2. COSE

Users can select the envelope format by using "--envelope-type" CLI switch. The default envelope format is JWS i.e. if no option is provided using --envelope-type switch, then notation uses JWS.

This poses two problems:

1. In the case where a user wants to use COSE as their default signature format, they have to provide "--envelope-type" switch in each and every "notation sign" command manually and it can be annoying.
2. Signature Envelope Generator plugins may implement only a select envelope formats and not others. That means, if a user tries to use a format with a plugin that is not implementing the format, then the signing fails and notation needs to handle that error gracefully.

Solution

To solve the first problem, Notation will support an option for envelope type in it's configuration file config.json. The field name would be envelopeType and it will support "jws" and "cose" values to begin with.

The order of precedence for the chosen envelope type for signing follows as below

1. Envelope type provided using the CLI switch "--envelope-type"
2. Envelope type provided in config.json using envelopeType key
3. The default envelope type i.e. jws

To solve the second problem, the plugin's signature envelope generator interface will support signatureEnvelopeType in the request and throw an error if the requested envelope type is not supported by the plugin, which will passed to the notation user. This functionality is already specified in plugin extensibility specification https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#generate-envelope