Password and Key Storage API

Haiku R1 introduces the first version of a system-wide key store service, allows you as developer to outsource some of the credential and certificate management, as well as providing an infrastructure that enables sharing these artifacts between applications.

Warning

The implementation in Haiku R1 is limited and is a promise of more to come. Functionality beyond storing and sharing passwords is for the future. Also please read the security section of this document, especially when you are working with artifacts that are more sensitive. In many cases you will find that this system service will work just as well as making your own implementation, but there are instances in which you may chose not to use it.

1. Highlevel Overview (components)

The implementation is based around the following concepts:

• The keystore is the centralized repository for your keys. It is managed by the keystore_server and it contains one or more keyrings.
• A keyring is a collection of keys. There is always a master keyring, which cannot be removed. Access is organized around keyrings. From a user's perspective, when an application wants to access keys in a keyring, the user will have to grant permission to that application to access the keyring. A keyring is identified by a name, which needs to be unique on the user's system.
• A keyring contains keys. These are the smallest unit in the system. A key can be anything that you want to safeguard in the keystore. Keys are identified by the combination of an identifier and a secondary identifier. These should be unique within a keyring.
• The final piece is the concept of permissions. In the current implementation, an application needs to ask permission to access a keyring. The keystore_server will validate the permissions, and if necessary prompt the user to grant one-time or a permant access. If the user only allows it once, access is granted until the application terminates.

As a user of the API, you will mostly be working with BKeyStore, as the access point that queries and modifies keyrings and keys. An individual key is represented by the BKey object.

2. Security

The current implementation of this API should be considered low-security. The most important thing to know is that there is no encryption applied when storing the keys and keyrings to the drive. This means that the data can be read by any malicious actor that can access the drive of your machine.

This should also puts the current locking mechanism in perspective. While the keystore_server will prompt the user to grant (or deny) access to your application, when it wants to access a keyring, this again does not prevent any malicious actor to bypass the keystore_server and directly read from (and write to!) the file.

When considering on whether to use the current API, there are a few things to think about:

• First, consider whether you should store the keys at all. Passwords to services with extremely sensitive personal or financial information, such as email passwords or credentials to financial institutions, should not be stored at all. Prompt your user for the credentials when needed, and don't keep them for later use.
• Secondly, if you are storing credentials for use with web services, check if the service you are using supports using access tokens. Many APIs have them, and often use it in combination with some form of permission system or scoping, making it possible for you to keep access as limited as possible. Furthermore, the user often has the ability to revoke access to a token, in case they think it is compromised.
• When you assess that you really do need to store the credentials, make a determination first about whether or not the credentials should have some form of encryption. For now you should consider looking for another solution to storing sensitive data, but contributions to improve this API are very welcome. It is beyond the scope of this document to discuss strategies around encryption.
• When you assess the risk is low enough not to employ encryption strategies, you may consider using this API. It is particularly recommended if you will be sharing the credentials with more than one application.

Warning

In the end, it is up to you as a developer to be conscious of any choices you make when it comes to user data, and credentials are no different. When you decide that the Password and Key API does not fit your needs, choose a framework or library that does fit your purpose.

3. Practical use of the API

Below are two distinct examples on how you may use the API.

The Langlaufer Web Browser

We are working on the infamous Langlaufer web browser, and we are adding a feature where we autocomplete user names and passwords. It is decided to use the Password and Key Storage API to do our key management. Whenever we land on a web page with a login screen, we will try to see if we have credentials for that web page. Part of the requirements is that we support more than one set of credentials for a web page.

It is decided that the application will store the user credentials in it's own keyring, as we do not want to interfere with any other keys in the master key. Additionally, we will use both the primary and secondary identifier fields. The primary will contain the hostname of the website, and the secondary will contain the user name.

One final design note is that all the calls to the keystore_server are synchronous, meaning they will block until there is a response back from the keystore. In the case that a user needs to be prompted for a password, the call will be blocked until they make a decision. That is why any calls on BKeyStore should be done on a separate worker thread, instead of within the logic of a Window.

For clarity, the example below displays the interaction with the BKeyStore and BKey classes through some utility functions. It is up to the reader to put that in a separate working thread.

#include <Key.h>
#include <KeyStore.h>
 
const char *kLanglauferKeyringName = "Langlaufer";
 
BObjectList<BPasswordKey>
GetKeysForWebsite(const char *baseUrl) {
    // There may be more than one match, so we use the iteration methods.
    BKeyStore keyStore;
    uint32 cookie;
    BPasswordKey currentKey;
    BObjectList<BPasswordKey> list;
    bool next = true;
 
    while(next) {
        status_t status = keyStore.GetNextKey(kLanglauferKeyringName,
            B_KEY_TYPE_PASSWORD, B_KEY_PURPOSE_WEB, cookie, currentKey);
        switch(status) {
            case B_OK:
                // Try to see if the key matches the website
                if (currentKey.Identifier() == baseUrl) {
                    // Add the item to the list.
                    list.AddItem(new BPasswordKey(currentKey));
                }
                break;
            case B_BAD_VALUE:
                // The keyring does not exist, create it, and end the
                // search
                CreateKeyring();
                next = false;
                break;
            default:
                // Something else went wrong, like the user did not give
                // authorization, or we are at the end of the list.
                // Bail out the search at this point.
                next = false;
                break;
            }
        }
    }
 
    return list;
}
 
void
CreateKeyring() {
    BKeyStore keyStore;
    // Ignore the return value in the next line, it may fail but that won't
    // interrupt the flow of our program.
    keyStore.AddKeyring(kLanglauferKeyringName);
}
 
void
AddOrReplaceKey(const char *baseUrl, const char *user, const char *password) {
    BKeyStore keyStore;
    BPasswordKey key;
 
    // Fill out the key with existing data, or create new data
    if (keyStore.GetKey(kLanglauferKeyringName, B_KEY_TYPE_PASSWORD, baseUrl, user, &key) == B_OK) {
        // Remove the existing key
        keyStore.RemoveKey(kLanglauferKeyringName, key);
        // Update the password
        key.SetPassword(password);
    } else {
        key.SetTo(password, B_KEY_PURPOSE_WEB, user, password);
    }
 
    // Store the updated/new key in the keyring
    keyStore.AddKey(kLanglauferKeyringName, key);
}

The CoolWebService Tool Suite

We are working on a set of tools that interface with a cool web service. Instead of building one monolithic application, we make several small tools with specific jobs for this cool web service. One of the tools does the authentication, and stores the key in the master keyring on the system. The other tools use this key to access the API.

Each tool requires the authentication token to be set up properly. That's why in the BApplication::ReadyToRun() hook we check for the availability of the key. If it is not available, or it does not work, the user will be redirected to the authentication tool. The key will be stored as a password. It will be identified by the identifier "CoolWebService".

void
CoolPushTool::ReadyToRun() {
    BKeyStore keyStore;
    BPasswordKey key;
 
    if (keyStore.GetKey(B_KEY_TYPE_PASSWORD, "CoolWebService", key) != B_OK) {
        // Terminate the application and re-authenticate
        ...
    }
 
    // Extract the key
    BString accessToken = key.Password();
 
    // Validate the key, and if succesful, continue
    ...
}