Git-Mirrors/keepassxc
1
0
Fork 0
mirror of https://github.com/keepassxreboot/keepassxc.git synced 2024-10-01 01:26:01 -04:00
Code Issues Packages Projects Releases Wiki Activity
484bc5dd01
keepassxc/INSTALL.md
Christoph Honal 6d1fc31e96
Implement support for Yubikeys and potential other tokens via wireless NFC using smartcard readers (Rebase) (#6895) 
* Support NFC readers for hardware tokens using PC/SC

This requires a new library dependency: PCSC.
The PCSC library provides methods to access smartcards. On Linux, the third-party pcsc-lite package is used. On Windows, the native Windows API (Winscard.dll) is used. On Mac OSX, the native OSX API (framework-PCSC) is used.

* Split hardware key access into multiple classes to handle different methods of communicating with the keys.

* Since the Yubikey can now be a wireless token as well, the verb "plug in" was replaced with a more
generic "interface with". This shall indicate that the user has to present their token to the reader, or plug it in via USB.

* Add PC/SC interface for YubiKey challenge-response

This new interface uses the PC/SC protocol and API
instead of the USB protocol via ykpers. Many YubiKeys expose their functionality as a CCID device, which can be interfaced with using PC/SC. This is especially useful for NFC-only or NFC-capable Yubikeys, when they are used together with a PC/SC compliant NFC reader device.

Although many (not all) Yubikeys expose their CCID functionality over their own USB connection as well, the HMAC-SHA1 functionality is often locked in this mode, as it requires eg. a touch on the gold button. When accessing the CCID functionality wirelessly via NFC (like this code can do using a reader), then the user interaction is to present the key to the reader.

This implementation has been tested on Linux using pcsc-lite, Windows using the native Winscard.dll library, and Mac OSX using the native PCSC-framework library.

* Remove PC/SC ATR whitelist, instead scan for AIDs

Before, a whitelist of ATR codes (answer to reset, hardware-specific)
was used to scan for compatible (Yubi)Keys.
Now, every connected smartcard is scanned for AIDs (applet identifier),
which are known to implement the HMAC-SHA1 protocol.

This enables the support of currently unknown or unreleased hardware.

Co-authored-by: Jonathan White <support@dmapps.us>
2021-10-01 10:39:07 -04:00

6.4 KiB
Raw Blame History

Build and Install KeePassXC

This document will guide you through the steps to build and install KeePassXC from source. For more information, see also the Building KeePassXC page on the wiki.

The QuickStart Guide gets you started using KeePassXC on your Windows, macOS, or Linux computer using pre-compiled binaries from the downloads page.

Build Dependencies

The following tools must exist within your PATH:

  • make
  • cmake (>= 3.3.0)
  • g++ (>= 4.7) or clang++ (>= 6.0)
  • asciidoctor

The following libraries are required:

  • Qt 5 (>= 5.9.5): qtbase5, qtbase5-private, libqt5svg5, qttools5, qt5-image-formats-plugins
  • botan (>= 2.12)
  • zlib
  • minizip
  • readline (for completion in cli)
  • libqt5x11extras5, libxi, and libxtst (for auto-type on X11)
  • qrencode
  • libusb-1.0, pcsclite (optional to support YubiKey on Linux)

Prepare the Building Environment

Build Steps

We recommend using the release tool to perform builds, please read up-to-date instructions on our wiki.

To compile from source, open a Terminal (on Linux/MacOS) or a MSYS2-MinGW shell (on Windows)
Note: on Windows you can also use MSVC to build natively, we recommend Visual Studio 2019

First, download the KeePassXC source tarball or check out the latest version from our Git repository.

To clone the project from Git, cd to a suitable location and run

git clone https://github.com/keepassxreboot/keepassxc.git

This will clone the entire contents of the repository and check out the current develop branch.

To update the project from within the project's folder, you can run the following command:

git pull

For a stable build, it is recommended to checkout the master branch.

git checkout master

NOTE: See the Windows Build Instructions for building with MSVC.

Navigate to the directory where you have downloaded KeePassXC and type these commands:

mkdir build
cd build
cmake -DWITH_XC_ALL=ON ..
make

NOTE: If you are using MSYS2, you may have to add -G "MSYS Makefiles" to the beginning of the cmake command.

These steps place the compiled KeePassXC binary inside the ./build/src/ directory. (Note the cmake notes/options below.)

Cmake Notes:

  • Common cmake parameters

    -DCMAKE_INSTALL_PREFIX=/usr/local
-DCMAKE_VERBOSE_MAKEFILE=ON
-DCMAKE_BUILD_TYPE=<RelWithDebInfo/Debug/Release>
-DWITH_GUI_TESTS=ON

  • cmake accepts the following options:

      -DWITH_XC_AUTOTYPE=[ON|OFF] Enable/Disable Auto-Type (default: ON)
  -DWITH_XC_YUBIKEY=[ON|OFF] Enable/Disable YubiKey HMAC-SHA1 authentication support (default: OFF)
  -DWITH_XC_BROWSER=[ON|OFF] Enable/Disable KeePassXC-Browser extension support (default: OFF)
  -DWITH_XC_NETWORKING=[ON|OFF] Enable/Disable Networking support (e.g., favicon downloading) (default: OFF)
  -DWITH_XC_SSHAGENT=[ON|OFF] Enable/Disable SSHAgent support (default: OFF)
  -DWITH_XC_TOUCHID=[ON|OFF] (macOS Only) Enable/Disable Touch ID unlock (default:OFF)
  -DWITH_XC_FDOSECRETS=[ON|OFF] (Linux Only) Enable/Disable Freedesktop.org Secrets Service support (default:OFF)
  -DWITH_XC_KEESHARE=[ON|OFF] Enable/Disable KeeShare group synchronization extension (default: OFF)
  -DWITH_XC_KEESHARE_SECURE=[ON|OFF] Enable/Disable KeeShare signed containers, requires libquazip5 (default: OFF)
  -DWITH_XC_ALL=[ON|OFF] Enable/Disable compiling all plugins above (default: OFF)

  -DWITH_XC_UPDATECHECK=[ON|OFF] Enable/Disable automatic updating checking (requires WITH_XC_NETWORKING) (default: ON)

  -DWITH_TESTS=[ON|OFF] Enable/Disable building of unit tests (default: ON)
  -DWITH_GUI_TESTS=[ON|OFF] Enable/Disable building of GUI tests (default: OFF)
  -DWITH_DEV_BUILD=[ON|OFF] Enable/Disable deprecated method warnings (default: OFF)
  -DWITH_ASAN=[ON|OFF] Enable/Disable address sanitizer checks (Linux / macOS only) (default: OFF)
  -DWITH_COVERAGE=[ON|OFF] Enable/Disable coverage tests (GCC only) (default: OFF)
  -DWITH_APP_BUNDLE=[ON|OFF] Enable Application Bundle for macOS (default: ON)

  -DKEEPASSXC_BUILD_TYPE=[Snapshot|PreRelease|Release] Set the build type to show/hide stability warnings (default: "Snapshot")
  -DKEEPASSXC_DIST_TYPE=[Snap|AppImage|Other] Specify the distribution method (default: "Other")
  -DOVERRIDE_VERSION=[X.X.X] Specify a version number when building. Used with snapshot builds (default: "")
  -DGIT_HEAD_OVERRIDE=[XXXXXXX] Specify the 7 digit git commit ref for this build. Used with distribution builds (default: "")

  • If you are on MacOS you must add this parameter to Cmake, with the Qt version you have installed
    -DCMAKE_PREFIX_PATH=/usr/local/Cellar/qt5/5.6.2/lib/cmake/

❗ When building with ASan support on macOS, you need to use export ASAN_OPTIONS=detect_leaks=0 before running the tests (no LSan support in macOS).

Installation

After you have successfully built KeePassXC, install the binary by executing the following:

sudo make install

You can specify the destination dir with

DESTDIR=X

Packaging

You can create a package to redistribute KeePassXC (zip, deb, rpm, dmg, etc..). Refer to keepassxc-packaging

Testing

You can perform tests on the built executables with:

make test ARGS+="--output-on-failure"

If you are not currently running on an X Server or Wayland, run the tests as follows:

make test ARGS+="-E test\(cli\|gui\) --output-on-failure"
xvfb-run -e errors -a --server-args="-screen 0 1024x768x24" make test ARGS+="-R test\(cli\|gui\) --output-on-failure"

Common parameters:

CTEST_OUTPUT_ON_FAILURE=1
ARGS+=-jX
ARGS+="-E testgui"