[OLD] [Requirement] Trust Policy and Trust Store Configuration

Out of scope

This document doesn't cover glass break mechanism required to bypass signature validation.
This document assumes that here will some mechanism to revoke an artifact. The Artifact level revocation(see) design and working are out of scope.

Requirements

Trust Store Requirements

Deployers who consumes and executes the signed artifact from a registry needs a mechanism to specify the trusted producers. This is where deployer will use Trust Store.

Deployer MUST be able to specify one or more trusted signing identity(keyId, public Key, certificates, etc.).
Deployer MUST be able to scope down the trusted signing identity to a specific repository.

Trust Policy Requirements

Deployers who consumes and executes the signed artifact from a registry needs a mechanism to specify how the artifacts should be evaluated for trust. This is where deployer will use Trust Policy.

Deployer MUST be able to enforce artifact integrity validation. If the artifact integrity validation is enabled and the artifact is unsigned or signature is not valid, the system MUST reject the artifact.
Deployer MUST be able to enforce the artifact expiry validation. The artifact is considered expired if either of artifact's signature, signing identity(e.g., certificate expiry) or timestamp certificate(s) is expired. If artifact expiry validation is enabled and the artifact is expired, the system MUST reject the artifact.
Deployer MUST be able to enforce revoked artifact validation. The artifact is considered as revoked if either of signature, signing identity(e.g., signing certificate) or timestamp certificate(s) is revoked. If revoked artifact validation artifact is enabled and the artifact is revoked, the system MUST reject the artifact.
Trust Policy MUST be extensible to allow deployer to enforce extended(custom) validations based on signature's signed metadata(such as isTested, isScanned).

Design

Trust Store

{
    "trustStore": [
        {
            "identities": {
                "x5c": [
                    "-----BEGIN CERTIFICATE-----rootCertificate1-----END CERTIFICATE-----",
                    "-----BEGIN CERTIFICATE-----rootCertificate2----END CERTIFICATE-----"
                ],
                "tsaX5c": [
                    "-----BEGIN CERTIFICATE-----rootCertificate1-----END CERTIFICATE-----",
                    "-----BEGIN CERTIFICATE-----rootCertificate22-----END CERTIFICATE-----"
                ],
                "key": [
                    "exampleKey2",
                    "exampleKey4"
                ],
                "keyId": [
                    "exampleKeyId2",
                    "exampleKeyId4"
                ]
            },
            "scope": "registry.wabbit-networks1.io"
        },
        {
            "identities": {
                "x5c": [
                    "-----BEGIN CERTIFICATE-----rootCertificate3-----END CERTIFICATE-----",
                ],
            },
            "scope": "registry.wabbit-networks2.io"
        },
        {
            "identities": {
                "x5c": [
                    "-----BEGIN CERTIFICATE-----rootCertificate4-----END CERTIFICATE-----",
                    "-----BEGIN CERTIFICATE-----rootCertificate5-----END CERTIFICATE-----"
                ],
                "tsaX5c": [
                    "-----BEGIN CERTIFICATE-----rootCertificate44-----END CERTIFICATE-----"
                ],
                "key": [
                    "exampleKey1",
                    "exampleKey3"
                ],
                "keyId": [
                    "exampleKeyId1",
                    "exampleKeyId3"
                ]
            }
        }
    ]
}

JSON Key description:
- trustStore: Parent node containing trust store information.
  - identities: The identities that deployer trusts.
    - x5c: The PEM representation of signing certificate.
    - tsaX5c: The PEM representation of timestamp certificate.
    - key: The Base64 encoded verification key.
    - keyId: The ASCII representation of keyId.
  - scope: Adding this field as sibling of identities, scopes down the identities that would be trusted for the artifact matching the scope. Scope supports wildcard(*).
No two children node of trustStore can have overlapping scope.
There can be only one child node of trustStore without scope node.

Evaluation

If an artifact matches the scope, then only the identities associated with scope are trusted for that artifact. e.g., For wabbit-networks2.io registry only rootCertificate3 is trusted.
If an artifact doesn’t match any scope, then the identities without any scope node are trusted for that artifact. e.g., For wabbit-networks999.io registry only rootCertificate5, rootCertificate5, exampleKey1... are trusted.

Trust Policy

Compact mode

{
    "trustPolicy": {
        "EnforceArtifactExpiryValidation": true/false,
        "EnforceArtifactRevocationValidation": "trueWithFailOpen/trueWithFailClose/false"
    }
}

Artifact Integrity Validation

Presence of trust policy means that artifact MUST be integrity validated and that’s the reason it is not explicitly configurable in trustPolicy.
If the artifact integrity validation is enabled and the artifact is unsigned or signature is not valid, the system MUST reject the artifact.

Artifact Expiry Validation

If artifact expiry is enabled and signature expiry is not present in the signature, then system MUST validate for expiry of signing identity and timestamp certificate(s).
If artifact expiry is enabled and signature expiry is present then system MUST validate that signature is not expired. If signature is expired the system MUST reject the artifact.
If artifact expiry is enabled and certificate(s) is used for signing and signature is not timestamped, the system must validate that the certificate(s) is not expired. If certificate(s) is expired the system MUST reject the artifact.
If artifact expiry is enabled and certificate(s) is used for signing, certificate(s) is not expired and signature is timestamped, the system MUST perform following validations
- Validate that timestamp signature if valid. If signature is not valid system MUST reject the artifact.
- If timestamp signature is valid then validate that timestamping certificate is not expired. If timestamping certificate is expired, system MUST reject the artifact.

Revoked Artifact Validation

If revoked artifact validation is enabled and artifact revocation URL is not present in the signature, the system MUST validate revocation of signing identity and timestamp certificate(s).
If artifact revocation validation is enabled and artifact revocation URL is present in the signature, the system MUST validate that artifact is not revoked. If artifact is revoked system MUST reject the artifact.
If artifact revocation validation is enabled and certificate(s) is used for signing artifact, the system MUST validate that certificate(s) is not revoked. If certificate(s) is revoked system MUST reject the artifact.
If artifact revocation validation is enabled, signature is timestamped and signing certificate is expired. The system MUST validate that the timestamp certificate(s) is not revoked. If timestamp certificate(s) is revoked system MUST reject the artifact.

Since revocation requires network call, the trustPolicy should provide option to either fail-open or fail-close in case the revocation URLs are not reachable.

When revocation validation is enforced in trueWithFailOpen mode and revocation URL is unreachable, the system continues to allow the artifact.
When revocation validation is enforced in trueWithFailClose mode and revocation URL is unreachable, the system MUST rejects the artifact.

Extensibility

TBD

Evaluation

Image Not Showing Possible Reasons

The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported

Learn More →

Revocation calls SHOULD be nonblocking.

Signature evaluation steps(in-progress)

Get the signing algorithm(hash+encyption) from signing identity and validate that the signing algorithm is valid and approved one.
Get the public key from signing identity and validate the artifact integrity using the public key and signing algorithm identified in step 1.
Artifact Expiry Validation
1. Validate that artifact signature is not expired using signature expiration time.
2. Validate signing identity expiry.
  1. Validate signing identity( e.g., certificate) is not expired.
  2. If signing identity( e.g., certificate) is expired, check for timestamp signature and validate that timestamp signature is valid and not expired.
  3. Compute and validate that singing certificate + cert chain and timestamp certificate + cert chain is valid and not expired.
Validate that signing identity leads to trusted identities.
Validate that artifact and singing identity is not revoked.
1. If ARL/OASP is present use ARL to check for artifact revocation.
2. In case of signing certificate this will involve validating each certificate in certificate chain for revocation. Similarly, if timestamped was used for signature evaluation check for revocation of timestamp certificate and its certificate chain.

Open Questions

In trust store, should we support keyId? Or it should always be raw public key?
In trust store, what all kind of scope we should support? Is registry sufficient?
In trust policy, what kind of extensibility we are looking for? Should notaryv2 account for this or registry owner like cloud providers can use as per their discretion.
For trust policy, should we support detailed mode(below) or just the compact mode(above in doc)?

# Trust policy Detailed mode

{
    "trustPolicy": {
        "ArtifactExpiryValidations": {
            "EnforceSignatureExpiryValidation": "true/false",
            "EnforceSigningIdentityExpiryValidation": "true/false",
            "EnforceTimestampExpiryValidation": "true/false"
        },
        "ArtifactRevocationValidations": {
            "EnforceSignatureRevocationValidation": "trueWithFailOpen/trueWithFailClose/false",
            "EnforceSigningIdentityRevocationValidation": "trueWithFailOpen/trueWithFailClose/false",
            "EnforceTimestampRevocationValidation": "trueWithFailOpen/trueWithFailClose/false"
        }
    }
}

Glossary

Artifact revocation URL: The signed metadata in the signature that would contain information about how to obtain artifact revocation details.

tags: `notary`

mnltejaswini

2021/08/09 16:46:20

Wouldn't timestamp be present only for cert based signatures? (Edited)

2021/08/09 16:48:25

ing. ## Signature evaluation steps(in-progress) 1. Get the signing algorithm(hash+encyption) from signing identity and validate that the signing a

what is this timestamp field? (Edited)

2021/08/09 16:48:56

What is the purpose of these trustedArtifacts? (Edited)

2021/08/09 16:49:28

can we specifically mention about the format? (Edited)

Sajay Antony

2021/08/24 00:39:19

tore ``` {

Given that a registry access always is scoped to a repository or endpoint. What scenario would need a break glass of a just a digest? I see this as the manifest pointed to by this disgest doesn't have a signature we can validate and hence is a validation bypass. Is that the case here? (Edited)

Pritesh Bandi

2021/08/24 01:04:08

Call out that breakglasss should happen outside the trust policy

2021/08/24 00:43:32

)

manifests don't encode the digest and is of the form `"digest": "sha256:a15ccba7f1ffe496b48587d67e5a49388e0d2031fb7a760eacb2aa1c722cc6c7",` I think we can can follow the same convention for digest to align with the registry. (Edited)

Shiwei Zhang

2021/08/24 00:46:25

SHA-2 is a hash algorithm family. What's the exact hash algorithm? What if we want to change the algorithm in the future? like to SHA-3? (Edited)

2021/08/24 00:48:15

rithm(hash+encyp

Is there a concern about alg:none kind of issues due to JWT here? I'm trying to understand how do we ensure that only a specific profile is applicable. Should that be a trust policy setting or is that out of scope? (Edited)

2021/08/24 18:03:38

Yes, there will be concern around enforcing specific JWS profile. As we dont have enough information about profile, will add this as per-condition

2021/08/24 00:48:20

How about just hash of artifact? verification system can determine which hashing algo to use from signing algo (Edited)

2021/08/24 00:49:14

Stor

Looks everything is flatened. Is it possible to have { "x5c": "aaa", "tsaXc": "bbb", "scope": "ccc" } That is, multiple fields in the same level? (Edited)

2021/08/24 00:51:14

It seems everything except "scope" can be an array. (Edited)

2021/08/24 17:10:37

Yes the json can be flattened. For rev1 I am keeping the json simple to avoid any confusion. Once we have this draft approved we can have rev2 to optimize the json

2021/08/24 00:52:09

ode.

Does it support wildcard? like "registry.wabbit-networks*.io" or "*.wabiit-netowkrs.io" (Edited)

2021/08/24 00:54:50

ed. If artifact expiry validation is enabled and the artifact is expired, the system MUST reject the artif

Reworded (Edited)

2021/08/24 01:03:20

and artifact revocatio

This implies the URL must be signed. (Edited)

2021/08/24 17:35:38

Yep it would signed, added it in glossary

2021/08/24 01:07:06

The digest is hex; (Edited)

2021/08/24 01:10:23

Ok looks like this is for defining a full set of acceptable images that can be run in the system. This sounds like its beyond scope of just signatures and should be handled by other parts like admission controllers or deployment gates. Break glass IMHO should be in scope since we are asking notation to return a result saying that the signature was unable to validate but it was OK'd due the breakglass section as a warning. (Edited)

2021/08/24 01:12:02

red. The system MUST validate that the timestamp certificate(s) is not revoked. If timestamp certificate(s) is revoked system MUST reject the arti

Do we need to specify how to verify the timestamp certificate is revoked? (Edited)

2021/08/24 01:12:31

Signatures have ARL. Then timestamp cerificate use CRL?

2021/08/24 17:55:29

How the revocation works is outside the scope of this doc. Timestamp certificate revocation is similar to codesigning/tls certificate revocation, user need to either use CRL or OCSP. So(this is how i am envisioning) there will be 3 type of revocation : 1. artifact revocation: for individual artifact 2. signing certificate + certificate chain revocation 3. timestamp certificate + certificate chain revocation

2021/08/24 01:13:41

the revocatio

Can we specify different revocation validitions for signatures and timestamp certs? (Edited)

2021/08/24 01:19:46

Add JWS profile evaluation/validation check. Get more info on JWS profile. (Edited)

Ian M

2021/08/30 14:51:58

Deployer MUST be able to specify one or more trusted signing identity(keyId, public Key, certificates, etc.).

Trusted signing identity includes an identity that chains to a trust anchor such as a root CA. (Edited)

2021/08/30 15:05:10

integrity validation

Is signing artifacts the only way to achieve integrity validation? This the typical question when integrity is listed/stated a singular goal, so we should say signature validation includes integrity + authenticity validation. I feel "trust" is more than integrity, so when you add that authenticity validation against a publishers key/cert (and the chain it is signed by) you are achieving a validation of trust in the artifact's integrity and authenticity of the publishers/producer that signed it. (Edited)

2021/08/30 15:09:02

timestamp certificate(s) is expired

TSA cert expiry shouldn't matter as long as the timestamp signature was inside the validity date range of both the signing identity's cert and the TSA's cert. This essentially makes a signed + timestamped artifact's signature like a "diamond"....it is forever (unless revoked or invalidated). (Edited)

2021/08/30 15:46:59

that timestamping certificate is not expired

See previous comment regarding TSA cert validity as part of validation. (Edited)

2021/08/31 16:38:53

Good point, will add that. (Edited)

2021/08/31 23:08:09

Like the idea of infinite validity(unless explicitly revoked) but TSArfc3161 says that signature should be valid until the timestamping cert is valid and artifact should be resigned when timestamp certificate expires. https://datatracker.ietf.org/doc/html/rfc3161#section-4 (Edited)

2021/08/31 23:08:17

RFC: “The TSA signing key MUST be of a sufficient length to allow for sufficiently long lifetime. Even if this is done, the key will have a finite lifetime. Thus, any token signed by the TSA SHOULD be time-stamped again (if authentic copies of old CRLs are available) or notarized (if they aren't) at a later date to renew the trust that exists in the TSA's signature. time-stamp tokens could also be kept with an Evidence Recording Authority to maintain this trust.” (Edited)

2021/08/31 23:08:50

Also, I’m concerned about following use cases: As per CA/B guideline, CAs are only required to keep revoked certificate in CRL for 10 years, which means that after 10 years the invalid artifact(revoked) becomes valid. (Edited)

2021/08/31 23:11:07

CA/B: "CAs MUST issue CRLs, and the serial number of a revoked certificate MUST remain on the CRL for at least 10 years after the expiration of the certificate." https://cabforum.org/wp-content/uploads/Baseline-Requirements-for-the-Issuance-and-Management-of-Code-Signing.v2.3.pdf (Edited)

[OLD] [Requirement] Trust Policy and Trust Store Configuration

Out of scope

Requirements

Trust Store Requirements

Trust Policy Requirements

Design

Trust Store

Evaluation

Trust Policy

Artifact Integrity Validation

Artifact Expiry Validation

Revoked Artifact Validation

Extensibility

Evaluation

Signature evaluation steps(in-progress)

Open Questions

Glossary

tags: notary

Read more

Untitled

Sign arbitrary data

Notation Debug Logs

[Draft] Verification extensibility

tags: `notary`