Keychain Core Documentation
Version:

Class gateway

#include <keychain/gateway/gateway.hpp>

Namespace: keychain

Inheritance: gateway

Description

gateway performs application-level cryptographic operations encrypt, decrypt, sign, and verify.

Through the gateway users create personas, contacts, and then execute the cryptographic operations with respect to those entities.

The gateway works together with the monitor. The gateway executes actions, and the monitor keeps the underlying state of personas, contacts and their associated keychains up to date.

Since: v2.0

Public Constructors

Constructor

gateway(std::string db_path, kc::settings settings)

gateway() = delete

gateway(const kc::gateway&) = delete

gateway(kc::gateway&&) = delete

kc::gateway& operator=(const kc::gateway&) = delete

kc::gateway& operator=(kc::gateway&&) = delete

Public Member Functions

Return type Method and Description

kc::code

add_signature(std::string &signed_text, const std::string &clear_text, bool approve = true, tkc::key_id_type pub_key_spec_type = tkc::key_id_type::txid_vout)

Adds the active persona signature alongside others in a signed message

kc::code

create_contact(kc::contact&, const std::string &name, const std::string &sub_name, kc::uri uri)

Create a contact from the provided information and add it to the current active persona

kc::code

create_persona(kc::persona &persona, std::string name, std::string sub_name, kc::security_level sec_level)

Create a new persona with the provided information

kc::code

decrypt(std::string &clear_text, tkc::char_encoding &cleartext_char_encoding, const std::string &cipher_text_xml)

Decrypts a ciphertext to a cleartext string along with the encoding used to encrypt

kc::code

decrypt_then_verify(std::string &clear_text, tkc::char_encoding &char_encoding, std::vector<kc::verification>& result, const std::string &cipher_text_xml)

Decrypts a ciphertext like decrypt, then verifies that all signatures are valid

kc::code

delete_facade(kc::facade facade)

Deletes a facade (persona or contact)

kc::code

encrypt(std::string &cipher_text_xml, const std::string &clear_text, const std::vector<kc::contact> &dest_names, tkc::char_encoding encoding = tkc::char_encoding::utf8, tkc::cipher cipher = tkc::cipher::aes_gcm_128, tkc::key_id_type pub_key_spec_type = tkc::key_id_type::txid_vout)

Encrypts a string so that it can be decrypted by the given contacts

kc::code

force_update_cache()

Force updates blockchain cache state

kc::code

get_active_persona(kc::persona &persona)

Gets the active persona

kc::code

get_contacts(std::vector<kc::contact> &contacts)

Gets the set of contacts for the current active persona

kc::code

get_personas(std::vector<kc::persona> &personas)

Gets all personas in this gateway

kc::code

hash(std::string& hash_result_hex, std::string clear_text)

Returns a hash of the string data

kc::code

rename_facade(kc::facade, std::string new_name, std::string new_subname)

Renames a facade (persona or contact)

kc::code

seed(std::string &address, std::vector<std::string> &mnemonic_list)

Seeds the private key pool and generates a mnemonic recovery string

kc::code

set_active_persona(persona persona)

Sets the active persona to the parameter

kc::code

sign(std::string &signed_text, const std::string &clear_text, bool approve = true, tkc::key_id_type pub_key_spec_type = tkc::key_id_type::txid_vout)

Signs a message

kc::code

sign_then_encrypt(std::string &cipher_text_xml, const std::string &clear_text, const std::vector<kc::contact> &dest_names, const kc::persona&, tkc::char_encoding encoding = tkc::char_encoding::utf8, tkc::cipher cipher = tkc::cipher::aes_gcm_128, tkc::key_id_type pub_key_spec_type = tkc::key_id_type::txid_vout)

Signs then encrypts a message

kc::code

verify(std::vector<kc::verification>& result, tkc::char_encoding& char_encoding, std::string& message, const std::string& signed_msg)

Verifies the signatures of a signed message

kc::code

decrypt(std::string &clear_text, tkc::char_encoding &char_encoding, const std::string &cipher_text_xml)`

Decrypts a ciphertext to a cleartext string along with the encoding used to encrypt.

kc::code

decrypt_then_verify(std::string &clear_text, tkc::char_encoding &char_encoding, std::vector<kc::verification>& result, const std::string &cipher_text_xml)

Decrypts a ciphertext like decrypt, then verifies that all signatures are valid

Static Member Functions

Return type Method and Description

kc::code

init(kc::settings& settings, std::string config_path, std::string db_path, bool force_clean, std::string drop_sql_file, std::string create_sql_file)

Creates a Keychain settings and validates the license

Public Member Functions Detail

add_signature

kc:code add_signature(std::string &signed_text, const std::string &clear_text, bool approve = true, tkc::key_id_type pub_key_spec_type = tkc::key_id_type::txid_vout)

Given a message M and set of signatures [S], add the current persona’s signature on M to the set [S].

The message M is unchanged but the set of signatures is augmented by precisely 1.

Returns:

The Keychain library error code indicating success or failure

create_contact

kc:code create_contact(kc::contact&, const std::string &name, const std::string &sub_name, kc::uri uri)

Create a contact from the provided information and add it to the current active persona.

This method goes to the blockchain with the provided uri to find the tip and validate the keychains for the contact.

Returns:

The Keychain library error code indicating success or failure

create_persona

kc:code create_persona(kc::persona &persona, std::string name, std::string sub_name, kc::security_level sec_level)

Create a new persona with the provided information.

This method is asynchronous with respect to the underlying blockchain and it will return a new persona object immediately even though the underlying object is not yet in a confirmed state as per the persona life cycle. Therefore the uri may not be available. Do not reference the uri until the persona is confirmed.

Returns:

The Keychain library error code indicating success or failure

decrypt

kc:code decrypt(std::string &clear_text, tkc::char_encoding &cleartext_char_encoding, const std::string &cipher_text_xml)

Decrypts a ciphertext to a cleartext string along with the encoding used to encrypt.

Returns:

The Keychain library error code indicating success or failure

decrypt_then_verify

kc:code decrypt_then_verify(std::string &clear_text, tkc::char_encoding &char_encoding, std::vector<kc::verification>& result, const std::string &cipher_text_xml)

Decrypts a ciphertext like decrypt, then verifies that all signatures are valid. Each signature is checked for validity and whether the signer is a known contact for the persona. The results are made available in the result out parameter.

Returns:

The Keychain library error code indicating success or failure

delete_facade

kc:code delete_facade(kc::facade facade)

Deletes a facade (persona or contact). The parameter must not be the current active persona.

Returns:

The Keychain library error code indicating success or failure

encrypt

kc:code encrypt(std::string &cipher_text_xml, const std::string &clear_text, const std::vector<kc::contact> &dest_names, tkc::char_encoding encoding = tkc::char_encoding::utf8, tkc::cipher cipher = tkc::cipher::aes_gcm_128, tkc::key_id_type pub_key_spec_type = tkc::key_id_type::txid_vout)

Encrypts a string so that it can be decrypted by the given contacts. The string encoding, desired cipher type and public key type are optionally provided.

Returns:

The Keychain library error code indicating success or failure

force_update_cache

kc:code force_update_cache()

Force update blockchain cache state.

Returns:

The Keychain library error code indicating success or failure

get_active_persona

kc:code get_active_persona(kc::persona &persona)

Gets the active persona.

Returns:

The Keychain library error code indicating success or failure

get_contacts

kc:code get_contacts(std::vector<kc::contact> &contacts)

Gets the set of contacts for the current active persona.

Returns:

The Keychain library error code indicating success or failure

get_personas

kc:code get_personas(std::vector<kc::persona> &personas)

Gets all personas in this gateway.

Returns:

The Keychain library error code indicating success or failure

hash

kc:code hash(std::string& hash_result_hex, std::string clear_text)

Returns a hash of the string data.

Returns:

The Keychain library error code indicating success or failure

rename_facade

kc:code rename_facade(kc::facade, std::string new_name, std::string new_subname)

Renames a facade (persona or contact). This operation is local to this gateway and does not hit the blockchain.

Returns:

The Keychain library error code indicating success or failure

seed

kc:code seed(std::string &address, std::vector<std::string> &mnemonic_list)

Seeds the private key pool and generates a mnemonic recovery string.

Returns:

The Keychain library error code indicating success or failure

set_active_persona

kc:code set_active_persona(persona persona)

Sets the active persona to the parameter. The parameter must be a valid persona.

Returns:

The Keychain library error code indicating success or failure

sign

kc:code sign(std::string &signed_text, const std::string &clear_text, bool approve = true, tkc::key_id_type pub_key_spec_type = tkc::key_id_type::txid_vout)

Given a message M and set of signatures [S], create a new message M + [S] and add the current persona’s signature on this new message.

This differs from add_signature in that the signature is attesting to the entire message and existing signatures, rather than just the message.

Given an input that is M a message and [S] a set of signatures,

add_signature: the result is M and [S, s_p] where s_p is the signature of the current persona on M

sign: the result is M' and [s_p], where s_p is the signature of the current persona on M', and M' is the combination of M and [S] together

This nuance allows for a signatory to attest other signatories, creating tiered attestations.

Returns:

The Keychain library error code indicating success or failure

sign_then_encrypt

kc:code sign_then_encrypt(std::string &cipher_text_xml, const std::string &clear_text, const std::vector<kc::contact> &dest_names, const kc::persona&, tkc::char_encoding encoding = tkc::char_encoding::utf8, tkc::cipher cipher = tkc::cipher::aes_gcm_128, tkc::key_id_type pub_key_spec_type = tkc::key_id_type::txid_vout)

Signs then encrypt a string so that it can be decrypted (and verified) by the given contacts.

Returns:

The Keychain library error code indicating success or failure

verify

kc:code verify(std::vector<kc::verification>& result, tkc::char_encoding& char_encoding, std::string& message, const std::string& signed_msg)

Verifies the signatures of a signed message. Results are placed in result and the unsigned message in message.

Static Member Functions Detail

init

kc::code init(kc::settings& settings, std::string config_path, std::string db_path, bool force_clean, std::string drop_sql_file, std::string create_sql_file)

Creates a Keychain settings and validates the license. The settings is required for gateway construction, meaning this method must be called before any other operations. Valid paths to config (keychain.cfg) and the Keychain DB must be passed. If force_clean is True, the database will be destroyed and recreated, so the 2 SQL files must also exist.

Parameters:

config_path - the path to the Keychain configuration file (e.g. keychain.cfg)

db_path - the path to the Keychain DB

force_clean - whether to wipe the DB and recreate or not

drop_sql_file - the path to an SQL file that drops all Keychain tables in an existing DB

create_sql_file - the path to an SQL file that recreates Keychain tables

Returns:

A kc::code representing the success or failure of the operation, and if failure the appropriate error code