flexSecure Quickstart

docs/quickstart.md

@@ -0,0 +1,164 @@
+# So you just got a flexSecure
+
+While there is some overlap with the Apex, app deployment happens quite differently on the flexSecure which relies on Global Platform Pro which is a command line tool.
+
+This is aimed at getting you up and running as quickly as possible but it is strongly suggested you read the [technology](docs/1-technology.md) and [hardware](docs/2-hardware.md) sections. 
+
+## flexSecure Preloaded Apps
+All of these sold after 12/2/2024 come preloaded with FIDO2Applet, javacard-memory, apex-totp, and openjavacard-ndef with a 32k container.
+Release v0.19.1:
+|App Name                                   |AID                        |Persistent Storage   |Transient Memory  |
+|-------------------------------------------|---------------------------|---------------------|------------------|
+|[JavaCard Memory](https://github.com/DangerousThings/javacard-memory)|A0000008466D656D6F727901|?                    |?                 |
+|[FIDO2Applet](#FIDO2Applet)                |A0000006472F0002           |~41748 bytes         |~2745 bytes       |
+|[Apex TOTP](#apex-totp)                    |A0000005272101014150455801 |5416 bytes           |2344 bytes        |
+|[Open JavaCard NDEF](#openjavacard-ndef)   |D2760000850101             |2428 bytes + 32 kB   |0                 |
+
+## Setting up Global Platform Pro
+- Windows
+- Linux
+- OS X
+
+### Basics
+Using the jar or exe, use the following flags:
+- Installing an applet
+  ```shell
+  --install <capfile>
+  ```
+- Uninstalling
+  ```shell
+  --uninstall <capfile>
+  or
+  --remove <capfile or AID>
+  ```
+- List installed applets
+  ```shell
+  --list
+  ```
+
+## Download applets
+Check the [latest release](releases) and download the apps you're interested in before proceeding.
+
+## Apps with a simple install
+The following apps can be installed with a single GPP command and the requisite cap file.
+### apex-tesla
+  Use your flexSecure as a Tesla key.
+### apex-totp
+  OTP codes generated in vivo.
+### flexsecure-ykhmac
+  Generate HMAC-SHA1 hashes on the flexSecure. Can be used to secure LastPass.
+### javacard-memory
+  This is used with Apex Manager to provide a rough estimate on available storage.
+### openjavacard-ndef
+  Create NDEF containers up to 32k on the flexSecure. If no parameters are provided, it defaults to a 2k container
+  - 2k
+    ```cmd
+    --params 810200F182020800
+    ```
+  - 4k
+    ```cmd
+    --params 810200F182021000
+    ```
+  - 8k
+    ```cmd
+    --params 810200F182022000
+    ```
+  - 16k
+    ```cmd
+    --params 810200F182024000
+    ```
+  - 32k
+    ```cmd
+    --params 810200F182027fff
+    ```
+
+    If you want to do other things such as preload data, enable read only or write once modes, [checkout the docs](https://github.com/OpenJavaCard/openjavacard-ndef).
+### SatoChipApplet
+  This allows your flexSecure to act as a cold wallet. Currently, cold wallets are not supported by Sato mobile apps.
+### Satodime-Applet
+  This is not compatible with Apex or flexSecure devices.
+### SeedKeeper-Applet
+### status-keycard
+  This allows your flexSecure to act as a cold wallet. Currently, cold wallets are not supported by Status.im mobile apps.
+### u2f-javacard
+  This is unnecessary if the FIDO2 applet is installed. If, however, you want U2F but don't care about passkeys, this will save you storage.
+
+## Apps with complex install
+### [FIDO2Applet](https://github.com/BryanJacobs/FIDO2Applet)
+  To install this applet, you'll need to generate and load attestation data. You'll need [Python](https://python.org/downloads) and [this repo](https://github.com/dangerousthings/fido-attestation-loader).
+  - Setup fido-attestation-loader
+    - Update the update settings.example.ini and save it as settings.ini
+      - You could generate a new one or use '27291256-2735-45b5-99f9-2863c9dedf72' as we do with the flexSecure we preload.
+      - Listed metadata, ca, and cert fields are required but they can (mostly) be anything you like.
+        - description: what device is it? we use flexSecure
+        - icon: we use a png around 40x40
+        - c: country. we use US
+        - o: organization. we use Dangerous Things
+        - cn: certificate name. Leave these alone
+    - Install python packages. This is presently broken. Install cbor2 and then the latest version of the other packages in requirements.txt
+    ```shell
+    pip install -r "requirements.txt"
+    ```
+  - Generate central authority and attestation certificates
+  You'll want to save the files generated by this as well as the passphrases you use to secure them. To make it easy, you can save the phrases in files called ca_key.pass and attestation_key.pass in the fido-attestation-loader directory.
+  ```shell
+  python attestation.py ca create
+  ```
+  ```shell
+  python attestation.py cert create -m fido21
+  ```
+  ```shell
+  python attestation.py cert validate
+  ```
+  ```shell
+  # Example Output
+  info: Validating an existing attestation certificate against a certificate authority
+  info: Loading settings file settings.ini
+  info: Public attestation certificate serial number: 723321508150486599877570106078221356789683409469
+  info: Public attestation certificate SHA256 fingerprint: 1c104b3380b028b703f2ab2cc841bfebb966d792f218aa2bb56bd81e88599842
+  info: Public certificate authority serial number: 385004152696321157272772190328151754561352515268
+  info: Public certificate authority SHA256 fingerprint: 9e8b43d2688663e9937c490bfa0ad4e59cc086d5e96e547f1c1f7ca27e977972
+  success: The attestation certificate has a valid signature by the certificate authority
+  ```
+  ```shell
+  python attestation.py cert -f show -m fido21
+  ```
+  ```shell
+  # Example Output
+  info: Showing an existing attestation certificate
+  info: Loading settings file settings.ini
+  info: Public certificate authority serial number: 385004152696321157272772190328151754561352515268
+  info: Public certificate authority SHA256 fingerprint: 9e8b43d2688663e9937c490bfa0ad4e59cc086d5e96e547f1c1f7ca27e977972
+  info: Public attestation certificate serial number: 723321508150486599877570106078221356789683409469
+  info: Public attestation certificate SHA256 fingerprint: 1c104b3380b028b703f2ab2cc841bfebb966d792f218aa2bb56bd81e88599842
+  info: Public attestation certificate (574 bytes):   <certificate>
+  info: Private attestation key (32 bytes): <private key>
+  info: AAGUID: ad7f2c9e-94e4-48e8-98d8-e8d288c769f5
+  info: Applet installation parameter (contains CBOR configuration map with private attestation key 32 bytes): <monstrous hex string>
+  ```
+  Copy the params value
+  - Install the applet with the "Applet installation parameter" for the install's --params switch. It will most likely complain about an invalid TLV.
+  ```shell
+  --install FIDO2.cap --params <monstrous-hex-string>
+  ```
+  - Load the attestation certificate
+  ```shell
+  python attestation.py cert upload -m fido21
+  ```
+
+## Apps with additional setup
+### [SmartPGP](https://github.com/github-af/SmartPGP)
+This one comes in two flavors: default and large. Do yourself a favor and stick to default--unless you want really large, inefficient RSA keys.
+
+The SmartPGP applet is configured with the following default values:
+- Admin PIN is 12345678;
+- User PIN is 123456;
+- No PUK (a.k.a. resetting code) is defined;
+- RSA 2048 bits for PGP keys;
+- NIST P-256 for the secure messaging key.
+
+### Android
+Checkout these [videos on using this app](https://github.com/github-af/SmartPGP/tree/master/videos) with [OpenKeychain](https://www.openkeychain.org/).
+
+### PC
+Checkout [aegis](https://gist.github.com/ageis)' [guide](https://gist.github.com/ageis/14adc308087859e199912b4c79c4aaa4).