Getting Started

On the page, you will learn about:

Getting started with Keychain Core for Android in Android Studio
Getting started with Keychain Core for .NET in Visual Studio
Getting started with Keychain Core for Linux using GNU G++

Getting Started with Keychain Core for Android in Android Studio

Setting up the Keychain Gradle package feed

First set up your Android project to download Keychain’s packages from Keychain’s bintray repository. By doing this, the project will be able to automatically import versions of Keychain packages and control which packages and dependencies to integrate.

1. Add the following code to the dependencies section of the project’s build.gradle file

classpath 'com.github.dcendents:android-maven-gradle-plugin:2.0'
classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.8.4'

so that it looks somewhat like this:

dependencies {
    classpath 'com.android.tools.build:gradle:3.2.1'

    classpath 'com.github.decendents:android-maven-gradle-plugin:2.0'
    classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.8.4'
}

2. Add the following code to the repositories section of the project’s build.gradle file

maven {
    credentials {
        username "$mavenUser"
        password "$mavenApiKey"
    }
    url  "https://dl.bintray.com/keychain/maven/"
}

so that it looks somewhat like this:

repositories {
    google()
    jcenter()

    maven {
        credentials {
            username "$mavenUser"
            password "$mavenApiKey"
        }
        url  "https://dl.bintray.com/keychain/maven/"
    }
}

3. Add the following import statement to the dependencies section of the app’s build.gradle file

api 'io.keychain:libkeychain_android:2.1.1'

It should look somewhat like this:

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])

    <...other dependencies...>

	api 'io.keychain:libkeychain_android:2.1.1'
}

The '2.1.1' in the above is the current version as of this writing. As new versions are made available, change this version number if and when you are ready to test against the newer version.

4. Retrieve your bintray API key from bintray.com:

If you haven’t yet create your bintray account from the email invite.
Under the account menu item, select menu:'Edit Profile'[API Key].

.. Confirm your password and copy the API key that is revealed.

5. Add these credentials to the bottom of your project’s gradle.properties file.

mavenUser=<your_bintray_user_name>
mavenApiKey=<your_API_key>

6. Synch gradle and rebuild your project. You should have a successful synch. If so, you are ready to use the Keychain SDK.

Using the Keychain Core library

1. Inside your Android activity, you can create the core Keychain wallet and gateway.

Gateway gateway;
Monitor monitor;
Context context = Gateway.initializeDb(getApplicationContext());

// If initialize succeeded
if (!context.isNull()) {

    // Create gateway
    try {
        gateway = new Gateway(context);
        gateway.seed();
        monitor = new Monitor(context);
    }
    catch (Exception e)
    {
        Log.i("keychain.core", "Gateway create failed");
    }
    Log.i("keychain.core", "Gateway create OK");

} else {
    Log.e("keychain.core", "Database init FAILED");
}

2. Create a Persona

String name = "Alice";
String subName = "InWonderland";
Persona persona = gateway.createPersona(name, subName, Wallet.SecurityLevel.MEDIUM);

3. Encrypt and Decrypt Some Data

String msg = "Got it!";
ArrayList<Contact> contacts = new ArrayList<Contact>();

try {
    String encryptedMsg = gateway.signThenEncrypt(persona, contacts, msg.getBytes());
    String recoveredMsg = gateway.decryptThenVerify(persona, encryptedMsg);
}

catch (Exception e){
    // Log exception
}

if (msg.equals(recoveredMsg)){
    // Yeah!!
}
else {
    // Should get here if no exception is thrown
}

Getting Started with Keychain Core for .NET in Visual Studio

The fastest way to get started with the Keychain Client for .NET is to set up the sample console application project in the Windows repository. This section provides the steps to set that project up in your own environment.

Note that in future releases, this process will leverage the NuGet package system, potentially removing the need for the steps presented here.

1. Download and save the Keychain Core for .NET package and the sample console application project.

Save and extract the package in a folder in your general project workspace. You will use the chosen path later in setting up your project. The sample console application project should be put in your normal project workspace separate from the Keychain Core for .NET package.

2. Open the sample project in Visual Studio.

3. Update the Keychain reference with the path of the Keychain Core for .NET package.

In the Solution Explorer, navigate to ConsoleApp1→References. Delete the KeychainCli reference if one exists. Add a reference to the KeychainCli.dll located in the bin folder of the recently extracted Keychain Core for .NET package.

4. Set the project’s working directory.

In the form at ConsoleApp1→Properties→Debug, browse to and select the bin folder of the recently extracted Keychain Core for .NET package.

5. Add the reference to your search path.

For debugging, you need to tell the loader where it will find the Keychain Core libraries and dependencies. In our testing, the surest way to do that is to add the path of the Keychain Core package’s bin folder to your user’s PATH environment variable.

In the Windows search box on your tool bar (typically located at the bottom of your screen), type in 'environment'. Click the Settings:Environment Variable launcher. Under 'User variables', click 'Path' and then 'Edit'. Add the path to the environment variable.

6. Add you api key to the Keychain config file.

Open the keychain.cfg file in the bin folder of the package and replace the following

ApiKey: REPLACEME

with

ApiKey: <apikey>

where <apikey> is the API key you have or will be given by Keychain.

Getting Started with Keychain Core for Linux Using GNU G++

Installing libkeychain for the Local User

1 Download the Linux package libkeychain-linux-x64.tar.gz from the distribution site.

2 Extract the contents.

tar -xvf libkeychain-linux-x64.tar.gz

3 Install the package for the local user.

cd keychain/scripts ./install.sh

This will create a directory structure in $HOME/.keychain and copy the library files into $HOME/.keychain/lib and the relevant header files into $HOME/.keychain/include.

The installation of libkeychain is complete at this point.

Building the C++ Sample Project

4 Download the sample project for Linux keychain-sample-linux-x64.tar.gz.

5 Extract the contents.

tar -xvf keychain-sample-linux-x64.tar.gz

6 Build the project with the sample makefile.

cd sample/ make -f makefile-sample

7 Edit the API key in file keychain.cfg to the API key given to you by the Keychain admin.

8 Run the sample.

./run_sample.sh

This will set the library path to $HOME/.keychain/lib and run the sample program.