[Draft] Trust Policy and Trust Store Configuration

[priteshbandi]

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

Deployer 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

Deployer 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

* Revocation calls SHOULD be non-blocking.

Signature evaluation steps(in-progress)

1. Get the signing algorithm(hash+encyption) from signing identity and validate that the signing algorithm is valid and approved one.
2. Get the public key from signing identity and validate the artifact integrity using the public key and signing algorithm identified in step 1.
3. 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.
4. Validate that signing identity leads to trusted identities.
5. 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

1. In trust store, what all kind of scope we should support? Is registry sufficient?

initially we will only support registry/namespace for scope and it will work like startsWith instead of regex. If there are overlapping scopes then the closest match will be used for evaluation. E.g. For an image wabbit-networks.io/software/dotnet/ocp-release if there are two overlapping scopes registry.wabbit-networks.io/software and registery.wabbit-networks.io/software/dotnet then closest matching scope i..e registry.wabbit-networks.io/software/dotnet will be used for evaluation.

2. Should we add scope support for trust policy?
3. In trust store, should we support keyId? Or it should always be raw public key?
4. 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.
5. For trust policy, should we support detailed mode(below) or just the compact mode(above in doc)? There might be a usecase where deployer might want to ignore revocation/exprity of timestamp certificate until they have freshly signed artifact.

# 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.

HackMD Doc: https://hackmd.io/s2mrFDOLQuWrV8Ib7ad7Ag

[SteveLasker]

Deployer MUST be able to scope down the trusted signing identity to a specific repository.

This goes back to the artifact and location of the artifact are decoupled. Can we tie this back to the root of trust conversation?

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.

There was a break-glass scenario, where a deployer can choose to continue using an artifact that has been revoked as the revocation/denial of the artifact being used can be more destructive to a users environment. This is a choice of the deployer, so it is an explicit choice.

In trust store, what all kind of scope we should support? Is registry sufficient?

If we're going to limit a scope to a registry, we should limit to a registry/namespace as different registries are shared across companies (docker hub) while multiple teams may share a common company registry

[justincormack]

Scoping to a single repository may be useful for a specific endpoint (eg in this cluster I get my content from this registry only, and I know that the Microsoft images there are stored under microsoft/ so I want to check that. If you assume that content is completely mobile then you have to accept content based on verified signature only, which is simpler to configure and will probably work fine for many use cases, so the location scopes will be irrelevant (so we would want to allow wildcard scopes in this structure).

[priteshbandi]

Will update doc to use registry/namespace for scope, supporting prefix match(not regex) .

[mtrmac]

In trust store, what all kind of scope we should support? Is registry sufficient?

No, consider public registries like quay.io or docker.io with a single host name but many vendors. I’d expect arbitrarily-deep namespace/repo structures, with the closest match governing (and no inheritance from parents, so that I can have a general docker.io key and a specific docker.io/vendor key for that vendor that doesn’t trust the docker.io key).

[SteveLasker]

So, you want to limit all signed content by docker to a specific vendor, without using a vendors key? Or, another example might be you want to limit all Microsoft signed content under MCR to a specific group of software, such as Dynamics or dotnet. That does make more sense and is a good example of scoping.

[mtrmac]

No, I have a direct relationship with the vendor, I know the vendor’s key, and I want to trust only the vendor’s key even if the repo is hosted on a public registry and the operator of that public registry is otherwise signing everything with the operator’s key (and I would otherwise check for the registry operator’s signature for all other repos on that registry).

I want end-to-end security with that vendor: I know the right key, and that vendor is important to me.
For other vendors on that registry, I don’t have a relationship, and I fall back on the registry operator’s signature just because it is better than nothing.

[priteshbandi]

Makes sense. Will update doc to use registry/namespace for scope, supporting prefix match(not regex).

[mtrmac]

If these files are at all expected to be human-written, the field names feel rather unergonomic — x5c is one extreme, too short and obscure, and EnforceSigningIdentityRevocationValidation is another extreme, too long that no—one is going to exactly remember (or probably even type without mistakes at a first try).

[priteshbandi]

The filed names are for only reference purpose, to get the discussion going. Will update field names during actual PR creation.

[mtrmac]

I don’t think the separation of trustStore and trustPolicy is quite practical: consider a disconnected site with a single local registry, which contains both locally-produced artifacts and external, mirrored ones. The user would like full signature validation (with expiration/revocation checks) for the locally-produced artifacts, and a disconnected-relaxed validation (with no revocation checks at all, and with expiration either disabled or relaxed by weeeks/months/years) for the external, mirrored artifacts.

[priteshbandi]

Are you suggesting both trustpolicy and truststore should have scope, thus allowing different trust + different level of signature validation enforcement for different registries OR combing the both policies into one document(like below)?

The rationale behind keeping trustpolicy and truststore separate is that, it will allow reuse by storing them separately. Usually in an organization there would few trust stores(trust anchors) while trust policy might vary from product to product.

[
    {
        "trustStore": {
            "x5c": [...],
            ...
        },
        "trustPolicy": {
            "EnforceArtifactExpiryValidation": "true/false",
            "EnforceArtifactRevocationValidation": "trueWithFailOpen/trueWithFailClose/false"
        },
        "scope": "registry.wabbit-networks1.io/dev/dotnet"
    },
    ...
]

[mtrmac]

Yes, I think it’s important to have the trustPolicy scoped.

I don’t have a strong opinion on whether they should share a scope hierarchy, or each have their own, but I wouldn’t personally start with the more complex user-facing approach of two separate hierarchies when the simple thing would probably work.

(I’d actually expect the opposite: trust policy with only a few broad scopes like local images / imported images / mirrored images, but scopes quite detailed, with one set of keys for each vendor or even each product. But I don’t have any data.)

[mtrmac]

Scope supports wildcard(*).

That’s going to create ambiguities and hard-to-reason behavior (quay.io/*/product vs quay.io/vendor/* vs quay.io/*/product* vs…). I’d much rather not have that, and just do “parent namespaces” (quay.io/vendor matches quay.io/vendor/anything)

[SteveLasker]

+1 to scoping namespaces, but not support wildcards.

[mtrmac]

For gradual deployment, it is very necessary to allow partial signature enforcement — e.g. enforce signatures on my registry, but impose no requirements at all on docker.io. That also naturally extends to “enforce signatures on my registry, and prohibit any use of docker.io at all”.

[justincormack]

I wonder if we can split the necessary parts (ie you must validate signatures correctly) from more generic policy choices and allow those to be determined by a more generic policy engine (eg OPA)?

[SteveLasker]

I do like the separation of concerns application here:

• leverage network policies for registries - although I do see the layered option for registry/repo scoping
• OPA and other policy managers for more details

[sudo-bmitch]

I posted my version over at #100. The big changes I'm suggesting:

• Remove scope from the trust store, this should only be a collection of keys, possibly something that could reference one or more external stores (KMS).
• Give each trust store entry a name that can be referenced in the policy.
• Extend the policy to be an array of policies, with references to trust stores, scopes, and other policies joined there. At least one match would be needed to consider the signature valid.

I've added a few more questions in mine, mostly around the developer experience:

• Should we allow the policy to define scopes that do not need any signatures (a local developer registry, or perhaps they only opt into checking signatures for images on a single secure registry but still want to run other images as a developer).
• If/how we want to list revocation servers or TSAs in the policy for disconnected environments.
• How to handle "multiple signatures are needed", perhaps from separate trust stores, in the policy.

Note that I see a lot of this as lower priority. If the signing and server side is working, different vendors can make different Notation clients that handle all of these use cases and more. Having a Notation client that becomes the reference implementation that many can use without forking would be a nice to have.

[shizhMSFT]

For the signature evaluation process, we should verify the signing identity first and then the actual artifact signature.