From 5b0f0527c4e2dfb3924133c40bd3fcd850c65c07 Mon Sep 17 00:00:00 2001 From: status-im-auto Date: Mon, 25 Sep 2023 12:47:15 +0000 Subject: [PATCH] Update documentation --- 404.html | 2 +- categories/index.html | 3 +- docs/index.html | 3 +- docs/index.xml | 11 + ...21ba2822f1db3a9280b7421e8b9b17482f2fa97.js | 2087 +++++++++++++++++ ...101d7523500ebcf0c7eb2a9b25dceabf3865173.js | 1 + index.html | 3 +- index.xml | 11 + sitemap.xml | 2 + spec/1/index.html | 3 +- spec/10/index.html | 3 +- spec/11/index.html | 3 +- spec/12/index.html | 260 +- spec/13/index.html | 3 +- spec/14/index.html | 3 +- spec/15/index.html | 3 +- spec/16/index.html | 3 +- spec/17/index.html | 3 +- spec/18/index.html | 3 +- spec/19/index.html | 3 +- spec/2/index.html | 3 +- spec/20/index.html | 3 +- spec/21/index.html | 3 +- spec/22/index.html | 3 +- spec/23/index.html | 3 +- spec/24/index.html | 3 +- spec/25/index.html | 3 +- spec/26/index.html | 3 +- spec/27/index.html | 3 +- spec/28/index.html | 3 +- spec/29/index.html | 3 +- spec/3/index.html | 3 +- spec/30/index.html | 3 +- spec/31/index.html | 3 +- spec/32/index.html | 3 +- spec/33/index.html | 3 +- spec/34/index.html | 3 +- spec/35/index.html | 3 +- spec/36/index.html | 3 +- spec/37/index.html | 3 +- spec/38/index.html | 3 +- spec/4/index.html | 3 +- spec/43/index.html | 3 +- spec/44/index.html | 3 +- spec/45/index.html | 3 +- spec/46/index.html | 3 +- spec/47/index.html | 3 +- spec/48/index.html | 3 +- spec/5/index.html | 3 +- spec/51/index.html | 3 +- spec/52/index.html | 3 +- spec/53/index.html | 3 +- spec/54/index.html | 3 +- spec/55/index.html | 3 +- spec/56/index.html | 3 +- spec/57/index.html | 3 +- spec/58/index.html | 3 +- spec/6/index.html | 3 +- spec/61/index.html | 3 +- spec/63/index.html | 727 ++++++ spec/64/index.html | 3 +- spec/7/index.html | 3 +- spec/8/index.html | 3 +- spec/9/index.html | 3 +- spec/xx/index.html | 3 +- .../index.html | 3 +- tags/index.html | 3 +- tags/logos/consensus/index.html | 3 +- tags/rln/index.html | 3 +- tags/waku-application/index.html | 3 +- tags/waku-core-protocol/index.html | 3 +- tags/waku-core/index.html | 3 +- tags/waku/anonymity/index.html | 3 +- tags/waku/application/index.html | 3 +- tags/waku/core-protocol/index.html | 3 +- 75 files changed, 3043 insertions(+), 259 deletions(-) create mode 100644 en.search-data.min.661ce2eb4a1222f006003541621ba2822f1db3a9280b7421e8b9b17482f2fa97.js create mode 100644 en.search.min.f4f594e7e343e38ffa6ecd18b101d7523500ebcf0c7eb2a9b25dceabf3865173.js create mode 100644 spec/63/index.html diff --git a/404.html b/404.html index e46746431..257f5aa87 100644 --- a/404.html +++ b/404.html @@ -14,7 +14,7 @@ - + + + + + + + + +
+ + +
+
+ +
+ + + 63/STATUS-Keycard-Usage + + +
+ + + + + + +
+ + + +
+

+ 63/STATUS-Keycard-Usage + # +

+ + +

+ Status Keycard Usage + # +

+ + + + + + + + + + + +
    +
  • Status: raw
    • +
  • Editor: Aaryamann Challani aaryamann@status.im
    • + +
  • Contributors: + + + ? + +
    • + +

+ Terminology + # +

+
    +
  • Account: A valid BIP-32 compliant key.
    • +
  • Multiaccount: An account from which multiple Accounts can be derived.
    • +
+

+ Abstract + # +

+

This specification describes how an application can use the Status Keycard to -

+
    +
  1. Create Multiaccounts
    2. +
  2. Store Multiaccounts
    3. +
  3. Use Multiaccounts for transaction or message signing
    4. +
  4. Derive Accounts from Multiaccounts
    5. +
+

More documentation on the Status Keycard can be found here

+

+ Motivation + # +

+

The Status Keycard is a hardware wallet that can be used to store and sign transactions. +For the purpose of the Status App, this specification describes how the Keycard SHOULD be used to store and sign transactions.

+

+ Usage + # +

+

+ Endpoints + # +

+

+ 1. Initialize Keycard (/init-keycard) + # +

+

To initialize the keycard for use with the application. +The keycard is locked with a 6 digit pin.

+

+ Request wire format + # +

+
{
+  "pin": 6_digit_pin
+}
+

+ Response wire format + # +

+
{
+  "password": password_to_unlock_keycard,
+  "puk": 12_digit_recovery_code,
+  "pin": provided_pin,
+}
+

The keycard MUST be initialized before it can be used with the application. +The application SHOULD provide a way to recover the keycard in case the pin is forgotten.

+

+ 2. Get Application Info (/get-application-info) + # +

+

To fetch if the keycard is ready to be used by the application.

+

+ Request wire format + # +

+

The requester MAY add a pairing field to filter through the generated keys

+
{
+  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt> OR null
+}
+

+ Response wire format + # +

+
+ If the keycard is not initialized yet + # +
+
{
+  "initialized?": false
+}
+
+ If the keycard is initialized + # +
+
{
+  "free-pairing-slots": number, 
+  "app-version": major_version.minor_version, 
+  "secure-channel-pub-key": valid_bip32_key,, 
+  "key-uid": unique_id_of_the_default_key,
+  "instance-uid": unique_instance_id, 
+  "paired?": bool,
+  "has-master-key?": bool, 
+  "initialized?" true
+}
+

+ 3. Pairing the Keycard to the Client device (/pair) + # +

+

To establish a secure communication channel described here, the keycard and the client device need to be paired.

+

+ Request wire format + # +

+
{
+  "password": password_to_unlock_keycard
+}
+

+ Response wire format + # +

+
"<shared_secret>/<pairing_index>/<256_bit_salt>"
+

+ 4. Generate a new set of keys (/generate-and-load-keys) + # +

+

To generate a new set of keys and load them onto the keycard.

+

+ Request wire format + # +

+
{
+  "mnemonic": 12_word_mnemonic,
+  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>,
+  "pin": 6_digit_pin
+}
+

+ Response wire format + # +

+
{
+  "whisper-address": 20_byte_whisper_compatible_address, 
+  "whisper-private-key": whisper_private_key, 
+  "wallet-root-public-key": 256_bit_wallet_root_public_key, 
+  "encryption-public-key": 256_bit_encryption_public_key,, 
+  "wallet-root-address": 20_byte_wallet_root_address, 
+  "whisper-public-key": 256_bit_whisper_public_key,
+  "address": 20_byte_address, 
+  "wallet-address": 20_byte_wallet_address,, 
+  "key-uid": 64_byte_unique_key_id, 
+  "wallet-public-key": 256_bit_wallet_public_key,
+  "public-key": 256_bit_public_key,
+  "instance-uid": 32_byte_unique_instance_id,
+}
+

+ 5. Get a set of generated keys (/get-keys) + # +

+

To fetch the keys that are currently loaded on the keycard.

+

+ Request wire format + # +

+
{
+  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>,
+  "pin": 6_digit_pin
+}
+

+ Response wire format + # +

+
{
+  "whisper-address": 20_byte_whisper_compatible_address, 
+  "whisper-private-key": whisper_private_key, 
+  "wallet-root-public-key": 256_bit_wallet_root_public_key, 
+  "encryption-public-key": 256_bit_encryption_public_key,
+  "wallet-root-address": 20_byte_wallet_root_address, 
+  "whisper-public-key": 256_bit_whisper_public_key,
+  "address": 20_byte_address, 
+  "wallet-address": 20_byte_wallet_address, 
+  "key-uid": 64_byte_unique_key_id, 
+  "wallet-public-key": 256_bit_wallet_public_key,
+  "public-key": 256_bit_public_key,
+  "instance-uid": 32_byte_unique_instance_id,
+}
+

+ 6. Sign a transaction (/sign) + # +

+

To sign a transaction using the keycard, passing in the pairing information and the transaction to be signed.

+

+ Request wire format + # +

+
{
+  "hash": 64_byte_hash_of_the_transaction,
+  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>,
+  "pin": 6_digit_pin,
+  "path": bip32_path_to_the_key
+}
+

+ Response wire format + # +

+
<256_bit_signature>
+

+ 7. Export a key (/export-key) + # +

+

To export a key from the keycard, passing in the pairing information and the path to the key to be exported.

+

+ Request wire format + # +

+
{
+  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>,
+  "pin": 6_digit_pin,
+  "path": bip32_path_to_the_key
+}
+

+ Response wire format + # +

+
<256_bit_public_key>
+

+ 8. Verify a pin (/verify-pin) + # +

+

To verify the pin of the keycard.

+

+ Request wire format + # +

+
{
+  "pin": 6_digit_pin
+}
+

+ Response wire format + # +

+
1_digit_status_code
+

Status code reference:

+
    +
  • 3: PIN is valid
    • +
+ +

+ 9. Change the pin (/change-pin) + # +

+

To change the pin of the keycard.

+

+ Request wire format + # +

+
{
+  "new-pin": 6_digit_new_pin,
+  "current-pin": 6_digit_new_pin,
+  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>
+}
+

+ Response wire format + # +

+
+ If the operation was successful + # +
+
true
+
+ If the operation was unsuccessful + # +
+
false
+

+ 10. Unblock the keycard (/unblock-pin) + # +

+

If the Keycard is blocked due to too many incorrect pin attempts, it can be unblocked using the PUK.

+

+ Request wire format + # +

+
{
+  "puk": 12_digit_recovery_code,
+  "new-pin": 6_digit_new_pin,
+  "pairing": <shared_secret>/<pairing_index>/<256_bit_salt>
+}
+

+ Response wire format + # +

+
+ If the operation was successful + # +
+
true
+
+ If the operation was unsuccessful + # +
+
false
+

+ Flows + # +

+

Any application that uses the Status Keycard MAY implement the following flows according to the actions listed above.

+

+ 1. A new user wants to use the Keycard with the application + # +

+
    +
  1. The user initializes the Keycard using the /init-keycard endpoint.
    2. +
  2. The user pairs the Keycard with the client device using the /pair endpoint.
    3. +
  3. The user generates a new set of keys using the /generate-and-load-keys endpoint.
    4. +
  4. The user can now use the Keycard to sign transactions using the /sign endpoint.
    5. +
+

+ 2. An existing user wants to use the Keycard with the application + # +

+
    +
  1. The user pairs the Keycard with the client device using the /pair endpoint.
    2. +
  2. The user can now use the Keycard to sign transactions using the /sign endpoint.
    3. +
+

+ 3. An existing user wants to use the Keycard with a new client device + # +

+
    +
  1. The user pairs the Keycard with the new client device using the /pair endpoint.
    2. +
  2. The user can now use the Keycard to sign transactions using the /sign endpoint.
    3. +
+

+ 4. An existing user wishes to verify the pin of the Keycard + # +

+
    +
  1. The user verifies the pin of the Keycard using the /verify-pin endpoint.
    2. +
+

+ 5. An existing user wishes to change the pin of the Keycard + # +

+
    +
  1. The user changes the pin of the Keycard using the /change-pin endpoint.
    2. +
+

+ 6. An existing user wishes to unblock the Keycard + # +

+
    +
  1. The user unblocks the Keycard using the /unblock-pin endpoint.
    2. +
+

+ Security Considerations + # +

+

Inherits the security considerations of Status Keycard

+

+ Privacy Considerations + # +

+

Inherits the privacy considerations of Status Keycard

+

+ Copyright + # +

+

Copyright and related rights waived via CC0.

+

+ References + # +

+
    +
  1. BIP-32 specification
    2. +
  2. Keycard documentation
    3. +
  3. 16/Keycard-Usage
    4. +
+
+ + + +
+ +
+ + + + + +
+ + + +
+ + + +
+ +
+ + + + +
+ + + + +
+ + + + + + + + + + + + + + + + + diff --git a/spec/64/index.html b/spec/64/index.html index 3d5d710a6..1970056d9 100644 --- a/spec/64/index.html +++ b/spec/64/index.html @@ -19,7 +19,7 @@ - +