feitian/OpenSK_USB
0
0
Fork 0
mirror of https://github.com/FeitianTech/OpenSK_USB.git synced 2026-08-28 10:40:45 -07:00
Code Issues Packages Projects Releases Wiki Activity

change soem message

Browse Source
This commit is contained in:
superskybird
2020-05-28 17:24:21 +08:00
parent a00fdd6c8f
commit bbee918e9a
4 changed files with 69 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/hardware.md
+27 -27
View File
@@ -1,27 +1,6 @@
# Overview
We have two types of OpenSK, V1 and V2. They have almost same schematic but different casing.
-----
## OpenSK V1
<img alt="OpenSK V1" src="../images/K46_with_label_reset.png" width="300px">
### 1. Switch To DFU 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 DFU mode. This is similar as user push the RESET button on 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.
### 2. LED status
| LED behaviour | Mode type | Triger Method |
| :-- | :-- | :-- |
| Blue LED is breathing | DFU mode | Use a paper clip or a SIM-eject tool to push RESET button in RESET button hole |
| Blue LED is flashing | DFU 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
The hardawre schematic and PCB files can be downloaded [here](hardware_files/OpenSK_V1.zip).
We have two types of OpenSK, V1 and V2. They have almost same schematic but different casing.
-----
## OpenSK V2
@@ -30,16 +9,37 @@ The hardawre schematic and PCB files can be downloaded [here](hardware_files/Ope
!!! note "NOTE"
The LED and User button are together. The button material is transparent, so user can see LED light through the button.
### 1. Switch To DFU mode
after user connect the device to computer, user should push and hold on the user button for more than 8 seconds, then OpenSK will be in DFU mode.
### 1. Switch To bootloader mode
After user connects the device to computer, user should push and hold on the user button for more than 8 seconds, then OpenSK will be in bootloader mode.
### 2. LED status
| LED behaviour | Mode type | Triger Method |
| :-- | :-- | :-- |
| Red LED is breathing | DFU mode | Use a paper clip or a SIM-eject tool to push RESET button in RESET button hole |
| Red LED is flashing | DFU mode | Flashing the firmware |
| Red LED is breathing | bootloader mode | Use a paper clip or a SIM-eject tool to push RESET button in RESET button hole |
| Red 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 |
| 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).
-----
## OpenSK V1
<img alt="OpenSK V1" src="../images/K46_with_label_reset.png" width="300px">
### 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.
!!! 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.
### 2. LED status
| LED behaviour | Mode type | Triger 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
The hardawre schematic and PCB files can be downloaded [here](hardware_files/OpenSK_V1.zip).
docs/index.md
+30 -45
View File
@@ -2,7 +2,8 @@
## Welcome to 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.
In this [**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
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
```
By opening up OpenSK as a research platform, our hope is that
it will be used by researchers, security key manufacturers,
@@ -16,11 +17,11 @@ To help and accelerate FIDO security key adoption, FEITIAN improves the housing
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.
### 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 Trigger DFU mode after connect it to USB port.
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.
To OpenSK V1, user should insert a paper clip or a SIM-eject tool to the RESET button hole to switch it to DFU 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 as user push the RESET button on nRF52840 USB dongle.
To OpenSK V2, after user connect the device to computer, he should push and hold on the user button for more 8 seconds, then OpenSK will be in DFU mode.
To OpenSK V2, after user connect the device to computer, he should push and hold on the user button for more 8 seconds, then OpenSK will be in bootloader mode.
For detailed informations, please refer to [hardware description page](./hardware.md).
@@ -29,75 +30,59 @@ For detailed informations, please refer to [hardware description page](./hardwar
### Pre-requisite
- The OpenSK USB Dongle V1 or V2.
Before you program the firmware to OpenSK USB Dongle, you should switch it to DFU mode. Please refer to [Harware Page](./hardware.md) to learn how to switch OpenSK to DFU mode.
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.
- 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).
2. Clone [Google OpenSK github repository](https://github.com/google/opensk "OpenSK").
```
$ git clone --recursive https://github.com/google/OpenSK.git
```
```
$ git clone --recursive https://github.com/google/OpenSK.git
```
3. Initial setup.
If you just cloned this repository, you need to run the following script:
```
$ ./setup.sh
```
```
$ ./setup.sh
```
For more information, please refer to [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.
### LED status
The LEDs show different behaviour in DFU mode and working mode.
##### OpenSK V1
| LED behaviour | Mode type | Triger Method |
| :-- | :-- | :-- |
| Blue LED is breathing | DFU mode | Use a paper clip or a SIM-eject tool to push RESET button in RESET button hole |
| Blue LED is flashing | DFU 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 |
##### OpenSK V2
| LED behaviour | Mode type | Triger Method |
| :-- | :-- | :-- |
| Red LED is breathing | DFU mode | Use a paper clip or a SIM-eject tool to push RESET button in RESET button hole |
| Red LED is flashing | DFU 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 |
### 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.
1. Switch OpenSK to DFU mode.
Please refer to [OpenSK Model](./index.md#opensk-model) or [hardware description page](./hardware.md) to learn how to switch OpenSK to DFU mode.
The LEDs show different behaviour in differet mode. Please refer to [LED status](./hardware.md#LED) .
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 .
2. Program the OpenSK USB dongle.
```
$ ./deploy.py --board=nrf52840_dongle_dfu --opensk --programmer=nordicdfu
```
```
$ ./deploy.py --board=nrf52840_dongle_dfu --opensk --programmer=nordicdfu
```
When prompt
```
Press [ENTER] when ready.
```
```
Press [ENTER] when ready.
```
Just press Enter, the firmware will be flahsed to your OpenSK USB Dongle.
3. Lock the working mode.
```
$ ./deploy.py --board=nrf52840_dongle_dfu --programmer=nordicdfu --no-app --dont-clear-apps
```
```
$ ./deploy.py --board=nrf52840_dongle_dfu --programmer=nordicdfu --no-app --dont-clear-apps
```
When prompt
```
Press [ENTER] when ready.
```
```
Press [ENTER] when ready.
```
Please press Enter and wait for the progress bar to be end.
Without Step 3, your USB Dongle will return to DFU mode when you remove and reinsert it. This step just locks the working mode unless you do Step 1 to swith it to DFU mode again.
Without Step 3, your USB Dongle will return to bootloader mode when you remove and reinsert it. This step just locks the working mode unless you do Step 1 to swith it to bootloader mode again.
!!! note "NOTE"
1. Step 2 and Step 3 are learned from [this discussion](https://github.com/google/OpenSK/issues/81 "Flash USB dongle without additional hardware"). The steps may change in the future.
docs/test.md
+11 -10
View File
@@ -1,7 +1,7 @@
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/).
##Manage OpenSK
There are two ways to manage your OpenSK USB Dongle, include Reset, Set 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.
@@ -11,29 +11,30 @@ There are two ways to manage your OpenSK USB Dongle, include Reset, Set and Chan
2. **Security Key** option in **Windows Settings** is only available from Windows 10 1903.
####Chrome Browser
1. From Chrome browser, select **Preferences...**, search **security key**, click **More** to expand, you can see **Manage security keys** at the bottom of the page.
2. Select **Manage security keys** to open a new page, then you can do corresponding operations following the tips.
1. From Chrome browser, input **chrome://settings/securityKeys** to address bar and open it.
2. You can see **Manage security keys** page, then you can do corresponding operations following the tips.
!!! note "NOTE"
1. The alternative way to open Security Key Setting UI from Chrome is open **chrome://settings/securityKeys**.
2. 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 which started to add this UI, but please update it to 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.
There are a lot of Demo websites list [here](https://github.com/herrjemand/awesome-webauthn#demos), you can try and test.
Here I recommend
- https://webauthn.io/ (from DUO)
- https://webauthndemo.appspot.com/ (from Google)
!!! warning "WARNING"
I can not guaranty that all the website can work well with OpenSK.
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 user 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 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.
Here just emphasize services from two big FIDO players, Google and Microsoft.
### Google
#### - Google 2-Step Verification
- 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.2 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.
- 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
- 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.
mkdocs.yml
+1 -2
View File
@@ -4,7 +4,6 @@ theme:
name: material
features:
- instant
- tabs
palette:
scheme: default
primary: indigo
@@ -47,7 +46,7 @@ markdown_extensions:
nav:
- Home: 'index.md'
- Hardware: 'hardware.md'
- Test FIDO: 'test.md'
- Hardware: 'hardware.md'
- About: 'about.md'
copyright: Copyright &copy; 2020 Feitian Technologies