First Steps

This page will guide you through the process of setting up Keychain Core. Keychain Core is the library upon which all other components depend, and gives you the ability to develop your own Keychain-enabled applications using numerous APIs to suit your needs.

Jump to Linux and MacOS installation steps.

Jump to Windows installation steps.

If you are designing an application to instead interface with the Keychain Web Server, you can skip this tutorial and go to the Keychain Web Server Getting Started page.

Artifactory

The Keychain Core library builds are located on the Keychain Jfrog public binary repositories at https://keychain.jfrog.io/artifactory/.

All releases are in the subtree keychain-core-release-generic, with the core library for Linux and MacOS found in /keychain-cpp and Windows in /keychain-csharp.

Linux and MacOS

Download

First, download the tarball from the repository. We can do this from the command line (please use your own values for variables)

# Keychain Core version
VERSION=2.4.13

# Operating System (linux, macos, ios, iossimulator)
OS=linux

# CPU/IS Architecture (armv7, armv8, x64)
ARCH=x64

# URL for the Keychain Core library (static)
KCURL = https://keychain.jfrog.io/artifactory/keychain-core-release-generic/keychain-cpp

# Download 'keychain-cpp-release-2.4.13-linux-x64.tar.gz'
curl -X GET "$KCURL/keychain-cpp-release-$VERSION-$OS-$ARCH.tar.gz"
bash

Install

Next, extract the contents of the tarball, which will create a folder of the same name without the .tar.gz

# creates folder 'keychain-cpp-release-2.4.13-linux-x64/'
tar zxf keychain-cpp-release-$VERSION-$OS-$ARCH.tar.gz
bash

Now go into the new folder, navigate to scripts/, and execute install.sh. If your environment has a variable KEYCHAIN_HOME, then Keychain will be installed to that location. The default is ~/.keychain.

cd keychain-cpp-release-$VERSION-$OS-$ARCH
cd scripts

# KEYCHAIN_HOME=/opt/keychain ./install.sh  <- install Keychain into '/opt/keychain'
./install.sh
bash

Now you have Keychain installed in $KEYCHAIN_HOME (or ~/.keychain). The directory contains the following files and folders:

bin/        Keychain test app
config/     configuration file skeleton
data/       SQL statements for the Keychain DB
include/    the Keychain Core headers for development
lib/        the Keychain Core shared library
scripts/    Scripts to install the SO and binaries

Further Steps

At this point, Keychain Core has been installed and can be used. The next few sections are "quality of life" enhancements that make development smoother.

Library Bindings

The library lib/libkeychain.so is unknown to the dynamic linker at this point. This means that when building and running applications on Keychain Core, you would need to specify -L<path_to_keychain/lib> and LD_LIBRARY_PATH=<path_to_keychain/lib>, respectively.

You can simplify this by letting the dynamic linker know about libkeychain.so. This requires root/sudo permissions, and is done like so:

# Note: /usr/lib is one option, but /usr/local/lib or /lib also work
cp lib/libkeychain.so /usr/lib/
ldconfig
bash

Includes

Include files are in a similar state as the library, in that the C preprocessor doesn’t know where they are by itself. One way around this is to build with -I<path_to_keychain/include>. Another is to set the environment variable(s) C_INCLUDE_PATH and/or CPLUS_INCLUDE_PATH.

However, a better way would be to place the include files in one of the preprocessor’s search paths, such as /usr/include.

cp -r include/keychain/keychain /usr/include/
cp -r include/tkcrypt/tkcrypt /usr/include/
bash

Windows

For Windows, the Keychain Core shared object is a DLL and found in the C# artifact.

Download

Go to the Keychain artifactory and navigate to keychain-core-release-generic/keychain-csharp, and click the latest version. The file will be named like keychain-csharp-2.4.2-windows-x86.zip (for 2.4.2).

For v2.4, only x86 binaries are available

Install

Unzip the file into a directory of your choice. For example, C:\Keychain\2.4.2.

Usage

With the archive unzipped and placed in a known directory, it can now be referenced in a C# .NET project.

This is done by adding a shared library reference to the project to the KeychainCli.dll file. See the image below.

Example of adding KeychainCli to the KeychainChat accelerator

After this step, the Keychain Core library can be used in the project.

Please keep in mind that for v2.4 the project will need to be compiled as x86 (32-bit) for the DLL to be recognized as valid.

Next Steps - Solution Accelerators

We recommend that you get familiar with the Keychain capabilities by downloading, building, and trying one or more of our solution accelerators.

These accelerators illustrate simple use cases and highlight usage patterns of Keychain Core in multiple programming languages and environments (primarily Java and Python on Linux, Android Java, and C#.NET on Windows).

These sample projects are provided as-is, solely for informational/educational purposes and do not represent production-level code.