Added signing and verification workflows #122

priteshbandi · 2022-01-11T23:15:33Z

Summary

Added signing and verification workflows
Added detailed steps for signature verification
- Added certificate requirements
- Added certificate revocation

Important call-outs

In verification, we are evaluating timestamp(if present) irrespective of whether the signing certificate is expired or not.
- IMO if a user has added a timestamp to the signature then they want the verification system to use that timestamp.
- Also, always evaluating timestamp(if present) avoid modes. e.g., if the timestamp is present but it's corrupted then the verification will continue to pass until the signing certificate hasn't expired but when the signing certificate expires, verification will start failing.
During signature verification, we don’t support multiple certificate chains leading to multiple roots. If multiple certificate chains are leading to trusted roots, Notary v2 randomly picks one(usually, the one which is encountered first).
Notary v2 doesn’t support building certificate chain by retrieving certificates from locations specified in the authority information access extension (AIA).

HackmdDoc: https://hackmd.io/@pritesh/signing-verfication-workflow

Signed-off-by: Pritesh Bandi [email protected]

signing-and-verification-workflow.md

SteveLasker · 2022-01-18T23:54:25Z

signing-and-verification-workflow.md

+
+1. **Generate signature:** Using notation CLI or any other compliant signing tool, sign the OCI artifact. The signing tool should follow the following guideline.
+    1. Verify that the signing certificate is valid and satisfies [certificate requirements](./signature-specification.md#certificate-requirements).
+    1. Verify that the signing algorithm satisfies [algorithm requirements](./signature-specification.md#signature-algorithm-requirements).


The signing algorithm MUST implement the Notary v2 algorithm requirements.

SteveLasker · 2022-01-18T23:58:12Z

signing-and-verification-workflow.md

+    1. Generate signature.
+        1. Generate signature using signature formats specified in [supported signature envelopes](./signature-specification.md#supported-signature-envelopes).
+        1. Obtain an [RFC-3161](https://datatracker.ietf.org/doc/html/rfc3161.html) compliant timestamp for the signature generated in the previous step. This step is optional but recommended.
+            1. Verify that the timestamp signing certificate satisfies [certificate requirements](./signature-specification.md#certificate-requirements).


If provided, the timestamp signing certificate MUST satisfy certificate requirements.

SteveLasker · 2022-01-18T23:58:47Z

signing-and-verification-workflow.md

+        1. Generate signature using signature formats specified in [supported signature envelopes](./signature-specification.md#supported-signature-envelopes).
+        1. Obtain an [RFC-3161](https://datatracker.ietf.org/doc/html/rfc3161.html) compliant timestamp for the signature generated in the previous step. This step is optional but recommended.
+            1. Verify that the timestamp signing certificate satisfies [certificate requirements](./signature-specification.md#certificate-requirements).
+            1. Verify that the timestamp signing algorithm satisfies [algorithm requirements](./signature-specification.md#signature-algorithm-requirements).


The timestamp signing algorithm MUST satisfy the Notary v2 algorithm requirements.

signing-and-verification-workflow.md

trust-store-trust-policy-specification.md

SteveLasker · 2022-01-19T20:53:41Z

trust-store-trust-policy-specification.md


-![uml diagram showing signature evaluation](./media/trust-store-trust-policy-evaluation.svg)


Visuals are always helpful. Perhaps a slightly simplified version, but it would be great to bring a simplified version back.

Yep, visuals are helpful but in this case it was becoming complicated so had to remove. I can try to create simplified version of it.

signing-and-verification-workflow.md

SteveLasker

Thanks @priteshbandi for all the details. Mostly nits, with a bit more details in some places.

signing-and-verification-workflow.md

trust-store-trust-policy-specification.md

SteveLasker · 2022-01-19T21:22:47Z

trust-store-trust-policy-specification.md

+- **Delta CRLs:** Contains only certificates that have changed status since the last base CRL was published. Delta CRLs are signed by the certificate issuing CAs.
+- **Indirect CRLs:** Special Case in which BaseCRLs and Delta CRLs are not signed by the certificate issuing CAs, instead they are signed with a completely different certificate.
+
+Notary v2 MUST support BaseCRLs and Delta CRLs. Notary v2 MAY support Indirect CRLs. Notary v2 supports only HTTP CRL URLs.


Just a note:
There are lots of ideas around how to improve the CRL models, but I'll leave those for later and we'll lean into the existing infra and work to improve it as incremental work.

trust-store-trust-policy-specification.md

signature-specification.md

signing-and-verification-workflow.md

trust-store-trust-policy-specification.md

shizhMSFT · 2022-01-30T08:08:34Z

signing-and-verification-workflow.md

+        1. Validate the signature envelope using trust-store and trust-policy as mentioned in [signature evaluation](./trust-store-trust-policy-specification.md#signature-evaluation) section.
+        1. If signature validation fails, skip the below steps and move to the next signature artifact descriptor(step 2.1). If all signature artifact manifests have already been processed, fail the signature verification and exit.
+        1. If signature validation succeeds, compare the digest derived from the given OCI artifact reference with the signed digest present in the signature envelope's payload. If digests are equal, signature verification is considered successful. Otherwise, move to the next signature artifact descriptor(step 2.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit.
+1. **Get OCI artifact:** Using the verified digest, download the OCI artifact. This step is not in the purview of Notary v2.


The signed payload of a signature contains the descriptor of the target OCI artifact, which includes digest, size, and media type.

Instead of using the verified digest, we should say using the verified descriptor.

Have mentioned digest instead of descriptor because we haven't verified the descriptor inside the signature envelope with the actual OCI artifact's descriptor (the one stored in the registry).

signing-and-verification-workflow.md

trust-store-trust-policy-specification.md

sudo-bmitch

We may want to make a clear separation between the policies that will likely be implemented in notation, from the process to verify a signature what would also be implemented in other tools that want to verify a notary signature with their own policy checks.

sudo-bmitch · 2022-02-01T16:41:05Z

trust-store-trust-policy-specification.md

+
+If the certificate revocation trust-store setting is set to `skip`, skip the below steps. Otherwise, check for revocation status for certificate and certificate chain.
+
+1. If the revocation status of any of the certificates cannot be determined (revocation unavailable) and `signingIdentityRevocation` is set to either `enforceWithFailClose` or `warn` then log a warning and skip the below steps. Otherwise, fail the signature validation and exit.


Should this be enforceWithFailOpen?

No, it should be enforceWithFailClose,

enforceWithFailOpen: This means implementation MUST perform validation and if validation fails because the endpoint is not reachable, the implementation MUST throw an error and MUST fail the validation.

enforceWithFailClose: This means implementation MUST perform validation and if validation fails because the endpoint is not reachable, the implementation MUST log an error and MUST NOT fail the validation.

Perhaps I'm misunderstanding, or our usage of the terminology is confusing here. The traditional usage of "fail open" means that you only throw a warning but do not stop workflows from running when the security check is unable to be performed. It sounds like we're saying "fail open" means to fail the validation which would block images from being deployed in the common use case.

Yep, you are correct our usage of terminology is incorrect. Recently I've been reading a lot about circuit breakers where open state represents failure scenario and close state represents business as usual. Perhaps I got confused and interpolated that with fail open and fail close of networking.
Have fixed it in the latest commit.

gokarnm · 2022-02-02T00:27:18Z

LGTM!

- Added detailed steps for signature verification - Added certificate requirements Co-authored-by: Milind Gokarn <[email protected]> Signed-off-by: Pritesh Bandi <[email protected]>

Signed-off-by: Pritesh Bandi <[email protected]>

SteveLasker

Overall LGTM, with a bit of redundant text on lines 237-238 and 245-247.

signature-specification.md

SteveLasker

A few more comments on trust-store-trust-policy-specification.md

SteveLasker · 2022-02-02T21:44:06Z

trust-store-trust-policy-specification.md

+If the certificate revocation trust-store setting is set to `skip`, skip the below steps. Otherwise, check for revocation status for certificate and certificate chain.
+
+1. If the revocation status of any of the certificates cannot be determined (revocation unavailable) and `signingIdentityRevocation` is set to either `enforceWithFailOpen` or `warn` then log a warning and skip the below steps. Otherwise, fail the signature validation and exit.
+1. If any of the certificates are revoked and `signingIdentityRevocation` is set to either `enforceWithFailOpen` or `enforceWithFailClose` then fail signature validation and exit else log a warning.


Am I reading this as enforceWithFailOpen or enforceWithFailClose have the same result?

Yep, when the notary can identify the revocation status of a certificate enforceWithFailOpen or enforceWithFailClose will have the same result. The behavior differs when notary is unable to determine certificate revocation status.

trust-store-trust-policy-specification.md

SteveLasker · 2022-02-02T21:49:45Z

trust-store-trust-policy-specification.md

+1. Verify the CRL signature.
+1. Verify that the CRL is valid (not expired). A CRL is considered expired if the current date is after the `NextUpdate` field in the CRL.
+1. Look up the certificate’s serial number in the CRL.
+    1. If the certificate’s serial number is listed in the CRL, look for `InvalidityDate`. If the invalidity date is present and timestamp signature is also present then if the invalidity date is before the timestamping date, the certificate is considered revoked. If the invalidity date is not present in CRL, the certificate is considered revoked.


Is this accurate, or complete?

If the invalidity date is present and timestamp signature is also present then if the invalidity date is before the timestamping date, the certificate is considered revoked.

Should this be:

If the invalidity date is present and timestamp signature is also present then if the invalidity date is before the current date and before the timestamping date, the certificate is considered revoked.

I have paraphrased the sentence for better readability.
If CRL has invalidity date and artifact signature is timestamped then compare the invalidity date with the timestamping date. If the invalidity date is before the timestamping date, the certificate is considered revoked.

Basically we are comparing the signature's timestamping date(signing date) with the certificate's effective revocation date.

trust-store-trust-policy-specification.md

Signed-off-by: Pritesh Bandi <[email protected]>

signature-specification.md

SteveLasker

LGTM

This was referenced Jan 12, 2022

Certificate Expiry notaryproject/roadmap#8

Closed

TSA Signature notaryproject/roadmap#10

Closed

CLI Cmds for Configuration notaryproject/roadmap#37

Closed

SteveLasker reviewed Jan 18, 2022

View reviewed changes

signing-and-verification-workflow.md Outdated Show resolved Hide resolved

SteveLasker reviewed Jan 18, 2022

View reviewed changes

signing-and-verification-workflow.md Outdated Show resolved Hide resolved

SteveLasker reviewed Jan 18, 2022

View reviewed changes

signing-and-verification-workflow.md Show resolved Hide resolved

SteveLasker reviewed Jan 18, 2022

View reviewed changes

SteveLasker reviewed Jan 19, 2022

View reviewed changes

signing-and-verification-workflow.md Outdated Show resolved Hide resolved

SteveLasker reviewed Jan 19, 2022

View reviewed changes

trust-store-trust-policy-specification.md Outdated Show resolved Hide resolved

SteveLasker reviewed Jan 19, 2022

View reviewed changes

signing-and-verification-workflow.md Outdated Show resolved Hide resolved

SteveLasker reviewed Jan 19, 2022

View reviewed changes

signing-and-verification-workflow.md Outdated Show resolved Hide resolved

SteveLasker reviewed Jan 19, 2022

View reviewed changes

signing-and-verification-workflow.md Outdated Show resolved Hide resolved

SteveLasker reviewed Jan 19, 2022

View reviewed changes

This was referenced Jan 25, 2022

Signature Verification process notaryproject/roadmap#19

Closed

Matching signatures to trust policy notaryproject/roadmap#20

Closed

gokarnm requested changes Jan 28, 2022

View reviewed changes

shizhMSFT reviewed Jan 30, 2022

View reviewed changes

gokarnm requested changes Feb 1, 2022

View reviewed changes

sudo-bmitch reviewed Feb 1, 2022

View reviewed changes

Pritesh Bandi and others added 2 commits February 1, 2022 22:22

Added signing and verification workflows

33576d5

- Added detailed steps for signature verification - Added certificate requirements Co-authored-by: Milind Gokarn <[email protected]> Signed-off-by: Pritesh Bandi <[email protected]>

Fix defination of fail open and fail close

90371bf

Signed-off-by: Pritesh Bandi <[email protected]>

SteveLasker reviewed Feb 2, 2022

View reviewed changes

signature-specification.md Outdated Show resolved Hide resolved

signature-specification.md Outdated Show resolved Hide resolved

SteveLasker reviewed Feb 2, 2022

View reviewed changes

some more minor changes

2ab406b

Signed-off-by: Pritesh Bandi <[email protected]>

briankr-ms reviewed Feb 3, 2022

View reviewed changes

signature-specification.md Show resolved Hide resolved

priteshbandi mentioned this pull request Feb 3, 2022

id-kp-codeSigning EKU restriction for signing certificate. #130

Closed

SteveLasker approved these changes Feb 3, 2022

View reviewed changes

SteveLasker merged commit a93eec8 into notaryproject:main Feb 3, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added signing and verification workflows #122

Added signing and verification workflows #122

priteshbandi commented Jan 11, 2022 •

edited

Loading

SteveLasker Jan 18, 2022

SteveLasker Jan 18, 2022

SteveLasker Jan 18, 2022

SteveLasker Jan 19, 2022

priteshbandi Jan 20, 2022

SteveLasker left a comment

SteveLasker Jan 19, 2022

shizhMSFT Jan 30, 2022

priteshbandi Jan 31, 2022

sudo-bmitch left a comment

sudo-bmitch Feb 1, 2022

priteshbandi Feb 2, 2022

sudo-bmitch Feb 2, 2022

priteshbandi Feb 2, 2022

gokarnm commented Feb 2, 2022

SteveLasker left a comment

SteveLasker left a comment

SteveLasker Feb 2, 2022

priteshbandi Feb 3, 2022

SteveLasker Feb 2, 2022

priteshbandi Feb 3, 2022 •

edited

Loading

SteveLasker left a comment


		![uml diagram showing signature evaluation](./media/trust-store-trust-policy-evaluation.svg)


		If the certificate revocation trust-store setting is set to `skip`, skip the below steps. Otherwise, check for revocation status for certificate and certificate chain.

		1. If the revocation status of any of the certificates cannot be determined (revocation unavailable) and `signingIdentityRevocation` is set to either `enforceWithFailClose` or `warn` then log a warning and skip the below steps. Otherwise, fail the signature validation and exit.

Added signing and verification workflows #122

Added signing and verification workflows #122

Conversation

priteshbandi commented Jan 11, 2022 • edited Loading

Summary

Important call-outs

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SteveLasker left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sudo-bmitch left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gokarnm commented Feb 2, 2022

SteveLasker left a comment

Choose a reason for hiding this comment

SteveLasker left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

priteshbandi Feb 3, 2022 • edited Loading

Choose a reason for hiding this comment

SteveLasker left a comment

Choose a reason for hiding this comment

priteshbandi commented Jan 11, 2022 •

edited

Loading

priteshbandi Feb 3, 2022 •

edited

Loading