# [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](https://hackmd.io/2rc07WwHTdmPjpgoMbvYfA?view#Artifact-level-revocation)) 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
* 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.
1. Get the public key from signing identity and validate the artifact integrity using the public key and signing algorithm identified in step 1.
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.
1. Validate that signing identity leads to trusted identities.
1. Validate that artifact and singing identity is not revoked.
1. If ARL/OASP is present use ARL to check for artifact revocation.
1. 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`