Merge pull request #80 from smlx/setup-slot

Setup slots documentation
smlx · Oct 25, 2021 · 7b1b883 · 7b1b883
2 parents f1efe3b + d9ac021
commit 7b1b883
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 2 deletions.
diff --git a/cmd/piv-agent/setupslots.go b/cmd/piv-agent/setupslots.go
@@ -13,7 +13,7 @@ type SetupSlotsCmd struct {
 	Card          string   `kong:"help='Specify a smart card device'"`
 	ResetSlots    bool     `kong:"help='Overwrite existing keys in the targeted slots'"`
 	PIN           uint64   `kong:"help='The PIN/PUK of the device (6-8 digits). Will be prompted interactively if not provided.'"`
-	SigningKeys   []string `kong:"default='',enum='cached,always,never',help='Set up slots for signing keys with various touch policies (default none)'"`
+	SigningKeys   []string `kong:"default='',enum='cached,always,never',help='Set up slots for signing keys with various touch policies (default none, possible values cached,always,never)'"`
 	DecryptingKey bool     `kong:"default='false',help='Set up slot for a decrypting key (default false)'"`
 }
 

diff --git a/docs/content/en/docs/setup.md b/docs/content/en/docs/setup.md
@@ -6,8 +6,10 @@ description: Set up piv-agent to work with your hardware.
 
 ## Hardware
 
+### Default setup
+
 {{% alert title="Warning" color="warning" %}}
-This procedure resets the state of the PIV applet and wipes any existing keys from PIV slots.
+This procedure resets the state of the PIV applet and wipes any existing keys from _all_ PIV slots.
 {{% /alert %}}
 
 This procedure is only required once per hardware security device.
@@ -35,6 +37,32 @@ piv-agent setup --pin=123456 --card='Yubico YubiKey FIDO+CCID 01 00' --reset-sec
 piv-agent list
 ```
 
+### Single slot setup
+
+{{% alert title="Warning" color="warning" %}}
+`piv-agent` has been designed to work best with the default setup.
+Only set up single slots if you know what you are doing.
+
+This action can be destructive.
+If you reset a slot which already contains a key, that key will be lost.
+{{% /alert %}}
+
+It is possible to set up a single PIV slot on your hardware device without resetting the device.
+This means that you target a single slot to set up a key if the slot has not been set up yet, or reset a key if the slot already contains one.
+Other PIV slots will not be affected, and will retain their existing keys.
+
+For example this command will reset just the decrypting slot on your Yubikey:
+
+```
+piv-agent setup-slots --card="Yubico YubiKey FIDO+CCID 01 00" --pin=123456 --decrypting-key --reset-slots
+```
+
+See the interactive help for more usage details:
+
+```
+piv-agent setup-slots --help
+```
+
 ## SSH
 
 ### List keys