add developers wiki for nrf52-u2f

makerdiary · Oct 23, 2018 · c7e27cb · c7e27cb
1 parent 747fe58
commit c7e27cb
Show file tree

Hide file tree

Showing 46 changed files with 823 additions and 0 deletions.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,11 @@
+Interested in contributing to this project? Want to report a bug? Before you do, please read the following guidelines.
+
+## Got a question or found a bug?
+
+If you got a question or found a bug in this project, you can help us by submitting an issue to the [issue tracker](https://github.com/makerdiary/nrf52-u2f/issues) in our GitHub repository. Even better, you can submit a Pull Request with a fix.
+
+## Missing a feature?
+
+You can request a new feature by submitting an issue to our GitHub Repository. Be sure that it is of use for everyone.
+
+<a href="https://github.com/makerdiary/nrf52-u2f/issues/new"><button data-md-color-primary="marsala"><i class="fa fa-github"></i> Create an Issue</button></a>
diff --git a/docs/LICENSE.md b/docs/LICENSE.md
@@ -0,0 +1,9 @@
+**MIT License**
+
+Copyright (c) 2018 [makerdiary](https://makerdiary.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/docs/building/images/build-u2f-firmware.png b/docs/building/images/build-u2f-firmware.png
diff --git a/docs/building/index.md b/docs/building/index.md
@@ -0,0 +1,160 @@
+# How to build the nRF52-U2F Firmware?
+
+This section describes how to build a new nRF52-U2F firmware and bootloader for your security key.
+
+## Install Dependencies
+
+To build the nRF52-U2F, you need to install some additional dependencies.
+
+On Windows, the easiest way to install dependencies is to use the [MSYS2](http://www.msys2.org/). You can do so by performing the following steps:
+
+1. [Download](http://www.msys2.org/) and run the installer - "x86_64" for 64-bit, "i686" for 32-bit Windows.
+
+2. Run MSYS2 from Start menu and install dependencies with:
+
+	``` sh
+	# Update the package database and core system packages
+	$ pacman -Syu
+
+	# Install dependencies
+	$ pacman -S git make python2 openssl
+	```
+
+
+Linux and macOS already have some necessary shell commands, run the following command to install the rest:
+
+``` sh
+# On macOS
+$ brew install openssl
+
+# On Ubuntu
+$ sudo apt-get install build-essential checkinstall openssl
+```
+
+## Clone the nRF52-U2F Repository
+
+To clone the nRF52-U2F source code repository from GitHub:
+
+``` sh
+git clone --recursive https://github.com/makerdiary/nrf52-u2f
+```
+
+## Download the nRF5 SDK
+
+Download the SDK package from [developer.nordicsemi.com](https://developer.nordicsemi.com/).
+
+The current version we are using is `15.2.0`, it can be downloaded directly here: [nRF5_SDK_v15.2.0_9412b96.zip](https://www.nordicsemi.com/eng/nordic/download_resource/59011/94/96002302/116085)
+
+Extract the zip file into the `nrf52-u2f/nrf_sdks/` directory. This should give you the following folder structure:
+
+``` info
+./nrf52-u2f/
+├── LICENSE.md
+├── README.md
+├── boards
+├── certs
+├── docs
+├── external
+├── firmware
+├── include
+├── material
+├── mkdocs.yml
+├── nrf_sdks
+│   ├── README.md
+│   └── nRF5_SDK_15.2.0_9412b96
+├── open_bootloader
+├── source
+└── tools
+```
+
+## Install GNU Arm Embedded Toolchain
+
+Download and install a [GNU ARM Embedded](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm) build for your operating system and extract it on your file system.
+
+!!! note
+	The current version we are using is `6-2017-q2-update`.
+
+Config the toolchain path in `makefile.windows` or `makefile.posix` depending on platform you are using. That is, the `.posix` should be edited if your are working on either Linux or macOS. These files are located in:
+
+``` sh
+<nRF5 SDK>/components/toolchain/gcc
+```
+
+Open the file in a text editor and make sure that the `GNU_INSTALL_ROOT` variable is pointing to your GNU Arm Embedded Toolchain install directory. For example:
+
+``` sh
+GNU_INSTALL_ROOT := $(HOME)/gcc-arm-none-eabi/gcc-arm-none-eabi-6-2017-q2-update/bin/
+GNU_VERSION := 6.3.1
+GNU_PREFIX := arm-none-eabi
+```
+
+## Generate Attestation Key and Certificate
+
+For more security, remember to generate a new attestation key and certificate.
+
+Change to the `tools` directory, run the `generate-certs.sh` to generate a new attestation key and certificate:
+
+``` sh
+$ cd ./nrf52-u2f/tools
+
+$ ./generate-certs.sh
+```
+
+If successfully completed, the private key and certificate are stored in `certs/keys.c` file.
+
+## Build the U2F Firmware
+
+Now you are ready to build nRF52-U2F source code.
+
+Open terminal and change directory to:
+
+``` sh
+# For nRF52840-MDK board
+$ cd ./nrf52-u2f/boards/nrf52840-mdk/armgcc
+$ make clean && make
+
+# For nRF52840 Micro Dev Kit USB Dongle
+$ cd ./nrf52-u2f/boards/nrf52840-mdk-usb-dongle/armgcc
+$ make clean && make
+```
+
+The firmware is in the `armgcc/_build/` directory with the name `nrf52840_xxaa.hex`.
+
+![](images/build-u2f-firmware.png)
+
+!!! note
+	Please follow the [Upgrading Firmware](../upgrading/#upgrade-u2f-firmware-with-nrf-connet-for-desktop) guide to flash the new firmware!
+
+
+## Build the Open Bootloader
+
+The nRF52-U2F contains a reliable open bootloader, which means that you can update the nRF52-U2F firmware from USB directly without an external programmer needed. 
+
+You can build a new bootloader by performing the following steps:
+
+Open terminal and change directory to:
+
+``` sh
+# For nRF52840-MDK board
+$ cd ./nrf52-u2f/open_bootloader/nrf52840-mdk/armgcc
+$ make clean && make
+$ make mergehex
+
+# For nRF52840 Micro Dev Kit USB Dongle
+$ cd ./nrf52-u2f/open_bootloader/nrf52840-mdk-usb-dongle/armgcc
+$ make clean && make
+$ make mergehex
+```
+
+The bootloader is in the `armgcc/_build/` directory with the name `nrf52840_xxaa_mbr.hex`.
+
+!!! note
+	Please follow the [Upgrading Firmware](../upgrading/#upgrade-open-bootloader-with-nrfutil) guide to flash the new bootloader!
+
+
+## Create an Issue
+
+Interested in contributing to this project? Want to report a bug? Feel free to click here:
+
+<a href="https://github.com/makerdiary/nrf52-u2f/issues/new"><button data-md-color-primary="marsala"><i class="fa fa-github"></i> Create an Issue</button></a>
+
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
@@ -0,0 +1,75 @@
+# Getting Started with nRF52 FIDO U2F Key
+
+This guide shows you how to get started with the nRF52 FIDO U2F Security Key. The following development boards are available to this nRF52-U2F implementation: 
+
+| **nRF52840-MDK** | **nRF52840 Micro Dev Kit USB Dongle** |
+|:---:|:---:|
+| [![](../images/nrf52840-mdk_top.png)](../../nrf52840-mdk/) <a href="https://store.makerdiary.com/collections/frontpage/products/nrf52840-mdk-iot-development-kit"><button data-md-color-primary="marsala">Get One!</button></a> | [![](../images/nrf52840-mdk-usb-dongle_top.png)](../../nrf52840-mdk-usb-dongle) <a href="https://store.makerdiary.com/collections/frontpage/products/nrf52840-mdk-usb-dongle"><button data-md-color-primary="marsala">Get One!</button></a> |
+
+If you have already one of these two boards, congratulations, let's go ahead! 
+
+So how do you set it up to protect your online service accounts? Follow these easy instructions and you'll set up your nRF52 U2F Key with online services that support FIDO U2F protocol (e.g. Google Account).
+
+## Requirements
+
+* Latest version of Google Chrome browser (or at least version 38) or Opera browser
+
+* [nRF52840-MDK](https://store.makerdiary.com/collections/frontpage/products/nrf52840-mdk-iot-development-kit) or [nRF52840 Micro Dev Kit USB Dongle](https://store.makerdiary.com/collections/frontpage/products/nrf52840-mdk-usb-dongle) with the nRF52-U2F firmware
+
+* A Google Account (such as Gmail, Google Docs, YouTube, Google+)
+
+!!! note
+	If no firmware available, please follow these guides to prepare the correct firmware: [Upgrading the firmware](../upgrading/) or [Building the firmware](../building).
+
+## Setting Up Your Google Account
+
+1. [Turn on 2-Step Verification](https://support.google.com/accounts/answer/9096865?hl=en&visit_id=636755555485133774-251791244&rd=1). If the 2-Step Verification is ON, continue with the next step.
+
+2. [Add the nRF52 U2F Security Key for 2-Step Verification](https://myaccount.google.com/signinoptions/two-step-verification). On **Security Key** option, click **ADD SECURITY KEY**.
+
+	![](../guides/images/add-u2f-key-with-google-1.png)
+
+3. Prepare a nRF52 U2F Security Key. Insert your key into your USB port, and press the button on the key when the BLUE LED begins to blink.
+
+	![](../guides/images/add-u2f-key-with-google-2.png)
+
+4. Your security key is registered. Enter a name to complete this step.
+
+	![](../guides/images/add-u2f-key-with-google-3.png)
+
+3. Set up at least one backup option so that you can sign in even if your other second steps aren't available.
+
+Your U2F Key is now registered to your account as your default 2-Step Verification device! 
+
+If you accidentally lose a key, come here and remove that key from your account. No one could log in to your account, though, because they would still need to know your username and password.
+
+## Signing in using your key
+
+Now you can sign in to your Google Account with the security key you add before.
+
+1. On your computer, [sign in to your Google Account](https://accounts.google.com/). Your device will detect that your account has a security key.
+
+2. Insert your key into the USB port in your computer.
+
+	![](../guides/images/sign-in-to-google-with-u2f.png)
+
+3. When the BLUE LED begins to blink, press the button on the security key.
+
+**Congratulations!** You can use your key each time you sign in to your Google Account.
+
+## Using with more Services
+
+You will find many more online services that support FIDO U2F, just have a try and enjoy the simplicity of U2F!
+
+* [Using nRF52-U2F with Facebook](../guides/using-u2f-with-facebook)
+* [Using nRF52-U2F with Twitter](../guides/using-u2f-with-twitter)
+* [Using nRF52-U2F with GitHub](../guides/using-u2f-with-github)
+* [Using nRF52-U2F with GitLab](../guides/using-u2f-with-gitlab)
+
+
+## Create an Issue
+
+Interested in contributing to this project? Want to report a bug? Feel free to click here:
+
+<a href="https://github.com/makerdiary/nrf52-u2f/issues/new"><button data-md-color-primary="marsala"><i class="fa fa-github"></i> Create an Issue</button></a>
+
diff --git a/docs/guides/images/add-extra-security-to-facebook.png b/docs/guides/images/add-extra-security-to-facebook.png
diff --git a/docs/guides/images/add-security-key-for-facebook.png b/docs/guides/images/add-security-key-for-facebook.png
diff --git a/docs/guides/images/add-u2f-key-with-google-1.png b/docs/guides/images/add-u2f-key-with-google-1.png
diff --git a/docs/guides/images/add-u2f-key-with-google-2.png b/docs/guides/images/add-u2f-key-with-google-2.png
diff --git a/docs/guides/images/add-u2f-key-with-google-3.png b/docs/guides/images/add-u2f-key-with-google-3.png
diff --git a/docs/guides/images/register-u2f-key-with-facebook.jpg b/docs/guides/images/register-u2f-key-with-facebook.jpg
diff --git a/docs/guides/images/register-u2f-key-with-github.gif b/docs/guides/images/register-u2f-key-with-github.gif
diff --git a/docs/guides/images/register-u2f-key-with-gitlab-1.png b/docs/guides/images/register-u2f-key-with-gitlab-1.png
diff --git a/docs/guides/images/register-u2f-key-with-gitlab-2.png b/docs/guides/images/register-u2f-key-with-gitlab-2.png
diff --git a/docs/guides/images/register-u2f-key-with-gitlab-3.png b/docs/guides/images/register-u2f-key-with-gitlab-3.png
diff --git a/docs/guides/images/register-u2f-key-with-twitter-1.jpg b/docs/guides/images/register-u2f-key-with-twitter-1.jpg
diff --git a/docs/guides/images/register-u2f-key-with-twitter-1.png b/docs/guides/images/register-u2f-key-with-twitter-1.png
diff --git a/docs/guides/images/register-u2f-key-with-twitter-2.jpg b/docs/guides/images/register-u2f-key-with-twitter-2.jpg
diff --git a/docs/guides/images/register-u2f-key-with-twitter-3.jpg b/docs/guides/images/register-u2f-key-with-twitter-3.jpg
diff --git a/docs/guides/images/register-u2f-key-with-twitter-4.jpg b/docs/guides/images/register-u2f-key-with-twitter-4.jpg
diff --git a/docs/guides/images/sign-in-to-facebook-with-u2f-1.jpg b/docs/guides/images/sign-in-to-facebook-with-u2f-1.jpg
diff --git a/docs/guides/images/sign-in-to-facebook-with-u2f-2.jpg b/docs/guides/images/sign-in-to-facebook-with-u2f-2.jpg
diff --git a/docs/guides/images/sign-in-to-github-with-u2f.png b/docs/guides/images/sign-in-to-github-with-u2f.png
diff --git a/docs/guides/images/sign-in-to-gitlab-with-u2f.png b/docs/guides/images/sign-in-to-gitlab-with-u2f.png
diff --git a/docs/guides/images/sign-in-to-google-with-u2f.png b/docs/guides/images/sign-in-to-google-with-u2f.png
diff --git a/docs/guides/images/sign-in-to-twitter-with-u2f.png b/docs/guides/images/sign-in-to-twitter-with-u2f.png
diff --git a/docs/guides/images/turn-on-two-factor-authentication-with-facebook.jpg b/docs/guides/images/turn-on-two-factor-authentication-with-facebook.jpg
diff --git a/docs/guides/images/u2f-key-added-for-facebook.jpg b/docs/guides/images/u2f-key-added-for-facebook.jpg
diff --git a/docs/guides/using-u2f-with-facebook.md b/docs/guides/using-u2f-with-facebook.md
@@ -0,0 +1,66 @@
+# Using nRF52 U2F Security Key with Facebook
+
+This guide describes how to use the nRF52 U2F Security Key with Facebook.
+
+## Requirements
+
+* Latest version of Google Chrome browser (or at least version 38) or Opera browser
+
+* [nRF52840-MDK](https://store.makerdiary.com/collections/frontpage/products/nrf52840-mdk-iot-development-kit) or [nRF52840 Micro Dev Kit USB Dongle](https://store.makerdiary.com/collections/frontpage/products/nrf52840-mdk-usb-dongle) with the nRF52-U2F firmware
+
+* A Facebook Account
+
+!!! note
+	If no firmware available, please follow these guides to prepare the correct firmware: [Upgrading the firmware](../upgrading/) or [Building the firmware](../building).
+
+## Setting Up Your Facebook Account
+
+1. In Google Chrome or Opera, log in to [Facebook](https://www.facebook.com/).
+
+2. Click the arrow at the top right, and then click **Settings**.
+
+3. In the Security Settings page, in the left pane, click **Security and Login**.
+
+4. Next to **Use two-factor authentication**, click **Edit**.
+
+5. Click **Get Started** button to add extra security with Two-Factor Authentication.
+
+	![](images/add-extra-security-to-facebook.png)
+
+6. Select **Authentication App** option, and set up an app like Google Authenticator or Duo Mobile to generate login codes.
+
+7. Follow the instructions on the screen to finish turning on Two-Factor Authentication.
+
+	![](images/turn-on-two-factor-authentication-with-facebook.jpg)
+
+8. Next, you are going to add your U2F Key. Under **Add a Backup**, to the right of **Security Keys**, click **Setup**.
+
+	![](images/add-security-key-for-facebook.png)
+
+	![](images/register-u2f-key-with-facebook.jpg)
+
+9. When the BLUE LED begins to blink, press the button on the key.
+
+	![](images/u2f-key-added-for-facebook.jpg)
+
+## Signing in using your key
+
+Now you can sign in to your Facebook account with the security key you add before.
+
+1. On your computer, [sign in to Facebook](https://www.facebook.com/). 
+
+2. Insert your security key into the USB port.
+
+	![](images/sign-in-to-facebook-with-u2f-1.jpg)
+
+3. When the BLUE LED begins to blink, press the button on the key.
+
+	![](images/sign-in-to-facebook-with-u2f-2.jpg)
+
+**Congratulations!** You can use your key each time you sign in to your Facebook account.
+
+## Create an Issue
+
+Interested in contributing to this project? Want to report a bug? Feel free to click here:
+
+<a href="https://github.com/makerdiary/nrf52-u2f/issues/new"><button data-md-color-primary="marsala"><i class="fa fa-github"></i> Create an Issue</button></a>
diff --git a/docs/guides/using-u2f-with-github.md b/docs/guides/using-u2f-with-github.md
@@ -0,0 +1,58 @@
+# Using nRF52 U2F Security Key with GitHub
+
+This guide describes how to use the nRF52 U2F Security Key with GitHub.
+
+## Requirements
+
+* Latest version of Google Chrome browser (or at least version 38) or Opera browser
+
+* [nRF52840-MDK](https://store.makerdiary.com/collections/frontpage/products/nrf52840-mdk-iot-development-kit) or [nRF52840 Micro Dev Kit USB Dongle](https://store.makerdiary.com/collections/frontpage/products/nrf52840-mdk-usb-dongle) with the nRF52-U2F firmware
+
+* A GitHub Account
+
+!!! note
+	If no firmware available, please follow these guides to prepare the correct firmware: [Upgrading the firmware](../upgrading/) or [Building the firmware](../building).
+
+## Configuring two-factor authentication using FIDO U2F
+
+1. You must have already configured 2FA via a TOTP mobile app or via SMS.
+
+2. Download and install [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en).
+
+3. Ensure that you have the nRF52 U2F Security Key inserted into your computer.
+
+4. In the upper-right corner of any page, click your profile photo, then click **Settings**.
+
+5. In the user settings sidebar, click **Security**.
+
+6. Next to "Security keys", click **Add**.
+
+7. Under "Security keys", click **Register new device**.
+
+8. Type a nickname for the security key, then click **Add**.
+
+9. When the BLUE LED begins to blink, press the button on the key to have it authenticate against GitHub.
+
+![](images/register-u2f-key-with-github.gif)
+
+
+## Signing in using your key
+
+Now you can sign in to your GitHub account with the security key you add before.
+
+1. On your computer, [sign in to GitHub](https://github.com/login). Your device will detect that your account has a security key.
+
+2. Insert your security key into the USB port.
+
+3. When the BLUE LED begins to blink, press the button on the key.
+
+	![](images/sign-in-to-github-with-u2f.png)
+
+
+**Congratulations!** You can use your key each time you sign in to your GitHub account.
+
+## Create an Issue
+
+Interested in contributing to this project? Want to report a bug? Feel free to click here:
+
+<a href="https://github.com/makerdiary/nrf52-u2f/issues/new"><button data-md-color-primary="marsala"><i class="fa fa-github"></i> Create an Issue</button></a>