[Draft] Trust Policy and Trust Store Configuration

[sudo-bmitch]

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": {
        "wabbit-networks.io": {
            "identities": {
                "x5c": [
                    "-----BEGIN CERTIFICATE-----rootCertificate1-----END CERTIFICATE-----",
                    "-----BEGIN CERTIFICATE-----rootCertificate2----END CERTIFICATE-----"
                ],
                "tsaX5c": [
                    "-----BEGIN CERTIFICATE-----rootCertificate11-----END CERTIFICATE-----",
                    "-----BEGIN CERTIFICATE-----rootCertificate22-----END CERTIFICATE-----"
                ],
                "key": [
                    "exampleKey2",
                    "exampleKey4"
                ],
                "keyId": [
                    "exampleKeyId2",
                    "exampleKeyId4"
                ]
            },
        },
        "dev.wabbit-networks.io": {
            "identities": {
                "x5c": [
                    "-----BEGIN CERTIFICATE-----rootCertificate3-----END CERTIFICATE-----",
                ],
                "key": [
                    "exampleKey1",
                    "exampleKey3"
                ],
                "keyId": [
                    "exampleKeyId1",
                    "exampleKeyId3"
                ]
            },
        },
        "docker.io": {
            "identities": {
                "x5c": [
                    "-----BEGIN CERTIFICATE-----rootCertificate4-----END CERTIFICATE-----",
                    "-----BEGIN CERTIFICATE-----rootCertificate5-----END CERTIFICATE-----"
                ],
                "tsaX5c": [
                    "-----BEGIN CERTIFICATE-----rootCertificate44-----END CERTIFICATE-----"
                ]
            }
        }
    }
}

• JSON Key description:
  • trustStore: Parent node containing trust store information. Each named entry can be referenced in the trust policy.
    • 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.

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

{
  "trustPolicies": [
    {
      "PolicyName": "Wabbit Corp",
      "Scopes": ["*"],
      "TrustStores": [ "wabbit-networks.io" ],
      "EnforceArtifactExpiryValidation": "enabled/disabled",
      "EnforceArtifactRevocationValidation": "enabledWithFailOpen/enabledWithFailClose/disabled"
    },
    {
      "PolicyName": "Wabbit Dev",
      "Scopes": ["dev.wabbit-networks.io"],
      "TrustStores": [ "dev.wabbit-networks.io" ],
      "EnforceArtifactExpiryValidation": "enabled/disabled",
      "EnforceArtifactRevocationValidation": "enabledWithFailOpen/enabledWithFailClose/disabled"
    },
    {
      "PolicyName": "Docker Hub",
      "Scopes": ["docker.io/library", "mirror.wabbit-networks.io/hub"],
      "TrustStores": [ "docker.io" ],
      "EnforceArtifactExpiryValidation": "enabled/disabled",
      "EnforceArtifactRevocationValidation": "enabledWithFailOpen/enabledWithFailClose/disabled"
    }
  ]
}

Detailed mode

{
  "trustPolicies": [
    {
      "PolicyName": "userDefinedName",
      "Scopes": ["registry.example.com"],
      "TrustStores": [ "store1", "store2" ],
      "ArtifactExpiryValidations": {
          "EnforceSignatureExpiryValidation": "enabled/disabled",
          "EnforceSigningIdentityExpiryValidation": "enabled/disabled",
          "EnforceTimestampExpiryValidation": "enabled/disabled"
      },
      "ArtifactRevocationValidations": {
          "EnforceSignatureRevocationValidation": "enabledWithFailOpen/enabledWithFailClose/disabled",
          "EnforceSigningIdentityRevocationValidation": "enabledWithFailOpen/enabledWithFailClose/disabled",
          "EnforceTimestampRevocationValidation": "enabledWithFailOpen/enabledWithFailClose/disabled"
      }
    }
  ]
}

Artifact Integrity Validation

• At least one trust policy MUST be successful to validate the artifact.
• 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 enabledWithFailOpen mode and revocation URL is unreachable, the system continues to allow the artifact.
• When revocation validation is enforced in enabledWithFailClose mode and revocation URL is unreachable, the system MUST rejects the artifact.

Extensibility

TBD

Evaluation

• Revocation calls SHOULD be nonblocking.

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, should we support keyId? Or it should always be raw public key?
2. In trust policy, what all kind of scope we should support? Is registry sufficient?
3. In trust policy, what kind of extensibility we are looking for? Should Notation account for this or registry owner like cloud providers can use as per their discretion.
4. For trust policy, should we support detailed mode or just the compact mode?
5. How should multiple signatures requirements be represented in the trust policy?
6. Should local revocation and TSA servers be listed in the trust policy to support disconnected environments?
7. Do we want to consider client side warnings (instead of only hard failures) in the trust policy, or leave that out of scope?
8. Should there be an option to have a policy for a scope without any trust store and permit all content (to support a developer's local registry, or scenarios where users only validate content from secure repositories but want to be able to run images from anywhere)?

Glossary

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

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