mirror of
https://github.com/FeitianTech/OpenSK_USB.git
synced 2026-08-28 10:40:45 -07:00
1 line
44 KiB
JSON
1 line
44 KiB
JSON
{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"\u00b6 Welcome to Feitian OpenSK USB Dongle \u00b6 OpenSK was announced by Google on January 30, 2020. It is a fully open-source FIDO security key implementation, include hardware and software. In that announcement , Google said By opening up OpenSK as a research platform, our hope is that it will be used by researchers, security key manufacturers, and enthusiasts to help develop innovative features and accelerate security key adoption. The firmware of OpenSK is developed in Rust and it implements both FIDO U2F and FIDO2 specifications . These specifications are released by FIDO Alliance , which is an open industry association with a focused mission: authentication standards to help reduce the world\u2019s 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 useless PCB components, public the design. Users can build firmware from the source code of Google OpenSK Github repository without changing anything, provision it to this OpenSK hardware, to experience and try FIDO authentications. attention Before you try or buy Feitian OpenSK Dongle, please be sure that you have read the important caution message.","title":"About OpenSK"},{"location":"#_1","text":"","title":""},{"location":"#welcome-to-feitian-opensk-usb-dongle","text":"OpenSK was announced by Google on January 30, 2020. It is a fully open-source FIDO security key implementation, include hardware and software. In that announcement , Google said By opening up OpenSK as a research platform, our hope is that it will be used by researchers, security key manufacturers, and enthusiasts to help develop innovative features and accelerate security key adoption. The firmware of OpenSK is developed in Rust and it implements both FIDO U2F and FIDO2 specifications . These specifications are released by FIDO Alliance , which is an open industry association with a focused mission: authentication standards to help reduce the world\u2019s 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 useless PCB components, public the design. Users can build firmware from the source code of Google OpenSK Github repository without changing anything, provision it to this OpenSK hardware, to experience and try FIDO authentications. attention Before you try or buy Feitian OpenSK Dongle, please be sure that you have read the important caution message.","title":"Welcome to Feitian OpenSK USB Dongle"},{"location":"about/","text":"Feitian Technologies US, Inc. \u00b6 Website: https://xpasskey.com Online Store: https://shop.ftsafe.us [US & CANADA] Amazon Store: https://www.amazon.com/s?me=A30V4CZBKPUCSD&marketplaceID=ATVPDKIKX0DER Feitian Technologies Co., Ltd. \u00b6 Website: https://www.ftsafe.com Online Store: https://www.ftsafe.com/Store [Other regions] Alibaba Store: https://ftsafe.en.alibaba.com/ [Other regions] Contact \u00b6 email: world.sales@ftsafe.com email: fido@ftsafe.com","title":"Contact"},{"location":"about/#feitian-technologies-us-inc","text":"Website: https://xpasskey.com Online Store: https://shop.ftsafe.us [US & CANADA] Amazon Store: https://www.amazon.com/s?me=A30V4CZBKPUCSD&marketplaceID=ATVPDKIKX0DER","title":"Feitian Technologies US, Inc."},{"location":"about/#feitian-technologies-co-ltd","text":"Website: https://www.ftsafe.com Online Store: https://www.ftsafe.com/Store [Other regions] Alibaba Store: https://ftsafe.en.alibaba.com/ [Other regions]","title":"Feitian Technologies Co., Ltd."},{"location":"about/#contact","text":"email: world.sales@ftsafe.com email: fido@ftsafe.com","title":"Contact"},{"location":"caution/","text":"Caution \u00b6 You should read the following notes before you try or buy our OpenSK dongle. Please keep in mind that OpenSK is a research platform, Google hopes it is used by researchers, security key manufacturers, and enthusiasts to help develop innovative features and accelerate security key adoption. Feitian OpenSK dongle is manufactured for researchers or enthusiasts to learn what FIDO is and how it works. It is not intended to be used for the circumstance that needs highest security. The core nRF52840 chip is just a microcontroller instead of a secure element , so this OpenSK dongle may not resist some advanced hardware and physical attacks. It is not much safe to protect your personal online account and secret data as other Feitian FIDO security keys can do. So if you are a government officer, journalist, activist, or someone else at risk of targeted online attacks and need deeply secure protection, we recommend you to use our commercial Feitian FIDO security keys . Except for some advanced hardware and physical attacks, OpenSK is still a better choice to protect your online account remotely. If you want to use it to protect your personal data, please keep it safe and do not provide it to any other one wittingly or involuntarily. \u00b6","title":"Caution"},{"location":"caution/#caution","text":"You should read the following notes before you try or buy our OpenSK dongle. Please keep in mind that OpenSK is a research platform, Google hopes it is used by researchers, security key manufacturers, and enthusiasts to help develop innovative features and accelerate security key adoption. Feitian OpenSK dongle is manufactured for researchers or enthusiasts to learn what FIDO is and how it works. It is not intended to be used for the circumstance that needs highest security. The core nRF52840 chip is just a microcontroller instead of a secure element , so this OpenSK dongle may not resist some advanced hardware and physical attacks. It is not much safe to protect your personal online account and secret data as other Feitian FIDO security keys can do. So if you are a government officer, journalist, activist, or someone else at risk of targeted online attacks and need deeply secure protection, we recommend you to use our commercial Feitian FIDO security keys . Except for some advanced hardware and physical attacks, OpenSK is still a better choice to protect your online account remotely. If you want to use it to protect your personal data, please keep it safe and do not provide it to any other one wittingly or involuntarily.","title":"Caution"},{"location":"caution/#_1","text":"","title":""},{"location":"feitianguiway/","text":"Background \u00b6 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 provides official steps 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 \u00b6 This tool is open source software, anyone can review the source code from OpenSK Update Tool Github Repository . Feitian will build the firmware from official Google OpenSK github repository aperiodically, and list the binary firmware on Feitian OpenSK Repository . User can choose the firmware version they like and re-program the OpenSK USB dongle directly without extra work. Guide \u00b6 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 to learn how to switch the OpenSK USB dongle to bootloader mode. 1. Download tool and files \u00b6 You can download the tool and from OpenSK Update Tool Github Repository . You can download firmware and attestation cryptographic material from Feitian OpenSK Repository . NOTE The crypto materials downloaded here were pre-generated just to show how to use the firmware update tool. To keep the hardware security and privacy, OpenSK dongle sold publicly uses different crypto materials. You can generate your own crypto materials (for example, use XCA tool). After you download the firmware and attestation cryptographic material, put them into the same directory of this update tool like below picture showed. 2. Launch Update Tool \u00b6 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. 3. Erase Storage (Optional) \u00b6 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 (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. 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 \u00b6 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. 5. Inject Attestation Certificate and Private Key \u00b6 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. Now you can test you OpenSK USB Dongle according to Test Page .","title":"Feitian GUI Tool"},{"location":"feitianguiway/#background","text":"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 provides official steps 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.","title":"Background"},{"location":"feitianguiway/#open-source","text":"This tool is open source software, anyone can review the source code from OpenSK Update Tool Github Repository . Feitian will build the firmware from official Google OpenSK github repository aperiodically, and list the binary firmware on Feitian OpenSK Repository . User can choose the firmware version they like and re-program the OpenSK USB dongle directly without extra work.","title":"Open Source"},{"location":"feitianguiway/#guide","text":"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 to learn how to switch the OpenSK USB dongle to bootloader mode.","title":"Guide"},{"location":"feitianguiway/#1-download-tool-and-files","text":"You can download the tool and from OpenSK Update Tool Github Repository . You can download firmware and attestation cryptographic material from Feitian OpenSK Repository . NOTE The crypto materials downloaded here were pre-generated just to show how to use the firmware update tool. To keep the hardware security and privacy, OpenSK dongle sold publicly uses different crypto materials. You can generate your own crypto materials (for example, use XCA tool). After you download the firmware and attestation cryptographic material, put them into the same directory of this update tool like below picture showed.","title":"1. Download tool and files"},{"location":"feitianguiway/#2-launch-update-tool","text":"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.","title":"2. Launch Update Tool"},{"location":"feitianguiway/#3-erase-storage-optional","text":"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 (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. 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.","title":"3. Erase Storage (Optional)"},{"location":"feitianguiway/#4-update-firmware","text":"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.","title":"4. Update Firmware"},{"location":"feitianguiway/#5-inject-attestation-certificate-and-private-key","text":"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. Now you can test you OpenSK USB Dongle according to Test Page .","title":"5. Inject Attestation Certificate and Private Key"},{"location":"hardware/","text":"Overview \u00b6 We have two types of OpenSK, V1 and V2. They have almost same schematic but different casing. Currently, only V2 is available to the market. OpenSK V2 \u00b6 It has a metal housing with only one button in the aft area. NOTE The LED and User button are together. The button material is transparent, so user can see LED light through the button. Since the LED is behind the button, you have to check it from the aft area to find it breathing or flashing. 1. Switch To bootloader mode \u00b6 After user connects the device to a computer, push and hold on the user button for more than 10 seconds and then release the button. If the red LED is breathing , OpenSK is in bootloader mode. 2. LED status \u00b6 LED behavior Mode type Trigger Method Red LED is breathing bootloader mode Connect OpenSK to USB port, press the user button for more than more than 10 seconds and then release the button Red LED is flashing bootloader mode Flash the firmware No LED on Working mode Idle R/G/B LED is flashing Working mode Wait for user presence when receiving FIDO command 3. Hardware \u00b6 The hardware schematic and PCB are shared here . OpenSK V1 \u00b6 It has a 3D-printed case with one user button and one RESET button. 1. Switch To bootloader mode \u00b6 After connecting OpenSK to the USB port, please insert a paper clip or a SIM-eject tool to the RESET button hole to switch it to bootloader mode. This is similar to user pushes the RESET button on the original nRF52840 USB dongle. NOTE The RESET button hole is covered by OpenSK label. So if you want to program the firmware occasionally, you can choose not to cover the label although we send the label to you together with OpenSK hardware. 2. LED status \u00b6 LED behavior Mode type Trigger Method Blue LED is breathing bootloader mode Use a paper clip or a SIM-eject tool to push RESET button in RESET button hole Blue LED is flashing bootloader mode Flashing the firmware No LED on Working mode Idle R/G/B LED is flashing Working mode Wait for user presence when receiving FIDO command 3. Hardware \u00b6 The hardware schematic and PCB files can be downloaded here . Check Bootloader Mode \u00b6 Sometimes, maybe you don't know whether your OpenSK is in bootloader mode after above operation, you can have three ways to check. 1. LED breathing \u00b6 If the red LED is breathing , OpenSK is in bootloader mode, this is the simplest way. 2. macOS \u00b6 2.1. lsusb command \u00b6 On macOS, open Terminal.app , run $ lsusb to check the result. (Plesae make sure you have this command installed previously.) If there is line similar to below message Bus XXX Device YYY: ID 1915:521f Nordic Semiconductor ASA Open DFU Bootloader Serial: FFCCAE942A17 then it is in bootloader mode. If there is line similar to below message Bus XXX Device YYY: ID 1915:521f Nordic Semiconductor ASA OpenSK Serial: v1.0 Then it is in normal working mode. 2.2. USB Prober.app \u00b6 On macOS, if you have USB Prober.app installed, run this app. If you have OpenSK attached and it is in bootloader mode, you should find USB information similar to below picture. This means it is in bootloader mode. 2. Linux \u00b6 On Linux (e.g., Ubuntu), Open Terminal. After you plug in the USB dongle, or the USB dongle is changed between bootload mode and normal working mode, run lsusb on Terminal. $ lsusb No matter your USB dongle is in normal working mode or bootloader mode, the result is always Bus XXX Device YYY: ID 1915:521f Nordic Semiconductor ASA Then run $ dmesg If your USB dongle is in bootloader mode, you should find below similar output message: [ XXXX.YYYYYY] usb 2-2.8: new full-speed USB device number 24 using uhci_hcd [ XXXX.YYYYYY] usb 2-2.8: New USB device found, idVendor=1915, idProduct=521f, bcdDevice= 1.00 [ XXXX.YYYYYY] usb 2-2.8: New USB device strings: Mfr=1, Product=2, SerialNumber=3 [ XXXX.YYYYYY] usb 2-2.8: Product: Open DFU Bootloader [ XXXX.YYYYYY] usb 2-2.8: Manufacturer: Nordic Semiconductor [ XXXX.YYYYYY] usb 2-2.8: SerialNumber: FFCCAE942A17 Otherwise, if your USB dongle is in normal working mode, the output message should be similar to [ XXXX.YYYYYY] usb 2-2.8: new full-speed USB device number 22 using uhci_hcd [ XXXX.YYYYYY] usb 2-2.8: New USB device found, idVendor=1915, idProduct=521f, bcdDevice= 0.01 [ XXXX.YYYYYY] usb 2-2.8: New USB device strings: Mfr=1, Product=2, SerialNumber=3 [ XXXX.YYYYYY] usb 2-2.8: Product: OpenSK [ XXXX.YYYYYY] usb 2-2.8: Manufacturer: Nordic Semiconductor ASA [ XXXX.YYYYYY] usb 2-2.8: SerialNumber: v1.0 [ XXXX.YYYYYY] hid-generic 0003:1915:521F.0009: hiddev0,hidraw2: USB HID v1.10 Device [Nordic Semiconductor ASA OpenSK ] on usb-0000:00:1d.0-2.8/input0 NOTE You'd better use sudo dmesg -c command instead of dmesg to output latest new added message.","title":"Hardware Type"},{"location":"hardware/#overview","text":"We have two types of OpenSK, V1 and V2. They have almost same schematic but different casing. Currently, only V2 is available to the market.","title":"Overview"},{"location":"hardware/#opensk-v2","text":"It has a metal housing with only one button in the aft area. NOTE The LED and User button are together. The button material is transparent, so user can see LED light through the button. Since the LED is behind the button, you have to check it from the aft area to find it breathing or flashing.","title":"OpenSK V2"},{"location":"hardware/#1-switch-to-bootloader-mode","text":"After user connects the device to a computer, push and hold on the user button for more than 10 seconds and then release the button. If the red LED is breathing , OpenSK is in bootloader mode.","title":"1. Switch To bootloader mode"},{"location":"hardware/#2-led-status","text":"LED behavior Mode type Trigger Method Red LED is breathing bootloader mode Connect OpenSK to USB port, press the user button for more than more than 10 seconds and then release the button Red LED is flashing bootloader mode Flash the firmware No LED on Working mode Idle R/G/B LED is flashing Working mode Wait for user presence when receiving FIDO command","title":"2. LED status"},{"location":"hardware/#3-hardware","text":"The hardware schematic and PCB are shared here .","title":"3. Hardware"},{"location":"hardware/#opensk-v1","text":"It has a 3D-printed case with one user button and one RESET button.","title":"OpenSK V1"},{"location":"hardware/#1-switch-to-bootloader-mode_1","text":"After connecting OpenSK to the USB port, please insert a paper clip or a SIM-eject tool to the RESET button hole to switch it to bootloader mode. This is similar to user pushes the RESET button on the original nRF52840 USB dongle. NOTE The RESET button hole is covered by OpenSK label. So if you want to program the firmware occasionally, you can choose not to cover the label although we send the label to you together with OpenSK hardware.","title":"1. Switch To bootloader mode"},{"location":"hardware/#2-led-status_1","text":"LED behavior Mode type Trigger Method Blue LED is breathing bootloader mode Use a paper clip or a SIM-eject tool to push RESET button in RESET button hole Blue LED is flashing bootloader mode Flashing the firmware No LED on Working mode Idle R/G/B LED is flashing Working mode Wait for user presence when receiving FIDO command","title":"2. LED status"},{"location":"hardware/#3-hardware_1","text":"The hardware schematic and PCB files can be downloaded here .","title":"3. Hardware"},{"location":"hardware/#check-bootloader-mode","text":"Sometimes, maybe you don't know whether your OpenSK is in bootloader mode after above operation, you can have three ways to check.","title":"Check Bootloader Mode"},{"location":"hardware/#1-led-breathing","text":"If the red LED is breathing , OpenSK is in bootloader mode, this is the simplest way.","title":"1. LED breathing"},{"location":"hardware/#2-macos","text":"","title":"2. macOS"},{"location":"hardware/#21-lsusb-command","text":"On macOS, open Terminal.app , run $ lsusb to check the result. (Plesae make sure you have this command installed previously.) If there is line similar to below message Bus XXX Device YYY: ID 1915:521f Nordic Semiconductor ASA Open DFU Bootloader Serial: FFCCAE942A17 then it is in bootloader mode. If there is line similar to below message Bus XXX Device YYY: ID 1915:521f Nordic Semiconductor ASA OpenSK Serial: v1.0 Then it is in normal working mode.","title":"2.1. lsusb command"},{"location":"hardware/#22-usb-proberapp","text":"On macOS, if you have USB Prober.app installed, run this app. If you have OpenSK attached and it is in bootloader mode, you should find USB information similar to below picture. This means it is in bootloader mode.","title":"2.2. USB Prober.app"},{"location":"hardware/#2-linux","text":"On Linux (e.g., Ubuntu), Open Terminal. After you plug in the USB dongle, or the USB dongle is changed between bootload mode and normal working mode, run lsusb on Terminal. $ lsusb No matter your USB dongle is in normal working mode or bootloader mode, the result is always Bus XXX Device YYY: ID 1915:521f Nordic Semiconductor ASA Then run $ dmesg If your USB dongle is in bootloader mode, you should find below similar output message: [ XXXX.YYYYYY] usb 2-2.8: new full-speed USB device number 24 using uhci_hcd [ XXXX.YYYYYY] usb 2-2.8: New USB device found, idVendor=1915, idProduct=521f, bcdDevice= 1.00 [ XXXX.YYYYYY] usb 2-2.8: New USB device strings: Mfr=1, Product=2, SerialNumber=3 [ XXXX.YYYYYY] usb 2-2.8: Product: Open DFU Bootloader [ XXXX.YYYYYY] usb 2-2.8: Manufacturer: Nordic Semiconductor [ XXXX.YYYYYY] usb 2-2.8: SerialNumber: FFCCAE942A17 Otherwise, if your USB dongle is in normal working mode, the output message should be similar to [ XXXX.YYYYYY] usb 2-2.8: new full-speed USB device number 22 using uhci_hcd [ XXXX.YYYYYY] usb 2-2.8: New USB device found, idVendor=1915, idProduct=521f, bcdDevice= 0.01 [ XXXX.YYYYYY] usb 2-2.8: New USB device strings: Mfr=1, Product=2, SerialNumber=3 [ XXXX.YYYYYY] usb 2-2.8: Product: OpenSK [ XXXX.YYYYYY] usb 2-2.8: Manufacturer: Nordic Semiconductor ASA [ XXXX.YYYYYY] usb 2-2.8: SerialNumber: v1.0 [ XXXX.YYYYYY] hid-generic 0003:1915:521F.0009: hiddev0,hidraw2: USB HID v1.10 Device [Nordic Semiconductor ASA OpenSK ] on usb-0000:00:1d.0-2.8/input0 NOTE You'd better use sudo dmesg -c command instead of dmesg to output latest new added message.","title":"2. Linux"},{"location":"originalway/","text":"Official Way -- Command Line Tool \u00b6 Background \u00b6 This way is mentioned officially by Google OpenSK GitHub pages and installation guide . Before you try to program firmware to OpenSK, please read the original OpenSK guide 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 \u00b6 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 to learn how to switch OpenSK to bootloader mode. You can check to make sure it is in bootloader according to this section . Read the Original OpenSK guide. Before you perform the following operations, please read original OpenSK and its installation guide to learn how to customize your security key, for example, to change the signature counter mechanism and Attestation Certificate. Install 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 . Firmware build and update \u00b6 1. Build firmware \u00b6 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 . $ 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 . Configure the OpenSK security parameter. Please follow the description to change the Attestation Certificate as you want. If you are not familiar with OpenSK and FIDO, we recommend you do not change anything. 2. Flash firmware \u00b6 Although you can download the firmware to our OpenSK V1 and V2 by using J-LINK as described in OpenSK installation guide , we recommend you program the firmware through the USB interface, it is more convenient. Switch OpenSK to bootloader mode. Please refer to OpenSK Model or hardware page to learn how to switch OpenSK to bootloader mode. The LEDs show different behavior in different mode. Please refer to the hardware page to see LED status of OpenSK V1 and V2. Program the OpenSK USB dongle. 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. 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 \u00b6 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 WARNING When you add a security to Google services, you may encount problem because OpenSK uses self attestation. So plesae click \"Skip\" when Chrome prompts \"allow this site to see your security key? google.com wants to see the make and model of your security key.\" Now you can test your OpenSK according to Test Page .","title":"Command Line Tool"},{"location":"originalway/#official-way-command-line-tool","text":"","title":"Official Way -- Command Line Tool"},{"location":"originalway/#background","text":"This way is mentioned officially by Google OpenSK GitHub pages and installation guide . Before you try to program firmware to OpenSK, please read the original OpenSK guide 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.","title":"Background"},{"location":"originalway/#pre-requisite","text":"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 to learn how to switch OpenSK to bootloader mode. You can check to make sure it is in bootloader according to this section . Read the Original OpenSK guide. Before you perform the following operations, please read original OpenSK and its installation guide to learn how to customize your security key, for example, to change the signature counter mechanism and Attestation Certificate. Install 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 .","title":"Pre-requisite"},{"location":"originalway/#firmware-build-and-update","text":"","title":"Firmware build and update"},{"location":"originalway/#1-build-firmware","text":"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 . $ 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 . Configure the OpenSK security parameter. Please follow the description to change the Attestation Certificate as you want. If you are not familiar with OpenSK and FIDO, we recommend you do not change anything.","title":"1. Build firmware"},{"location":"originalway/#2-flash-firmware","text":"Although you can download the firmware to our OpenSK V1 and V2 by using J-LINK as described in OpenSK installation guide , we recommend you program the firmware through the USB interface, it is more convenient. Switch OpenSK to bootloader mode. Please refer to OpenSK Model or hardware page to learn how to switch OpenSK to bootloader mode. The LEDs show different behavior in different mode. Please refer to the hardware page to see LED status of OpenSK V1 and V2. Program the OpenSK USB dongle. 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. 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.","title":"2. Flash firmware"},{"location":"originalway/#3-configure-attestation-certificate-and-private-key","text":"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 WARNING When you add a security to Google services, you may encount problem because OpenSK uses self attestation. So plesae click \"Skip\" when Chrome prompts \"allow this site to see your security key? google.com wants to see the make and model of your security key.\" Now you can test your OpenSK according to Test Page .","title":"3. Configure Attestation Certificate and Private Key"},{"location":"test/","text":"Congratulations that you have got your OpenSK USB dongle, now you can try FIDO functions to do fast online authentication. OpenSK implements FIDO2(CTAP2) and FIDO U2F specifications, it can support any website leveraging W3C WebAuthN . Manage OpenSK \u00b6 There are two ways to manage your OpenSK USB Dongle, include Reset, Set PIN, and Change PIN. Windows Settings \u00b6 Open the Windows Settings app , select Accounts , select Sign-in options , select Security Key , and then select Manage . You can then attach OpenSK to the USB port to manage it as you want. NOTE Please refer to Microsoft Document for detailed information. Security Key option in Windows Settings is only available from Windows 10 1903. Chrome Browser \u00b6 From Chrome browser, open URL chrome://settings/securityKeys , or open menu \"Settings\u201d => \u201cPrivacy and security\u201d (More)=> \u201cManage security keys\u201d. You can see Manage security keys page, then you can do corresponding operations following the tips. NOTE I don't know the exact version of Chrome that started to add this UI, but please update it to the latest version to have this function. Demo Websites \u00b6 There are a lot of Demo websites list here , you can try and test. Here I recommend - https://webauthn.io/ (from DUO) - https://webauthndemo.appspot.com/ (from Google) WARNING I can not guaranty that all the demo websites can work well with OpenSK. Real use cases \u00b6 There are a lot of online services that can use FIDO2/U2F to do 2FA or passwordless authentication, please refer to FEITIAN website and click corresponding service ICON to learn. Here just emphasize services from two big FIDO players, Google and Microsoft. Google \u00b6 - Google 2-Step Verification \u00b6 Please refer to Google's help to bind OpenSK to your Google services. Or Take a look at 2.1 of Feitian's help document to bind and try OpenSK instead of ePass FIDO security key. - Google Advanced Protection \u00b6 Please refer to landing page or help page of Google Advanced Protection to get how to setup. WARNING When you add a security to Google services, you may encount problem because OpenSK uses self attestation. So plesae click \"Skip\" when Chrome prompts \"allow this site to see your security key? google.com wants to see the make and model of your security key.\" Microsoft \u00b6 Microsoft Account Passwordless Logon \u00b6 Please refer to Microsoft Blog to learn how to do Microsoft Account Passwordless Logon with FIDO2 security keys. Or Take a look at Chapter 2.2 of FEITIAN FIDO2 scenarios to configure OpenSK with Microsoft Account step by step. Others \u00b6 Surely there are a lot of other online services except for Google's and Microsoft's, you can learn from - FIDO2 Scenarios and U2F Scenarios from Feitian's resources. - Knowledge Base from Feitian - fido.ftsafe.com Dedicated FIDO website from Feitian. Here you can find the list of online services to use FIDO.","title":"Test FIDO"},{"location":"test/#manage-opensk","text":"There are two ways to manage your OpenSK USB Dongle, include Reset, Set PIN, and Change PIN.","title":"Manage OpenSK"},{"location":"test/#windows-settings","text":"Open the Windows Settings app , select Accounts , select Sign-in options , select Security Key , and then select Manage . You can then attach OpenSK to the USB port to manage it as you want. NOTE Please refer to Microsoft Document for detailed information. Security Key option in Windows Settings is only available from Windows 10 1903.","title":"Windows Settings"},{"location":"test/#chrome-browser","text":"From Chrome browser, open URL chrome://settings/securityKeys , or open menu \"Settings\u201d => \u201cPrivacy and security\u201d (More)=> \u201cManage security keys\u201d. You can see Manage security keys page, then you can do corresponding operations following the tips. NOTE I don't know the exact version of Chrome that started to add this UI, but please update it to the latest version to have this function.","title":"Chrome Browser"},{"location":"test/#demo-websites","text":"There are a lot of Demo websites list here , you can try and test. Here I recommend - https://webauthn.io/ (from DUO) - https://webauthndemo.appspot.com/ (from Google) WARNING I can not guaranty that all the demo websites can work well with OpenSK.","title":"Demo Websites"},{"location":"test/#real-use-cases","text":"There are a lot of online services that can use FIDO2/U2F to do 2FA or passwordless authentication, please refer to FEITIAN website and click corresponding service ICON to learn. Here just emphasize services from two big FIDO players, Google and Microsoft.","title":"Real use cases"},{"location":"test/#google","text":"","title":"Google"},{"location":"test/#-google-2-step-verification","text":"Please refer to Google's help to bind OpenSK to your Google services. Or Take a look at 2.1 of Feitian's help document to bind and try OpenSK instead of ePass FIDO security key.","title":"- Google 2-Step Verification"},{"location":"test/#-google-advanced-protection","text":"Please refer to landing page or help page of Google Advanced Protection to get how to setup. WARNING When you add a security to Google services, you may encount problem because OpenSK uses self attestation. So plesae click \"Skip\" when Chrome prompts \"allow this site to see your security key? google.com wants to see the make and model of your security key.\"","title":"- Google Advanced Protection"},{"location":"test/#microsoft","text":"","title":"Microsoft"},{"location":"test/#microsoft-account-passwordless-logon","text":"Please refer to Microsoft Blog to learn how to do Microsoft Account Passwordless Logon with FIDO2 security keys. Or Take a look at Chapter 2.2 of FEITIAN FIDO2 scenarios to configure OpenSK with Microsoft Account step by step.","title":"Microsoft Account Passwordless Logon"},{"location":"test/#others","text":"Surely there are a lot of other online services except for Google's and Microsoft's, you can learn from - FIDO2 Scenarios and U2F Scenarios from Feitian's resources. - Knowledge Base from Feitian - fido.ftsafe.com Dedicated FIDO website from Feitian. Here you can find the list of online services to use FIDO.","title":"Others"},{"location":"update/","text":"OpenSK Model \u00b6 We have two models of OpenSK USB Dongle, V1 and V2. They are designed according to the nRF52840 USB 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 . Firmware Update \u00b6 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 \u00b6 This way is mentioned officially by Google OpenSK GitHub pages . 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 to learn details. 2. Feitian GUI Tool \u00b6 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 to find the detailed instruction. Test FIDO functions \u00b6 After you update the firmware, please refer to Test Page to test FIDO functions.","title":"Overview"},{"location":"update/#opensk-model","text":"We have two models of OpenSK USB Dongle, V1 and V2. They are designed according to the nRF52840 USB 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 .","title":"OpenSK Model"},{"location":"update/#firmware-update","text":"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.","title":"Firmware Update"},{"location":"update/#1-official-way-command-line-tool","text":"This way is mentioned officially by Google OpenSK GitHub pages . 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 to learn details.","title":"1. Official Way -- Command Line Tool"},{"location":"update/#2-feitian-gui-tool","text":"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 to find the detailed instruction.","title":"2. Feitian GUI Tool"},{"location":"update/#test-fido-functions","text":"After you update the firmware, please refer to Test Page to test FIDO functions.","title":"Test FIDO functions"}]} |