Kync.asciidoc

Kync v1

Table of Contents

• General
• Plugin API
  • General Rules
  • API Overview
  • init
  • id
  • configs
  • set_context
  • auth_info_protect, auth_info_recover
  • protect
  • recover
  • slice_t
  • write_t

General

Kync describes a KeYeNCapsulation plugin API – a KyNc plugin performs the task of protecting your app’s secret.

The advantage of separating the app and the key storage is that the secret can be stored in a context specific and user defined way by simply loading another plugin – how the secret is protected becomes completely opaque to your app.

Plugin API

To achieve a simple and cross-platform compatible API, we use dynamic libraries that expose a C API/ABI.

General Rules

These rules apply to all functions:

1. All functions may fail. If they fail they return a pointer to a statically allocated, \0-terminated C string. Otherwise they return NULL.

2. All structs, callbacks etc. are passed as pointers; no ownership is transferred

3. An API-call MUST NOT take longer than 90 seconds before returning

4. If a callback fails, the operation must be canceled and the callback error MUST be propagated

API Overview

These functions are defined by the API and MUST be implemented:

1. init: Initializes the library, sets the log level and checks if the requested API is supported

2. id: Queries the plugin/format ID

3. configs: Queries all possible plugin configurations (available algorithms, tokens etc.)

4. auth_info: Queries the authentication requirements for a specific configuration

5. protect: Protects a secret and generates the necessary public recovery information for it

6. recover: Recovers a secret using the public recovery information

7. slice_t: An immutable slice over some bytes

8. write_t: A write callback

init

const char* init(uint16_t api, uint8_t log_level);

This function initializes the library, sets the log_level and checks if the requested api version is implemented.

Parameters:

1. api: The requested API version (this document defines the API 0x01_00)

2. log_level: The logging level the plugin should use (0 means no logging). Note: This applies to StdErr-logging only

id

const char* id(write_t* sink);

This function writes the capsule UID to sink using a single sink.write-call.

Parameters:

1. sink: The sink to write the ID to

configs

const char* configs(write_t* sink);

This function writes all available configs to sink using a single sink.write-call for each config (e.g. three configs result in three sink.write-calls).

Configs identify a specific algorithm/storage/token etc. There must at least be one config.

Parameters:

1. sink: The sink to write the configs to

set_context

const char* set_context(const slice_t* context);

This functions sets an optional application specific context. This makes it possible for the plugin to generate more meaningful names etc. Plugins may silently ignore a call to set_context and MUST NOT return an error unless they want to but cannot use the context.

Parameters:

1. context: The application context (e.g. the application name and key usage)

auth_info_protect, auth_info_recover

const char* auth_info_protect(uint8_t* is_required, uint64_t* retries, const slice_t* config);
const char* auth_info_recover(uint8_t* is_required, uint64_t* retries, const slice_t* config);

These functions query the authentication requirements to protect/recover a secret for a specific config. The functions check if an authentication is necessary and get the number if retries left.

Parameters:

1. is_required: Is set to 1 if an authentication is required, 0 otherwise

2. retries: Is set to the amount of retries left or UINT64_MAX if there is no limit

3. config: The config to get the authentication information for

protect

const char* protect(write_t* sink, const slice_t* data, const slice_t* config, const slice_t* auth);

This function protects data and writes the public recovery information to sink.

Parameters:

1. sink: The sink to write the public recovery information to

2. data: The secret data to protect

3. config: The configuration to use

4. auth: The authentication information or NULL if no authentication attempt should be performed

recover

const char* recover(write_t* sink, const slice_t* data, const slice_t* auth);

This recovers a secret from the recovery data and writes it to sink.

Parameters:

1. sink: The sink to write the public recovery information to

2. data: The secret data to protect

3. auth: The authentication information or NULL if no authentication attempt should be performed

slice_t

typedef struct slice_t slice_t;
/// A slice over some data
struct slice_t {
	/// The data
	const uint8_t* ptr;
	/// The data length
	const size_t len;
};

An immutable slice over some data.

Fields:

1. ptr: A pointer to the data

2. len: The length of the data

write_t

typedef struct write_t write_t;
/// A write callback
struct write_t {
	/// An opaque handle to the data sink
	void* handle;
	/// Pushes a segment to `handle` and returns `NULL` on success or a pointer to a static error
	/// description
	const char* (*write)(void* handle, const slice_t* data);
};

A write callback to write some data to an opaque handle. The write function may be called multiple times – either to split the data into different logical segments (e.g. configs) or just because the data is not available at once (e.g. protect and recover).

Fields:

1. handle: A pointer to an opaque handle

2. write: A pointer to a write implementation that writes data to handle and returns NULL on success or an error pointer on error