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

Initial commit

Browse Source
This commit is contained in:
Jean-Michel Picod
2020-01-30 11:47:29 +01:00
commit f91d2fd3db
90 changed files with 31123 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cargo/config
+7
View File
@@ -0,0 +1,7 @@
# Target configuration for the CTAP2 app on the nRF52840 chip
[target.thumbv7em-none-eabi]
rustflags = [
"-C", "link-arg=-Tnrf52840dk_layout.ld",
"-C", "relocation-model=static",
"-D", "warnings",
]
.github/ISSUE_TEMPLATE.md
+16
View File
@@ -0,0 +1,16 @@
## Expected Behavior
## Actual Behavior
## Steps to Reproduce the Problem
1.
1.
1.
## Specifications
- Version:
- Platform:
.github/PULL_REQUEST_TEMPLATE.md
+6
View File
@@ -0,0 +1,6 @@
Fixes #<issue_number_goes_here>
> It's a good idea to open an issue first for discussion.
- [ ] Tests pass
- [ ] Appropriate changes to README are included in PR
.gitignore
+7
View File
@@ -0,0 +1,7 @@
target/
Cargo.lock
# Prevent people from commiting sensitive files.
crypto_data/
src/ctap/key_material.rs
.gitmodules
+6
View File
@@ -0,0 +1,6 @@
[submodule "third_party/libtock-rs"]
path = third_party/libtock-rs
url = https://github.com/tock/libtock-rs
[submodule "third_party/tock"]
path = third_party/tock
url = https://github.com/tock/tock
.markdownlint.json
+35
View File
@@ -0,0 +1,35 @@
{
"default": true,
"heading-style": {
"style": "atx"
},
"no-trailing-spaces": {
"br_spaces": 0,
"strict": true
},
"ul-indent": {
"indent": 4
},
"line-length": {
"line_length": 80,
"code_blocks": false
},
"list-marker-space": {
"ol_single": 2,
"ol_multi": 2,
"ul_single": 3,
"ul_multi": 3
},
"no-inline-html": {
"allowed_elements": [
"img"
]
},
"fenced-code-language": true,
"code-block-style": {
"style": "fenced"
},
"code-fence-style": {
"style": "backtick"
}
}
.travis.yml
+45
View File
@@ -0,0 +1,45 @@
# Copyright 2019 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
language: rust
rust:
- nightly-2020-01-16
os:
- linux
dist: "trusty" # we need python3-pip
addons:
apt:
packages:
- "python3"
- "python3-pip"
cache:
- rust
- cargo
before-install:
- openssl version
install:
- rustup target add thumbv7em-none-eabi
- rustup component add rustfmt
- cargo install cargo-audit
script:
- ./setup.sh
- cargo audit
- ./run_desktop_tests.sh
.vscode/extensions.json
Vendored
+6
View File
@@ -0,0 +1,6 @@
{
"recommendations": [
"davidanson.vscode-markdownlint",
"rust-lang.rust"
]
}
.vscode/settings.json
Vendored
+7
View File
@@ -0,0 +1,7 @@
{
"editor.formatOnSave": true,
"rust-client.channel": "nightly",
// The toolchain is updated from time to time so let's make sure that RLS is updated too
"rust-client.updateOnStartup": true,
"rust.clippy_preference": "on"
}
Cargo.toml
+35
View File
@@ -0,0 +1,35 @@
[package]
name = "ctap2"
version = "0.1.0"
authors = [
"Fabian Kaczmarczyck <kaczmarczyck@google.com>",
"Guillaume Endignoux <guillaumee@google.com>",
"Jean-Michel Picod <jmichel@google.com>",
]
license = "Apache-2.0"
edition = "2018"
[dependencies]
libtock = { path = "third_party/libtock-rs" }
cbor = { path = "libraries/cbor" }
crypto = { path = "libraries/crypto" }
byteorder = { version = "1", default-features = false }
arrayref = "0.3.6"
subtle = { version = "2.2", default-features = false, features = ["nightly"] }
[features]
std = ["cbor/std", "crypto/std", "crypto/derive_debug"]
debug_ctap = ["crypto/derive_debug"]
with_ctap1 = ["crypto/with_ctap1"]
panic_console = ["libtock/panic_console"]
[dev-dependencies]
elf2tab = "0.4.0"
[profile.dev]
panic = "abort"
lto = true # Link Time Optimization usually reduces size of binaries and static libraries
[profile.release]
panic = "abort"
lto = true # Link Time Optimization usually reduces size of binaries and static libraries
LICENSE
+202
View File
@@ -0,0 +1,202 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
README.md
+116
View File
@@ -0,0 +1,116 @@
# <img alt="OpenSK logo" src="docs/img/OpenSK.svg" width="200px">
[![Build Status](https://travis-ci.org/google/OpenSK.svg?branch=master)](https://travis-ci.org/google/OpenSK)
## OpenSK
This repository contains a Rust implementation of a
[FIDO2](https://fidoalliance.org/fido2/) authenticator.
We developed this as a [Tock OS](https://tockos.org) application and it has been
successfully tested on the following boards:
* [Nordic nRF52840-DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK)
* [Nordic nRF52840-dongle](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-Dongle)
## Disclaimer
This project is proof-of-concept and a research platform. It's still under
development and as such comes with a few limitations:
### FIDO2
Although we tested and implemented our firmware based on the published
[CTAP2.0 specifications](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html),
our implementation was not reviewed nor officially tested and doesn't claim to
be FIDO Certified.
### Cryptography
We're currently still in the process on making the
[ARM&reg; CryptoCell-310](https://developer.arm.com/ip-products/security-ip/cryptocell-300-family)
embedded in the
[Nordic nRF52840 chip](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fps_nrf52840%2Fcryptocell.html)
work to get hardware-accelerated cryptography. In the meantime we implemented
the required cryptography algorithms (ECDSA, ECC secp256r1, HMAC-SHA256 and
AES256) in Rust as a placeholder. Those implementations are research-quality
code and haven't been reviewed. They don't provide constant-time guarantees and
are not designed to be resistant against side-channel attacks.
## Installation
For a more detailed guide, please refer to our
[installation guide](docs/install.md).
1. If you just cloned this repository, run the following script (**Note**: you
only need to do this once):
```shell
./setup.sh
```
2. If you have a Nordic development board that doesn't already have Tock OS
installed, you can install both TockOS and the OpenSK application by running
the following command, depending on the board you have:
```shell
# Nordic nRF52840-DK board
board=nrf52840dk ./deploy.sh os app
# Nordic nRF52840-Dongle
board=nrf52840_dongle ./deploy.sh os app
```
3. If Tock OS is already installed and you want to install/update the OpenSK
application on your board (**Warning**: it will erase the locally stored
credentials), run:
```shell
./deploy.sh app
```
4. On Linux, you may want to avoid the need for `root` privileges to interact
with the key. For that purpose we provide a udev rule file that can be
installed with the following command:
```shell
sudo cp rules.d/55-opensk.rules /etc/udev/rules.d/ &&
sudo udevadm control --reload
```
### Customization
If you build your own security key, depending on the hardware you use, there are
a few things you can personalize:
1. If you have multiple buttons, choose the buttons responsible for user
presence in main.rs.
2. Decide whether you want to use batch attestation. There is a boolean flag in
`ctap/mod.rs`. It is mandatory for U2F, and you can create your own
self-signed certificate. The flag is used for FIDO2 and has some privacy
implications. Please check
[WebAuthn](https://www.w3.org/TR/webauthn/#attestation) for more
information.
3. Decide whether you want to use signature counters. Currently, only global
signature counters are implemented, as they are the default option for U2F.
The flag in `ctap/mod.rs` only turns them off for FIDO2. The most privacy
preserving solution is individual or no signature counters. Again, please
check [WebAuthn](https://www.w3.org/TR/webauthn/#signature-counter) for
documentation.
4. Depending on your available flash storage, choose an appropriate maximum
number of supported residential keys and number of pages in
`ctap/storage.rs`.
### 3D printed enclosure
To protect and carry your key, we partnered with a professional designer and we
are providing a custom enclosure that can be printed on both professional 3D
printers and hobbyist models.
All the required files can be downloaded from
[Thingiverse](https://www.thingiverse.com/thing:4132768) including the STEP
file, allowing you to easily make the modifications you need to further
customize it.
## Contributing
See [Contributing.md](docs/contributing.md).
deploy.sh
Executable
+321
View File
@@ -0,0 +1,321 @@
#!/usr/bin/env bash
# Copyright 2019 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
set -e
if [ "x$VERBOSE" != "x" ]
then
set -x
fi
info_text="$(tput bold)info:$(tput sgr0)"
error_text="$(tput bold)error:$(tput sgr0)"
tab_folder="target/tab"
# elf2tab requires a file named "cortex-m4", so this path is used for all
# target applications.
elf_file_name="${tab_folder}/cortex-m4.elf"
# elf2tab 0.4.0 and below uses "-n" flag but 0.5.0-dev changes that "-p" or
# "--package-name"
# We try to be compatible with both versions.
elf2tab_package_param="-n"
if which elf2tab > /dev/null 2>&1
then
if [ "$(elf2tab --version | cut -d' ' -f2)" = "0.5.0-dev" ]
then
# Short parameter is "-p" but long parameter names should be prefered
# when they are used in scripts.
elf2tab_package_param="--package-name"
fi
else
echo ""
echo "Command elf2tab not found. Have you run the setup.sh script?"
exit 2
fi
# We need to specify the board explicitly to be able to flash after 0x80000.
tockloader_flags=(
--jlink
--board="${board:-nrf52840}"
--arch=cortex-m4
--jlink-device=nrf52840_xxaa
--page-size=4096
)
declare -A supported_boards
supported_boards["nrf52840dk"]="Y"
supported_boards["nrf52840_dongle"]="Y"
declare -A enabled_features=( [with_ctap1]=Y )
print_usage () {
cat <<EOH
Usage: $0 [options...] <actions...>
Example:
In order to install TockOS and a debug version of OpenSK on a Nordic nRF52840-DK
board, you need to run the following command:
board=nrf52840dk $0 --panic-console os app_debug
Actions:
os
Compiles and installs Tock OS on the selected board.
The target board must be indicated by setting the environment
variable \$board
app
Compiles and installs OpenSK application.
app_debug
Compiles and installs OpenSK application in debug mode (i.e. more debug messages
will be sent over the console port such as hexdumps of packets)
crypto_bench
Compiles and installs the crypto_bench example that tests the performance
of the cryptographic algorithms on the board.
Options:
--dont-clear-apps
When installing an application, previously installed applications won't
be erased from the board.
--no-u2f
Compiles OpenSK application without backward compatible support for
U2F/CTAP1 protocol.
--regen-keys
Forces the generation of src/ctap/key_materials.rs file.
This won't force re-generate OpenSSL files under crypto_data/ directory.
If the OpenSSL files needs to be re-generated, simply delete them (or
the whole directory).
--panic-console
In case of application panic, the console will be used to output messages
before starting blinking the LEDs on the board.
EOH
}
display_supported_boards () {
echo "$info_text Currently supported boards are:"
for b in ${!supported_boards[@]}
do
if [ -d "third_party/tock/boards/nordic/$b" -a \
-e "third_party/tock/boards/nordic/$b/Cargo.toml" ]
then
echo " - $b"
fi
done
}
# Import generate_crypto_materials function
source tools/gen_key_materials.sh
build_app_padding () {
# On nRF52840, the MMU can have 8 sub-regions and the flash size is 0x1000000.
# By default, applications are flashed at 0x30000 which means the maximum size
# for an application is 0x40000 (an application of size 0x80000 would need 16
# sub-regions of size 0x10000; sub-regions need to be aligned on their size).
# This padding permits to have the application start at 0x40000 and increase
# the maximum application size to 0x80000 (with 4 sub-regions of size
# 0x40000).
(
# Version: 2
echo -n "0200"
# Header size: 0x10
echo -n "1000"
# Total size: 0x10000
echo -n "00000100"
# Flags: 0
echo -n "00000000"
# Checksum
echo -n "02001100"
) | xxd -p -r > "${tab_folder}/padding.bin"
}
build_app () {
# Flatten the array
# This is equivalent to the following python snippet: ' '.join(arr).replace(' ', ',')
local feature_list=$(IFS=$'\n'; echo "$@")
if [ "X${feature_list}" != "X" ]
then
feature_list="${feature_list// /,}"
fi
cargo build \
--release \
--target=thumbv7em-none-eabi \
--features="${feature_list}"
mkdir -p "target/tab"
cp "target/thumbv7em-none-eabi/release/ctap2" "$elf_file_name"
elf2tab \
"${elf2tab_package_param}" "ctap2" \
-o "${tab_folder}/ctap2.tab" \
"$elf_file_name" \
--stack 16384 \
--app-heap 90000 \
--kernel-heap 1024 \
--protected-region-size=64
}
build_crypto_bench () {
cargo build \
--release \
--target=thumbv7em-none-eabi \
--example crypto_bench
mkdir -p "target/tab"
cp "target/thumbv7em-none-eabi/release/examples/crypto_bench" "$elf_file_name"
elf2tab \
"${elf2tab_package_param}" "crypto_bench" \
-o "${tab_folder}/crypto_bench.tab" \
"$elf_file_name" \
--stack 16384 \
--app-heap 90000 \
--kernel-heap 1024 \
--protected-region-size=64
}
deploy_tock () {
if [ "x$board" = "x" ];
then
echo "$error_text You must set the board in order to install Tock OS (example: \`board=nrf52840dk $0 os\`)"
display_supported_boards
return 1
fi
if [ "${supported_boards[$board]+x}" = "x" -a -d "third_party/tock/boards/nordic/$board" ]
then
make -C third_party/tock/boards/nordic/$board flash
else
echo "$error_text The board '$board' doesn't seem to be supported"
display_supported_boards
return 1
fi
}
clear_apps=Y
install_os=N
install_app=none
force_generate=N
has_errors=N
if [ "$#" -eq "0" ]
then
print_usage
exit 1
fi
while [ "$#" -ge "1" ]
do
case "$1" in
--dont-clear-apps)
clear_apps=N
;;
--no-u2f)
unset enabled_features["with_ctap1"]
;;
--regen-keys)
force_generate=Y
;;
--panic-console)
enabled_features["panic_console"]="Y"
;;
os)
install_os=Y
;;
app)
install_app=ctap2
;;
app_debug)
install_app=ctap2
enabled_features["debug_ctap"]="Y"
;;
crypto_bench)
install_app=crypto_bench
;;
*)
echo "$error_text Unsupported option: '"$1"'"
has_errors=Y
;;
esac
shift 1
done
if [ "$has_errors" = "Y" ]
then
echo ""
print_usage
exit 1
fi
# Test if we need to update Rust toolchain
# rustc --version outputs a version line such as:
# rustc 1.40.0-nightly (0e8a4b441 2019-10-16)
# The sed regexp turns it into:
# nightly-2019-10-16
current_toolchain=$(rustc --version | sed -e 's/^rustc [0-9]*\.[0-9]*\.[0-9]*-\(nightly\) ([0-9a-f]* \([0-9]*-[0-9]*-[0-9]*\))$/\1-\2/')
target_toolchain=$(head -n 1 rust-toolchain)
if [ "x${current_toolchain}" != "x${target_toolchain}" ]
then
rustup install "${target_toolchain}"
rustup target add thumbv7em-none-eabi
fi
if [ "$install_os" = "Y" ]
then
deploy_tock
fi
# Don't try to uninstall app if we don't plan to install after.
if [ "$install_app" != "none" -a "$clear_apps" = "Y" ]
then
# Uninstall can fail if there's no app already installed.
# This is fine and we don't want that to stop the script
tockloader uninstall "${tockloader_flags[@]}" -a 0x40000 || true
fi
if [ "$install_app" = "ctap2" ]
then
generate_crypto_materials "${force_generate}"
build_app "${!enabled_features[@]}"
fi
if [ "$install_app" = "crypto_bench" ]
then
build_crypto_bench
fi
if [ "$install_app" != "none" ]
then
build_app_padding
tockloader flash "${tockloader_flags[@]}" -a 0x30000 "${tab_folder}/padding.bin"
tockloader install "${tockloader_flags[@]}" -a 0x40000 "${tab_folder}/${install_app}.tab"
fi
docs/contributing.md
+28
View File
@@ -0,0 +1,28 @@
# How to Contribute
We'd love to accept your patches and contributions to this project. There are
just a few small guidelines you need to follow.
## Contributor License Agreement
Contributions to this project must be accompanied by a Contributor License
Agreement. You (or your employer) retain the copyright to your contribution;
this simply gives us permission to use and redistribute your contributions as
part of the project. Head over to <https://cla.developers.google.com/> to see
your current agreements on file or to sign a new one.
You generally only need to submit a CLA once, so if you've already submitted one
(even if it was for a different project), you probably don't need to do it
again.
## Code reviews
All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
information on using pull requests.
## Community Guidelines
This project follows [Google's Open Source Community
Guidelines](https://opensource.google/conduct/).
docs/img/OpenSK.svg
+1
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 4.2 KiB

docs/img/devkit_annotated.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 532 KiB

docs/img/dongle_clip.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 172 KiB

docs/img/dongle_front.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 400 KiB

docs/img/dongle_pads.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 127 KiB

docs/install.md
+262
View File
@@ -0,0 +1,262 @@
<img alt="OpenSK logo" src="img/OpenSK.svg" width="200px">
# Installation guide
This document describes in details how to turn a Nordic nRF52840 board into a
working FIDO2 security key.
## Pre-requisite
### Hardware
You will need one the following supported boards:
* [Nordic nRF52840-DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK)
development kit. This board is more convenient for development and debug
scenarios as the JTAG probe is already on the board.
* [Nordic nRF52840 Dongle](https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF52840-Dongle)
to have a more practical form factor.
In the case of the Nordic USB dongle, you will also need the following extra
hardware:
* a [Segger J-Link](https://www.segger.com/products/debug-probes/j-link/) JTAG
probe.
* a
[TC2050 Tag-Connect programming cable](http://www.tag-connect.com/TC2050-IDC-NL-050-ALL).
* a [Tag-Connect TC2050 ARM2010](http://www.tag-connect.com/TC2050-ARM2010)
adaptor
* optionally a
[Tag-Connect TC2050 retainer clip](http://www.tag-connect.com/TC2050-CLIP)
to keep the spring loaded connector pressed to the PCB.
Although [OpenOCD](http://openocd.org/) should be supported we encountered some
issues while trying to flash a firmware with it. Therefore we suggest at the
moment to use a
[Segger J-Link](https://www.segger.com/products/debug-probes/j-link/) probe
instead.
This guide **does not** cover how to setup the JTAG probe on your system.
### Software
In order to compile and flash a working OpenSK firmware, you will need the
following:
* a working [Rust](https://rustup.rs/) toolchain installed on your system
* python3 and pip
* the OpenSSL command line tool
The scripts provided in this project have been tested under Linux and OS X. We
haven't tested them on Windows and other platforms.
## Compiling the firmware
### Initial setup
If you just cloned this repository, you need to run the following script
(_output may differ_):
```shell
$ ./setup.sh
[-] Applying patch "01-persistent-storage.patch"... DONE.
[-] Applying patch "02-usb.patch"... DONE.
[-] Applying patch "03-app-memory.patch"... DONE.
[-] Applying patch "04-rtt.patch"... DONE.
[-] Applying patch "01-panic_console.patch"... DONE.
[-] Applying patch "02-timer.patch"... DONE.
[-] Applying patch "03-public_syscalls.patch"... DONE.
[-] Applying patch "04-bigger_heap.patch"... DONE.
Signature ok
subject=CN = Google OpenSK CA
Getting Private key
Signature ok
subject=CN = Google OpenSK Hacker Edition
Getting CA Private Key
info: syncing channel updates for 'nightly-2020-01-16-x86_64-unknown-linux-gnu'
nightly-2020-01-16-x86_64-unknown-linux-gnu unchanged - rustc 1.42.0-nightly (3291ae339 2020-01-15)
Requirement already up-to-date: tockloader in /usr/lib/python3/dist-packages/tockloader-1.4.0.dev0-py3.7.egg (1.4.0.dev0)
Requirement already satisfied, skipping upgrade: argcomplete>=1.8.2 in /usr/lib/python3/dist-packages (from tockloader) (1.10.0)
Requirement already satisfied, skipping upgrade: colorama>=0.3.7 in /usr/lib/python3/dist-packages (from tockloader) (0.3.7)
Requirement already satisfied, skipping upgrade: crcmod>=1.7 in /usr/lib/python3/dist-packages (from tockloader) (1.7)
Requirement already satisfied, skipping upgrade: pyserial>=3.0.1 in /usr/lib/python3/dist-packages (from tockloader) (3.4)
Requirement already satisfied, skipping upgrade: pytoml>=0.1.11 in /usr/lib/python3/dist-packages (from tockloader) (0.1.21)
info: component 'rust-std' for target 'thumbv7em-none-eabi' is up to date
Updating crates.io index
Ignored package `elf2tab v0.4.0` is already installed, use --force to override
```
The script performs the following steps:
1. Make sure that the git submodules are checked out
1. Apply our patches that haven't yet been merged upstream to both
[Tock](https://github.com/tock/tock) and
[libtock-rs](https://github.com/tock/libtock-rs)
1. Generate a self-signed certificate authority as well as a private key and a
corresponding certificate for your OpenSK key signed by this CA. You will be
able to replace them with your own certificate and private key.
1. Ensure that your Rust toolchain is using the same version that we tested
OpenSK with.
1. Install [tockloader](https://github.com/tock/tockloader).
1. Ensure that the Rust toolchain can compile code for ARM devices.
### Replacing the certificates
All the generated certificates and private keys are stored in the directory
`crypto_data/`.
This is the expected content after running our `setup.sh` script:
File | Purpose
----------------- | --------------------------------------------------------
`opensk_ca.csr` | Certificate sign request for the Root CA
`opensk_ca.key` | ECC secp256r1 private key used for the Root CA
`opensk_ca.pem` | PEM encoded certificate of the Root CA
`opensk_ca.srl` | File generated by OpenSSL
`opensk_cert.csr` | Certificate sign request for the attestation certificate
`opensk_cert.pem` | PEM encoded certificate used for the authenticator
`opensk.key` | ECC secp256r1 private key used for the autenticator
If you want to use your own attestation certificate and private key, simply
replace `opensk_cert.pem` and `opensk.key` files.
Our build script is responsible for converting `opensk_cert.pem` and
`opensk.key` files into the following Rust file: `src/ctap/key_material.rs`.
### Flashing a firmware
#### Nordic nRF52840-DK board
![Nordic development kit](img/devkit_annotated.jpg)
1. Connect a micro USB cable to the JTAG USB port.
1. Run our script for compiling/flashing your device (_output may differ_):
```shell
$ board=nrf52840dk ./deploy.sh app os
make: Entering directory './third_party/tock/boards/nordic/nrf52840dk'
Compiling kernel v0.1.0 (./third_party/tock/kernel)
Compiling cortexm v0.1.0 (./third_party/tock/arch/cortex-m)
Compiling nrf5x v0.1.0 (./third_party/tock/chips/nrf5x)
Compiling capsules v0.1.0 (./third_party/tock/capsules)
Compiling cortexm4 v0.1.0 (./third_party/tock/arch/cortex-m4)
Compiling nrf52 v0.1.0 (./third_party/tock/chips/nrf52)
Compiling nrf52840 v0.1.0 (./third_party/tock/chips/nrf52840)
Compiling components v0.1.0 (./third_party/tock/boards/components)
Compiling nrf52dk_base v0.1.0 (./third_party/tock/boards/nordic/nrf52dk_base)
Compiling nrf52840dk v0.1.0 (./third_party/tock/boards/nordic/nrf52840dk)
Finished release [optimized + debuginfo] target(s) in 11.28s
text data bss dec hex filename
114688 1760 260384 376832 5c000 target/thumbv7em-none-eabi/release/nrf52840dk
tockloader flash --address 0x00000 --jlink --board nrf52dk target/thumbv7em-none-eabi/release/nrf52840dk.bin
[STATUS ] Flashing binar(y|ies) to board...
[INFO ] Using known arch and jtag-device for known board nrf52dk
[INFO ] Finished in 0.324 seconds
make: Leaving directory './third_party/tock/boards/nordic/nrf52840dk'
[STATUS ] Preparing to uninstall apps...
[INFO ] Using known arch and jtag-device for known board nrf52dk
[ERROR ] No apps are installed on the board
Compiling libtock v0.1.0 (./third_party/libtock-rs)
Compiling crypto v0.1.0 (./libraries/crypto)
Compiling ctap2 v0.1.0 (.)
Finished release [optimized] target(s) in 7.60s
[STATUS ] Flashing binar(y|ies) to board...
[INFO ] Using known arch and jtag-device for known board nrf52dk
[INFO ] Finished in 0.305 seconds
[STATUS ] Installing app on the board...
[INFO ] Using known arch and jtag-device for known board nrf52dk
[INFO ] Finished in 0.975 seconds
```
1. Connect a micro USB cable to the device USB port.
**Note**: Due to current limitations of our implementation and Tock, you may
have to press the `BOOT/RESET` button, located next to the device USB port on
the board in order to see your OpenSK device on your system.
#### Nordic nRF52840 Dongle
![Nordic dongle](img/dongle_front.jpg)
1. The JTAG probe used for programming won't provide power to the board.
Therefore you will need to use a USB-A extension cable to power the dongle
through its USB port.
1. Connect the TC2050 cable to the pads below the PCB:
![Nordic dongle pads](img/dongle_pads.jpg)
1. You can use the retainer clip if you have one to avoid maintaining pressure
between the board and the cable:
![Nordic dongle retainer clip](img/dongle_clip.jpg)
1. Run our script for compiling/flashing your device (_output may differ_):
```shell
$ board=nrf52840_dongle ./deploy.sh app os
make: Entering directory './third_party/tock/boards/nordic/nrf52840_dongle'
Compiling kernel v0.1.0 (./third_party/tock/kernel)
Compiling cortexm v0.1.0 (./third_party/tock/arch/cortex-m)
Compiling nrf5x v0.1.0 (./third_party/tock/chips/nrf5x)
Compiling capsules v0.1.0 (./third_party/tock/capsules)
Compiling cortexm4 v0.1.0 (./third_party/tock/arch/cortex-m4)
Compiling nrf52 v0.1.0 (./third_party/tock/chips/nrf52)
Compiling nrf52840 v0.1.0 (./third_party/tock/chips/nrf52840)
Compiling components v0.1.0 (./third_party/tock/boards/components)
Compiling nrf52dk_base v0.1.0 (./third_party/tock/boards/nordic/nrf52dk_base)
Compiling nrf52840_dongle v0.1.0 (./third_party/tock/boards/nordic/nrf52840_dongle)
Finished release [optimized + debuginfo] target(s) in 10.47s
text data bss dec hex filename
110592 1688 252264 364544 59000 target/thumbv7em-none-eabi/release/nrf52840_dongle
tockloader flash --address 0x00000 --jlink --board nrf52dk target/thumbv7em-none-eabi/release/nrf52840_dongle.bin
[STATUS ] Flashing binar(y|ies) to board...
[INFO ] Using known arch and jtag-device for known board nrf52dk
[INFO ] Finished in 0.296 seconds
make: Leaving directory './third_party/tock/boards/nordic/nrf52840_dongle'
[STATUS ] Preparing to uninstall apps...
[INFO ] Using known arch and jtag-device for known board nrf52dk
[ERROR ] No apps are installed on the board
Compiling libtock v0.1.0 (./third_party/libtock-rs)
Compiling crypto v0.1.0 (./libraries/crypto)
Compiling ctap2 v0.1.0 (.)
Finished release [optimized] target(s) in 7.60s
[STATUS ] Flashing binar(y|ies) to board...
[INFO ] Using known arch and jtag-device for known board nrf52dk
[INFO ] Finished in 0.317 seconds
[STATUS ] Installing app on the board...
[INFO ] Using known arch and jtag-device for known board nrf52dk
[INFO ] Finished in 0.902 seconds
```
1. Remove the programming cable and the USB-A extension cable.
### Installing the udev rule (Linux only)
By default on Linux, a USB device will require root privilege in order interact
with it. As it is not recommended to run your web browser with such a high
privileged account, we made a `udev` rule file to allow regular users to
interact with OpenSK authenticators.
To install it, you need to execute the following commands:
```shell
sudo cp rules.d/55-opensk.rules /etc/udev/rules.d/
sudo udevadm control --reload
```
Then, you will need to unplug and replug the key for the rule to trigger.

Some files were not shown because too many files have changed in this diff Show More