Worked use case template
A blank in the shape of a worked use case. Each section below says what belongs in it, why that part has to come before the next one, and how to tell when it is finished. Copy this page, work down it, and delete the instructions as you replace them. The PQC migration page is the same shape filled in, and is worth reading alongside this one.
Starting one
Five mechanical steps, none of which involve writing prose.
- Copy this file to
docs/use-cases/<short-name>.html. The short name becomes part of the URL and is awkward to change later, so pick the consumer's word for the thing rather than the working group's. - Change the front matter
nav:value touc-<short-name>. - Add one line to the first group in
docs/_data/usecases_nav.yml, with the same id. - Add one row to the table on the section overview, with the state set to draft.
- Fix the previous and next links in the footer of this page and of its new neighbours. This section's footer links are written by hand;
tools/renumber-pagenav.pymanages the methodology's and will not touch these.
Then work down the eight sections. They are in dependency order, which is the reason for doing them in order rather than a matter of presentation: section three cannot be done without section one, and section four cannot be reviewed without section six.
1 · The decision being supported
Name the consumer, the actions it is choosing between, and the questions it has to answer to choose. All three, not just the first. A consumer without actions is an audience, and a profile written for an audience has no principled place to stop.
The test is whether a reader could disagree with you. "A security team wants visibility of its cryptography" is not a decision and cannot be argued with. "A fleet operator is choosing, per device model, between update in place, replace, and accept with a compensating control" can be: someone can say that a fourth option exists, or that two of these are really one.
The consumer. Who is reading the CBOM and acting on it. A role, not an organisation.
The actions. Two or more, mutually exclusive, each with a different cost. If you can only think of one, the use case is a reporting requirement rather than a decision, which is a different and usually cheaper thing to serve.
The questions. Three to five. Each one has to be answerable from a document, or it belongs to a different process.
Why the existing profiles do not already answer them. If the interface disclosure baseline answers them all, stop here and say so on the overview page. That is a good outcome, not a failed one.
2 · The constraint the producer is under
What the party filling the document in can actually observe. This section is what keeps the profile satisfiable, and skipping it is the most common way to produce a profile nobody can conform to.
The PQC migration profile has one constraint, the black box: the vendor will not expose internals, so every attribute must be declarable at the boundary. Yours may have others. A producer may not know how its product is deployed. It may know at manufacture and not afterwards. It may be a different party from the one the consumer is asking.
Who produces the document, and whether that is the same party the consumer is in a relationship with.
What they can observe, and at what moment. Design time, build time, ship time and run time give different answers, and capture phase is how the document says which one it is.
What they will not disclose even though they know it, and whether the profile should permit that as a withholding or require it outright.
A diagram, if the constraint is structural. The migration page draws its black box because the shape of the constraint is the argument for the shape of the profile.
3 · From questions to attributes
Take each question from section one and turn it into one fact that can be declared at the boundary. Work in that direction. Starting from the fields a format happens to offer produces a profile with no stated purpose and no way to argue about whether it asks for the right things.
Record the questions that do not survive. A question that cannot be turned into a declarable fact is a finding about the limits of a CBOM, and it is worth more written down than dropped.
A two-column table: what the consumer needs to know against the attribute that supplies it. One row per question, and more than one row per question where the answer needs several facts.
For each attribute, say whether it already exists in the baseline, exists under a different name, or is new to this profile. Reusing a name means inheriting its meaning; Method has the naming conventions and they are not optional.
Then the questions that did not survive, with the reason each one failed. Usually: not observable by the producer, or a judgement rather than a fact.
4 · The profile definition
The rules. State which profile this one extends, then list what it adds and what it tightens. Do not restate inherited rules as though they were yours; the base profile remains authoritative for them, and repeating them creates two places to maintain one requirement.
Rules are numbered in this profile's own space, from P1, I1 and G1, and cited against this profile's tag. A tightened rule keeps the id of the profile that introduced it. Profile has the scheme and Objects has the identity rules.
The relationship to the base. One table with three rows: inherited unchanged, tightened, added.
Product-level rules, per-interface rules and group rules, each with a conformance level and a note saying what the rule is for. The note is what a reviewer argues with.
Every tightening, with its justification. A tightening removes an option the base profile deliberately offered, so each one owes the reader a reason. Remember that extension is monotonic: you may add and tighten, never relax.
Conditional rules. A rule that applies only under a stated condition, with the condition written as something checkable rather than as advice.
5 · A worked interface
One real interface with every required attribute filled in, so the rules can be read against something concrete. This is the section reviewers use, and it routinely shows up problems the rule table hides: an attribute with no sensible value, two attributes that cannot both be true, a MUST that the producer has no way to satisfy.
One interface, named and typed, with each attribute the profile requires and a plain-language column saying what the value tells the consumer.
At least one attribute where the honest answer is unknown or withheld, if the profile permits either. A worked example in which everything is known is not the case the profile has to survive.
6 · What the profile deliberately excludes
Each exclusion with its reason. Without this section the profile cannot be reviewed, because a reader cannot tell an exclusion that was argued from an attribute nobody thought of.
Two exclusions are likely to apply to any profile and are worth stating even when they feel obvious. Verdicts and scores belong in a policy rather than a profile, because the criteria change and the document does not. Internal implementation detail is out of scope wherever the producer is a vendor, and asking for it produces a profile nobody satisfies.
Each excluded attribute or class of attribute, with the reason. "Not needed for this decision" is a reason. "We could not agree" is also a reason, and should be recorded as an open question rather than presented as a choice.
Anything a reader of the base profile would expect to see here and will not find.
7 · Expressing it in a CBOM
How the attributes land in the formats, and which of them have no native field. The attribute list is format-independent by design; this section is where that design meets CycloneDX and SPDX. Formats has the encoding conventions.
Which attributes map to native fields, and which are carried as properties under the pkic:profile: namespace.
Anything structural that the mapping makes awkward. Lists where the baseline holds single values are the usual one, and the usual failure is a consumer that cannot tell an empty list from an absent one, or either from a withheld one.
What the four disclosure outcomes mean here, and specifically what a producer should record when it does not know rather than guessing.
8 · Recorded decisions and open questions
What was settled while writing it, and what was not. A decision taken during the work and not written down will be reopened, usually by the person who took it.
Decision records for any choice made against a more obvious alternative. One file in decisions/ each, with the options, the rationale and what reversing it would involve, plus a row in the decisions README. Summarise them here and link out; the record is authoritative, not the summary.
Open questions added to open-questions.md, each mapped to one of the thirteen topics, each with its options and their trade-offs. Cite them by number here.
Before it counts as developed
The overview page lists a use case as developed only when three things exist, and they are the three a reader can check without taking anyone's word for it.
- A rules file that passes requirements C1 to C17 of Conformance. Run
check_profile.pyagainst it. - One document that conforms to the profile, and one that does not. The second is the one that matters: a profile no document has ever failed has not been shown to constrain anything.
- A test in
tests/run-profile-tests.shthat asserts both outcomes, including the exit status.
Until then the page is a draft, which is a perfectly good state for it to be in and should be labelled rather than avoided. A draft that names its consumer and its decision is already more useful to the working group than a finished profile whose purpose has to be reverse-engineered from its rules.