evan.jarrett.net
A container registry that uses the AT Protocol for manifest storage and S3 for blob storage.
atcr.io
docker
container
atproto
go
1# Ratify ATProto Verifier Plugin
2
3This is a reference implementation of a Ratify verifier plugin for ATProto signatures.
4
5## Overview
6
7Ratify is a verification framework that integrates with OPA Gatekeeper to enforce signature policies in Kubernetes. This plugin adds support for verifying ATProto signatures on ATCR container images.
8
9## Architecture
10
11```
12Kubernetes Pod Creation
13 ↓
14OPA Gatekeeper (admission webhook)
15 ↓
16Ratify (verification engine)
17 ↓
18ATProto Verifier Plugin ← This plugin
19 ↓
20 1. Fetch signature artifact from registry
21 2. Parse ATProto signature metadata
22 3. Resolve DID to public key
23 4. Fetch repository commit from PDS
24 5. Verify ECDSA K-256 signature
25 6. Check trust policy
26 ↓
27 Return: Allow/Deny
28```
29
30## Files
31
32- `verifier.go` - Main verifier implementation
33- `config.go` - Configuration and trust policy
34- `resolver.go` - DID and PDS resolution
35- `crypto.go` - K-256 signature verification
36- `Dockerfile` - Build custom Ratify image with plugin
37- `deployment.yaml` - Kubernetes deployment manifest
38- `verifier-crd.yaml` - Ratify Verifier custom resource
39
40## Prerequisites
41
42- Go 1.21+
43- Ratify source code (for building plugin)
44- Kubernetes cluster with OPA Gatekeeper installed
45- Access to ATCR registry
46
47## Building
48
49```bash
50# Clone Ratify
51git clone https://github.com/ratify-project/ratify.git
52cd ratify
53
54# Copy plugin files
55cp -r /path/to/examples/plugins/ratify-verifier plugins/verifier/atproto/
56
57# Build plugin
58CGO_ENABLED=0 go build -o atproto-verifier \
59 -ldflags="-w -s" \
60 ./plugins/verifier/atproto
61
62# Build custom Ratify image with plugin
63docker build -f Dockerfile.with-atproto -t atcr.io/atcr/ratify-with-atproto:latest .
64```
65
66## Deployment
67
68### 1. Deploy Ratify with Plugin
69
70```bash
71# Push custom image
72docker push atcr.io/atcr/ratify-with-atproto:latest
73
74# Deploy Ratify
75kubectl apply -f deployment.yaml
76```
77
78### 2. Configure Verifier
79
80```bash
81# Create Verifier custom resource
82kubectl apply -f verifier-crd.yaml
83```
84
85### 3. Configure Trust Policy
86
87```bash
88# Create ConfigMap with trust policy
89kubectl create configmap atcr-trust-policy \
90 --from-file=trust-policy.yaml \
91 -n gatekeeper-system
92```
93
94### 4. Create Gatekeeper Constraint
95
96```bash
97kubectl apply -f constraint.yaml
98```
99
100### 5. Test
101
102```bash
103# Try to create pod with signed image (should succeed)
104kubectl run test-signed --image=atcr.io/alice/myapp:latest
105
106# Try to create pod with unsigned image (should fail)
107kubectl run test-unsigned --image=atcr.io/malicious/fake:latest
108```
109
110## Configuration
111
112### Trust Policy Format
113
114```yaml
115# trust-policy.yaml
116version: 1.0
117
118trustedDIDs:
119 did:plc:alice123:
120 name: "Alice (DevOps)"
121 validFrom: "2024-01-01T00:00:00Z"
122 expiresAt: null
123
124 did:plc:bob456:
125 name: "Bob (Security)"
126 validFrom: "2024-06-01T00:00:00Z"
127 expiresAt: "2025-12-31T23:59:59Z"
128
129policies:
130 - name: production
131 scope: "atcr.io/*/prod-*"
132 require:
133 signature: true
134 trustedDIDs:
135 - did:plc:alice123
136 - did:plc:bob456
137 action: enforce
138```
139
140### Verifier Configuration
141
142```yaml
143apiVersion: config.ratify.deislabs.io/v1beta1
144kind: Verifier
145metadata:
146 name: atproto-verifier
147spec:
148 name: atproto
149 artifactType: application/vnd.atproto.signature.v1+json
150 address: /.ratify/plugins/atproto-verifier
151 parameters:
152 trustPolicyPath: /config/trust-policy.yaml
153 didResolverTimeout: 10s
154 pdsTimeout: 10s
155 cacheEnabled: true
156 cacheTTL: 300s
157```
158
159## Implementation Details
160
161### Verifier Interface
162
163The plugin implements Ratify's `ReferenceVerifier` interface:
164
165```go
166type ReferenceVerifier interface {
167 Name() string
168 Type() string
169 CanVerify(artifactType string) bool
170 VerifyReference(
171 ctx context.Context,
172 subjectRef common.Reference,
173 referenceDesc ocispecs.ReferenceDescriptor,
174 store referrerstore.ReferrerStore,
175 ) (VerifierResult, error)
176}
177```
178
179### Verification Flow
180
1811. **Artifact Fetch**: Download signature artifact from registry via Ratify's store
1822. **Parse Metadata**: Extract ATProto signature metadata (DID, PDS, commit CID)
1833. **DID Resolution**: Resolve DID to public key via PLC directory or did:web
1844. **Commit Fetch**: Get repository commit from PDS via XRPC
1855. **Signature Verify**: Verify ECDSA K-256 signature over commit bytes
1866. **Trust Check**: Validate DID against trust policy
1877. **Result**: Return success/failure with metadata
188
189### Error Handling
190
191The plugin returns detailed error information:
192
193```go
194type VerifierResult struct {
195 IsSuccess bool
196 Name string
197 Type string
198 Message string
199 Extensions map[string]interface{}
200}
201```
202
203**Extensions include:**
204- `did` - Signer's DID
205- `handle` - Signer's handle (if available)
206- `signedAt` - Signature timestamp
207- `commitCid` - ATProto commit CID
208- `pdsEndpoint` - PDS URL
209- `error` - Error details (if verification failed)
210
211## Troubleshooting
212
213### Plugin Not Found
214
215```bash
216# Check plugin is in image
217kubectl exec -n gatekeeper-system deployment/ratify -c ratify -- ls -la /.ratify/plugins/
218
219# Check logs
220kubectl logs -n gatekeeper-system deployment/ratify -c ratify
221```
222
223### Verification Failing
224
225```bash
226# Check Ratify logs for details
227kubectl logs -n gatekeeper-system deployment/ratify -c ratify | grep atproto
228
229# Check Verifier status
230kubectl get verifier atproto-verifier -o yaml
231
232# Test DID resolution manually
233curl https://plc.directory/did:plc:alice123
234```
235
236### Trust Policy Issues
237
238```bash
239# Check ConfigMap exists
240kubectl get configmap atcr-trust-policy -n gatekeeper-system
241
242# View policy contents
243kubectl get configmap atcr-trust-policy -n gatekeeper-system -o yaml
244```
245
246## Performance Considerations
247
248### Caching
249
250The plugin caches:
251- DID documents (TTL: 5 minutes)
252- PDS endpoints (TTL: 5 minutes)
253- Public keys (TTL: 5 minutes)
254
255Configure via `cacheEnabled` and `cacheTTL` parameters.
256
257### Timeouts
258
259Configure timeouts for external calls:
260- `didResolverTimeout` - DID resolution (default: 10s)
261- `pdsTimeout` - PDS XRPC calls (default: 10s)
262
263### Rate Limiting
264
265Consider implementing rate limiting for:
266- DID resolution (PLC directory)
267- PDS XRPC calls
268- Signature verification
269
270## Security Considerations
271
272### Trust Policy Management
273
274- Store trust policy in version control
275- Review DID additions/removals carefully
276- Set expiration dates for temporary access
277- Audit trust policy changes
278
279### Private Key Protection
280
281- Plugin only uses public keys
282- No private keys needed for verification
283- DID resolution is read-only
284- PDS queries are read-only
285
286### Denial of Service
287
288- Implement timeouts for all external calls
289- Cache DID documents to reduce load
290- Rate limit verification requests
291- Monitor verification latency
292
293## See Also
294
295- [Ratify Documentation](https://ratify.dev/)
296- [Ratify Plugin Development](https://ratify.dev/docs/plugins/verifier/overview)
297- [ATCR Signature Integration](../../../docs/SIGNATURE_INTEGRATION.md)
298- [ATCR Integration Strategy](../../../docs/INTEGRATION_STRATEGY.md)
299
300## Support
301
302For issues or questions:
303- GitHub Issues: https://github.com/atcr-io/atcr/issues
304- Ratify GitHub: https://github.com/ratify-project/ratify