diff --git a/docs/feitianguiway.md b/docs/feitianguiway.md new file mode 100644 index 0000000..9a4d0b4 --- /dev/null +++ b/docs/feitianguiway.md @@ -0,0 +1,47 @@ +## Background +After Feitian OpenSK USB Dongle was released, the official OpenSK github firmware source code has been updated for many times, and the update seems to be frequent. So there is request from user to update the firmware. +[Google OpenSK github repository](https://github.com/google/opensk "OpenSK") provides [official steps](https://github.com/google/OpenSK/blob/stable/docs/install.md "installation guide") to update the firmware. But to end users who are not familiar with development, it is very hard for them to setup the development environment, install several tools, clone and build the source code, and run command line tool to update. So Feitian developped this GUI tool for user to simply update the firmware. + +## Open Source +This tool is open source software, anyone can review the source code from [OpenSK Update Tool Github Repository](https://github.com/FeitianTech/OpenSKUpdateTool/releases "OpenSK Update Tool") . +Feitian will build the firmware from official [Google OpenSK github repository](https://github.com/google/opensk "OpenSK") aperiodically, and list the binary firmware on [Feitian OpenSK Repository](https://github.com/FeitianTech/OpenSK/releases "OpenSK Firmware"). User can choose the firmware version they like and re-program the OpenSK USB dongle directly without extra work. + +## Guide +Here show how to use the OpenSK GUI Update Tool to update firmware on macOS. The steps and UI are similar on other platforms (Windows, Linux). +Please refer to [hardware description page](./hardware.md) to learn how to switch the OpenSK USB dongle to bootloader mode. + +### 1. Download tool and files +You can download the tool and from [OpenSK Update Tool Github Repository](https://github.com/FeitianTech/OpenSKUpdateTool/releases "OpenSK Update Tool") . +You can download firmware and attestation cryptographic material from [Feitian OpenSK Repository](https://github.com/FeitianTech/OpenSK/releases "OpenSK Firmware"). +After you download the firmware and attestation cryptographic material, put them into the same directory of this update tool like below picture showed. + +File Locations +### 2. Launch Update Tool +Insert your OpenSK USB Dongle to your USB port, no matter whether it is in Bootloader mode or not. +Launch this tool, it shows as below picture. +Update Tool overview + +### 3. Erase Storage (Optional) +If you want to keep your existing Credentials or your OpenSK USB dongle works well after you upgrade the firmware, you can skip this step. + +This step is optional, used to [clear all storage](https://github.com/google/OpenSK/pull/247 "OpenSK") (include firmware and all data) if you meet some issues after you update firmware, for example, incompatible storage version. + +To try this step, choose first "Erase" Tab, insert your OpenSK USB Dongle to your USB port, press the user button on hardware for more than 10 seconds to switch your OpenSK USB Dongle to bootloader mode, then click "Erase" button, confirm the question as below dialog shows, wait for this operation to be successfully performed. + +Update Tool overview +Update Tool overview + +After this step, the OpenSK USB Dongle will not be recognized by this tool as normal, you can switch it to bootloader mode and perform the next step. + +### 4. Update Firmware +Please make sure you have downloaded firmware nrf52840_dongle_dfu_dfu.zip package to the same directory of this tool. +To perform this step, choose second "Update" Tab, insert your OpenSK USB Dongle to your USB port, press the user button on hardware for more than 10 seconds to switch your OpenSK USB Dongle to bootloader mode, then click "Update" button, wait for the firmware to be 100% flashed. +Update Tool overview + +### 5. Inject Attestation Certificate and Private Key +The last step is to inject the cryptographic material if you enabled batch attestation or CTAP1/U2F compatibility (which is the case by default), otherwise, it can not work well. + +Choose third "Inject" Tab, attach your OpenSK USB Dongle to your USB port, click "Inject" button on this page. The user button of the OpenSK will flash, press the user button to agree, success status message will be showed quickly. +Update Tool overview + +Now you can test you OpenSK USB Dongle according to [Test Page](./test.md). \ No newline at end of file diff --git a/docs/images/Injectattestation.png b/docs/images/Injectattestation.png new file mode 100644 index 0000000..03608b4 Binary files /dev/null and b/docs/images/Injectattestation.png differ diff --git a/docs/images/erase_successfully.png b/docs/images/erase_successfully.png new file mode 100644 index 0000000..36d05f5 Binary files /dev/null and b/docs/images/erase_successfully.png differ diff --git a/docs/images/eraseconfirm.png b/docs/images/eraseconfirm.png new file mode 100644 index 0000000..78a2761 Binary files /dev/null and b/docs/images/eraseconfirm.png differ diff --git a/docs/images/filelocations.png b/docs/images/filelocations.png new file mode 100644 index 0000000..656f3ca Binary files /dev/null and b/docs/images/filelocations.png differ diff --git a/docs/images/tool_overview.png b/docs/images/tool_overview.png new file mode 100644 index 0000000..03746b3 Binary files /dev/null and b/docs/images/tool_overview.png differ diff --git a/docs/images/update_firmware_progress.png b/docs/images/update_firmware_progress.png new file mode 100644 index 0000000..62f7a39 Binary files /dev/null and b/docs/images/update_firmware_progress.png differ diff --git a/docs/index.md b/docs/index.md index 64b2df0..4eac19c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,105 +12,7 @@ In that [announcement](https://security.googleblog.com/2020/01/say-hello-to-open ``` The firmware of OpenSK is developed in Rust and it implements both FIDO U2F and FIDO2 [specifications](https://fidoalliance.org/specs/fido2/fido-client-to-authenticator-protocol-v2.1-rd-20191217.html). These specifications are released by [FIDO Alliance](https://fidoalliance.org/ "FIDO Alliance"), which is an open industry association with a focused mission: authentication standards to help reduce the world’s over-reliance on passwords. FEITIAN is the Board Member. -To help and accelerate FIDO security key adoption, FEITIAN improves the housing and makes new designs of OpenSK USB Dongle, removes unused PCB components, public the design. Users can build firmware from the source code of [Google OpenSK Github repository](https://github.com/google/opensk "OpenSK") without changing anything, provision it to this OpenSK hardware, to experience and try [FIDO](https://fidoalliance.org/ "FIDO Alliance") authentications. - -Before you try to program firmware to OpenSK, please read the original [OpenSK guide](https://github.com/google/OpenSK) at first. The following documents are most like additional remarks. +To help and accelerate FIDO security key adoption, FEITIAN improves the housing and makes new designs of OpenSK USB Dongle, removes useless PCB components, public the design. Users can build firmware from the source code of [Google OpenSK Github repository](https://github.com/google/opensk "OpenSK") without changing anything, provision it to this OpenSK hardware, to experience and try [FIDO](https://fidoalliance.org/ "FIDO Alliance") authentications. !!! warning "attention" Before you try or buy Feitian OpenSK Dongle, please be sure that you have read the important [caution](./caution.md) message. - -### OpenSK Model -We have two models of OpenSK USB Dongle, V1 and V2. They are designed according to the [nRF52840 USB dongle](https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF52840-Dongle), which is used by Google OpenSK firmware. The difference between V1 and V2 is the method to enter bootloader mode. - -To OpenSK V1, user should insert a paper clip or a SIM-eject tool to the RESET button hole to enter bootloader mode. This is similar to user push the RESET button on the nRF52840 USB dongle. - -To OpenSK V2, after user connects the device to a computer, he should push and hold on to the user button for more than 10 seconds, then OpenSK will be in bootloader mode. - -For detailed information, please refer to the [hardware description page](./hardware.md). - -## Programming firmware - -### 1. Pre-requisite - -- The OpenSK USB Dongle V1 or V2. -Before you program the firmware to OpenSK USB Dongle, you should switch it to ^^**==bootloader==**^^ mode. Please refer to the [Hardware Page](./hardware.md) to learn how to switch OpenSK to ^^**==bootloader==**^^ mode. You can check to make sure it is in bootloader according to [this section](./hardware#check-bootloader-mode) . -- Read the Original OpenSK guide. -Before you perform the following operations, please read [OpenSK](https://github.com/google/opensk) and its [installation guide](https://github.com/google/OpenSK/blob/master/docs/install.md) to learn how to customize your security key, for example, to change the signature counter mechanism and Attestation Certificate. -- Install [nrfutil](https://pypi.org/project/nrfutil/) tool. (```sudo pip3 install nrfutil``` or ```sudo pip3 install nrfutil --user```) -This tool allows you to directly flash firmware to OpenSK over USB without additional hardware. -Please find right version nrfutil and python. Make sure you have noted that nrfutil 6.x requires: Python ==>=3.6, <3.9== . -- Apply udev rule (Linux only). -If you are using Linux, you should add a udev rule to make OpenSK work well with FIDO applications and browsers. -``` -sudo cp rules.d/55-opensk.rules /etc/udev/rules.d/ -sudo udevadm control --reload -``` -Then unplug and replug the key for the rule to trigger. - -### 2. Development Environment and configuration -- Prepare a Development environment. -You should prepare a Development environment by yourself according to [this section](https://github.com/google/OpenSK/blob/master/docs/install.md#software). -The scripts provided in this project have been tested under **Linux** and **macOS**. We haven't tested them on Windows and other platforms. -- Clone [Google OpenSK Github repository](https://github.com/google/opensk "OpenSK"). -``` -$ git clone --recursive https://github.com/google/OpenSK.git -``` - -- Initial setup. -If you just cloned this repository, you need to run the following script: - -``` -$ ./setup.sh -``` -For more information, please refer to the [Initial setup](https://github.com/google/OpenSK/blob/master/docs/install.md#initial-setup). - -- Configure the OpenSK security parameter. -Please follow the description to change the [Attestation Certificate](https://github.com/google/OpenSK/blob/master/docs/install.md#replacing-the-certificates) as you want. If you are not familiar with OpenSK and FIDO, we recommend you do not change anything. - - -### 3. Flashing the firmware - -Although you can download the firmware to our OpenSK V1 and V2 by using J-LINK as described in [OpenSK installation guide](https://github.com/google/OpenSK/blob/master/docs/install.md), we recommend you program the firmware through the USB interface, it is more convenient. - -- Switch OpenSK to bootloader mode. -Please refer to [OpenSK Model](./index.md#opensk-model) or [hardware page](./hardware.md) to learn how to switch OpenSK to bootloader mode. -The LEDs show different behavior in different mode. Please refer to the [hardware page](./hardware.md) to see LED status of OpenSK V1 and V2. -2. Program the OpenSK USB dongle. -!!! note "NOTE" - If your USB dongle can not work well, you can erase the storage at first. - ``` - ./deploy.py --board=nrf52840_dongle_dfu --programmer=nordicdfu --erase_storage - ``` - After this command, you should switch your OpenSK to bootloader mode again to perform following operations. - - -``` -$ ./deploy.py --board=nrf52840_dongle_dfu --programmer=nordicdfu --opensk -``` - When prompt -``` -Press [ENTER] when ready. -``` - Just press Enter, the firmware will be flashed to your OpenSK USB Dongle. -When the progress bar reaches 100%, OpenSK USB Dongle will be in working mode automatically. - -!!! note "Linux" - If ```deploy.py``` returns error "==Permission denied: /dev/ttyxxxx==", - please change access permission of this device ```sudo chmod 666 /dev/ttyxxxx``` - - -Please provision Attestation Certificate and Private Key before you test your OpenSK. - - -### 4. Configure Attestation Certificate and Private Key -You need to inject the cryptographic material if you enabled batch attestation or CTAP1/U2F compatibility (which is the case by default), otherwise, it can not work well. -``` -./tools/configure.py \ - --certificate=crypto_data/opensk_cert.pem \ - --private-key=crypto_data/opensk.key -``` - -Now you can test your OpenSK. - -### Test FIDO functions -Please refer to [Test Page](./test.md). diff --git a/docs/originalway.md b/docs/originalway.md new file mode 100644 index 0000000..4c25f41 --- /dev/null +++ b/docs/originalway.md @@ -0,0 +1,90 @@ +# Official Way -- Command Line Tool + +## Background +This way is mentioned officially by [Google OpenSK GitHub pages](https://github.com/google/opensk) and [installation guide](https://github.com/google/OpenSK/blob/stable/docs/install.md). +Before you try to program firmware to OpenSK, please read the original [OpenSK guide](https://github.com/google/OpenSK) at first. +By using this way, you should install develop environment, such as python, rust, nrfutil, openssl and etc, clone the source code and build the project. Then use command line to download the firmware. +The following documents are most like additional remarks. + +## Pre-requisite + +- The OpenSK USB Dongle V1 or V2. +During the programming, you may need to switch OpenSK USB Dongle to ^^**==bootloader==**^^ mode. Please refer to the [Hardware Page](./hardware.md) to learn how to switch OpenSK to ^^**==bootloader==**^^ mode. You can check to make sure it is in bootloader according to [this section](./hardware#check-bootloader-mode) . +- Read the Original OpenSK guide. +Before you perform the following operations, please read original [OpenSK](https://github.com/google/opensk) and its [installation guide](https://github.com/google/OpenSK/blob/master/docs/install.md) to learn how to customize your security key, for example, to change the signature counter mechanism and Attestation Certificate. +- Install [nrfutil](https://pypi.org/project/nrfutil/) tool. (```sudo pip3 install nrfutil``` or ```sudo pip3 install nrfutil --user```) +This tool allows you to directly flash firmware to OpenSK over USB without additional hardware. +Please find right version nrfutil and python. Make sure you have noted that nrfutil 6.x requires: Python ==>=3.6, <3.9== . +- Apply udev rule (Linux only). +If you are using Linux, you should add a udev rule to make OpenSK work well with FIDO applications and browsers. +``` +sudo cp rules.d/55-opensk.rules /etc/udev/rules.d/ +sudo udevadm control --reload +``` +Then unplug and replug the key for the rule to trigger. + +- Development Environment and configuration +You should prepare a Development environment by yourself according to [this section](https://github.com/google/OpenSK/blob/master/docs/install.md#software). + +## Firmware build and update +### 1. Build firmware +The command and scripts showed below have been tested on **Linux** and **macOS**. We haven't tested them on Windows and other platforms. + +- Clone [Google OpenSK Github repository](https://github.com/google/opensk "OpenSK"). +``` +$ git clone --recursive https://github.com/google/OpenSK.git +``` + +- Initial setup. +If you just cloned this repository, you need to run the following script: +``` +$ ./setup.sh +``` +For more information, please refer to the [Initial setup](https://github.com/google/OpenSK/blob/master/docs/install.md#initial-setup). + +- Configure the OpenSK security parameter. +Please follow the description to change the [Attestation Certificate](https://github.com/google/OpenSK/blob/master/docs/install.md#replacing-the-certificates) as you want. If you are not familiar with OpenSK and FIDO, we recommend you do not change anything. + +### 2. Flash firmware + +Although you can download the firmware to our OpenSK V1 and V2 by using J-LINK as described in [OpenSK installation guide](https://github.com/google/OpenSK/blob/master/docs/install.md), we recommend you program the firmware through the USB interface, it is more convenient. + +- Switch OpenSK to bootloader mode. +Please refer to [OpenSK Model](./index.md#opensk-model) or [hardware page](./hardware.md) to learn how to switch OpenSK to bootloader mode. +The LEDs show different behavior in different mode. Please refer to the [hardware page](./hardware.md) to see LED status of OpenSK V1 and V2. +2. Program the OpenSK USB dongle. +!!! note "NOTE" + If your USB dongle can not work well, you can erase the storage at first. + ``` + ./deploy.py --board=nrf52840_dongle_dfu --programmer=nordicdfu --erase_storage + ``` + After this command, you should switch your OpenSK to bootloader mode again to perform following operations. + + +``` +$ ./deploy.py --board=nrf52840_dongle_dfu --programmer=nordicdfu --opensk +``` + When prompt +``` +Press [ENTER] when ready. +``` + Just press Enter, the firmware will be flashed to your OpenSK USB Dongle. +When the progress bar reaches 100%, OpenSK USB Dongle will be in working mode automatically. + +!!! note "Linux" + If ```deploy.py``` returns error "==Permission denied: /dev/ttyxxxx==", + please change access permission of this device ```sudo chmod 666 /dev/ttyxxxx``` + + +Please provision Attestation Certificate and Private Key before you test your OpenSK. + + +### 3. Configure Attestation Certificate and Private Key +You need to inject the cryptographic material if you enabled batch attestation or CTAP1/U2F compatibility (which is the case by default), otherwise, it can not work well. +``` +./tools/configure.py \ + --certificate=crypto_data/opensk_cert.pem \ + --private-key=crypto_data/opensk.key +``` + +Now you can test your OpenSK according to [Test Page](./test.md). diff --git a/docs/update.md b/docs/update.md new file mode 100644 index 0000000..e1e357a --- /dev/null +++ b/docs/update.md @@ -0,0 +1,25 @@ +## OpenSK Model +We have two models of OpenSK USB Dongle, V1 and V2. They are designed according to the [nRF52840 USB dongle](https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF52840-Dongle), which is used by Google OpenSK firmware. The difference between V1 and V2 is the method to enter bootloader mode. + +To OpenSK V1, user should insert a paper clip or a SIM-eject tool to the RESET button hole to enter bootloader mode. This is similar to user push the RESET button on the nRF52840 USB dongle. + +To OpenSK V2, after user connects the device to a computer, he should push and hold on to the user button for more than 10 seconds, then OpenSK will be in bootloader mode. + +For detailed information, please refer to the [hardware description page](./hardware.md). + +## Firmware Update +There are two ways to update firmware of OpenSK USB dongle. +One way is to follow the steps listed on official OpenSK github pages. +The other way is to use GUI Tool develop by Feitian Technologies. + +### 1. Official Way -- Command Line Tool +This way is mentioned officially by [Google OpenSK GitHub pages](https://github.com/google/opensk). +By using this way, you should install develop environment, such as python, rust, nrfutil, openssl and etc, clone the source code and build the project. Then use command line to download the firmware. +Please refer to [Official Way to update firmware](./originalway.md) to learn details. + +### 2. Feitian GUI Tool +It is very hard for end user to setup the develop environment, install required tools, build from the source code. To facilitate people who are not familiar with software development, Feitian developed a GUI tool for any user to simply download the firmware. +Please refer to [Feitian GUI tool](./feitianguiway.md) to find the detailed instruction. + +## Test FIDO functions +After you update the firmware, please refer to [Test Page](./test.md) to test FIDO functions. diff --git a/mkdocs.yml b/mkdocs.yml index 87a185f..6e11c21 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,9 +46,13 @@ markdown_extensions: - pymdownx.tilde nav: - - Home: 'index.md' + - About OpenSK: 'index.md' + - Update Firmware: + - Overview: "update.md" + - Command Line Tool: "originalway.md" + - Feitian GUI Tool: "feitianguiway.md" - Test FIDO: 'test.md' - - Hardware: 'hardware.md' - - About: 'about.md' + - Hardware Type: 'hardware.md' + - Contact: 'about.md' - Caution: 'caution.md' copyright: Copyright © 2020-2021 Feitian Technologies \ No newline at end of file