diff --git a/docs/hardware.md b/docs/hardware.md index a6e49b2..4e63da3 100644 --- a/docs/hardware.md +++ b/docs/hardware.md @@ -1,7 +1,7 @@ # Overview 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. +Currently, only **V2** is available to the market. ----- ## OpenSK V2 @@ -13,10 +13,10 @@ It has a metal housing with only one button in the aft area. The LED and User button are together. The button material is transparent, so user can see LED light through the button. ### 1. Switch To bootloader mode -After user connects the device to computer, **push and hold on** the user button for **more than 8** seconds and then release the button. If the red LED is breathing, OpenSK is in bootloader mode. +After user connects the device to a computer, **push and hold on** the user button for **more than 8** seconds and then release the button. If the red LED is breathing, OpenSK is in bootloader mode. ### 2. LED status -| LED behaviour | Mode type | Triger Method | +| LED behavior | Mode type | Trigger Method | | :-- | :-- | :-- | | Red LED is breathing | bootloader mode | Connect OpenSK to USB port, press the user button for more than 8 seconds and then release the button | | Red LED is flashing | bootloader mode | Flash the firmware | @@ -24,7 +24,7 @@ After user connects the device to computer, **push and hold on** the user button | R/G/B LED is flashing | Working mode | Wait for user presence when receiving FIDO command | ### 3. Hardware -The hardawre schematic and PCB are shared [here](hardware_files/OpenSK_V2.zip). +The hardware schematic and PCB are shared [here](hardware_files/OpenSK_V2.zip). ----- ## OpenSK V1 @@ -33,13 +33,13 @@ The hardawre schematic and PCB are shared [here](hardware_files/OpenSK_V2.zip). It has a 3D-printed case with one user button and one RESET button. ### 1. Switch To bootloader mode -After connect OpenSK to 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 as user pushes the [RESET button](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fug_nrf52840_dongle%2FUG%2Fnrf52840_Dongle%2Fprogramming.html) on original nRF52840 USB dongle. +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](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fug_nrf52840_dongle%2FUG%2Fnrf52840_Dongle%2Fprogramming.html) on the original nRF52840 USB dongle. !!! note "NOTE" - 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. + 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 -| LED behaviour | Mode type | Triger Method | +| 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 | @@ -47,4 +47,4 @@ After connect OpenSK to USB port, please insert a paper clip or a SIM-eject tool | R/G/B LED is flashing | Working mode | Wait for user presence when receiving FIDO command | ### 3. Hardware -The hardawre schematic and PCB files can be downloaded [here](hardware_files/OpenSK_V1.zip). +The hardware schematic and PCB files can be downloaded [here](hardware_files/OpenSK_V1.zip). diff --git a/docs/index.md b/docs/index.md index f3c8a1f..88d5045 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ # OpenSK logoFIDO logo ## Welcome to Feitian OpenSK USB Dongle -OpenSK was [announced](https://security.googleblog.com/2020/01/say-hello-to-opensk-fully-open-source.html "Say hello to OpenSK: a fully open-source security key implementation") by Google at January 30, 2020. It is a fully open-source FIDO security key implementation, include hardware and software. +OpenSK was [announced](https://security.googleblog.com/2020/01/say-hello-to-opensk-fully-open-source.html "Say hello to OpenSK: a fully open-source security key implementation") by Google on January 30, 2020. It is a fully open-source FIDO security key implementation, include hardware and software. In that [announcement](https://security.googleblog.com/2020/01/say-hello-to-opensk-fully-open-source.html "Say hello to OpenSK: a fully open-source security key implementation"), Google said ``` @@ -12,33 +12,33 @@ 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 design of OpenSK USB Dongle, remove unused PCB components, public the design. Users can build firmware from source code of [Google OpenSK github repository](https://github.com/google/opensk "OpenSK") without changing anything, provision it to this OpenSK hardware, to experence and try [FIDO](https://fidoalliance.org/ "FIDO Alliance") authentications. +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 original [OpenSK guide](https://github.com/google/OpenSK) at first. The following documents are most like additional remarks. +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. ### OpenSK Model -We have two model of OpenSK USB Dongle, V1 and V2. They are designed according to [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. +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 as user push the RESET button on nRF52840 USB dongle. +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 computer, he should push and hold on the user button for more 8 seconds, then OpenSK will be in bootloader mode. +To OpenSK V2, after user connects the device to a computer, he should push and hold on to the user button for more than 8 seconds, then OpenSK will be in bootloader mode. -For detailed informations, please refer to [hardware description page](./hardware.md). +For detailed information, please refer to the [hardware description page](./hardware.md). ## Programming firmware ### 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 [Harware Page](./hardware.md) to learn how to switch OpenSK to bootloader mode. -- Read Original OpenSK guide. -Before you perform following opertaions, 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 mechnisam and Attestation Certificate. +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. +- 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. This tool allows you to directly flash firmware to OpenSK over USB without additional hardware. -### Develop Environment and configuration -1. Prepare develop environment. -You should prepare developing environment by yourself according to [this section](https://github.com/google/OpenSK/blob/master/docs/install.md#software). +### Development Environment and configuration +1. 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). 2. Clone [Google OpenSK github repository](https://github.com/google/opensk "OpenSK"). ``` $ git clone --recursive https://github.com/google/OpenSK.git @@ -50,19 +50,19 @@ If you just cloned this repository, you need to run the following script: ``` $ ./setup.sh ``` -For more information, please refer to [Initial setup](https://github.com/google/OpenSK/blob/master/docs/install.md#initial-setup). +For more information, please refer to the [Initial setup](https://github.com/google/OpenSK/blob/master/docs/install.md#initial-setup). 4. Configure the OpenSK security parameter. -Please follow the description to change [Attestation Certificate](https://github.com/google/OpenSK/blob/master/docs/install.md#replacing-the-certificates) as you want. If you are not familar with OpenSK and FIDO, we recommend you do not change anything. +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. ### 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 USB interface, it is more convenient. +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. 1. 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 behaviour in differet mode. Please refer to [hardware page](./hardware.md) to see LED status of OpenSK V1 and V2 . +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. ``` $ ./deploy.py --board=nrf52840_dongle_dfu --opensk --programmer=nordicdfu @@ -71,9 +71,9 @@ $ ./deploy.py --board=nrf52840_dongle_dfu --opensk --programmer=nordicdfu ``` Press [ENTER] when ready. ``` - Just press Enter, the firmware will be flahsed to your OpenSK USB Dongle. + Just press Enter, the firmware will be flashed to your OpenSK USB Dongle. - When progress bar reaches 100%, OpenSK USB Dongle will be in working mode automatically. You can now test FIDO function. + When the progress bar reaches 100%, OpenSK USB Dongle will be in working mode automatically. You can now test FIDO function. !!! note "NOTE" If your dongle can not work well, please refer to https://github.com/google/OpenSK/pull/247 to erase the storage at first and then flash the firmware to try. ### Test FIDO functions diff --git a/docs/test.md b/docs/test.md index c87d32a..9be41b8 100644 --- a/docs/test.md +++ b/docs/test.md @@ -1,10 +1,10 @@ -Congratulations that you have got your own OpenSK USB dongle, now you can try FIDO functions to do fast online authentication. OpenSK implements [FIDO2(CTAP2)](https://fidoalliance.org/fido2/) and FIDO U2F specifications, it can support any website leveraging [W3C WebAuthN](https://www.w3.org/TR/webauthn/). +Congratulations that you have got your OpenSK USB dongle, now you can try FIDO functions to do fast online authentication. OpenSK implements [FIDO2(CTAP2)](https://fidoalliance.org/fido2/) and FIDO U2F specifications, it can support any website leveraging [W3C WebAuthN](https://www.w3.org/TR/webauthn/). ##Manage OpenSK -There are two ways to manage your OpenSK USB Dongle, include Reset, Set PIN and Change PIN. +There are two ways to manage your OpenSK USB Dongle, include Reset, Set PIN, and Change PIN. ####Windows Settings 1. Open the **Windows Settings app**, select **Accounts**, select **Sign-in options**, select **Security Key**, and then select **Manage**. -2. You can then attach OpenSK to USB port to manage it as as you want. +2. You can then attach OpenSK to the USB port to manage it as you want. !!! note "NOTE" 1. Please refer to [Microsoft Document](https://docs.microsoft.com/en-us/azure/active-directory/user-help/security-info-setup-security-key#manage-your-security-key-settings-from-windows-settings "Manage your security key settings from Windows Settings") for detailed information. @@ -15,7 +15,7 @@ There are two ways to manage your OpenSK USB Dongle, include Reset, Set PIN and 2. You can see **Manage security keys** page, then you can do corresponding operations following the tips. !!! note "NOTE" - I don't know the exact version of Chrome which started to add this UI, but please update it to latest version to have this function. + 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 There are a lot of Demo websites list [here](https://github.com/herrjemand/awesome-webauthn#demos), you can try and test. @@ -27,7 +27,7 @@ Here I recommend I can not guaranty that all the demo websites can work well with OpenSK. ##Real use cases -There are a lot of online servides which can use FIDO2/U2F to do 2FA or passwordless authentication, please refer to [FEITIAN website](https://www.ftsafe.com/article/620.html) and click corresponding service ICON to learn. +There are a lot of online services that can use FIDO2/U2F to do 2FA or passwordless authentication, please refer to [FEITIAN website](https://www.ftsafe.com/article/620.html) and click corresponding service ICON to learn. Here just emphasize services from two big FIDO players, Google and Microsoft. @@ -36,7 +36,7 @@ Here just emphasize services from two big FIDO players, Google and Microsoft. - Please refer to [Google's help](https://support.google.com/accounts/answer/185839?co=GENIE.Platform%3DAndroid&hl=en) to bind OpenSK to your Google services. Or - Take a look at 2.1 of [Feitian's help document](https://www.ftsafe.com/download/webdownload/FIDO/Manual/FEITIAN%20U2F%20scenarios%20instructions.pdf) to bind and try OpenSK instead of ePass FIDO security key. -#### - Googel Advanced Protection +#### - Google Advanced Protection - Please refer to [landing page](https://landing.google.com/advancedprotection/) or [help page](https://support.google.com/accounts/answer/7519408?co=GENIE.Platform%3DAndroid&hl=en&oco=0) of Google Advanced Protection to get how to setup. ### Microsoft @@ -48,6 +48,6 @@ Here just emphasize services from two big FIDO players, Google and Microsoft. Surely there are a lot of other online services except for Google's and Microsoft's, you can learn from - [FIDO2 Scenarios](https://download.ftsafe.com/files/FIDO/fido2/FEITIAN%20FIDO2%20scenarios%20instructions.pdf) and [U2F Scenarios](https://www.ftsafe.com/download/webdownload/FIDO/Manual/FEITIAN%20U2F%20scenarios%20instructions.pdf) from Feitian's resources. - [Knowledge Base](https://xpass.freshdesk.com/support/solutions/60000318639) from Feitian -- [fido.ftsafe.com](https://fido.ftsafe.com/catalog/) Dedicated FIDO website from Feitian. Here you can find list of online services to use FIDO. +- [fido.ftsafe.com](https://fido.ftsafe.com/catalog/) Dedicated FIDO website from Feitian. Here you can find the list of online services to use FIDO.