From 3908b4ea71ba956d3b9d43110a03a1add9ee30a7 Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Wed, 25 Dec 2024 11:25:00 +0800 Subject: [PATCH] update docs Signed-off-by: Patrick Zheng --- example_localSign_test.go | 2 +- example_localVerify_test.go | 6 ++--- example_remoteSign_test.go | 2 +- example_remoteVerify_test.go | 2 +- example_signBlob_test.go | 10 ++++---- example_signWithTimestmap_test.go | 2 +- example_verifyBlob_test.go | 27 +++++++++++----------- example_verifyWithTimestamp_test.go | 4 ++-- notation.go | 29 ++++++++++++----------- plugin/manager.go | 2 +- plugin/plugin.go | 6 ++++- registry/repository.go | 10 ++++---- signer/plugin.go | 10 ++++---- signer/signer.go | 15 ++++++------ signer/signer_test.go | 3 ++- verifier/helpers.go | 6 ++--- verifier/trustpolicy/blob.go | 22 ++++++++++-------- verifier/trustpolicy/oci.go | 33 ++++++++++++++------------ verifier/trustpolicy/trustpolicy.go | 7 +++--- verifier/truststore/truststore.go | 9 ++++---- verifier/verifier.go | 36 ++++++++++++++++------------- verifier/verifier_test.go | 2 +- 22 files changed, 133 insertions(+), 112 deletions(-) diff --git a/example_localSign_test.go b/example_localSign_test.go index 9672c02f..4022cc32 100644 --- a/example_localSign_test.go +++ b/example_localSign_test.go @@ -46,7 +46,7 @@ func Example_localSign() { // exampleSigner is a notation.Signer given key and X509 certificate chain. // Users should replace `exampleCertTuple.PrivateKey` with their own private // key and replace `exampleCerts` with the corresponding full certificate - // chain, following the Notary certificate requirements: + // chain, following the Notary Project certificate requirements: // https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements exampleSigner, err := signer.NewGenericSigner(exampleCertTuple.PrivateKey, exampleCerts) if err != nil { diff --git a/example_localVerify_test.go b/example_localVerify_test.go index 50426763..c77395ab 100644 --- a/example_localVerify_test.go +++ b/example_localVerify_test.go @@ -73,8 +73,8 @@ func Example_localVerify() { } // createTrustStore creates a trust store directory for demo purpose. - // Users could use the default trust store from Notary and add trusted - // certificates into it following the trust store spec: + // Users could use the default trust store from Notary Project and + // add trusted certificates into it following the trust store spec: // https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-store if err := createTrustStore(); err != nil { panic(err) // Handle error @@ -172,7 +172,7 @@ func createTrustStore() error { // generate the `exampleSignatureEnvelopePem` above.) // Users should replace `exampleX509Certificate` with their own trusted // certificate and add to the trust store, following the - // Notary certificate requirements: + // Notary Project certificate requirements: // https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements exampleX509Certificate := `-----BEGIN CERTIFICATE----- MIIDQDCCAiigAwIBAgIBUTANBgkqhkiG9w0BAQsFADBOMQswCQYDVQQGEwJVUzEL diff --git a/example_remoteSign_test.go b/example_remoteSign_test.go index 03565e98..e654c7a4 100644 --- a/example_remoteSign_test.go +++ b/example_remoteSign_test.go @@ -45,7 +45,7 @@ func Example_remoteSign() { // exampleSigner is a notation.Signer given key and X509 certificate chain. // Users should replace `exampleCertTuple.PrivateKey` with their own private // key and replace `exampleCerts` with the corresponding full certificate - // chain, following the Notary certificate requirements: + // chain, following the Notary Project certificate requirements: // https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements exampleSigner, err := signer.NewGenericSigner(exampleCertTuple.PrivateKey, exampleCerts) if err != nil { diff --git a/example_remoteVerify_test.go b/example_remoteVerify_test.go index 1fffed34..f712891d 100644 --- a/example_remoteVerify_test.go +++ b/example_remoteVerify_test.go @@ -101,7 +101,7 @@ func generateTrustStore() error { // an example of a valid X509 self-signed certificate for demo purpose ONLY. // Users should replace `exampleX509Certificate` with their own trusted // certificate and add to the trust store, following the - // Notary certificate requirements: + // Notary Project certificate requirements: // https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements exampleX509Certificate := `-----BEGIN CERTIFICATE----- MIIDQDCCAiigAwIBAgIBUTANBgkqhkiG9w0BAQsFADBOMQswCQYDVQQGEwJVUzEL diff --git a/example_signBlob_test.go b/example_signBlob_test.go index cab78ca5..35a12e0e 100644 --- a/example_signBlob_test.go +++ b/example_signBlob_test.go @@ -24,13 +24,15 @@ import ( "github.com/notaryproject/notation-go/signer" ) -// ExampleSignBlob demonstrates how to use signer.BlobSign to sign arbitrary data. +// ExampleSignBlob demonstrates how to use [signer.BlobSign] to sign arbitrary +// data. func Example_signBlob() { - //exampleSigner implements notation.Signer and notation.BlobSigner. Given key and X509 certificate chain, - // it provides method to sign OCI artifacts or blobs. + // exampleSigner implements [notation.Signer] and [notation.BlobSigner]. + // Given key and X509 certificate chain, it provides method to sign OCI + // artifacts or blobs. // Users should replace `exampleCertTuple.PrivateKey` with their own private // key and replace `exampleCerts` with the corresponding certificate chain, - //following the Notary certificate requirements: + //following the Notary Project certificate requirements: // https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements exampleSigner, err := signer.NewGenericSigner(exampleCertTuple.PrivateKey, exampleCerts) if err != nil { diff --git a/example_signWithTimestmap_test.go b/example_signWithTimestmap_test.go index ef4eeb47..043cfe62 100644 --- a/example_signWithTimestmap_test.go +++ b/example_signWithTimestmap_test.go @@ -45,7 +45,7 @@ func Example_signWithTimestamp() { // exampleSigner is a notation.Signer given key and X509 certificate chain. // Users should replace `exampleCertTuple.PrivateKey` with their own private // key and replace `exampleCerts` with the corresponding full certificate - // chain, following the Notary certificate requirements: + // chain, following the Notary Project certificate requirements: // https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements exampleSigner, err := signer.NewGenericSigner(exampleCertTuple.PrivateKey, exampleCerts) if err != nil { diff --git a/example_verifyBlob_test.go b/example_verifyBlob_test.go index ce9d94de..06ad22e9 100644 --- a/example_verifyBlob_test.go +++ b/example_verifyBlob_test.go @@ -27,9 +27,9 @@ import ( "github.com/notaryproject/notation-go/verifier/truststore" ) -// examplePolicyDocument is an example of a valid trust policy document. -// trust policy document should follow this spec: -// https://github.com/notaryproject/notaryproject/blob/v1.1.0/specs/trust-store-trust-policy.md#trust-policy +// exampleBlobPolicyDocument is an example of a valid blob trust policy document. +// blob trust policy document should follow this spec: +// https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#blob-trust-policy var exampleBlobPolicyDocument = trustpolicy.BlobDocument{ Version: "1.0", TrustPolicies: []trustpolicy.BlobTrustPolicy{ @@ -42,8 +42,8 @@ var exampleBlobPolicyDocument = trustpolicy.BlobDocument{ }, } -// ExampleVerifyBlob demonstrates how to use verifier.Verify to verify a -// signature of the blob. +// ExampleVerifyBlob demonstrates how to use [verifier.Verify] to verify a +// signature of an arbitrary blob. func Example_verifyBlob() { // Both COSE ("application/cose") and JWS ("application/jose+json") // signature mediaTypes are supported. @@ -53,23 +53,24 @@ func Example_verifyBlob() { exampleSignatureEnvelope := getSignatureEnvelope() // createTrustStoreForBlobVerify creates a trust store directory for demo purpose. - // Users could use the default trust store from Notary and add trusted + // Users could use the default trust store from Notation and add trusted // certificates into it following the trust store spec: - // https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-store + // https://github.com/notaryproject/notaryproject/blob/v1.1.0/specs/trust-store-trust-policy.md#trust-store if err := createTrustStoreForBlobVerify(); err != nil { panic(err) // Handle error } - // exampleVerifier implements notation.Verify and notation.VerifyBlob. + // exampleVerifier implements [notation.Verify] and [notation.VerifyBlob]. exampleVerifier, err := verifier.NewVerifier(nil, &exampleBlobPolicyDocument, truststore.NewX509TrustStore(dir.ConfigFS()), nil) if err != nil { panic(err) // Handle error } - // exampleReader reads the data that needs to be verified. This data can be in a file or in memory. + // exampleReader reads the data that needs to be verified. + // This data can be in a file or in memory. exampleReader := strings.NewReader("example blob") - // exampleVerifyOptions is an example of notation.VerifierVerifyOptions + // exampleVerifyOptions is an example of [notation.VerifierVerifyOptions] exampleVerifyOptions := notation.VerifyBlobOptions{ BlobVerifierVerifyOptions: notation.BlobVerifierVerifyOptions{ SignatureMediaType: exampleSignatureMediaType, @@ -91,7 +92,7 @@ func Example_verifyBlob() { // Note, upon successful verification, payload.TargetArtifact from the // signature envelope matches exactly with our exampleTargetDescriptor. - // (This check has been done for the user inside verifier.Verify.) + // (This check has been done for the user inside [verifier.Verify].) fmt.Println("payload Content:", string(outcome.EnvelopeContent.Payload.Content)) // Output: @@ -110,8 +111,8 @@ func createTrustStoreForBlobVerify() error { // generate the `exampleSignatureEnvelopePem` above.) // Users should replace `exampleX509Certificate` with their own trusted // certificate and add to the trust store, following the - // Notary certificate requirements: - // https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements + // Notary Project certificate requirements: + // https://github.com/notaryproject/notaryproject/blob/v1.1.0/specs/signature-specification.md#certificate-requirements exampleX509Certificate := `-----BEGIN CERTIFICATE----- MIIEbDCCAtSgAwIBAgIBUzANBgkqhkiG9w0BAQsFADBkMQswCQYDVQQGEwJVUzEL MAkGA1UECBMCV0ExEDAOBgNVBAcTB1NlYXR0bGUxDzANBgNVBAoTBk5vdGFyeTEl diff --git a/example_verifyWithTimestamp_test.go b/example_verifyWithTimestamp_test.go index 56c21d59..09baaf8e 100644 --- a/example_verifyWithTimestamp_test.go +++ b/example_verifyWithTimestamp_test.go @@ -115,7 +115,7 @@ func generateTrustStoreWithTimestamp() error { // an example of a valid X509 self-signed certificate for demo purpose ONLY. // Users should replace `exampleX509Certificate` with their own trusted // certificate and add to the trust store, following the - // Notary certificate requirements: + // Notary Project certificate requirements: // https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements exampleX509Certificate := `-----BEGIN CERTIFICATE----- MIIDQDCCAiigAwIBAgIBUTANBgkqhkiG9w0BAQsFADBOMQswCQYDVQQGEwJVUzEL @@ -149,7 +149,7 @@ GLAfj/jSf9OH9VLTPHOS8/N0Ka4= // an example of a valid TSA root certificate for demo purpose ONLY. // Users should replace `exampleTSARootCertificate` with their own trusted // TSA root certificate and add to the trust store, following the - // Notary certificate requirements: + // Notary Project certificate requirements: // https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements exampleTSARootCertificate := `-----BEGIN CERTIFICATE----- MIIFkDCCA3igAwIBAgIQBZsbV56OITLiOQe9p3d1XDANBgkqhkiG9w0BAQwFADBi diff --git a/notation.go b/notation.go index d4e13f52..284ec775 100644 --- a/notation.go +++ b/notation.go @@ -12,7 +12,7 @@ // limitations under the License. // Package notation provides signer and verifier for notation Sign -// and Verification. +// and Verification. It supports both OCI artifact and arbitrary blob. package notation import ( @@ -48,7 +48,7 @@ var errDoneVerification = errors.New("done verification") var reservedAnnotationPrefixes = [...]string{"io.cncf.notary"} -// SignerSignOptions contains parameters for Signer and BlobSigner. +// SignerSignOptions contains parameters for [Signer] and [BlobSigner]. type SignerSignOptions struct { // SignatureMediaType is the envelope type of the signature. // Currently, both `application/jose+json` and `application/cose` are @@ -86,7 +86,7 @@ type Signer interface { Sign(ctx context.Context, desc ocispec.Descriptor, opts SignerSignOptions) ([]byte, *signature.SignerInfo, error) } -// SignBlobOptions contains parameters for notation.SignBlob. +// SignBlobOptions contains parameters for [notation.SignBlob]. type SignBlobOptions struct { SignerSignOptions @@ -125,7 +125,7 @@ type signerAnnotation interface { PluginAnnotations() map[string]string } -// SignOptions contains parameters for notation.Sign. +// SignOptions contains parameters for [notation.Sign]. type SignOptions struct { SignerSignOptions @@ -329,7 +329,8 @@ func (outcome *VerificationOutcome) UserMetadata() (map[string]string, error) { return payload.TargetArtifact.Annotations, nil } -// VerifierVerifyOptions contains parameters for Verifier.Verify used for verifying OCI artifact. +// VerifierVerifyOptions contains parameters for [Verifier.Verify] used for +// verifying OCI artifact. type VerifierVerifyOptions struct { // ArtifactReference is the reference of the artifact that is being // verified against to. It must be a full reference. @@ -348,17 +349,17 @@ type VerifierVerifyOptions struct { UserMetadata map[string]string } -// Verifier is a interface for verifying an OCI artifact. +// Verifier is a generic interface for verifying an OCI artifact. type Verifier interface { // Verify verifies the `signature` associated with the target OCI artifact - //with manifest descriptor `desc`, and returns the outcome upon + // with manifest descriptor `desc`, and returns the outcome upon // successful verification. // If nil signature is present and the verification level is not 'skip', // an error will be returned. Verify(ctx context.Context, desc ocispec.Descriptor, signature []byte, opts VerifierVerifyOptions) (*VerificationOutcome, error) } -// BlobVerifierVerifyOptions contains parameters for BlobVerifier.Verify. +// BlobVerifierVerifyOptions contains parameters for [BlobVerifier.Verify]. type BlobVerifierVerifyOptions struct { // SignatureMediaType is the envelope type of the signature. // Currently only `application/jose+json` and `application/cose` are @@ -379,7 +380,7 @@ type BlobVerifierVerifyOptions struct { // BlobVerifier is a generic interface for verifying a blob. type BlobVerifier interface { - // VerifyBlob verifies the `signature` against the target artifact using the + // VerifyBlob verifies the `signature` against the target blob using the // descriptor returned by descGenFunc parameter and // returns the outcome upon successful verification. VerifyBlob(ctx context.Context, descGenFunc BlobDescriptorGenerator, signature []byte, opts BlobVerifierVerifyOptions) (*VerificationOutcome, error) @@ -390,7 +391,7 @@ type verifySkipper interface { SkipVerify(ctx context.Context, opts VerifierVerifyOptions) (bool, *trustpolicy.VerificationLevel, error) } -// VerifyOptions contains parameters for notation.Verify. +// VerifyOptions contains parameters for [notation.Verify]. type VerifyOptions struct { // ArtifactReference is the reference of the artifact that is being // verified against to. @@ -409,7 +410,7 @@ type VerifyOptions struct { UserMetadata map[string]string } -// VerifyBlobOptions contains parameters for notation.VerifyBlob. +// VerifyBlobOptions contains parameters for [notation.VerifyBlob]. type VerifyBlobOptions struct { BlobVerifierVerifyOptions @@ -418,9 +419,9 @@ type VerifyBlobOptions struct { } // VerifyBlob performs signature verification for a blob using notation supported -// verification types (like integrity, authenticity, etc.) and return the -// successful signature verification outcome. The blob is read using blobReader and -// upon successful verification, it returns the descriptor of the blob. +// verification types (like integrity, authenticity, etc.) and returns the +// successful signature verification outcome. The blob is read using blobReader, +// and upon successful verification, it returns the descriptor of the blob. // For more details on signature verification, see // https://github.com/notaryproject/notaryproject/blob/main/specs/trust-store-trust-policy.md#signature-verification func VerifyBlob(ctx context.Context, blobVerifier BlobVerifier, blobReader io.Reader, signature []byte, verifyBlobOpts VerifyBlobOptions) (ocispec.Descriptor, *VerificationOutcome, error) { diff --git a/plugin/manager.go b/plugin/manager.go index e332dd84..6570c805 100644 --- a/plugin/manager.go +++ b/plugin/manager.go @@ -35,7 +35,7 @@ type Manager interface { List(ctx context.Context) ([]string, error) } -// CLIManager implements Manager +// CLIManager implements [Manager] type CLIManager struct { pluginFS dir.SysFS } diff --git a/plugin/plugin.go b/plugin/plugin.go index 6402fb96..a4a64433 100644 --- a/plugin/plugin.go +++ b/plugin/plugin.go @@ -40,26 +40,30 @@ const maxPluginOutputSize = 64 * 1024 * 1024 // 64 MiB var executor commander = &execCommander{} // for unit test // GenericPlugin is the base requirement to be a plugin. +// // Deprecated: GenericPlugin exists for historical compatibility and should not be used. // To access GenericPlugin, use the notation-plugin-framework-go's plugin.GenericPlugin type. type GenericPlugin = plugin.GenericPlugin // SignPlugin defines the required methods to be a SignPlugin. +// // Deprecated: SignPlugin exists for historical compatibility and should not be used. // To access SignPlugin, use the notation-plugin-framework-go's plugin.SignPlugin type. type SignPlugin = plugin.SignPlugin // VerifyPlugin defines the required method to be a VerifyPlugin. +// // Deprecated: VerifyPlugin exists for historical compatibility and should not be used. // To access VerifyPlugin, use the notation-plugin-framework-go's plugin.VerifyPlugin type. type VerifyPlugin = plugin.VerifyPlugin // Plugin defines required methods to be a Plugin. +// // Deprecated: Plugin exists for historical compatibility and should not be used. // To access Plugin, use the notation-plugin-framework-go's plugin.Plugin type. type Plugin = plugin.Plugin -// CLIPlugin implements Plugin interface to CLI plugins. +// CLIPlugin implements [Plugin] interface to CLI plugins. type CLIPlugin struct { name string path string diff --git a/registry/repository.go b/registry/repository.go index e778613a..0edce7ed 100644 --- a/registry/repository.go +++ b/registry/repository.go @@ -48,17 +48,17 @@ var ( notationEmptyConfigData = ocispec.DescriptorEmptyJSON.Data ) -// RepositoryOptions provides user options when creating a Repository +// RepositoryOptions provides user options when creating a [Repository] // it is kept for future extensibility type RepositoryOptions struct{} -// repositoryClient implements Repository +// repositoryClient implements [Repository] type repositoryClient struct { oras.GraphTarget RepositoryOptions } -// NewRepository returns a new Repository. +// NewRepository returns a new [Repository]. // Known implementations of oras.GraphTarget: // - [remote.Repository](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote#Repository) // - [oci.Store](https://pkg.go.dev/oras.land/oras-go/v2/content/oci#Store) @@ -68,7 +68,7 @@ func NewRepository(target oras.GraphTarget) Repository { } } -// NewRepositoryWithOptions returns a new Repository with user specified +// NewRepositoryWithOptions returns a new [Repository] with user specified // options. func NewRepositoryWithOptions(target oras.GraphTarget, opts RepositoryOptions) Repository { return &repositoryClient{ @@ -77,7 +77,7 @@ func NewRepositoryWithOptions(target oras.GraphTarget, opts RepositoryOptions) R } } -// NewOCIRepository returns a new Repository with oci.Store as +// NewOCIRepository returns a new [Repository] with oci.Store as // its oras.GraphTarget. `path` denotes directory path to the target OCI layout. func NewOCIRepository(path string, opts RepositoryOptions) (Repository, error) { fileInfo, err := os.Stat(path) diff --git a/signer/plugin.go b/signer/plugin.go index 86b607b5..1f2eeaa9 100644 --- a/signer/plugin.go +++ b/signer/plugin.go @@ -36,7 +36,7 @@ import ( // PluginSigner signs artifacts and generates signatures. // -// It implements notation.Signer and notation.BlobSigner. +// It implements [notation.Signer] and [notation.BlobSigner]. type PluginSigner struct { plugin plugin.SignPlugin keyID string @@ -50,17 +50,17 @@ var algorithms = map[crypto.Hash]digest.Algorithm{ crypto.SHA512: digest.SHA512, } -// NewFromPlugin creates a PluginSigner that signs artifacts and generates +// NewFromPlugin creates a [PluginSigner] that signs artifacts and generates // signatures by delegating the one or more operations to the named plugin, // as defined in https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#signing-interfaces. // -// Deprecated: NewFromPlugin function exists for historical compatibility and should not be used. -// To create PluginSigner, use NewPluginSigner() function. +// Deprecated: NewFromPlugin function exists for historical compatibility and +// should not be used. To create [PluginSigner], use NewPluginSigner() function. func NewFromPlugin(plugin plugin.SignPlugin, keyID string, pluginConfig map[string]string) (notation.Signer, error) { return NewPluginSigner(plugin, keyID, pluginConfig) } -// NewPluginSigner creates a PluginSigner that signs artifacts and generates +// NewPluginSigner creates a [PluginSigner] that signs artifacts and generates // signatures by delegating the one or more operations to the named plugin, // as defined in https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#signing-interfaces. func NewPluginSigner(plugin plugin.SignPlugin, keyID string, pluginConfig map[string]string) (*PluginSigner, error) { diff --git a/signer/signer.go b/signer/signer.go index ff380d82..ad22ac7d 100644 --- a/signer/signer.go +++ b/signer/signer.go @@ -12,8 +12,8 @@ // limitations under the License. // Package signer provides notation signing functionality. It implements the -// notation.Signer interface by providing builtinSigner for local signing and -// PluginSigner for remote signing. +// [notation.Signer] and [notation.BlobSigner] interface by providing +// builtinSigner for local signing and [PluginSigner] for remote signing. package signer import ( @@ -36,16 +36,17 @@ import ( // signingAgent is the unprotected header field used by signature. const signingAgent = "notation-go/1.3.0+unreleased" -// GenericSigner implements notation.Signer and notation.BlobSigner. +// GenericSigner implements [notation.Signer] and [notation.BlobSigner]. // It embeds signature.Signer. type GenericSigner struct { signer signature.Signer } -// New returns a notation.Signer given key and cert chain. +// New returns a [notation.Signer] given key and cert chain. // -// Deprecated: New function exists for historical compatibility and should not be used. -// To create GenericSigner, use NewGenericSigner() function. +// Deprecated: New function exists for historical compatibility and +// should not be used. To create [GenericSigner], +// use NewGenericSigner() function. func New(key crypto.PrivateKey, certChain []*x509.Certificate) (notation.Signer, error) { return NewGenericSigner(key, certChain) } @@ -61,7 +62,7 @@ func NewGenericSigner(key crypto.PrivateKey, certChain []*x509.Certificate) (*Ge }, nil } -// NewFromFiles returns a notation.Signer given key and certChain paths. +// NewFromFiles returns a [notation.Signer] given key and certChain paths. func NewFromFiles(keyPath, certChainPath string) (notation.Signer, error) { return NewGenericSignerFromFiles(keyPath, certChainPath) } diff --git a/signer/signer_test.go b/signer/signer_test.go index 22f3e2a1..afaef743 100644 --- a/signer/signer_test.go +++ b/signer/signer_test.go @@ -55,7 +55,8 @@ type keyCertPair struct { var keyCertPairCollections []*keyCertPair -// setUpKeyCertPairCollections setups all combinations of private key and certificates. +// setUpKeyCertPairCollections setups all combinations of private key and +// certificates. func setUpKeyCertPairCollections() []*keyCertPair { // rsa var keyCertPairs []*keyCertPair diff --git a/verifier/helpers.go b/verifier/helpers.go index f1835f8d..785ff678 100644 --- a/verifier/helpers.go +++ b/verifier/helpers.go @@ -60,10 +60,10 @@ func loadX509TrustStores(ctx context.Context, scheme signature.SigningScheme, po return loadX509TrustStoresWithType(ctx, typeToLoad, policyName, trustStores, x509TrustStore) } -// isCriticalFailure checks whether a VerificationResult fails the entire -// signature verification workflow. +// isCriticalFailure checks whether a [notation.ValidationResult] fails the +// entire signature verification workflow. // signature verification workflow is considered failed if there is a -// VerificationResult with "Enforced" as the action but the result was +// ValidationResult with "Enforced" as the action but the result was // unsuccessful. func isCriticalFailure(result *notation.ValidationResult) bool { return result.Action == trustpolicy.ActionEnforce && result.Error != nil diff --git a/verifier/trustpolicy/blob.go b/verifier/trustpolicy/blob.go index b016c0ec..bed6e182 100644 --- a/verifier/trustpolicy/blob.go +++ b/verifier/trustpolicy/blob.go @@ -24,7 +24,7 @@ import ( "github.com/notaryproject/notation-go/internal/slices" ) -// BlobDocument represents a trustpolicy.blob.json document +// BlobDocument represents a trustpolicy.blob.json document for arbitrary blobs type BlobDocument struct { // Version of the policy document Version string `json:"version"` @@ -33,7 +33,8 @@ type BlobDocument struct { TrustPolicies []BlobTrustPolicy `json:"trustPolicies"` } -// BlobTrustPolicy represents a policy statement in the blob policy document +// BlobTrustPolicy represents a policy statement in the blob trust policy +// document type BlobTrustPolicy struct { // Name of the policy statement Name string `json:"name"` @@ -53,15 +54,16 @@ type BlobTrustPolicy struct { var supportedBlobPolicyVersions = []string{"1.0"} -// LoadBlobDocument loads a trust policy document from a local file system +// LoadBlobDocument loads a blob trust policy document from a local file system func LoadBlobDocument() (*BlobDocument, error) { var doc BlobDocument err := getDocument(dir.PathBlobTrustPolicy, &doc) return &doc, err } -// Validate validates a policy document according to its version's rule set. -// if any rule is violated, returns an error +// Validate validates a blob trust policy document according to its version's +// rule set. +// If any rule is violated, returns an error func (policyDoc *BlobDocument) Validate() error { // sanity check if policyDoc == nil { @@ -111,11 +113,12 @@ func (policyDoc *BlobDocument) Validate() error { return nil } -// GetApplicableTrustPolicy returns a pointer to the deep copied TrustPolicy for given policy name +// GetApplicableTrustPolicy returns a pointer to the deep copied [BlobTrustPolicy] +// for given policy name. // see https://github.com/notaryproject/notaryproject/blob/v1.1.0/specs/trust-store-trust-policy.md#blob-trust-policy func (policyDoc *BlobDocument) GetApplicableTrustPolicy(policyName string) (*BlobTrustPolicy, error) { if strings.TrimSpace(policyName) == "" { - return nil, errors.New("policy name cannot be empty") + return nil, errors.New("policy name cannot be empty") } for _, policyStatement := range policyDoc.TrustPolicies { // exact match @@ -127,7 +130,8 @@ func (policyDoc *BlobDocument) GetApplicableTrustPolicy(policyName string) (*Blo return nil, fmt.Errorf("no applicable blob trust policy with name %q", policyName) } -// GetGlobalTrustPolicy returns a pointer to the deep copy of the TrustPolicy that is marked as global policy +// GetGlobalTrustPolicy returns a pointer to the deep copied [BlobTrustPolicy] +// that is marked as global policy. // see https://github.com/notaryproject/notaryproject/blob/v1.1.0/specs/trust-store-trust-policy.md#blob-trust-policy func (policyDoc *BlobDocument) GetGlobalTrustPolicy() (*BlobTrustPolicy, error) { for _, policyStatement := range policyDoc.TrustPolicies { @@ -139,7 +143,7 @@ func (policyDoc *BlobDocument) GetGlobalTrustPolicy() (*BlobTrustPolicy, error) return nil, fmt.Errorf("no global blob trust policy") } -// clone returns a pointer to the deeply copied TrustPolicy +// clone returns a pointer to the deep copied [BlobTrustPolicy] func (t *BlobTrustPolicy) clone() *BlobTrustPolicy { return &BlobTrustPolicy{ Name: t.Name, diff --git a/verifier/trustpolicy/oci.go b/verifier/trustpolicy/oci.go index 1203d2b8..838e4aa9 100644 --- a/verifier/trustpolicy/oci.go +++ b/verifier/trustpolicy/oci.go @@ -25,7 +25,7 @@ import ( "github.com/notaryproject/notation-go/internal/trustpolicy" ) -// OCIDocument represents a trustPolicy.json document for OCI artifacts +// OCIDocument represents a trustpolicy.oci.json document for OCI artifacts type OCIDocument struct { // Version of the policy document Version string `json:"version"` @@ -34,7 +34,7 @@ type OCIDocument struct { TrustPolicies []OCITrustPolicy `json:"trustPolicies"` } -// OCITrustPolicy represents a policy statement in the policy document for OCI artifacts +// OCITrustPolicy represents a policy statement in the OCI trust policy document type OCITrustPolicy struct { // Name of the policy statement Name string `json:"name"` @@ -53,27 +53,31 @@ type OCITrustPolicy struct { } // Document represents a trustPolicy.json document -// Deprecated: Document exists for historical compatibility and should not be used. -// To create OCI Document, use OCIDocument. +// +// Deprecated: Document exists for historical compatibility and +// should not be used. To create OCI Document, use [OCIDocument]. type Document = OCIDocument // TrustPolicy represents a policy statement in the policy document -// Deprecated: TrustPolicy exists for historical compatibility and should not be used. -// To create OCI TrustPolicy, use OCITrustPolicy. +// +// Deprecated: TrustPolicy exists for historical compatibility and +// should not be used. To create OCI TrustPolicy, use [OCITrustPolicy]. type TrustPolicy = OCITrustPolicy // LoadDocument loads a trust policy document from a local file system -// Deprecated: LoadDocument function exists for historical compatibility and should not be used. -// To load OCI Document, use LoadOCIDocument function. +// +// Deprecated: LoadDocument function exists for historical compatibility and +// should not be used. To load OCI Document, use [LoadOCIDocument] function. var LoadDocument = LoadOCIDocument var supportedOCIPolicyVersions = []string{"1.0"} // LoadOCIDocument retrieves a trust policy document from the local file system. -// It attempts to read from dir.PathOCITrustPolicy first; if not found, it tries dir.PathTrustPolicy. -// If both dir.PathOCITrustPolicy and dir.PathTrustPolicy exist, dir.PathOCITrustPolicy will be read. +// It attempts to read from [dir.PathOCITrustPolicy] first; if not found, +// it tries [dir.PathTrustPolicy]. +// If both dir.PathOCITrustPolicy and dir.PathTrustPolicy exist, +// dir.PathOCITrustPolicy will be read. func LoadOCIDocument() (*OCIDocument, error) { - var doc OCIDocument // attempt to load the document from dir.PathOCITrustPolicy if err := getDocument(dir.PathOCITrustPolicy, &doc); err != nil { @@ -87,7 +91,6 @@ func LoadOCIDocument() (*OCIDocument, error) { // if an error occurred other than the document not found, return it return nil, err } - return &doc, nil } @@ -134,9 +137,9 @@ func (policyDoc *OCIDocument) Validate() error { return nil } -// GetApplicableTrustPolicy returns a pointer to the deep copied TrustPolicy +// GetApplicableTrustPolicy returns a pointer to the deep copied [OCITrustPolicy] // statement that applies to the given registry scope. If no applicable trust -// policy is found, returns an error +// policy is found, returns an error. // see https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/trust-store-trust-policy.md#selecting-a-trust-policy-based-on-artifact-uri func (policyDoc *OCIDocument) GetApplicableTrustPolicy(artifactReference string) (*OCITrustPolicy, error) { artifactPath, err := getArtifactPathFromReference(artifactReference) @@ -167,7 +170,7 @@ func (policyDoc *OCIDocument) GetApplicableTrustPolicy(artifactReference string) } } -// clone returns a pointer to the deeply copied TrustPolicy +// clone returns a pointer to the deep copied [OCITrustPolicy] func (t *OCITrustPolicy) clone() *OCITrustPolicy { return &OCITrustPolicy{ Name: t.Name, diff --git a/verifier/trustpolicy/trustpolicy.go b/verifier/trustpolicy/trustpolicy.go index cbab4275..8a6ba841 100644 --- a/verifier/trustpolicy/trustpolicy.go +++ b/verifier/trustpolicy/trustpolicy.go @@ -158,8 +158,9 @@ func (e errPolicyNotExist) Error() string { return fmt.Sprintf("trust policy is not present. To create a trust policy, see: %s", trustPolicyLink) } -// GetVerificationLevel returns VerificationLevel struct for the given -// SignatureVerification struct throws error if SignatureVerification is invalid +// GetVerificationLevel returns [VerificationLevel] struct for the given +// [SignatureVerification] struct throws error if SignatureVerification is +// invalid func (signatureVerification *SignatureVerification) GetVerificationLevel() (*VerificationLevel, error) { if signatureVerification.VerificationLevel == "" { return nil, errors.New("signature verification level is empty or missing in the trust policy statement") @@ -385,7 +386,7 @@ func validateOverlappingDNs(policyName string, parsedDNs []parsedDN) error { } // isValidTrustStoreType returns true if the given string is a valid -// truststore.Type, otherwise false. +// [truststore.Type], otherwise false. func isValidTrustStoreType(s string) bool { for _, p := range truststore.Types { if s == string(p) { diff --git a/verifier/truststore/truststore.go b/verifier/truststore/truststore.go index 067372c1..31449905 100644 --- a/verifier/truststore/truststore.go +++ b/verifier/truststore/truststore.go @@ -30,8 +30,7 @@ import ( "github.com/notaryproject/notation-go/internal/slices" ) -// Type is an enum for trust store types supported such as -// "ca" and "signingAuthority" +// Type is an enum for trust store types supported type Type string const ( @@ -48,18 +47,18 @@ var ( } ) -// X509TrustStore provide list and get behaviors for the trust store +// X509TrustStore provides list and get behaviors for the trust store type X509TrustStore interface { // GetCertificates returns certificates under storeType/namedStore GetCertificates(ctx context.Context, storeType Type, namedStore string) ([]*x509.Certificate, error) } -// NewX509TrustStore generates a new X509TrustStore +// NewX509TrustStore generates a new [X509TrustStore] func NewX509TrustStore(trustStorefs dir.SysFS) X509TrustStore { return &x509TrustStore{trustStorefs} } -// x509TrustStore implements X509TrustStore +// x509TrustStore implements [X509TrustStore] type x509TrustStore struct { trustStorefs dir.SysFS } diff --git a/verifier/verifier.go b/verifier/verifier.go index 66eef46d..4c759201 100644 --- a/verifier/verifier.go +++ b/verifier/verifier.go @@ -11,7 +11,8 @@ // See the License for the specific language governing permissions and // limitations under the License. -// Package verifier provides an implementation of notation.Verifier interface +// Package verifier provides implementations of [notation.Verifier] and +// [notation.BlobVerifier] interfaces. package verifier import ( @@ -57,7 +58,8 @@ var algorithms = map[crypto.Hash]digest.Algorithm{ crypto.SHA512: digest.SHA512, } -// verifier implements notation.Verifier, notation.BlobVerifier and notation.verifySkipper +// verifier implements [notation.Verifier], [notation.BlobVerifier] and +// notation.verifySkipper interfaces. type verifier struct { ociTrustPolicyDoc *trustpolicy.OCIDocument blobTrustPolicyDoc *trustpolicy.BlobDocument @@ -69,7 +71,7 @@ type verifier struct { } // VerifierOptions specifies additional parameters that can be set when using -// the NewVerifierWithOptions constructor +// the [NewVerifierWithOptions] constructor type VerifierOptions struct { // RevocationClient is an implementation of revocation.Revocation to use for // verifying revocation of code signing certificate chain @@ -88,7 +90,7 @@ type VerifierOptions struct { RevocationTimestampingValidator revocation.Validator } -// NewOCIVerifierFromConfig returns a OCI verifier based on local file system +// NewOCIVerifierFromConfig returns an OCI verifier based on local file system func NewOCIVerifierFromConfig() (*verifier, error) { // load trust policy policyDocument, err := trustpolicy.LoadOCIDocument() @@ -117,19 +119,20 @@ func NewBlobVerifierFromConfig() (*verifier, error) { // NewWithOptions creates a new verifier given ociTrustPolicy, trustStore, // pluginManager, and VerifierOptions. // -// Deprecated: NewWithOptions function exists for historical compatibility and should not be used. -// To create verifier, use NewVerifierWithOptions function. +// Deprecated: NewWithOptions function exists for historical compatibility and +// should not be used. To create verifier, use [NewVerifierWithOptions] function. func NewWithOptions(ociTrustPolicy *trustpolicy.OCIDocument, trustStore truststore.X509TrustStore, pluginManager plugin.Manager, opts VerifierOptions) (notation.Verifier, error) { return NewVerifierWithOptions(ociTrustPolicy, nil, trustStore, pluginManager, opts) } -// NewVerifier creates a new verifier given ociTrustPolicy, trustStore and pluginManager +// NewVerifier creates a new verifier given ociTrustPolicy, trustStore and +// pluginManager func NewVerifier(ociTrustPolicy *trustpolicy.OCIDocument, blobTrustPolicy *trustpolicy.BlobDocument, trustStore truststore.X509TrustStore, pluginManager plugin.Manager) (*verifier, error) { return NewVerifierWithOptions(ociTrustPolicy, blobTrustPolicy, trustStore, pluginManager, VerifierOptions{}) } -// NewVerifierWithOptions creates a new verifier given ociTrustPolicy, blobTrustPolicy, -// trustStore, pluginManager, and verifierOptions +// NewVerifierWithOptions creates a new verifier given ociTrustPolicy, +// blobTrustPolicy, trustStore, pluginManager, and verifierOptions func NewVerifierWithOptions(ociTrustPolicy *trustpolicy.OCIDocument, blobTrustPolicy *trustpolicy.BlobDocument, trustStore truststore.X509TrustStore, pluginManager plugin.Manager, verifierOptions VerifierOptions) (*verifier, error) { if trustStore == nil { return nil, errors.New("trustStore cannot be nil") @@ -160,18 +163,19 @@ func NewVerifierWithOptions(ociTrustPolicy *trustpolicy.OCIDocument, blobTrustPo return v, nil } -// NewFromConfig returns a OCI verifier based on local file system. +// NewFromConfig returns an OCI verifier based on local file system. // -// Deprecated: NewFromConfig function exists for historical compatibility and should not be used. -// To create an OCI verifier, use NewOCIVerifierFromConfig function. +// Deprecated: NewFromConfig function exists for historical compatibility and +// should not be used. To create an OCI verifier, use [NewOCIVerifierFromConfig] +// function. func NewFromConfig() (notation.Verifier, error) { return NewOCIVerifierFromConfig() } // New creates a new verifier given ociTrustPolicy, trustStore and pluginManager. // -// Deprecated: New function exists for historical compatibility and should not be used. -// To create verifier, use NewVerifier function. +// Deprecated: New function exists for historical compatibility and +// should not be used. To create verifier, use [NewVerifier] function. func New(ociTrustPolicy *trustpolicy.OCIDocument, trustStore truststore.X509TrustStore, pluginManager plugin.Manager) (notation.Verifier, error) { return NewVerifier(ociTrustPolicy, nil, trustStore, pluginManager) } @@ -238,7 +242,7 @@ func (v *verifier) SkipVerify(ctx context.Context, opts notation.VerifierVerifyO return false, verificationLevel, nil } -// VerifyBlob verifies the signature of given blob , and returns the outcome upon +// VerifyBlob verifies the signature of given blob, and returns the outcome upon // successful verification. func (v *verifier) VerifyBlob(ctx context.Context, descGenFunc notation.BlobDescriptorGenerator, signature []byte, opts notation.BlobVerifierVerifyOptions) (*notation.VerificationOutcome, error) { logger := log.GetLogger(ctx) @@ -319,7 +323,7 @@ func (v *verifier) VerifyBlob(ctx context.Context, descGenFunc notation.BlobDesc return outcome, outcome.Error } -// Verify verifies the signature associated the target OCI +// Verify verifies the signature associated to the target OCI // artifact with manifest descriptor `desc`, and returns the outcome upon // successful verification. // If nil signature is present and the verification level is not 'skip', diff --git a/verifier/verifier_test.go b/verifier/verifier_test.go index 90f9cb51..faac221b 100644 --- a/verifier/verifier_test.go +++ b/verifier/verifier_test.go @@ -1509,7 +1509,7 @@ func verifyResult(outcome *notation.VerificationOutcome, expectedResult notation } } -// testTrustStore implements truststore.X509TrustStore and returns the trusted certificates for a given trust-store. +// testTrustStore implements [truststore.X509TrustStore] and returns the trusted certificates for a given trust-store. type testTrustStore struct{} func (ts *testTrustStore) GetCertificates(_ context.Context, _ truststore.Type, _ string) ([]*x509.Certificate, error) {