notaryproject/notation-go

A collection of libraries for supporting sign and verify OCI artifacts. Based on Notary Project specifications.

Notary Project Specifications

This repository is in active maintenance and contains specifications shared across repositories under Notary Project as well as used by other open source projects and/or vendor tools that want to interoperate with Notary Project tooling.

Please see the Notary Project README file to learn about overall Notary Project.

In this README

• Folder Structure
• Requirements
• Security Documents
• Specifications
• Threat Models
• Community

Folder Structure

Folder Name	Description
media	Media files referenced by documents in this repository
requirements	Requirements for Notary Project
security	Notary Project security related documents and reports
specs	Notary Project specifications
status-updates	This folder is not in active maintenance and contains status updates report for Notary Project
threatmodels	Threat models for repositories under Notary Project

Requirements

File Name	Description
definitions-terms.md	A collection of definitions and terms used within this repository
key-revocation.md	Requirements and proposals for key revocation
keymanagementrequirements.md	Requirements for key management
requirements.md	A collection of requirements and scenarios for Notary Project
scenarios.md	Notary Project signing scenarios
verification-by-reference.md	Requirement of verification by reference

Security Documents

File Name	Description
ADA-notation-security-audit-23.pdf	Security audit report in 2023 covering notation, notation-go, and notation-core-go repositories
ADA-fuzzing-audit-22-23.pdf	Fuzz testing audit in 2023 covering notary, notation-go, and notation-core-go repositories

Specifications

File Name	Description
plugin-extensibility.md	Notation Plugin specification
signature-envelope-cose.md	Notary Project OCI COSE signature envelope
signature-envelope-jws.md	Notary Project OCI JWS signature envelope
signature-specification.md	Notary Project OCI signature specification
signing-and-verification-workflow.md	Notary Project OCI signing and verification workflow
signing-scheme.md	Notary Project signing scheme
trust-store-trust-policy.md	Notary Project Trust Store and Trust Policy

Threat Models

File Name	Description
notation-threatmodel.md	Threat models for Notation CLI

Community

If you have any questions about Notary Project or contributing, do not hesitate to file an issue on relevant repository or contact the Notary Project maintainers and community members via the following channels:

• Join the Notary Project community slack channel
• Join the Community meetings

notation-go's Issues

Implement Semantic Versioning

Notary V2 uses SemVer for plugin versioning. See spec here
At the time of writing this issue, Golang has no standard library support for parsing or comparing SemVer strings. This issue is to track implementing SemVer in Notation if no alternative is available. This issue is blocking using verification plugin minimum version critical attribute in signature verification workflow.

code:

notation-go/verifier/verifier.go

Lines 127 to 128 in 7e391f7

	// TODO verify the plugin's version is equal to or greater than `outcome.SignerInfo.SignedAttributes.HeaderVerificationPluginMinVersion`
	// https://github.com/notaryproject/notation-go/issues/102

Notation plug-in design / notation-go-lib integration

Issue #22 surfaced an interesting question.
When using Notary v2 from a cli, we direct users to the notation repo and output
When using Notary v2 as a library, for use in other clis, how do we enable the notation plug-ins for specific key vault providers?

The current design enables users to install the notation cli and their desired plug-ins.
If someone uses the notation-go-lib to incorporate an SBoM signing solution, or some other integration, should they have to implement all the plug-in redirection?

Can we create an easy experience for developers to reference the notation-go-lib, and still get normal plug-in capabilities?

Release v0.8.0-alpha

Since the library has been renamed to notation-go and there are other breaking changes, we need to have a new release of notary at a minimum to make golang package references work well.

/cc @SteveLasker, @justincormack, @sajayantony

Can the maintainers please respond with a +1 comment once you are in favor of cutting this release.

Add Go lib support (for Buildpacks)

The Cloud Native Buildpacks project is considering adding support for notary v2, potentially in https://github.com/buildpacks/lifecycle when constructing images (either as part of our current phases, or as a new phase, depending on project decisions). As such, we will need Go lib support, in order to utilize it as part of the lifecycle.

Tracking issue for pending feedbacks/Issues in PR5

Tracking issue for multiple comments/issues that were called out in #5 and needs to be resolved.

Issues marked with [Alpha], must to be resolved for alpha release.

Security

• [Alpha] We shouldn't automatically fetch and trust system certificates as user might not trust them for signature verification.
• [Alpha] JWS: We should add validation for list of supported algorithms(to avoid algorithm substitution and signature bypass attacks)
• [Alpha] We should add validation for codesigning certificate

Package Hygiene

• [Alpha] Remove all dead/unused code. For e.g.:
  • All example related modules. The default file based(read cert and key from disk) implementaion of Signer and verifier can act as example.
  • All Registry related modules and dependencies
  • type.go
  • Remove dependency on libtrust as its no longer maintained

Readability & Maintainability

• [Alpha] For better readability, we should to add documentation for important packages and exported names.
• [Alpha] Add unit tests. At minimum we need test which exercises positive scenario(successful signing and verification) to avoid breaking changes.

Signature(JWS)

• Signer and Verifier should be generic and signature agnostic.
• [Alpha] Move to JWS and as part of that we need to address following issues:
  • iat shoudnt be empty
  • nbf should be removed
  • Descriptor mediaType must not be empty
  • For notation alpha we can stick to only supporing x509 Cert; no need for keyId as its not actully getting used
• Add path is valid check while reading/writing cert and key from local disk:

Support signing and verifying tag references

Currently, notation supports signing and verifying digest references only.

Plugin not compliant error with test signature generation plugin

I’m creating a test plugin that supports signature generation, however am getting this error:

2022/06/06 00:17:51 generate-signature command failed: test-csp: failed to decode json response: plugin not compliant

Seems like it is having an issue with unmarshaling the plugin.GenerateSignatureResponse interface. If I unmarshal similar to where I believe the error is happening within the plugin there is no problem.

err = json.Unmarshal(out, resp)
if err != nil {
return nil, fmt.Errorf("failed to decode json response: %w", ErrNotCompliant)
}

plugin.GenerateSignatureResponse is:

{"keyId":"test-p256","signature":"MEUCIQDQv46z4MxdbSKgPnCuGrVmpU7UjR5Nw1/YN9zeChOzowIgallmITjnjhIvkZdXjME/vpJS8cgy6ow1pyo3AO8o1Qw=","signingAlgorithm":"ECDSA_SHA_256","certificateChain":["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"]}

Verify JWS header content

The content of JWS header is not verified including the cty and crit fields.
We need to verify those fields in case we have different types of payload.

Refactor to use oras-go

Once oras.go 2.0-alpha.1 is released, update to use oras-go for registry calls.

Shift Go Support Window to [1.18, 1.19]

Go 1.19 is released with release notes!

It is time to shift the window for go support to [1.18, 1.19] by updating

• go. mod
• GitHub Actions via notation-core-go

Implement updated signature format - JWS candidate specification

Match implementation with signature specification

Modify signature implementation to match signature spec

• Remove signedAttributes and use annotations for signed attributes.
• update payload key names.
• Add/update support for version in Artifact manifest and in JWS signature envelope.

Implement Verification Plugin Spec

Plugin Spec : notaryproject/specifications#165

Implementing signature filtering

Summary

Implementing signature filtering according to "Filter signature artifact manifest" documented in https://github.com/notaryproject/notaryproject/blob/main/signing-and-verification-workflow.md#verification-steps

Intended Outcome

Signature filtering works as described in "Filter signature artifact manifest"

Additional context

Using Verifier without a repository

Hello Notation Maintainers,

We have been using notation-go v0.8.0-alpha.1 for notaryv2 signature validation in the ratify project. As part of ratify-project/ratify#274 we have been looking at updating to notation-go v0.10.0-alpha.3 to take advantage of some of the added trust store features, but have run into some challenges with integrating the new Verifier type.

In ratify we have a core executor that performs artifact verification for a provided subject by collecting artifact references from stores and verifying them with the appropriate verifiers. This means that when we call a verifier we have already retrieved the associated artifact from the registry. In our existing notaryv2 verifier implementation we use the Verify function and pass the signature, but in the new Verify function the verifier expects to retrieve all of the references itself and verify all of them in one call. Would it be possible to expose some of the functionality in the new Verifier type to operate on pre-fetched signatures?

I took a look at the Verify implementation it looks like it would fit our use case to call processSignature directly. Ideally we would like to use the Verifier without having to provide a repository since our execution model separates repositories and verifiers. Do you have any suggestions or concerns with this approach?

Thanks!

@shizhMSFT @binbin-li @dtzar

Move to generic registry and client

Opening this issue to track refactoring. We might not even need registry client and can be scoped to just the signature formats.

directory structure needs to isolate `read` and `write` path

As current design, when system level directory has the config file while user level directory doesn't have the config file, it uses the system level config file for read and write.

It is necessary to allow the user to know that whether the write path is user level or system level, so we need to:

1. isolate read /write path
2. provide the ability to select user/system level directory to write.
   Linked to System vs User file/directory precedence#203

Remote signature envelope digest should be resolved as Blob instead of Manifest

This issue is paired with Notation issue #258.

Implement defining multiple trust stores in a trust policy

Spec notaryproject/specifications#164

Upgrade to go 1.18

Some unit tests fail on Windows platforms

Some unit tests in store_test.go fail on Windows platforms, and the error message is like below:

--- FAIL: TestLoadTrustStoreWithSymlinks (0.01s)
store_test.go:28: symlinks should return error : "Error while reading certificates from "testdata\\trust-store\\trust-store-with-cert-symlinks\\GlobalSignRootCA_SYMLINK.crt". Error : "x509: malformed certificate""
--- FAIL: TestLoadTrustStoreWithDirs (0.00s)
store_test.go:35: sub directories should return error : ""testdata\\trust-store\\trust-store-with-directories\\sub-dir" is not a regular file (directories or symlinks are not supported)"
--- FAIL: TestLoadTrustStoreWithInvalidCerts (0.00s)
store_test.go:42: invalid certs should return error : %!q()
--- FAIL: TestLoadTrustStoreWithLeafCerts (0.01s)
store_test.go:49: leaf cert in a trust store should return error : "certificate with subject "CN=lol,OU=lol,O=lol,L=lol,ST=Some-State,C=AU,1.2.840.113549.1.9.1=#13036c6f6c" from file "testdata\\trust-store\\trust-store-with-leaf-certs\\non-ca.crt" is not a CA certificate, only CA certificates (BasicConstraint CA=True) are allowed"
FAIL
FAIL github.com/notaryproject/notation-go/verification 4.042s
FAIL

It's because these test functions check the returned error by comparing its error message with a hard-coded error string, but the returned error message contains a Windows-style path which does not match the hard-coded path (See TestLoadTrustStoreWithInvalidCerts).

Support TSA trust stores in trust policy

See #72 (comment)

Tracks multiple TODOs in signature package

• include external signing plugin's name and version in signing agent.
• Verify plugin didnot add any additional top level payload attributes.
• Add tests for this method. NewSignerFromFiles

#77

The associated Linked PullRequest - #178

Support push and pull signature

As Notation verification workflow defined, Notation will support push and pull signature through the SDK capability of ORAS-go. It means notation-go has dependencies on the ORAS-go library.

Currently, we are working on these two dependencies in ORAS-go oras-project/oras-go#175 and oras-project/oras-go#205 to support push and pull signature artifact manifest with Notation.

Resolve bug in oras-go to enable interop with OCI compliant registries like ECR

As a user of Notation I want to use it to push and pull signatures from ECR.

• oras-project/oras-go#225 , blocks the above.

Notation open source maintainers will work with ORAS-go maintainers to resolve the above issue, and release a new version of oras-go client, that Notation can use. Likely v2.0.0-rc.3 Milestone ( refer v2.0.0-rc.3 )

Adding Notary v2 payload validation

Currently, notation-go and notation-core-go don't validate the content type of the payload as described in the spec. As discussed in the #131 (comment), create an issue here to discuss if we need to do the validation.

Add more validations for timestamp response

We do need to add more validation for timestamp response to avoid MitM, replay, etc. attacks and also to be a compliant client. The validations are more from timestamp security and correctness perspective. If the timestamp signature is bad then it is of no use for users.

Haven't gone through complete rfc3161 but here are some notable mentions:

• MitM and replay attack: https://datatracker.ietf.org/doc/html/rfc3161#section-4 point 4 and 5
• Policy: https://datatracker.ietf.org/doc/html/rfc3161#section-2.2
• nonce https://datatracker.ietf.org/doc/html/rfc3161#section-2.4.1
• PKIStatus,PKIFailureInfo https://datatracker.ietf.org/doc/html/rfc3161#section-2.4.2

Originally posted by @priteshbandi in #11 (comment)

Reenable timestamping for signing and verification

As part of #77(Refactor to use notation-core-go's SignatureEnvelope), we disabled time-stamping support for signing and verification workflows.

Action Required:

1. Implement timestamping support in notation-core-go.
2. Enable timestamping support for signing and verification workflows in notation-go.
3. Review verify TSA code which includes CMS parsing and verification. This code was included in alpha.1 and did not get through enough code review.
4. Ensure adequate test coverage in notation-core-go for CMS parsing and verification.

Update Golang packages to proper names

The golang packages should match the URL of the repository as well as the released tagged versions available in GitHub.

https://pkg.go.dev/github.com/notaryproject/[email protected]?tab=importedby
Have dependencies on the repository. 1.0.0-alpha-1 doesn't exist as a release in the GitHub repository.

These two PRs will help fix a couple of the dependencies once there is a new release of notation-go and the packages are published.
notaryproject/notation#164
Azure/notation-azure-kv#16

Release a new version of notation-go library

• Decide on main commit for this release

  • Commit: 3d8de5f

• Update dependencies in go.mod

  • notation-core-go from v0.1.0-alpha.3.0.20220929020818-b5df54c7465b to v0.1.0-alpha.4

• Decide on a tag name for this release

  • Tag name: v0.11.0-alpha.4

• Cut branch named with the tag name based on agreed upon main commit

• Cut a tag

@iamsamirzon @vaninrao10 @priteshbandi @shizhMSFT @dtzar @FeynmanZhou

Release a new version of Notation-go libraries

It's time to release a new version for Notation-go repo

• Decide on main commit for this release
• Decide on a tag name for this release
• Cut branch named with the tag name based on agreed upon main commit
• Cut a tag

@gokarnm @iamsamirzon @dtzar @SteveLasker @FeynmanZhou @shizhMSFT @yizha1 @vaninrao10

notation-go config package

notation config is a package for notation-go configuration, so it should be migrated to notation-go repo. Also, according to directory structure spec signingkeys related configuration should be moved out of config.json file to be a signingkeys.json file.

Related discussion is here

Notation-go supporting OCI reference type

Notation-go depends on ORAS-go to support OCI reference type. The ORAS-go work item is tracked here at oras-project/oras-go#271. Besides the update in ORAS-go, this issue tracks any other tasks of notation-go to support OCI reference type.

Dependency on go-ldap

We are using go-ldap for parsing Distinguished Names (DN) of a trust policy's trustedIdentities field. Although we are using a single function from this library, this dependency is bringing bunch of additional dependencies unrelated to what notation does. We can remove the dependency and just copy the code that we need. But, we need to figure out a way to give attribution to go-ldap. Also, if we remove the dependency, we need to have a mechanism to pull the relevant updates, security patches periodically. This issue is to track how we are going to proceed with this dependency as we approach RC1 launch.

Finalize referrers API path for RC1

The current artifact manifest referrers api calls out GET /v2/_ext/oci-artifacts/v1/{repository}/manifests/{digest}/referrers?n=10&artifactType={artifactType}
This is a tracking issue to attempt to align with opencontainers/distribution-spec#111 if we can get closure for the fall 2021 release. If not, we can resolve this for spring 2022

Perform X509 revocation check in signature verification

Signature verification needs to perform x509 revocation check (CRL/OCSP) and fail if a certificate in the chain is revoked.

See https://github.com/notaryproject/notaryproject/blob/main/trust-store-trust-policy-specification.md#certificate-revocation-evaluation

Migrate to codecov.io

Apply notatryproject/notation#267 to notation-go

Allow timestamping to be per signature configuration.

One signer implementation(like file-based one) can be reused by multiple organization. Some organizations might not want to timestamp signature because of availability concerns or something else but other might prefer to timestamp signature.
So there should be a way to for user to disable/enable time-stamping on per signature basis. One way to achieve is that only add timestamp when user explicitly specifies it

• notation sign --timestamp=${serverURL} <-- signs and timestamps
• notation sign <-- only signs

Originally posted by @priteshbandi in #11 (comment)

Move code to `notation-core-go`

As discussed in notaryproject/notation#160, all crypto code should be moved to notation-core-go. notation-go should depend on notation-core-go and should implement registry auth and registry interactions, including ORAS APIs, key config, trust store, trust policy, plugin interaction

Implement Custom Signature Verification Level

Spec notaryproject/specifications#164

API Testing

Summary
Automated Test Cases to be executed before every release for all APIs
Intended Outcome
A test suite is created over time and added iteratively over the lifetime of this project development
Additional context
The unit testing will be included in RC-1. The community met on 5/26 and made the decision to split this work as unit and end to end testing.

ci/cd: consider exporting some go routines so other projects can ci/cd against notation

For example,

https://github.com/notaryproject/notation/blob/main/cmd/notation/cert_gen.go

Rename notation-go-lib to notation-go

Part of the cleanup and refactoring, including the creation of notation-core-go

Please 👍 to confirm

Consider OpenSSL for signature generation and verification.

• We are using homegrown/custom implementation of pkcs7 for timestamp signature, should we consider using openssl?
• OpenSSl is FIPS compliant so we can offload crypto operations to openssl

Release notation-go-lib-v0.7.0-alpha.1

Proposing we release notation-go-lib-v0.7.0-alpha.1 as we have completed the milestone. Release process is defined here.

High level deliverables as as follows:

• Decide on main commit for release
• Cut branch named v0.7.0-alpha.1 based on agreed upon main commit
• Cut a tag named v0.7.0-alpha.1
• Update README.md

/cc @SteveLasker @NiazFK @justincormack @sajayantony

Can the maintainers please respond with a +1 comment once you are in favor of cutting this release.

Add unit tests to the registry submodule

What?

As we moved registry from the notation to notation-go #63, unit tests are still missing for now. We need to add necessary tests to avoid breaking changes in the future.

New release v0.9.0-alpha.1

Lots of important changes merged since v0.8.0 and should cut a new release.
Would like to just take what's on main now plus merge #44

• Decide on main commit for a release
• Cut branch named v0.9.0-alpha.1 based on agreed upon main commit
• Cut a tag named v0.9.0-alpha.1

@SteveLasker @gokarnm @iamsamirzon @FeynmanZhou

Run symlink unit tests on Windows

Currently, Trust Store unit tests are skipping symlink tests on Windows as Windows requires Admin permissions to create Symlinks (see this). This issue is to identify a way to run symlink tests on Windows. More context : #58

Dont allow signer-provider or verification-provider to override the TSAVerifyOptions.

We don't want signer-provider or verification-provider to override the TSAVerifyOptions because then user can override this value and start using non time-stamping cert(like ssl) for time-stamping.

Also as per rfc3161#section-2.3
The corresponding certificate MUST contain only one instance of the extended key usage field extension as defined in [RFC2459] Section 4.2.1.13 with KeyPurposeID having value: id-kp-timeStamping.

I would suggest to start with not exposing TSAVerifyOptions and then later if need arises we can expose this option with sane defaults.

Originally posted by @priteshbandi in #15 (comment)

Move `notation/pkg/registry` to `notation-go`