From c93701268726ac09411884307bd9a738601e1dfe Mon Sep 17 00:00:00 2001 From: dangerous-tac0s Date: Tue, 3 Dec 2024 11:31:57 -0800 Subject: [PATCH 1/5] Create quickstart.md Outline quick start guide. --- docs/quickstart.md | 121 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 docs/quickstart.md diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..7902dbf --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,121 @@ +# 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. + +## Setting up Global Platform Pro +- Windows +- Linux +- OS X + +### Basics +Using the jar or exe, use the following flags: +- Installing an applet + ```shell + --install + ``` +- Uninstalling + ```shell + --uninstall + or + --remove + ``` +- 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 + ``` +- SatochipApplet + This allows your flexSecure to act as a cold wallet. Currently, cold wallets are not supported by Sato mobile apps. +- Satodime-Applet +- 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 + 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 + ```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 -m fido21 + ``` + ```shell + # Example Output + ``` + ```shell + python attestation.py cert -f show -m fido21 + ``` + ```shell + # Example Output + ``` + Copy the params value + - Install the applet with the generated parameters + ```shell + --install FIDO2.cap --params + ``` + - Load the attestation certificate + ```shell + python attestation.py cert upload -m fido21 + ``` +- SmartPGP From 60aea6e1c23d45fd5118c6fe78a07f92f8ae9d23 Mon Sep 17 00:00:00 2001 From: dangerous-tac0s Date: Wed, 4 Dec 2024 12:49:36 -0800 Subject: [PATCH 2/5] Update quickstart.md Added examples for FIDO2 outputs (validate, show) --- docs/quickstart.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 7902dbf..dcd6890 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -85,7 +85,7 @@ The following apps can be installed with a single GPP command and the requisite - c: country. we use US - o: organization. we use Dangerous Things - cn: certificate name. Leave these alone - - Install python packages + - 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" ``` @@ -98,19 +98,36 @@ The following apps can be installed with a single GPP command and the requisite python attestation.py cert create -m fido21 ``` ```shell - python attestation.py cert validate -m fido21 + 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): + info: Private attestation key (32 bytes): + info: AAGUID: ad7f2c9e-94e4-48e8-98d8-e8d288c769f5 + info: Applet installation parameter (contains CBOR configuration map with private attestation key 32 bytes): ``` Copy the params value - - Install the applet with the generated parameters + - 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 ``` From e587089ac536cf458296be506c241062d275c1f0 Mon Sep 17 00:00:00 2001 From: dangerous-tac0s Date: Tue, 1 Apr 2025 16:48:13 -0700 Subject: [PATCH 3/5] Update quickstart.md Added a quick reference for the preloaded apps and added some links to smartpgp references. --- docs/quickstart.md | 43 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 9 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index dcd6890..de74af6 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -6,6 +6,13 @@ This is aimed at getting you up and running as quickly as possible but it is str ## 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 @@ -34,15 +41,15 @@ Check the [latest release](releases) and download the apps you're interested in ## Apps with a simple install The following apps can be installed with a single GPP command and the requisite cap file. -- [apex-tesla]() +### apex-tesla Use your flexSecure as a Tesla key. -- apex-totp +### apex-totp OTP codes generated in vivo. -- flexsecure-ykhmac +### flexsecure-ykhmac Generate HMAC-SHA1 hashes on the flexSecure. Can be used to secure LastPass. -- javacard-memory +### javacard-memory This is used with Apex Manager to provide a rough estimate on available storage. -- openjavacard-ndef +### openjavacard-ndef Create NDEF containers up to 32k on the flexSecure. If no parameters are provided, it defaults to a 2k container - 2k ```cmd @@ -64,17 +71,19 @@ The following apps can be installed with a single GPP command and the requisite ```cmd --params 810200F182027fff ``` -- SatochipApplet + + 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 -- Seedkeeper-Applet +- 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 +### [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 @@ -135,4 +144,20 @@ The following apps can be installed with a single GPP command and the requisite ```shell python attestation.py cert upload -m fido21 ``` -- SmartPGP + +## 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, insecure 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). From 4866dea13c2752f8b5bd877f17ef4416d40d45c0 Mon Sep 17 00:00:00 2001 From: dangerous-tac0s Date: Sat, 5 Apr 2025 15:24:46 -0700 Subject: [PATCH 4/5] Update quickstart.md Fixed some formatting issues. --- docs/quickstart.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index de74af6..587ed1d 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -73,13 +73,14 @@ The following apps can be installed with a single GPP command and the requisite ``` 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 +### SatoChipApplet This allows your flexSecure to act as a cold wallet. Currently, cold wallets are not supported by Sato mobile apps. -- Satodime-Applet -- SeedKeeper-Applet -- status-keycard +### 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 +### 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 From 4a479d041565c4a1a07ea12f5cd4950148385bf4 Mon Sep 17 00:00:00 2001 From: dangerous-tac0s Date: Fri, 5 Sep 2025 06:18:15 -0700 Subject: [PATCH 5/5] Update quickstart.md Corrected statement that suggested large RSA keys were insecure. --- docs/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 587ed1d..663547e 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -148,7 +148,7 @@ The following apps can be installed with a single GPP command and the requisite ## 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, insecure RSA keys. +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;