assh/assh_algo.h header reference

Description [link]

This header file contains the declaration of the algorithm base module interface common to all five types of algorithms used by ssh2. It also provides functions to register algorithms on an struct assh_context_s object.

See also suppalgos, coremod, assh/assh_kex.h, assh/assh_sign.h, assh/assh_cipher.h, assh/assh_mac.h and assh/assh_compress.h.

Header inclusion [link]

assh/assh.h

Members [link]

Types [link]

enum assh_algo_class_e
typedef [...] assh_algo_id_t
struct assh_algo_name_s
struct assh_algo_s
enum assh_algo_safety_e
enum assh_algo_spec_e
typedef [...] assh_safety_t
typedef [...] assh_speed_t
typedef assh_bool_t (assh_algo_suitable_key_t)(struct assh_context_s *c, const struct assh_algo_with_key_s *awk, const struct assh_key_s *key)
struct assh_algo_with_key_s

Functions [link]

assh_status_t assh_algo_by_key(struct assh_context_s *c, const struct assh_key_s *key, assh_algo_id_t *pos, const struct assh_algo_with_key_s **awk)
assh_status_t assh_algo_by_name(struct assh_context_s *c, enum assh_algo_class_e class_, const char *name, size_t name_len, const struct assh_algo_s **algo, const struct assh_algo_name_s **namep)
assh_status_t assh_algo_by_name_static(const struct assh_algo_s **table, enum assh_algo_class_e class_, const char *name, size_t name_len, const struct assh_algo_s **algo, const struct assh_algo_name_s **namep)
const char * assh_algo_implem(const struct assh_algo_s *algo)
const char * assh_algo_name(const struct assh_algo_s *algo)
assh_status_t assh_algo_register(struct assh_context_s *c, assh_safety_t min_safety, const struct assh_algo_s *table[])
assh_status_t assh_algo_register_default(struct assh_context_s *c, assh_safety_t min_safety)
assh_status_t assh_algo_register_names_va(struct assh_context_s *c, assh_safety_t min_safety, enum assh_algo_class_e class_, ...)
assh_status_t assh_algo_register_static(struct assh_context_s *c, const struct assh_algo_s *table[])
assh_status_t assh_algo_register_va(struct assh_context_s *c, assh_safety_t min_safety, ...)
const struct assh_algo_s * assh_algo_registered(struct assh_context_s *c, assh_algo_id_t i)
assh_safety_t assh_algo_safety(const struct assh_algo_s *algo)
const char * assh_algo_safety_name(const struct assh_algo_s *algo)
assh_status_t assh_algo_unregister(struct assh_context_s *c)
const char * assh_algo_variant(const struct assh_algo_s *algo)
const struct assh_algo_with_key_s * assh_algo_with_key(const struct assh_algo_s *algo)
const char * assh_safety_name(assh_safety_t safety)
assh_status_t assh_algo_check_table(struct assh_context_s *c)
void assh_algo_filter_variants(struct assh_context_s *c)
void assh_algo_kex_init_size(struct assh_context_s *c)
const struct assh_algo_name_s * assh_algo_name_match(const struct assh_algo_s *a, enum assh_algo_class_e class_, const char *name, size_t name_len)
void assh_algo_sort(struct assh_context_s *c)
assh_bool_t assh_algo_suitable_key(struct assh_context_s *c, const struct assh_algo_with_key_s *awk, const struct assh_key_s *key)

Variable [link]

const struct assh_algo_s * assh_algo_table[]

Macros [link]

Members detail [link]

assh_status_t assh_algo_by_key(struct assh_context_s c, const struct assh_key_s key, assh_algo_id_t *pos, const struct assh_algo_with_key_s **awk) [link]

This function is declared in assh/assh_algo.h source file, line 405.

This function finds a registered algorithm which can be used with the given key. If the pos parameter is not NULL, it specifies the starting index of the search and it will be updated with the index of the matching entry.

assh_status_t assh_algo_by_name(struct assh_context_s c, enum assh_algo_class_e class_, const char name, size_t name_len, const struct assh_algo_s algo, const struct assh_algo_name_s namep) [link]

This function is declared in assh/assh_algo.h source file, line 396.

This function finds a registered algorithm with matching class and name. If the namep parameter is not NULL, the matched algorithm name is returned.

assh_status_t assh_algo_by_name_static(const struct assh_algo_s **table, enum assh_algo_class_e class_, const char *name, size_t name_len, const struct assh_algo_s algo, const struct assh_algo_name_s namep) [link]

This function is declared in assh/assh_algo.h source file, line 381.

This function finds an algorithm with matching class and name in a NULL terminated array of pointers to algorithm descriptors.

enum assh_algo_class_e [link]

This enum is declared in assh/assh_algo.h source file, line 98.

This enum specifies the classes of ssh2 algorithms.

Identifier	Value	Description
ASSH_ALGO_KEX	0	Identify the Key-exchange class of algorithms.
ASSH_ALGO_SIGN	1	Identify the signature class of algorithms.
ASSH_ALGO_CIPHER	2	Identify the cipher class of algorithms.
ASSH_ALGO_MAC	3	Identify the message authentication class of algorithms.
ASSH_ALGO_COMPRESS	4	Identify the compression class of algorithms.
ASSH_ALGO_ANY	5	For use as a class wildcard where relevant.

typedef uint_fast16_t assh_algo_id_t [link]

This typedef is declared in assh/assh_algo.h source file, line 48.

This typedef is used as algorithm index.

const char * assh_algo_implem(const struct assh_algo_s *algo) [link]

This function is declared in assh/assh_algo.h source file, line 359.

This function returns the name of the algorithm implementationvariant from its descriptor.

const char * assh_algo_name(const struct assh_algo_s *algo) [link]

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

This function returns the algorithm default name from its descriptor.

struct assh_algo_name_s [link]

This struct is declared in assh/assh_algo.h source file, line 139.

Field	Description
enum assh_algo_spec_e spec:8;	Specification status flags
const char * name;	Algorithm name

assh_status_t assh_algo_register(struct assh_context_s c, assh_safety_t min_safety, const struct assh_algo_s table[]) [link]

This function is declared in assh/assh_algo.h source file, line 287.

This function registers the specified array of algorithms for use by the given library context. The last entry must be NULL.

The array is copied and the algorithms are sorted depending on their safety factor and speed factor. The order can be modified thanks to the assh_kex_set_order function. Algorithms with a safety factor less than min_safety are discarded.

If this function is called more than once, the internal array of algorithms is resized and new algorithms are appended.

When multiple implementations of the same algorithm are in conflict, the variant with the highest score is retained.

It is not possible to modify the list of registered algorithms when some sessions are associated to the context. The assh_session_algo_filter function can still be used to setup a per session algorithm filter for the key-exchange.

assh_status_t assh_algo_register_default(struct assh_context_s *c, assh_safety_t min_safety) [link]

This function is declared in assh/assh_algo.h source file, line 335.

This function registers the default set of available algorithms depending on the library configuration. It relies on the assh_algo_register function.

See also algoreg.

assh_status_t assh_algo_register_names_va(struct assh_context_s *c, assh_safety_t min_safety, enum assh_algo_class_e class_, ...) [link]

This function is declared in assh/assh_algo.h source file, line 257.

This function registers the algorithms specified as a list of names. The last entry must be NULL.

It needs to be called more than once to register different classes of algorithms. It reports a success when at least one of the designated algorithms has been registered successfully.

The function beahves like the assh_algo_register function.

See also algoreg.

assh_status_t assh_algo_register_static(struct assh_context_s c, const struct assh_algo_s table[]) [link]

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

This function registers the specified array of algorithms for use by the given library context. The last entry must be NULL. The array is not copied and must remain valid. No memory allocation is performed by the library. The array of algorithms is replaced on every call.

In order to initialize some struct assh_session_s objects associated to the context, the provided table of algorithms must be sorted in ascending class order and all classes must be represented.

Once this function has been called, it is not possible to register more algorithms by calling assh_algo_register without first calling assh_algo_unregister.

It is not possible to modify registered algorithms when some sessions are associated to the context. The assh_session_algo_filter function can still be used to setup a per session algorithm filter for the key-exchange.

See also algoreg.

assh_status_t assh_algo_register_va(struct assh_context_s *c, assh_safety_t min_safety, ...) [link]

This function is declared in assh/assh_algo.h source file, line 240.

This function registers the algorithms specified as a list of pointers to struct assh_algo_s objects. The last entry must be NULL.

The function beahves like the assh_algo_register function.

See also algoreg.

const struct assh_algo_s * assh_algo_registered(struct assh_context_s *c, assh_algo_id_t i) [link]

This function is declared in assh/assh_algo.h source file, line 324.

This function returns a pointer to the descriptor of the registered algorithm at specified index. The first valid index is 0. NULL is returned when out of range.

struct assh_algo_s [link]

This struct is declared in assh/assh_algo.h source file, line 184.

This struct is the generic algorithm descriptor structure.

Descriptor structures for specific algorithm types inherit from this structure. This means that algorithm descriptors have this structure as first field.

See also coremod, struct assh_algo_cipher_s, struct assh_algo_mac_s, struct assh_algo_sign_s, struct assh_algo_kex_s and struct assh_algo_compress_s.

Field	Description
uint8_t api;	module API version
enum assh_algo_class_e class_:3;	Class of algorithm
uint8_t priority:5;	used to choose between entries with the same name
uint8_t speed:8;	speed factor in range [0, 255]
uint8_t safety:7;	safety factor in range [0, 99]
uint8_t nondeterministic:1;	Must be set when a different implementation may yield a different result due to use of random data.
const struct assh_algo_name_s * names;	List of SSH algorithm identifiers, used during key exchange
const char * variant;	Variant description string.
const char * implem;	Implementation identification string. Format is vendor-library.

assh_safety_t assh_algo_safety(const struct assh_algo_s *algo) [link]

This function is declared in assh/assh_algo.h source file, line 365.

This function returns the estimated algorithm safety factor value from its descriptor.

enum assh_algo_safety_e [link]

This enum is declared in assh/assh_algo.h source file, line 53.

This enum is used to estimate algorithms and keys safety.

Identifier	Value	Description
ASSH_SAFETY_BROKEN	0	Safety in range [0 - 19] is broken
ASSH_SAFETY_WEAK	20	Safety in range [20 - 25] is weak
ASSH_SAFETY_MEDIUM	26	Safety in range [26 - 49] is medium
ASSH_SAFETY_STRONG	50	Safety in range [50 - 99] is strong

const char * assh_algo_safety_name(const struct assh_algo_s *algo) [link]

This function is declared in assh/assh_algo.h source file, line 370.

enum assh_algo_spec_e [link]

This enum is declared in assh/assh_algo.h source file, line 120.

This enum specifies various algorithms specification status. Values can be ored together.

Identifier	Value	Description
ASSH_ALGO_STD_IETF	0x01	The algorithm is specified in an approved IETF standard.
ASSH_ALGO_STD_DRAFT	0x02	The algorithm is specified in an IETF draft document.
ASSH_ALGO_STD_PRIVATE	0x04	The algorithm is private and specified as an extension of some ssh implementations.
ASSH_ALGO_ASSH	0x08	The algorithm is private and specified as an extension of assh.
ASSH_ALGO_COMMON	0x10	The algorithm is common under this name.
ASSH_ALGO_OLDNAME	0x20	The algorithm is private under this name but is now available under a different name specified as an approved IETF standard.

const struct assh_algo_s * assh_algo_table[] [link]

This constant is declared in assh/assh_algo.h source file, line 318.

This is a NULL terminated array of descriptors for algorithm provided by the library. Multiple variants of the same algorithm may exist.

assh_status_t assh_algo_unregister(struct assh_context_s *c) [link]

This function is declared in assh/assh_algo.h source file, line 346.

Unregister all algorithms.

It is not possible to modify registered algorithms when some sessions are associated to the context.

const char * assh_algo_variant(const struct assh_algo_s *algo) [link]

This function is declared in assh/assh_algo.h source file, line 354.

This function returns the name of the algorithm variant from its descriptor.

const struct assh_algo_with_key_s * assh_algo_with_key(const struct assh_algo_s *algo) [link]

This function is declared in assh/assh_algo.h source file, line 424.

This function casts and returns the passed pointer if the algorithm class is ASSH_ALGO_KEX or ASSH_ALGO_SIGN. In other cases, NULL is returned.

const char * assh_safety_name(assh_safety_t safety) [link]

This function is declared in assh/assh_algo.h source file, line 74.

This function returns the name associated to an algorithm safety factor value.

typedef enum assh_algo_safety_e assh_safety_t [link]

This typedef is declared in assh/assh_algo.h source file, line 66.

A safety factor in the range [0-99].

typedef uint_fast8_t assh_speed_t [link]

This typedef is declared in assh/assh_algo.h source file, line 68.

#define ASSH_ALGO_BASE(class__, implem_, safety_, speed_, ...) [link]

This macro is for internal use only.

This macro is declared in assh/assh_algo.h source file, line 159.

This macro initializes the fields of the struct assh_algo_s structure

This macro expands to:

  .algo = {                                                             
    .class_ = ASSH_ALGO_##class__,                                      
    .api = ASSH_ALGO_API_VERSION,                                       
    .safety = safety_,                                                  
    .speed = speed_,                                                    
    .implem = implem_,                                                  
    __VA_ARGS__                                                         
  }

#define ASSH_ALGO_CLASS_NAMES [link]

This macro is for internal use only.

This macro is declared in assh/assh_algo.h source file, line 113.

This macro expands to:

{ "KEX", "SIGN", "CIPHER", "MAC", "COMPRESS", "ANY" }

#define ASSH_ALGO_SUITABLE_KEY_FCN(n) [link]

This macro is for internal use only.

This macro is declared in assh/assh_algo.h source file, line 85.

This macro expands to:

 assh_bool_t (n)    
  (struct assh_context_s *c,                             
   const struct assh_algo_with_key_s *awk,                 
   const struct assh_key_s *key)

#define ASSH_SAFETY_PRIMEFIELD(n) [link]

This macro is for internal use only.

This macro is declared in assh/assh_algo.h source file, line 171.

map prime field size to assh safety factor, See doc/dh

This macro expands to:

((n) / 128 + 12)