Agent keys subtree

Overview

// typedefs

typedef enum tapi_cfg_key_manager tapi_cfg_key_manager;
typedef enum tapi_cfg_key_type tapi_cfg_key_type;
typedef enum tapi_cfg_key_size tapi_cfg_key_size;
typedef enum tapi_cfg_key_mode tapi_cfg_key_mode;

// enums

enum tapi_cfg_key_manager;
enum tapi_cfg_key_mode;
enum tapi_cfg_key_size;
enum tapi_cfg_key_type;

// global functions

bool tapi_cfg_key_exists(const char* ta, const char* key_name);
te_errno tapi_cfg_key_add(const char* ta, const char* key_name, tapi_cfg_key_manager manager, tapi_cfg_key_type type, tapi_cfg_key_size size, tapi_cfg_key_mode mode);
unsigned tapi_cfg_key_get_bitsize(const char* ta, const char* key_name);
char* tapi_cfg_key_get_private_key_path(const char* ta, const char* key_name);
char* tapi_cfg_key_get_public_key(const char* ta, const char* key_name);
te_errno tapi_cfg_key_del(const char* ta, const char* key_name);
te_errno tapi_cfg_key_append_public(const char* ta, const char* key_name, const char* dst_ta, const char* list_name);

Detailed Documentation

Typedefs

typedef enum tapi_cfg_key_manager tapi_cfg_key_manager

Support key managers

typedef enum tapi_cfg_key_type tapi_cfg_key_type

Key types.

Different key managers may have different sets of key types.

typedef enum tapi_cfg_key_size tapi_cfg_key_size

Key sizes.

The values are abstract, not exact bit sizes, because different key type may have totally different semantics of a key size, therefore requesting a exact size rarely makes any sense

typedef enum tapi_cfg_key_mode tapi_cfg_key_mode

Key replacement modes.

If a key does not exist, it is always created.

Global Functions

bool tapi_cfg_key_exists(const char* ta, const char* key_name)

Check whether a key exists

Parameters:

ta	Agent name
key_name	Key name

Returns:

true if the key exists

te_errno tapi_cfg_key_add(const char* ta, const char* key_name, tapi_cfg_key_manager manager, tapi_cfg_key_type type, tapi_cfg_key_size size, tapi_cfg_key_mode mode)

Add or replace a key with given parameters.

Because keys may be generated by an external tool at the agent, there may not be simple diagnostics if something goes wrong there. An assortment of error codes may be returned, such as TE_ESHCMD, TE_EIO and others.

Parameters:

ta	Agent name
key_name	Key name
manager	Key manager
type	Key type
size	Key size
mode	Key replacement mode. If a key does not exist, it is always created in any mode.
TE_EEXIST	New key has been requested, but a key already exists
TE_EBADSLT	A key cannot be reused due to different parameters
TE_TE_EPROTONOSUPPORT	The agent does not support a requested manager

Returns:

Status code

unsigned tapi_cfg_key_get_bitsize(const char* ta, const char* key_name)

Get the real bit size of a generated key.

Parameters:

ta	Agent name
key_name	Key_name
0	There is an error
1	This may be returned instead of a real size for some key types which do not have a sensible notion of a key bit size

Returns:

The real bit size of a key

char* tapi_cfg_key_get_private_key_path(const char* ta, const char* key_name)

Get the private key file path at the agent side.

The name shall not change if a key is re-generated.

Parameters:

ta	Agent name
key_name	Key name
NULL	An error happened

Returns:

Private key path (should be free()’d)

char* tapi_cfg_key_get_public_key(const char* ta, const char* key_name)

Get the public key.

This is the real encoded public key string, not a file name. The string is guaranteed not to have any embedded zeroes.

Parameters:

ta	Agent name
key_name	Key name
NULL	An error happened

Returns:

Public key string (should be free()’d)

te_errno tapi_cfg_key_del(const char* ta, const char* key_name)

Delete a key from the agent.

Parameters:

ta	Agent name
key_name	Key name

Returns:

Status code

te_errno tapi_cfg_key_append_public(const char* ta, const char* key_name, const char* dst_ta, const char* list_name)

Append a public key to a list of keys.

Append the public key of key_name from ta to a file list_name on dst_ta. If the file does not exist, it is created. If list_name is relative, it is relative to /agent :dst_ta/tmp_dir

Parameters:

ta	Source agent name
key_name	Key name
dst_ta	Destination agent name
list_name	Key list file name

Returns:

Status code