1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
# notation policy
## Description
As part of signature verification workflow of signed OCI artifacts, users need to configure trust policy configuration file to specify trusted identities that signed the artifacts, the level of signature verification to use and other settings. For more details, see [trust policy specification and examples](https://github.com/notaryproject/specifications/blob/v1.1.0-rc.1/specs/trust-store-trust-policy.md#trust-policy).
The `notation policy` command provides a user-friendly way to manage trust policies for signed OCI images. It allows users to show trust policy configuration, import/export a trust policy configuration file from/to a JSON file.
To get started, user can refer to the following trust policy configuration sample `trustpolicy.json` that is applicable for verifying signed OCI artifacts using `notation verify` command. In this sample, there are four policies configured for different requirements:
- The Policy named "wabbit-networks-images" is for verifying OCI artifacts signed by Wabbit Networks and stored in two repositories `registry.acme-rockets.io/software/net-monitor` and `registry.acme-rockets.io/software/net-logger`.
- Policy named "unsigned-image" is for skipping the verification on unsigned OCI artifacts stored in repository `registry.acme-rockets.io/software/unsigned/net-utils`.
- Policy "allow-expired-images" is for logging instead of failing expired OCI artifacts stored in repository `registry.acme-rockets.io/software/legacy/metrics`.
- Policy "global-policy-for-all-other-images" is for verifying any other OCI artifacts that signed by the ACME Rockets.
```jsonc
{
"version": "1.0",
"trustPolicies": [
{
"name": "wabbit-networks-images",
"registryScopes": [
"registry.acme-rockets.io/software/net-monitor",
"registry.acme-rockets.io/software/net-logger"
],
"signatureVerification": {
"level": "strict"
},
"trustStores": [
"ca:wabbit-networks",
],
"trustedIdentities": [
"x509.subject: C=US, ST=WA, L=Seattle, O=wabbit-networks.io, OU=Security Tools"
]
},
{
"name": "unsigned-image",
"registryScopes": [ "registry.acme-rockets.io/software/unsigned/net-utils" ],
"signatureVerification": {
"level" : "skip"
}
},
{
"name": "allow-expired-images",
"registryScopes": [ "registry.acme-rockets.io/software/legacy/metrics" ],
"signatureVerification": {
"level" : "strict",
"override" : {
"expiry" : "log"
}
},
"trustStores": ["ca:acme-rockets"],
"trustedIdentities": ["*"]
},
{
"name": "global-policy-for-all-other-images",
"registryScopes": [ "*" ],
"signatureVerification": {
"level": "strict"
},
"trustStores": [
"ca:acme-rockets"
],
"trustedIdentities": [
"x509.subject: C=US, ST=WA, L=Seattle, O=acme-rockets.io, CN=SecureBuilder"
]
}
]
}
```
## Outline
### notation policy command
```text
Manage trust policy configuration for signature verification.
Usage:
notation policy [command]
Available Commands:
import import trust policy configuration from a JSON file
show show trust policy configuration
Flags:
-h, --help help for policy
```
### notation policy import
```text
Import trust policy configuration from a JSON file
Usage:
notation policy import [flags] <file_path>
Flags:
--force override the existing trust policy configuration, never prompt
-h, --help help for import
```
### notation policy show
```text
Show trust policy configuration
Usage:
notation policy show [flags]
Flags:
-h, --help help for show
```
## Usage
### Import trust policy configuration from a JSON file
An example of import trust policy configuration from a JSON file:
```shell
notation policy import ./my_policy.json
```
The trust policy configuration in the JSON file should be validated according to [trust policy properties](https://github.com/notaryproject/specifications/blob/v1.1.0-rc.1/specs/trust-store-trust-policy.md#trust-policy-properties). A successful message should be printed out if trust policy configuration are imported successfully. Error logs including the reason should be printed out if the importing fails.
If there is an existing trust policy configuration, prompt for users to confirm whether discarding existing configuration or not. Users can use `--force` flag to discard existing trust policy configuration without prompt.
### Show trust policies
Use the following command to show trust policy configuration:
```shell
notation policy show
```
Upon successful execution, the trust policy configuration is printed out to standard output. If trust policy is not configured or is malformed, users should receive an error message via standard error output, and a tip to import trust policy configuration from a JSON file.
### Export trust policy configuration into a JSON file
Users can redirect the output of command `notation policy show` to a JSON file.
```shell
notation policy show > ./trustpolicy.json
```
### Update trust policy configuration
The steps to update trust policy configuration:
1. Export trust policy configuration into a JSON file.
```shell
notation policy show > ./trustpolicy.json
```
2. Edit the exported JSON file "trustpolicy.json", update trust policy configuration and save the file.
3. Import trust policy configuration from the file.
```shell
notation policy import ./trustpolicy.json
```
|
