Debian Codegraph @

src/pins/template/README.md

raw
1
2 # Writing your own pin
3
4 The files here should give you an introduction into writing your own pin.
5
6 ## Overall workflow
7
8 The `encrypt` script reads a plain text from stdin, encrypts it using
9 `jose jwe enc` which writes the result to stdout, together with some
10 information how to re-create the plain text later. The encryption key
11 itself *must* *not* be included here.
12
13 The encryption key is provided or created by the pin and stashed away
14 in some way. That is the core logic of a pin.
15
16 A configuration in the JSON format is provided as the first parameter,
17 it controls the pin's operation.
18
19 The `decrypt` script reads the encrypted information from stdin,
20 decrypts it using `ose jwe dec` which again writes the result to
21 stdout. The information provided by `encrypt` above is available, this
22 must be sufficient to restore the encryption key.
23
24 ## How to use this template
25
26 Copy all the files here (except for this one) into a new subdirectory
27 of `src/pins/`, named as your pin.
28
29 Replace @pin@ with the name of your pin everywhere, including file names.
30
31 The `clevis-{en,de}crypt-@pin@` scripts require the most attention.
32
33 Have a man page in `clevis-encrypt-@[email protected]`.
34
35 Adjust `meson.build`.
36
37 Provide a test in `pin-@pin@`.
38
39 Adjust dracut configuration in `dracut.module-setup.sh.in`.
40
41 Adjust initramfs configuration in `initramfs.in`.
42
43 Optionally add something to `clevis-luks-list`.
44
45 Finally, add your pin in `../meson.build`.
46
47 ## Comments
48
49 An extra form of comments is used to explain concepts. They all should
50 be removed before sending out patches/merge requests.
51
52 #%# some generic information
53 #!# things worth to know, gotchas
54 #?# some bits that require more understanding
55
56 ## Nameing your pin and configuration variables
57
58 The pin name should be short and reflect the purpose. To avoid trouble
59 or extra work, the name should start with a letter, followed by letters,
60 digits, or underscore.
61
62 Parameter names for the pin configuration should follow the same
63 syntax. These templates assume they can be used as a shell variable.
64
65 ## Templates variables
66
67 The templates use `@...@` to mark places that can semi-automatically
68 be adjusted to your needs. Variables are
69
70 * `@pin@`: The name of this pin, see above
71 * `@PIN@`: The name of this pin, uppercase
72 * `@year@`: Current year
73 * `@name@`: Your name
74 * `@email@`: Your e-mail address
75 * `@mand1@`: The name of a mandatory parameter
76 * `@mand2@`: The name of another mandatory parameter
77 * `@opt1@`: The name of an optional parameter
78 * `@param1@`: The name of a parameter needed for decryption
79 * `@param2@`: Another name
80
81 If you have more parameters, extend accordingly
82
83 Any `@@` requires attention in wording.
84
85 Make sure you've replaced *all* occurances of template variables.
86 Else the build will probably fail.