From 3934f92eff684c2cc8004e444e30b9bccb30fb08 Mon Sep 17 00:00:00 2001
From: Lars Wirzenius <liw@liw.fi>
Date: Mon, 28 Feb 2022 15:06:36 +0200
Subject: initial subplot

Sponsored-by: author
---
 hagrid-subplot.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 hagrid-subplot.md

diff --git a/hagrid-subplot.md b/hagrid-subplot.md
new file mode 100644
index 0000000..8c4b3f3
--- /dev/null
+++ b/hagrid-subplot.md
@@ -0,0 +1,79 @@
+---
+title: System tests for Hagrid
+template: python
+bindings:
+- subplot.yaml
+- lib/files.yaml
+functions:
+- subplot.py
+- lib/files.py
+...
+
+# Introduction
+
+This document documents the acceptance criteria for Hagrid, an OpenPGP
+key server. The criteria are expressed against a system running
+Hagrid, on its HTTP API. The [Subplot][] tool can be used to generate
+code that verifies that a Hagrid system works as required.
+
+[Subplot]: https://subplot.tech/
+
+
+# VKS interface
+
+## Lookup certificate by fingerprint
+
+### We can look up an existing certificate
+
+_Requirement: We can retrieve a certificate whose fingerprint we
+have._
+
+FIXME: a well-known test cert must be injected into the running Hagrid
+instance prior to the test, and `EXAMPLEFP` must be replaced with its
+fingerprint.
+
+~~~scenario
+given a running Hagrid system
+given file well-known.pgp
+when I make request GET /vks/v1/by-fingerprint/EXAMPLEFP
+then response HTTP status code is 200
+then response has header content-type: image/jpeg
+then response body matches file well-known.pgp
+~~~
+
+~~~{#well-known.pgp .file}
+FIXME this should be the well-known cert in ASCII armor
+~~~
+
+### We get an error if using lower case hexadecimal
+
+_Requirement: we get an error if we use a fingerprint with lowercase
+hexadecimal digits._
+
+~~~scenario
+given a running Hagrid system
+when I make request GET /vks/v1/by-fingerprint/EXAMPLEFP
+then response HTTP status code is 400
+~~~
+
+### We get an error for a malformed fingerprint
+
+_Requirement: we get an error if we try to retrieve a certificate
+using a string that is not a syntactically valid fingerprint._
+
+~~~scenario
+given a running Hagrid system
+when I make request GET /vks/v1/by-fingerprint/IMPOSSIBLE
+then response HTTP status code is 400
+~~~
+
+### We get an error for a missing fingerprint
+
+_Requirement: we get an error if we try to retrieve a certificate
+that isn't on the server._
+
+~~~scenario
+given a running Hagrid system
+when I make request GET /vks/v1/by-fingerprint/010203
+then response HTTP status code is 400
+~~~
-- 
cgit v1.2.1