From 2ac6e71fc11b48849b46000d6219a29e44996c5f Mon Sep 17 00:00:00 2001 From: Scott Leggett Date: Mon, 25 Oct 2021 13:55:12 +0800 Subject: [PATCH 1/2] feat: improve interactive setup-slots help --- cmd/piv-agent/setupslots.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/piv-agent/setupslots.go b/cmd/piv-agent/setupslots.go index da91a91..9390578 100644 --- 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)'"` } From d9ac0211ef25be032b21ee043ccbb4e663959041 Mon Sep 17 00:00:00 2001 From: Scott Leggett Date: Mon, 25 Oct 2021 14:09:53 +0800 Subject: [PATCH 2/2] chore: add setup-slots to setup documentation --- docs/content/en/docs/setup.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/content/en/docs/setup.md b/docs/content/en/docs/setup.md index cbd3a17..0c03f46 100644 --- 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