aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 91def3a8c84475855bb11fc5a7cb92f4b675980f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
<!---
Copyright 2019 Robin Krahl <robin.krahl@ireas.org>
SPDX-License-Identifier: CC0-1.0
-->

# ntw

`ntw` is an experimental firmware for the Nitrokey Pro.  It is in very early
development and supports:

- connecting as a USB device with the Nitrokey Pro’s product and vendor ID
- connecting as a HID class device
- using these Nitrokey commands:
  - `GET_STATUS`
  - `READ_SLOT_NAME`

## Usage Example

To be able to compile `ntw`, you have to add the thumbv7m-none-eabi target to
your Rust installation, for example by running:

```
$ rustup target add thumbv7m-none-eabi
```

Now you can compile `ntw`:

```
$ cargo build --release
```

To communicate with an MCU connected using an ST-Link debugger, start `openocd`
using the provided configuration file:

```
$ openocd --file etc/openocd.cfg
```

Now you can use `gdb` to flash `ntw` to the MCU and to start a debugging
session.  `cargo run` is configured to execute `gdb`,  flash the MCU and add
breakpoints at the beginning of the program and at the panic handlers.  Once
you see the `gdb` prompt, type `c` to continue the program execution.

```
$ cargo run --release
```

Depending on your operating system, you might have to change the name of the
`gdb` executable in `.cargo/config`.

To verify that everything works as expected, you can try to access the device:

```
$ nitrocli status
Status:
  model:             Pro
  serial number:     0x00000000
  firmware version:  0.1
  user retry count:  0
  admin retry count: 0
```

If this does not work, check the output of `dmesg`, `lsusb` and `usbhid-dump`.

## Resources

### Development Setup

- NUCLEO-F103RB: [data sheet][NUCLEO-F103RB-ds]
- XNUCLEO-F103RB: [Waveshare wiki][XNUCLEO-F103RB-wiki]
- STM32F103RB: [data sheet][STM32F103RB-ds], [reference manual][STM32F103RB-rm]

[NUCLEO-F103RB-ds]: https://www.st.com/resource/en/data_brief/nucleo-f103rb.pdf
[XNUCLEO-F103RB-wiki]: https://www.waveshare.com/wiki/XNUCLEO-F103RB
[STM32F103RB-ds]: https://www.st.com/resource/en/datasheet/stm32f103rb.pdf
[STM32F103RB-rm]: https://www.st.com/content/ccc/resource/technical/document/reference_manual/59/b9/ba/7f/11/af/43/d5/CD00171190.pdf/files/CD00171190.pdf/jcr:content/translations/en.CD00171190.pdf

### Protocols

- [Universal Serial Bus Specification][usb], Revision 1.1
- [Universal Serial Bus: Device Class Definition for Human Interface Devices
  (HID)][hid], Firmware Specification, Version 1.11

[usb]: http://esd.cs.ucr.edu/webres/usb11.pdf
[hid]: https://www.usb.org/sites/default/files/documents/hid1_11.pdf

## Contact

For bug reports, patches, feature requests or other messages, please send a
mail to [ntw-dev@ireas.org][].

## License

This project is licensed under the [GNU General Public License version 3][GPL]
or later.  The documentation and configuration files contained in this
repository are licensed under the [Creative Commons Zero][CC0] license.  You
can find a copy of the license texts in the `LICENSES` directory.

`ntw` complies with [version 2.0 of the REUSE practices][reuse].

[ntw-dev@ireas.org]: mailto:ntw-dev@ireas.org
[GPL]: https://www.gnu.org/licenses/gpl-3.0.en.html
[CC0]: https://creativecommons.org/publicdomain/zero/1.0/
[reuse]: https://reuse.software/practices/2.0/