assh/assh_key.h header reference

Description [link]

This header file contains descriptors for key management modules implemented in the library as well as SSH keys management related declarations.

See also keysalgos, coremod and assh/helper_key.h.

Header inclusion [link]

assh/assh_algo.h

Members [link]

Types [link]

struct assh_key_algo_s
struct assh_key_format_desc_s
enum assh_key_format_e
struct assh_key_s
enum assh_key_validate_result_e
typedef void (assh_key_cleanup_t)(struct assh_context_s *c, struct assh_key_s *key)
typedef assh_bool_t (assh_key_cmp_t)(struct assh_context_s *c, const struct assh_key_s *key, const struct assh_key_s *b, assh_bool_t pub)
typedef assh_status_t (assh_key_create_t)(struct assh_context_s *c, const struct assh_key_algo_s *algo, size_t bits, struct assh_key_s **key)
typedef assh_status_t (assh_key_load_t)(struct assh_context_s *c, const struct assh_key_algo_s *algo, const uint8_t **blob_, size_t blob_len, struct assh_key_s **key, enum assh_key_format_e format)
typedef assh_status_t (assh_key_output_t)(struct assh_context_s *c, const struct assh_key_s *key, uint8_t *blob, size_t *blob_len, enum assh_key_format_e format)
typedef assh_status_t (assh_key_validate_t)(struct assh_context_s *c, const struct assh_key_s *key, enum assh_key_validate_result_e *result)

Functions [link]

const struct assh_key_algo_s * assh_key_algo(const struct assh_key_s *key)
assh_status_t assh_key_algo_by_name(const struct assh_context_s *c, enum assh_algo_class_e cl, const char *name, size_t name_len, const struct assh_key_algo_s **algo)
assh_status_t assh_key_algo_enumerate_implems(struct assh_context_s *c, enum assh_algo_class_e cl, size_t *count, const struct assh_key_algo_s **table)
assh_status_t assh_key_algo_enumerate_names(struct assh_context_s *c, enum assh_algo_class_e cl, size_t *count, const struct assh_key_algo_s **table)
const enum assh_key_format_e * assh_key_algo_formats(const struct assh_key_algo_s *kya)
const char * assh_key_algo_implem(const struct assh_key_algo_s *kya)
const char * assh_key_algo_name(const struct assh_key_algo_s *kya)
size_t assh_key_bits(struct assh_key_s *key)
assh_bool_t assh_key_cmp(struct assh_context_s *c, const struct assh_key_s *key, const struct assh_key_s *b, assh_bool_t pub)
assh_status_t assh_key_create(struct assh_context_s *c, struct assh_key_s **key, size_t bits, const struct assh_key_algo_s *algo, enum assh_algo_class_e role)
void assh_key_drop(struct assh_context_s *c, struct assh_key_s **head)
void assh_key_flush(struct assh_context_s *c, struct assh_key_s **head)
const struct assh_key_format_desc_s * assh_key_format_desc(enum assh_key_format_e fmt)
const char * assh_key_get_comment(const struct assh_key_s *key)
void assh_key_insert(struct assh_key_s **head, struct assh_key_s *key)
assh_status_t assh_key_load(struct assh_context_s *c, struct assh_key_s **key, const struct assh_key_algo_s *algo, enum assh_algo_class_e role, enum assh_key_format_e format, const uint8_t **blob, size_t blob_len)
assh_status_t assh_key_lookup(struct assh_context_s *c, struct assh_key_s **key, assh_bool_t private, const struct assh_algo_with_key_s *awk)
assh_status_t assh_key_output(struct assh_context_s *c, const struct assh_key_s *key, uint8_t *blob, size_t *blob_len, enum assh_key_format_e format)
assh_bool_t assh_key_private(const struct assh_key_s *key)
void assh_key_refinc(struct assh_key_s *key)
assh_safety_t assh_key_safety(struct assh_key_s *key)
const char * assh_key_safety_name(struct assh_key_s *key)
assh_status_t assh_key_set_comment(struct assh_context_s *c, struct assh_key_s *key, const char *comment)
const char * assh_key_type_name(struct assh_key_s *key)
assh_status_t assh_key_validate(struct assh_context_s *c, const struct assh_key_s *key, enum assh_key_validate_result_e *result)

Constant [link]

const struct assh_key_algo_s assh_key_none

Macros [link]

Members detail [link]

const struct assh_key_algo_s * assh_key_algo(const struct assh_key_s *key) [link]

This function is declared in assh/assh_key.h source file, line 305.

This function returns a pointer to the key algorithm descritor associated to a key.

assh_status_t assh_key_algo_by_name(const struct assh_context_s c, enum assh_algo_class_e cl, const char name, size_t name_len, const struct assh_key_algo_s **algo) [link]

This function is declared in assh/assh_key.h source file, line 412.

This function finds a key algorithm with matching name.

assh_status_t assh_key_algo_enumerate_implems(struct assh_context_s c, enum assh_algo_class_e cl, size_t count, const struct assh_key_algo_s **table) [link]

This function is declared in assh/assh_key.h source file, line 427.

This function fills a table of pointers to key algorithms associated to the registered algorithms of the context.

The count parameter must initially indicate the maximum number of entries that can be stored in the table. It is updated with the actual number of entries stored.

This function returns ASSH_NO_DATA when there is not enough space to store all the entries.

assh_status_t assh_key_algo_enumerate_names(struct assh_context_s c, enum assh_algo_class_e cl, size_t count, const struct assh_key_algo_s **table) [link]

This function is declared in assh/assh_key.h source file, line 434.

This function is similar to the assh_key_algo_enumerate_implems function but implementations with duplicate names are filtered out.

const enum assh_key_format_e * assh_key_algo_formats(const struct assh_key_algo_s *kya) [link]

This function is declared in assh/assh_key.h source file, line 318.

This function returns a zero terminated array of pointers to key formats supported by the key algorithm.

const char * assh_key_algo_implem(const struct assh_key_algo_s *kya) [link]

This function is declared in assh/assh_key.h source file, line 313.

This function returns the implementation name of a key algorithm.

const char * assh_key_algo_name(const struct assh_key_algo_s *kya) [link]

This function is declared in assh/assh_key.h source file, line 309.

This function returns the name of a key algorithm.

struct assh_key_algo_s [link]

This struct is declared in assh/assh_key.h source file, line 177.

This struct is the key algorithm descriptor of the ssh2 key module interface.

A key algorithm is able to handle a single type of key as described in keysalgos.

Field	Description
const char * name;
const char * implem;
assh_key_load_t * f_load;
assh_key_create_t * f_create;
assh_key_output_t * f_output;
assh_key_validate_t * f_validate;
assh_key_cmp_t * f_cmp;
assh_key_cleanup_t * f_cleanup;
const enum assh_key_format_e * formats;	Supported storage formats, zero terminated. This includes container formats supported by helper functions. The preferred storage formats for private and public keys are the first and second entries respectively.
uint16_t min_bits;	minimum number of bits for assh_key_create
uint16_t bits;	suggested number of bits for assh_key_create
uint16_t max_bits;	maximuu number of bits for assh_key_create
int8_t priority;	used when we need to choose between multiple implementations of the same key management algorithm.

size_t assh_key_bits(struct assh_key_s *key) [link]

This function is declared in assh/assh_key.h source file, line 400.

This function returns the number of bits of the key.

assh_bool_t assh_key_cmp(struct assh_context_s c, const struct assh_key_s key, const struct assh_key_s *b, assh_bool_t pub) [link]

This function is declared in assh/assh_key.h source file, line 343.

This function returns true if both keys are equals. If the pub parameter is set, only the public parts of the key are taken into account.

assh_status_t assh_key_create(struct assh_context_s *c, struct assh_key_s **key, size_t bits, const struct assh_key_algo_s *algo, enum assh_algo_class_e role) [link]

This function is declared in assh/assh_key.h source file, line 289.

Preprocessor condition: defined( CONFIG_ASSH_KEY_CREATE )

This function creates a new key of specified type and bits size. A default suggested key size is used when the bits parameter is 0.

void assh_key_drop(struct assh_context_s *c, struct assh_key_s **head) [link]

This function is declared in assh/assh_key.h source file, line 349.

This function removes the first key from the singly linked list. The key is also released unless assh_key_refinc has been called.

void assh_key_flush(struct assh_context_s *c, struct assh_key_s **head) [link]

This function is declared in assh/assh_key.h source file, line 355.

This function releases all the keys on the linked list by calling assh_key_drop and set the list head to NULL.

const struct assh_key_format_desc_s * assh_key_format_desc(enum assh_key_format_e fmt) [link]

This function is declared in assh/assh_key.h source file, line 237.

This function returns a descritor for the specified key storage format.

When iterating over formats, entries with a NULL name must be ignored. The function returns NULL when fmt is beyond the last supported format.

struct assh_key_format_desc_s [link]

This struct is declared in assh/assh_key.h source file, line 212.

This struct describes a key format.

Field	Description
const char * name;	A short human readable identifier for the format.
const char * desc;	A long description string for the format.
assh_bool_t public:1;	True for public key only formats.
assh_bool_t internal:1;	True when the format is not commonly used for key storage.
assh_bool_t encrypted:1;	True when the format supports encryption.
assh_bool_t pub_part:1;	True when this contains the public part of a private format. May only be used during loading.
assh_bool_t pv_part:1;	True when this format only contains the private key data. The loading function will complete an exisiting public key.

enum assh_key_format_e [link]

This enum is declared in assh/assh_key.h source file, line 48.

This enum specifies the storage formats of ssh2 keys. Private key formats are listed first.

Identifier	Value	Description
ASSH_KEY_FMT_NONE	0
ASSH_KEY_FMT_PV_OPENSSH_V1	1	Keys openssh-key-v1 base64 format
ASSH_KEY_FMT_PV_OPENSSH_V1_BLOB	2	Keys blob openssh-key-v1 binary format
ASSH_KEY_FMT_PV_OPENSSH_V1_KEY	3	Single private key encoding used as part of the ASSH_KEY_FMT_PV_OPENSSH_V1_BLOB format.
ASSH_KEY_FMT_PV_PEM	4	Private key in rfc2440 like format. Base64 encoding of ASSH_KEY_FMT_PV_PEM_ASN1.
ASSH_KEY_FMT_PV_PEM_ASN1	5	Private key in PEM Asn1 DER format.
ASSH_KEY_FMT_PUB_RFC4716	6	Public key in standard base64 format as described in rfc4716.
ASSH_KEY_FMT_PUB_RFC4253	7	Public key in standard binary format as described in rfc4253 section 6.6.
ASSH_KEY_FMT_PUB_OPENSSH	8	Public key in legacy openssh base64 format.
ASSH_KEY_FMT_PUB_OPENSSH_V1	9	Keys openssh-key-v1 base64 format. Load public key part only
ASSH_KEY_FMT_PUB_OPENSSH_V1_BLOB	10	Keys blob openssh-key-v1 binary format, Load public key part only
ASSH_KEY_FMT_PUB_PEM	11	Public key in rfc2440 like format. Base64 encoding of ASSH_KEY_FMT_PUB_PEM_ASN1.
ASSH_KEY_FMT_PUB_PEM_ASN1	12	Public key in PEM Asn1 DER format.
ASSH_KEY_FMT_LAST	12

const char * assh_key_get_comment(const struct assh_key_s *key) [link]

This function is declared in assh/assh_key.h source file, line 300.

This function returns the key comment string or NULL.

void assh_key_insert(struct assh_key_s **head, struct assh_key_s *key) [link]

This function is declared in assh/assh_key.h source file, line 362.

This function inserts a key in the linked list.

See also assh_key_drop and assh_key_flush.

assh_status_t assh_key_load(struct assh_context_s *c, struct assh_key_s **key, const struct assh_key_algo_s *algo, enum assh_algo_class_e role, enum assh_key_format_e format, const uint8_t **blob, size_t blob_len) [link]

This function is declared in assh/assh_key.h source file, line 280.

This function allocates and intiailizes the key structure from the passed key blob data. The blob pointer is updated so that the key blob is skipped.

This function will only support some binary key formats specific to a given key algorithm. More formats are handled by helper functions provided by assh/helper_key.h

assh_status_t assh_key_lookup(struct assh_context_s *c, struct assh_key_s **key, assh_bool_t private, const struct assh_algo_with_key_s *awk) [link]

This function is declared in assh/assh_key.h source file, line 382.

This function looks for a key usable with the given algorithm among keys registered on the context.

const struct assh_key_algo_s assh_key_none [link]

This constant is declared in assh/assh_key.h source file, line 437.

Dummy key algorithm

assh_status_t assh_key_output(struct assh_context_s c, const struct assh_key_s key, uint8_t blob, size_t blob_len, enum assh_key_format_e format) [link]

This function is declared in assh/assh_key.h source file, line 336.

This function writes the key in blob representation to the blob buffer.

If the blob parameter is NULL, the function updates the blob_len parmeter with a size value which is equal or slightly greater to what is needed to actually store the blob. In the other case, the size of the available buffer must be passed and the function updates it with the actual number of bytes written.

This function will only support some binary key formats specific to a given key algorithm. More formats are handled by helper functions provided by assh/helper_key.h

assh_bool_t assh_key_private(const struct assh_key_s *key) [link]

This function is declared in assh/assh_key.h source file, line 386.

This function returns 1 if the object contains a private key.

void assh_key_refinc(struct assh_key_s *key) [link]

This function is declared in assh/assh_key.h source file, line 367.

This function increases the reference counter of the key so that it is not released by the next call to assh_key_drop.

struct assh_key_s [link]

This struct is declared in assh/assh_key.h source file, line 242.

This struct is the generic ssh2 key structure. Actual key structures inherit from this type.

Field	Description
const char * type;
char * comment;
struct assh_key_s * next;	Next key in the list
const struct assh_key_algo_s * algo;	Key algorithm
uint32_t ref_count;
uint16_t bits;
enum assh_algo_class_e role:3;	Class of algorithm the key is intended to be used with
assh_bool_t private:1;
assh_bool_t stored:1;
assh_safety_t safety:8;

assh_safety_t assh_key_safety(struct assh_key_s *key) [link]

This function is declared in assh/assh_key.h source file, line 395.

This function returns the estimated algorithmic safety of the key.

const char * assh_key_safety_name(struct assh_key_s *key) [link]

This function is declared in assh/assh_key.h source file, line 404.

This function combines assh_safety_name and assh_key_safety.

assh_status_t assh_key_set_comment(struct assh_context_s c, struct assh_key_s key, const char *comment) [link]

This function is declared in assh/assh_key.h source file, line 296.

This function changes the key comment string.

const char * assh_key_type_name(struct assh_key_s *key) [link]

This function is declared in assh/assh_key.h source file, line 390.

This function returns the type name of the key.

assh_status_t assh_key_validate(struct assh_context_s c, const struct assh_key_s key, enum assh_key_validate_result_e *result) [link]

This function is declared in assh/assh_key.h source file, line 374.

Preprocessor condition: defined( CONFIG_ASSH_KEY_VALIDATE )

This function checks the validity of the key.

enum assh_key_validate_result_e [link]

This enum is declared in assh/assh_key.h source file, line 113.

Preprocessor condition: defined( CONFIG_ASSH_KEY_VALIDATE )

This enum specifies the possible results of key validation.

Identifier	Value	Description
ASSH_KEY_BAD	-2	Something is wrong with the key.
ASSH_KEY_NOT_SUPPORTED	-1	The key may not be bad but some of its parameters have unusual values which make this key not supported by the implementation.
ASSH_KEY_NOT_CHECKED	2	Checking this type of key is not supported yet or there is no way to check this type of public key due to the algorithm design.
ASSH_KEY_PARTIALLY_CHECKED	3	Some checks have been performed but there is no way to fully validate this type of public key due to the algorithm design.
ASSH_KEY_GOOD	4	The key has passed a full validation check.

#define ASSH_KEY_CLEANUP_FCN(n) [link]

This macro is for internal use only.

This macro is declared in assh/assh_key.h source file, line 161.

This macro expands to:

 void (n)                                
  (struct assh_context_s *c,                                            
   struct assh_key_s *key)

#define ASSH_KEY_CMP_FCN(n) [link]

This macro is for internal use only.

This macro is declared in assh/assh_key.h source file, line 151.

This macro expands to:

 ASSH_WARN_UNUSED_RESULT assh_bool_t (n)     
  (struct assh_context_s *c,                                            
   const struct assh_key_s *key,                                        
   const struct assh_key_s *b, assh_bool_t pub)

#define ASSH_KEY_CREATE_FCN(n) [link]

This macro is for internal use only.

This macro is declared in assh/assh_key.h source file, line 99.

Preprocessor condition: defined( CONFIG_ASSH_KEY_CREATE )

This macro expands to:

 ASSH_WARN_UNUSED_RESULT assh_status_t (n) 
  (struct assh_context_s *c,                                            
   const struct assh_key_algo_s *algo,                                  
   size_t bits, struct assh_key_s **key)

#define ASSH_KEY_LOAD_FCN(n) [link]

This macro is for internal use only.

This macro is declared in assh/assh_key.h source file, line 86.

This macro expands to:

 ASSH_WARN_UNUSED_RESULT assh_status_t (n)   
  (struct assh_context_s *c,                                            
   const struct assh_key_algo_s *algo,                                   
   const uint8_t **blob_, size_t blob_len,                              
   struct assh_key_s **key,                                             
   enum assh_key_format_e format)

#define ASSH_KEY_OUTPUT_FCN(n) [link]

This macro is for internal use only.

This macro is declared in assh/assh_key.h source file, line 140.

This macro expands to:

 ASSH_WARN_UNUSED_RESULT assh_status_t (n) 
  (struct assh_context_s *c,                                            
   const struct assh_key_s *key,                                        
   uint8_t *blob, size_t *blob_len,                                     
   enum assh_key_format_e format)

#define ASSH_KEY_VALIDATE_FCN(n) [link]

This macro is for internal use only.

This macro is declared in assh/assh_key.h source file, line 129.

Preprocessor condition: defined( CONFIG_ASSH_KEY_VALIDATE )

This macro expands to:

 ASSH_WARN_UNUSED_RESULT assh_status_t (n) 
  (struct assh_context_s *c,                                            
   const struct assh_key_s *key,                                        
   enum assh_key_validate_result_e *result)