1Nitrokey App [](https://travis-ci.org/Nitrokey/nitrokey-app) [](https://scan.coverity.com/projects/4744) 2============ 3Nitrokey App is a cross-platform (runs under Windows, Linux and Mac OS) application created to manage [Nitrokey devices](https://www.nitrokey.com/). Lately developed under Ubuntu 17.10/18.04 with Qt5.9. 4Underneath it uses [libnitrokey](https://github.com/Nitrokey/libnitrokey) to communicate with the supported devices. Both Nitrokey App and libnitrokey are available under GPLv3 license. 5 6##### Supported devices 7Currently Nitrokey App supports: 8- Nitrokey Pro v0.7/v0.8, 9- Nitrokey Storage. 10 11For Nitrokey HSM please see [Nitrokey Encryption Tool](https://github.com/Nitrokey/nitrokey-encryption-tool). Nitrokey Start has its own tools in its [firmware repository](https://github.com/Nitrokey/nitrokey-start-firmware/tree/gnuk1.2-regnual-fix). 12 13 14##### Compatibility 15The implementation is compatible to the Google Authenticator application which can be used for testing purposes. Test vectors from proper specifications also works: 16- HOTP: An HMAC-Based One-Time Password Algorithm - [RFC4226](https://tools.ietf.org/html/rfc4226), 17- TOTP: Time-Based One-Time Password Algorithm - [RFC6238](https://tools.ietf.org/html/rfc6238). 18 19Each libnitrokey's and supported devices' firmware release OTPs are tested automatically, according to the RFCs test vectors. 20 21##### Builds 22Ready to use binaries are available at [releases page](https://github.com/Nitrokey/nitrokey-app/releases). More details could be found at [main download site](https://www.nitrokey.com/download). 23 24##### Using under Linux 25Using the application under Linux requires configuration of device privileges in udev (due to USB communication). 26The configuration is installed automatically with the libnitrokey library (either with a package or after `make install`). Without it application cannot communicate unless run with root privileges. 27 28## Known issues 29 30#### Tray icon under Gnome 3.26 31 32Gnome 3.26 (and later) removed support for the tray dock and tray icon (Ubuntu 18.04 is not affected - it contains own plugin to support it). For more details please see: [NitrokeyApp#274](https://github.com/Nitrokey/nitrokey-app/issues/274). Nitrokey App v1.3 should solve this by introducing main window, which is shown right on application's start. 33 34#### Tray icon under Debian Jessie 35Under Debian Jessie application's tray icon might be unavailable. There were reports it can be fixed with updating Qt libraries to 5.4.2 version and up. The packages are available in experimental OS branch. For more details please refer to: [NitrokeyApp#86](https://github.com/Nitrokey/nitrokey-app/issues/86). Another way to workaround this is using an AppImage binary release, introduced in [Nitrokey App v1.3](https://github.com/Nitrokey/nitrokey-app/releases/tag/v1.3). 36 37## Installation and downloads 38Ready to use packages and install instructions are available on main site in download section: https://www.nitrokey.com/download 39 40## Compilation 41Ready to use Docker containers for building AppImage, Windows and Snapcraft binaries are available at [nitrokey-app.build](https://github.com/Nitrokey/nitrokey-app.build/tree/master/docker) project. There are set [automatic builds using Travis CI](https://travis-ci.org/Nitrokey/nitrokey-app) as well. 42Below are detailed instructions how to make a build manually. 43 44### Compiling on Ubuntu Linux 45 46Prerequisites for building on Ubuntu 17.10: 47- `build-essential` - for building applications 48- `cmake` - for compiling libnitrokey 49- `qt5-default` - QT5 library 50- `qttools5-dev` and `qttools5-dev-tools` - QT5 library tools - generating translations 51- `libqt5svg5-dev` - QT5 library for rendering SVG 52- `libqt5concurrent5` - QT5 library for concurrent calls 53- `pkg-config` - system libraries detection 54- `libnitrokey` (v3.3+) - this is built only, if not already installed in the OS (otherwise App will use system library) 55 - `libusb-1.0-0-dev` - library to communicate with USB devices 56 - `libhidapi-dev` - to communicate using HID layer 57 58Whole command for Ubuntu: 59``` 60sudo apt-get install libusb-1.0.0-dev cmake qt5-default qttools5-dev qttools5-dev-tools pkg-config libhidapi-dev build-essential libqt5svg5-dev libqt5concurrent5 61``` 62 63During the compilation CMake will test via `pkg-config`, whether system libnitrokey is available, and is it at least [LIBNK_MIN_VERSION](https://github.com/Nitrokey/nitrokey-app/blob/d6fad2bd1aecbda2e36d4e9873f613ef5bf7649d/CMakeLists.txt#L210) version. On failed test libnitrokey will be compiled as well. 64 65#### Getting the Nitrokey Sources 66 67Clone the Nitrokey-App repository using `git` and `--recursive` switch: 68``` 69git clone https://github.com/Nitrokey/nitrokey-app.git --recursive 70``` 71 72#### Qt Creator 73Prerequisites: Install Qt manually using [download page](http://www.qt.io/download-open-source/#section-2) or through package manager: 74``` 75sudo apt-get install qt5-default 76sudo apt-get install qtcreator #for compilation using IDE 77``` 78 79Please open `nitrokey-app-qt5.pro` file and select `Build All` from `Build` menu. 80 81#### Using CMake: 82General use: 83``` 84# in nitrokey-app directory: 85mkdir build 86cd build 87mkdir install 88cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=./install .. 89make -j4 90make install 91``` 92This will build and install binary to `./build/install` directory. Please omit `-DCMAKE_INSTALL_PREFIX=./install` in case you would like to install it to the system. 93 94Note: In case you have downloaded Qt manually from web download page you have to set `CMAKE_PREFIX_PATH` to your corresponding Qt path. 95Example: (If QT5.5 (64bit) was installed in your `$HOME` DIR): 96``` 97export CMAKE_PREFIX_PATH=$HOME/Qt/5.5/gcc_64/ 98``` 99 100#### Using QMake: 101Please run following commands for out-of-the-source build: 102``` 103mkdir build && cd build 104qmake .. 105make -j4 106# make install 107``` 108 109 110### Debian Packages 111#### Building Debian Packages 112 113Execute the following in directory "nitrokey-app": 114 115``` 116 fakeroot make -f debian/rules binary 117``` 118 119Cleanup with: 120 ``` 121 fakeroot make -f debian/rules clean 122 ``` 123 124Requirements: fakeroot, debhelper, hardening-wrapper, qt5-default, libusb-1.0-0-dev, cmake. 125 126#### Building RPM and Debian Packages (alternative) 127CMake can generate RPM packages using CPack. It can also generate `.deb` package using other method than presented in previous section. To create both packages please execute the following in directory "nitrokey-app": 128``` 129mkdir build && cd build 130cmake -DCMAKE_BUILD_TYPE=Release .. 131make -j4 package 132``` 133This will result in two packages: `.deb` and `.rpm`. 134 135#### Cross Compiling with QT5 for Windows on Ubuntu Linux (using MXE) 136 137Please run following commands: 138 139``` 140# install dependencies for compilation 141sudo apt-get install bison cmake flex intltool libtool scons 142# MXE GCC6, x32 143#remove MXE_PLUGIN_DIRS switch to use GCC 5.4.0 instead of GCC 6 144git clone https://github.com/mxe/mxe.git && pushd mxe 145make MXE_TARGETS=i686-w64-mingw32.static.posix MXE_PLUGIN_DIRS=plugins/gcc6 qtbase # takes about 1 hour first time 146popd 147 148#following should download nitrokey-app and libnitrokey with hidapi (own clone with applied OS-specific patches) 149git clone https://github.com/Nitrokey/nitrokey-app.git --recursive 150pushd nitrokey-app/libnitrokey/build 151ln -s ../../../mxe/usr/bin/ 152./bin/i686-w64-mingw32.static.posix-cmake .. 153make -j 154popd 155 156mkdir nitrokey-app/build/ 157pushd nitrokey-app/build/ 158ln -s ../mxe/usr/bin/ 159./bin/i686-w64-mingw32.static.posix-qmake .. 160PATH=$PATH:./bin make -j 161popd 162``` 163 164 165#### Compiling and creating a package for MAC OS 166 1671. Use Qt (qmake) to compile the Nitrokey App 1682. Navigate to `<build_dir>/<app_name>/Contents` 1693. Create a .dmg file: go to the build directory and run: 170`macdeployqt <app_name>/ -dmg`. `<app_name>.dmg` file will be created at the same folder. This is the final file for distributing the App on Mac OS 1714. Compress the `.dmg` package: 172 * Open Disk Utility 173 * Select the dmg package from left column (or drag'n'drop) 174 * Select Convert, check "compressed" option and then "Save" 175 176## Tray 177Note that the Nitrokey App's graphical interface is based on a QT system tray widget. If you are using a Linux desktop environment that does not support system tray widgets, then you may be unable to access the graphical interface. Nitrokey App v1.3 shows main window right on start, offering tray's menu, and it is possible to configure it to quit once the main window is closed. 178 179 180## Internals 181All configuration data including OTP secrets are stored in clear text in the flash of Nitrokey's microcontroller. This is not tamper resistant and may only be used for low to medium security requirements. 182Password Safe is encrypted using 256 bit AES key to which access is protected with SIM card. 183 184By default the OTP serial number (OTP Token) is OpenPGP Card's serial number. It can be changed within the GUI for each entry. The USB device serial number is set to the card's serial number when the device powers up. 185 186(disabled feature) Keyboard Layout: The user will input the token ID values as he wants them displayed, then the gui will translate them to keycodes of the selected layout. The keycodes will be stored on the device, along with a number saying which layout was used, this number is important when the GUI application reads the conifg back from the device (to translate the keycodes back into characters). 187 188The report protocol is described [here](https://github.com/Nitrokey/nitrokey-pro-firmware/blob/master/src/inc/report_protocol.h) for Pro and [here](https://github.com/Nitrokey/nitrokey-storage-firmware/blob/master/src/OTP/report_protocol.h) for Storage. 189The HID reports are set to 64 bytes. The "output report" is what you get from the device. When you send a report (command), the first byte sets the command type, then you have 59 bytes for your data, and the last 4 bytes are the CRC32 of the whole report. 190 191On the client side, please check documentation of [libnitrokey](https://github.com/Nitrokey/libnitrokey) project. 192 193## Advantages of App 1.x branch over 0.x 194Nitrokey App v1.x uses `libnitrokey` for communication with device, making the code both testable and reusable. 195Furthermore communication speed is vastly improved. Most of the code now makes requests to device in the background improving 196GUI responsiveness. Also the delay between sending and receiving is decreased. Additionally device-related information is now lazy-loaded, 197which means App requests the data only when it needs them (it was earlier loading all OTP slot data to memory). 198 199Migration to `libnitrokey` comes with a cost of increasing compiler's requirements to be compliant with C++14 standard. 200Fortunately most compatible compilers have been released in 2015 and all current ones should work. 201
){kind=link}
){kind=link}