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] 

Members [link] 

Types [link] 

Functions [link] 

Variable [link] 

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.

See also assh_algo_table.

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.

IdentifierValueDescription
ASSH_ALGO_KEX0Identify the Key-exchange class of algorithms.
ASSH_ALGO_SIGN1Identify the signature class of algorithms.
ASSH_ALGO_CIPHER2Identify the cipher class of algorithms.
ASSH_ALGO_MAC3Identify the message authentication class of algorithms.
ASSH_ALGO_COMPRESS4Identify the compression class of algorithms.
ASSH_ALGO_ANY5For 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.

See also struct assh_algo_s.

FieldDescription
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.

See also assh_algo_register_default, assh_algo_register_va, assh_algo_register_names_va and algoreg.

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.

FieldDescription
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.

See also assh_algo_register.

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.

See also assh_safety_name.

IdentifierValueDescription
ASSH_SAFETY_BROKEN0Safety in range [0 - 19] is broken
ASSH_SAFETY_WEAK20Safety in range [20 - 25] is weak
ASSH_SAFETY_MEDIUM26Safety in range [26 - 49] is medium
ASSH_SAFETY_STRONG50Safety in range [50 - 99] is strong

See also assh_safety_t.

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.

IdentifierValueDescription
ASSH_ALGO_STD_IETF0x01The algorithm is specified in an approved IETF standard.
ASSH_ALGO_STD_DRAFT0x02The algorithm is specified in an IETF draft document.
ASSH_ALGO_STD_PRIVATE0x04The algorithm is private and specified as an extension of some ssh implementations.
ASSH_ALGO_ASSH0x08The algorithm is private and specified as an extension of assh.
ASSH_ALGO_COMMON0x10The algorithm is common under this name.
ASSH_ALGO_OLDNAME0x20The 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].

See also enum assh_algo_safety_e.

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" }

See also enum assh_algo_class_e.

#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)

See also assh_algo_suitable_key_t.

#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)

See also assh_algo_register_va.

assh_status_t assh_algo_check_table(struct assh_context_s *c) [link] 

This function is for internal use only.

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

This function checks that the list of registered algorithms is valid for use by a session.

void assh_algo_filter_variants(struct assh_context_s *c) [link] 

This function is for internal use only.

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

void assh_algo_kex_init_size(struct assh_context_s *c) [link] 

This function is for internal use only.

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

This function computes the size of the SSH_MSG_KEXINIT packet based on the current list of registered algorithms.

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) [link] 

This function is for internal use only.

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

void assh_algo_sort(struct assh_context_s *c) [link] 

This function is for internal use only.

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

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) [link] 

This function is for internal use only.

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

This function returns true if the provided key can be used with the algorithm and has been loaded or created for that purpose. When the key parameter is NULL, the return value indicates if the algorithm needs a key when used during a key exchange.

This does not check the validity of the key, the assh_key_validate function is provided for that purpose.

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) [link] 

This typedef is for internal use only.

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

This declaration involves expansion of the ASSH_ALGO_SUITABLE_KEY_FCN macro.

This typedef defines the function type for the key compatibility checking operation common to all the algorithm module interfaces.

See also assh_algo_suitable_key.

struct assh_algo_with_key_s [link] 

This struct is for internal use only.

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

This struct extends the struct assh_algo_s algorithm descriptor structure for algorithms that may requires an struct assh_key_s object to work. This are ASSH_ALGO_KEX and ASSH_ALGO_SIGN algorithms.

See also assh_algo_with_key.

FieldDescription
struct assh_algo_s algo;
const struct assh_key_algo_s * key_algo;Pointer to associated key operations, may be NULL.
assh_algo_suitable_key_t * f_suitable_key; Test if a key can be used with the algorithm, may be NULL.
Valid XHTML 1.0 StrictGenerated by diaxen on Sun Oct 25 23:31:03 2020 using MkDoc