docs: verify user provided chain code

README.md

@@ -184,6 +184,21 @@ To see more detail, include the CVC on the command line.
 `cktap --version`
 - Get the version of cktap library
 
+`cktap list`
+- List all cards detected on any reader attached
+
+`cktap certs`
+-  Check this card was made by Coinkite
+
+## For both SATSCARD and TAPSIGNER
+
+`cktap status`
+- Shows status info.
+
+`cktap setup`
+- Tells card to pick private key. Chain code can be provided by user. User can [verify](docs/best-practices.md) that provided chain code was used.
+- called only once on TAPSIGNER, and for each slot setup on SATSCARD
+
 ### For SATSCARD
 
 `cktap open`
@@ -203,12 +218,6 @@ To see more detail, include the CVC on the command line.
 
 ### For TAPSIGNER
 
-`cktap status`
-- Shows status info.
-
-`cktap setup`
-- Tells card to pick private key (call once).
-
 `cktap xpub`
 - Shows the XPUB in effect.
 

docs/best-practices.md

@@ -3,22 +3,44 @@
 ## Overall
 
 1. Never store a CVC (PIN code). Just prompt when needed, and keep in memory
-during operation. You should associate it with the `card_ident` (card pubkey)
-and if a different card is seen, assume a new CVC is needed.
+   during operation. You should associate it with the `card_ident` (card pubkey)
+   and if a different card is seen, assume a new CVC is needed.
 
 2. Always verify the factory certificate of the card before trusting
-any data from it. Otherwise, your users will be tricked by cloned
-or emulated cards.
+   any data from it. Otherwise, your users will be tricked by cloned
+   or emulated cards.
 
 3. Verify that when the card picks a key it uses BIP-32 chain code you gave it.
-Take the `chain_code` your code provided, and check that the public key it
-gives after picking is derived using that `chain_code`. This check applies to
-both the SATSCARD, where the path is always `m/0` and also the TAPSIGNER,
-where you may control the derivation path. On the TAPSIGNER, the `xpub`
-command should return the same chain code as you proided.
+   Take the `chain_code` your code provided, and check that the public key it
+   gives after picking is derived using that `chain_code`. This check applies to
+   both the SATSCARD, where the path is always `m/0` and also the TAPSIGNER,
+   where you may control the derivation path. On the TAPSIGNER, the `xpub`
+   command should return the same chain code as you provided. Verification steps:
+    * TAPSIGNER
+        1. setup Tapsigner with own chain
+           code `cktap setup 123456 -c 17b1987d0d4d8975d38bedbc2ac5142a201d96130fd870244b30a36c1f9f50d3`
+        2. get master extended public key `cktap xpub 123456 -m`
+        3. I got `xpub661MyMwAqRbcEn7gz6LkGur9F4G3YQ2xEBzr7h8mVxduNox4aDwMWo2QQahtYktGufVkY4jALmLWAHT1iUTBqaYi7jHyRxHEEK94VVhum7D` but yours will be different as private key is generated by cards TRNG.
+        4. verify with lib:
+            ```python
+            from cktap.bip32 import PubKeyNode
+            n = PubKeyNode.parse("xpub661MyMwAqRbcEn7gz6LkGur9F4G3YQ2xEBzr7h8mVxduNox4aDwMWo2QQahtYktGufVkY4jALmLWAHT1iUTBqaYi7jHyRxHEEK94VVhum7D")
+            n.chain_code.hex()
+            ```
+        5. verify on commnad line:
+            ```shell
+            cktap xpub 123456 -m | base58 -d | xxd -p -l32 -s13
+            ```
+        6. assert provided chain code matches output from 4. or 5.
+
+    * SATSCARD
+        1. setup Satscard with own chain
+           code `cktap setup 123456 -c 17b1987d0d4d8975d38bedbc2ac5142a201d96130fd870244b30a36c1f9f50d3`
+        2. chain code can be accessed only after slot was unsealed with `unseal` command
+        3. execute `ckcc dump <SLOT NUM>` to see that provided chain code was used
 
 4. You can safely assume the PIN code (CVC) is all-numeric and provide
-your users with a digits-only on-screen keyboard.
+   your users with a digits-only on-screen keyboard.
 
 
 ## SATSCARD

emulator/requirements.txt

@@ -2,7 +2,7 @@
 pytest
 cbor2==5.4.1
 hexdump==3.3
-wallycore==0.8.5
+wallycore==0.8.5  # may need something newer like 1.3.0 on ubuntu24+
 bech32==1.2.0
 pyqrcode==1.2.1
 base58==2.1.1