assh/assh_algo.h header reference
Description
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 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
Members
Types
- 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)(assh_context_s *c, const assh_algo_with_key_s *awk, const assh_key_s *key)
- struct assh_algo_with_key_s
Functions
- assh_status_t assh_algo_by_key(assh_context_s *c, const assh_key_s *key, assh_algo_id_t *pos, const assh_algo_with_key_s **awk)
- assh_status_t assh_algo_by_name(assh_context_s *c, assh_algo_class_e class_, const char *name, size_t name_len, const assh_algo_s **algo, const assh_algo_name_s **namep)
- assh_status_t assh_algo_by_name_static(const assh_algo_s **table, assh_algo_class_e class_, const char *name, size_t name_len, const assh_algo_s **algo, const assh_algo_name_s **namep)
- const char * assh_algo_implem(const assh_algo_s *algo)
- const char * assh_algo_name(const assh_algo_s *algo)
- assh_status_t assh_algo_register(assh_context_s *c, assh_safety_t min_safety, const assh_algo_s *table[])
- assh_status_t assh_algo_register_default(assh_context_s *c, assh_safety_t min_safety)
- assh_status_t assh_algo_register_names_va(assh_context_s *c, assh_safety_t min_safety, assh_algo_class_e class_, ...)
- assh_status_t assh_algo_register_static(assh_context_s *c, const assh_algo_s *table[])
- assh_status_t assh_algo_register_va(assh_context_s *c, assh_safety_t min_safety, ...)
- const assh_algo_s * assh_algo_registered(assh_context_s *c, assh_algo_id_t i)
- assh_safety_t assh_algo_safety(const assh_algo_s *algo)
- const char * assh_algo_safety_name(const assh_algo_s *algo)
- assh_status_t assh_algo_unregister(assh_context_s *c)
- const char * assh_algo_variant(const assh_algo_s *algo)
- const assh_algo_with_key_s * assh_algo_with_key(const assh_algo_s *algo)
- const char * assh_safety_name(assh_safety_t safety)
- assh_status_t assh_algo_check_table(assh_context_s *c)
- void assh_algo_filter_variants(assh_context_s *c)
- void assh_algo_kex_init_size(assh_context_s *c)
- const assh_algo_name_s * assh_algo_name_match(const assh_algo_s *a, assh_algo_class_e class_, const char *name, size_t name_len)
- void assh_algo_sort(assh_context_s *c)
- assh_bool_t assh_algo_suitable_key(assh_context_s *c, const assh_algo_with_key_s *awk, const assh_key_s *key)
Variable
- const assh_algo_s * assh_algo_table[]
Macros
Members detail
assh_status_t assh_algo_by_key(assh_context_s *c, const assh_key_s *key, assh_algo_id_t *pos, const assh_algo_with_key_s **awk)
This function is declared in assh/assh_algo.h source file, line 406.
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(assh_context_s *c, assh_algo_class_e class_, const char *name, size_t name_len, const assh_algo_s **algo, const assh_algo_name_s **namep)
This function is declared in assh/assh_algo.h source file, line 397.
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 assh_algo_s **table, assh_algo_class_e class_, const char *name, size_t name_len, const assh_algo_s **algo, const assh_algo_name_s **namep)
This function is declared in assh/assh_algo.h source file, line 382.
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.
This enum is declared in assh/assh_algo.h source file, line 98.
This enum specifies classes for SSH algorithms.
Identifier | Value | Description |
---|---|---|
ASSH_ALGO_KEX | 0 | |
ASSH_ALGO_SIGN | 1 | |
ASSH_ALGO_CIPHER | 2 | |
ASSH_ALGO_MAC | 3 | |
ASSH_ALGO_COMPRESS | 4 | |
ASSH_ALGO_ANY | 5 |
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 assh_algo_s *algo)
This function is declared in assh/assh_algo.h source file, line 360.
This function returns the name of the algorithm implementationvariant from its descriptor.
const char * assh_algo_name(const assh_algo_s *algo)
This function is declared in assh/assh_algo.h source file, line 350.
This function returns the algorithm default name from its descriptor.
This struct is declared in assh/assh_algo.h source file, line 133.
See also assh_algo_s.
Field | Description |
---|---|
assh_algo_spec_e spec:8; | Specification status flags |
const char * name; | Algorithm name |
assh_status_t assh_algo_register(assh_context_s *c, assh_safety_t min_safety, const assh_algo_s *table[])
This function is declared in assh/assh_algo.h source file, line 288.
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. Algorithms with a safety factor less than min_safety are discarded.
When multiple implementations of the same algorithm are in conflict, the variant with the highest score is retained.
See also assh_algo_register_default and algoreg.
assh_status_t assh_algo_register_default(assh_context_s *c, assh_safety_t min_safety)
This function is declared in assh/assh_algo.h source file, line 337.
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(assh_context_s *c, assh_safety_t min_safety, assh_algo_class_e class_, ...)
This function is declared in assh/assh_algo.h source file, line 269.
This function registers the algorithms with the given names for specified class for use the given library context. The last entry must be NULL.
This function needs to be called more than once to register different classes of algorithms.
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.
The function is successful when at least one of the designated algorithms has been registered successfully.
See also assh_algo_register_va, assh_algo_register_default, assh_algo_register and algoreg.
assh_status_t assh_algo_register_static(assh_context_s *c, const assh_algo_s *table[])
This function is declared in assh/assh_algo.h source file, line 315.
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.
In order to initialize some assh_session_s objects associated to the context, the table of algorithms must be sorted in ascending class order and all classes must be represented.
If this function is called more than once, the array of algorithms is replaced.
When 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(assh_context_s *c, assh_safety_t min_safety, ...)
This function is declared in assh/assh_algo.h source file, line 243.
This function registers the specified array of algorithms for use by the given library context. The last entry must be NULL.
If this function is called more than once, the internal array of algorithms is resized and new algorithms are appended.
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_names_va, assh_algo_register_default, assh_algo_register and algoreg.
const assh_algo_s * assh_algo_registered(assh_context_s *c, assh_algo_id_t i)
This function is declared in assh/assh_algo.h source file, line 326.
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.
This struct is declared in assh/assh_algo.h source file, line 178.
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, assh_algo_cipher_s, assh_algo_mac_s, assh_algo_sign_s, assh_algo_kex_s and assh_algo_compress_s.
Field | Description |
---|---|
uint8_t api; | module API version |
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 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 assh_algo_s *algo)
This function is declared in assh/assh_algo.h source file, line 366.
This function returns the estimated algorithm safety factor value from its descriptor.
See also assh_algo_register.
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.
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 |
See also assh_safety_t.
const char * assh_algo_safety_name(const assh_algo_s *algo)
This function is declared in assh/assh_algo.h source file, line 371.
This enum is declared in assh/assh_algo.h source file, line 114.
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 assh_algo_s * assh_algo_table[]
This constant is declared in assh/assh_algo.h source file, line 320.
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(assh_context_s *c)
This function is declared in assh/assh_algo.h source file, line 347.
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 assh_algo_s *algo)
This function is declared in assh/assh_algo.h source file, line 355.
This function returns the name of the algorithm variant from its descriptor.
const assh_algo_with_key_s * assh_algo_with_key(const assh_algo_s *algo)
This function is declared in assh/assh_algo.h source file, line 425.
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)
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 assh_algo_safety_e assh_safety_t
This typedef is declared in assh/assh_algo.h source file, line 66.
A safety factor in the range [0-99].
See also assh_algo_safety_e.
This typedef is declared in assh/assh_algo.h source file, line 68.
This macro is for internal use only.
This macro is declared in assh/assh_algo.h source file, line 153.
This macro initializes the fields of the 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__
}
This macro is for internal use only.
This macro is declared in assh/assh_algo.h source file, line 107.
This macro expands to:
{ "KEX", "SIGN", "CIPHER", "MAC", "COMPRESS", "ANY" }
See also assh_algo_class_e.
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.
This macro is for internal use only.
This macro is declared in assh/assh_algo.h source file, line 165.
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(assh_context_s *c)
This function is for internal use only.
This function is declared in assh/assh_algo.h source file, line 439.
This function checks that the list of registered algorithms is valid for use by a session.
void assh_algo_filter_variants(assh_context_s *c)
This function is for internal use only.
This function is declared in assh/assh_algo.h source file, line 443.
void assh_algo_kex_init_size(assh_context_s *c)
This function is for internal use only.
This function is declared in assh/assh_algo.h source file, line 451.
This function computes the size of the SSH_MSG_KEXINIT packet based on the current list of registered algorithms.
const assh_algo_name_s * assh_algo_name_match(const assh_algo_s *a, assh_algo_class_e class_, const char *name, size_t name_len)
This function is for internal use only.
This function is declared in assh/assh_algo.h source file, line 388.
void assh_algo_sort(assh_context_s *c)
This function is for internal use only.
This function is declared in assh/assh_algo.h source file, line 447.
assh_bool_t assh_algo_suitable_key(assh_context_s *c, const assh_algo_with_key_s *awk, const assh_key_s *key)
This function is for internal use only.
This function is declared in assh/assh_algo.h source file, line 418.
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)(assh_context_s *c, const assh_algo_with_key_s *awk, const assh_key_s *key)
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.
This struct is for internal use only.
This struct is declared in assh/assh_algo.h source file, line 211.
This struct extends the assh_algo_s algorithm descriptor structure for algorithms that may requires an assh_key_s object to work. This are ASSH_ALGO_KEX and ASSH_ALGO_SIGN algorithms.
See also assh_algo_with_key.
Field | Description |
---|---|
assh_algo_s algo; | |
const 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. |