Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reworks the README #659

Merged
merged 2 commits into from
Nov 8, 2023
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions CITATION.cff
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
cff-version: 1.2.0
message: "If you use this software, please cite it as below."
repository-code: "https://github.com/google/OpenSK"
license: "Apache-2.0"
preferred-citation:
type: article
authors:
- family-names: "Ghinea"
given-names: "Diana"
- family-names: "Kaczmarczyck"
given-names: "Fabian"
- family-names: "Pullman"
given-names: "Jennifer"
- family-names: "Cretin"
given-names: "Julien"
- family-names: "Kölbl"
given-names: "Stefan"
- family-names: "Invernizzi"
given-names: "Luca"
- family-names: "Bursztein"
given-names: "Elie"
- family-names: "Picod"
given-names: "Jean-Michel"
title: "Hybrid Post-Quantum Signatures in Hardware Security Keys"
journal: "4th ACNS Workshop on Secure Cryptographic Implementation"
year: 2023
month: 6
75 changes: 55 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,47 +6,60 @@
![Cargo format](https://github.com/google/OpenSK/workflows/Cargo%20format/badge.svg?branch=develop)
[![Coverage Status](https://coveralls.io/repos/github/google/OpenSK/badge.svg?branch=develop)](https://coveralls.io/github/google/OpenSK?branch=develop)

*News:*

- 2023-08-24: [PQC paper reference](#Research)

## OpenSK

This repository contains a Rust implementation of a
[FIDO2](https://fidoalliance.org/fido2/) authenticator.
We developed OpenSK as a [Tock OS](https://tockos.org) application.
Also called security keys, they are a external devices that can be used for
signing in on websites.
kaczmarczyck marked this conversation as resolved.
Show resolved Hide resolved
You can see OpenSK in action in this
[video on YouTube](https://www.youtube.com/watch?v=klEozvpw0xg)!

We intend to bring a full open source experience to security keys, from
application to operating system. You can even 3D print your own open source
enclosure!
You can see OpenSK in action in this
[video on YouTube](https://www.youtube.com/watch?v=klEozvpw0xg)!

You are viewing the branch for developers. New features are developed here
before they are stabilized. If you instead want to use the FIDO certified
firmware, please go back to the
[stable branch](https://github.com/google/OpenSK).
<img src="docs/img/enclosure.jpg" alt="OpenSK Enclosure" width="200"/>

You can run OpenSK as a [Tock OS](https://tockos.org) application, or use the
library to bring OpenSK to your own hardware.

You are viewing the branch for developers. New features are developed here.
Go to the latest numbered branch for a more stable version of OpenSK.
kaczmarczyck marked this conversation as resolved.
Show resolved Hide resolved

### FIDO2

The develop branch implements the
[CTAP2.1 specification](https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html).
This branch is not FIDO certified. The implementation is backwards compatible
to CTAP2.0. Additionally, OpenSK supports U2F, and non-discoverable credentials
created with either protocol are compatible with the other.
OpenSK's version that implemented CTAP 2.0 was certified by the FIDO Alliance.
kaczmarczyck marked this conversation as resolved.
Show resolved Hide resolved

The develop branch tracks the latest release version of the
[CTAP specification](https://fidoalliance.org/specs/fido-v2.2-rd-20230321/fido-client-to-authenticator-protocol-v2.2-rd-20230321.html).
This branch is not FIDO certified.
OpenSK supports U2F, and non-discoverable credentials created with either
protocol are compatible with the other.

### :warning: Disclaimer

This project is **proof-of-concept and a research platform**. It is **NOT**
meant for a daily usage. It comes with a few limitations:

* This branch is under development, and therefore less rigorously tested than the stable branch.
* The cryptography implementations are not resistent against side-channel attacks.
meant for a daily usage. This branch is under development, and therefore less
rigorously tested than the numbered branches.

We're still in the process of integrating 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)
to enable hardware-accelerated cryptography. Our placeholder implementations of required
cryptography algorithms (ECDSA, ECC secp256r1, HMAC-SHA256 and AES256) in Rust are research-quality
code. They haven't been reviewed and don't provide constant-time guarantees.

to enable hardware-accelerated cryptography.
In the meantime, there are 2 options for cryptography implementations:

* Our own placeholder implementation. The code is research quality and doesn't
provide constant-time guarantees.
* The [RustCrypto](https://github.com/RustCrypto) interface. Deploy with
`--rust-crypto`. Note that our own ECC implementation is faster and has
smaller binary size, so not all boards support RustCrypto yet.

## Hardware

You will need one the following supported boards:
Expand Down Expand Up @@ -75,6 +88,28 @@ Please check our [Troubleshooting and Debugging](docs/debugging.md) section if y
have problems with the installation process or during development. To find out what
else you can do with your OpenSK, see [Customization](docs/customization.md).

## Research

We implemented post-quantum cryptography on OpenSK. The code is released under
the [hybrid-pqc tag](https://github.com/google/OpenSK/releases/tag/hybrid-pqc).
Our [paper](https://eprint.iacr.org/2022/1225) was published in the ACNS
Secure Cryptographic Implementation workshop 2023 and won the best paper award.

<details>
<summary>Bibtex reference</summary>

```
@InProceedings{Ghinea2023hybrid,
author= {Diana Ghinea and Fabian Kaczmarczyck and Jennifer Pullman and Julien Cretin and Rafael Misoczki and Stefan Kölbl and Luca Invernizzi and Elie Bursztein and Jean-Michel Picod},
title= {{Hybrid Post-Quantum Signatures in Hardware Security Keys}},
booktitle= {{4th ACNS Workshop on Secure Cryptographic Implementation, Kyoto, Japan}},
month= {June},
year= {2023},
}
```

</details>

## Contributing

See [Contributing.md](docs/contributing.md).
Expand Down
Loading