assh/assh_kex.h header reference
Description [link]
This header file contains API descriptors for key-exchange algorithm modules implemented in the library.
It also contains declaration of key-exchange related events.It also provides some helper functions to compute the exchange-hash and deals with the host key signature.
The key exchange process involve several functions calls performed in the following order:
The assh_kex_send_init and assh_kex_got_init function are called by the transport layer code.
The assh_kex_init_t function of the pluggable algorithm module is called from assh_kex_got_init.
The assh_kex_process_t function of the module is called multiple times so that the module key-exchange FSM code can execute. It may return events.
The assh_kex_new_keys function must be called once from the assh_kex_process_t function when the shared secret is available.
The assh_kex_end function must be called once from the assh_kex_process_t function when the key exchange is over. This calls the assh_kex_cleanup_t function and a SSH_MSG_NEWKEYS packet is sent.
The server host key must be verified during the key exchange by using the pluggable signature algorithm given in assh_session_s::host_sign_algo.
See also kexalgos and coremod.
Header inclusion [link]
Members [link]
Types [link]
- struct assh_algo_kex_s
- struct assh_event_kex_done_s
- struct assh_event_kex_hostkey_lookup_s
- union assh_event_kex_u
- struct assh_kex_keys_s
- typedef void (assh_kex_cleanup_t)(struct assh_session_s *s)
- typedef assh_status_t (assh_kex_init_t)(struct assh_session_s *s, size_t cipher_key_size)
- typedef assh_status_t (assh_kex_process_t)(struct assh_session_s *s, struct assh_packet_s *p, struct assh_event_s *e)
Functions [link]
- const struct assh_algo_kex_s * assh_algo_kex(const struct assh_algo_s *algo)
- assh_status_t assh_algo_kex_by_key(struct assh_context_s *c, const struct assh_key_s *key, assh_algo_id_t *pos, const struct assh_algo_kex_s **ka)
- assh_status_t assh_algo_kex_by_name(struct assh_context_s *c, const char *name, size_t name_len, const struct assh_algo_kex_s **ka, const struct assh_algo_name_s **namep)
- assh_status_t assh_algo_kex_by_name_static(const struct assh_algo_s **table, const char *name, size_t name_len, const struct assh_algo_kex_s **ka, const struct assh_algo_name_s **namep)
- assh_status_t assh_kex_set_order(struct assh_context_s *c, uint_fast8_t safety_weight)
- assh_status_t assh_kex_set_threshold(struct assh_session_s *s, uint32_t bytes)
- assh_status_t assh_kex_client_get_key(struct assh_session_s *s, const uint8_t *ks_str, struct assh_event_s *e, assh_status_t (*done)(struct ::assh_session_s *,const struct ::assh_event_s *,enum ::assh_status_e) , void *pv)
- assh_status_t assh_kex_client_hash1(struct assh_session_s *s, struct assh_hash_ctx_s *hash_ctx, const uint8_t *k_str)
- assh_status_t assh_kex_client_hash2(struct assh_session_s *s, struct assh_hash_ctx_s *hash_ctx, const uint8_t *secret_str, const uint8_t *h_str)
- void assh_kex_done(struct assh_session_s *s, struct assh_event_s *e)
- assh_status_t assh_kex_end(struct assh_session_s *s, assh_bool_t accept)
- assh_status_t assh_kex_got_init(struct assh_session_s *s, struct assh_packet_s *p)
- void assh_kex_keys_cleanup(struct assh_session_s *s, struct assh_kex_keys_s *keys)
- void assh_kex_lower_safety(struct assh_session_s *s, assh_safety_t safety)
- assh_status_t assh_kex_new_keys(struct assh_session_s *s, const struct assh_hash_algo_s *hash_algo, const uint8_t *ex_hash, const uint8_t *secret_str)
- assh_status_t assh_kex_send_init(struct assh_session_s *s)
- assh_status_t assh_kex_server_hash1(struct assh_session_s *s, size_t kex_len, struct assh_hash_ctx_s *hash_ctx, struct assh_packet_s **pout, size_t *sign_len, struct assh_key_s **host_key, enum assh_ssh_msg_e msg)
- assh_status_t assh_kex_server_hash2(struct assh_session_s *s, struct assh_hash_ctx_s *hash_ctx, struct assh_packet_s *pout, size_t sign_len, const struct assh_key_s *host_key, const uint8_t *secret_str)
Constants [link]
- const struct assh_algo_kex_s assh_kex_none
- const struct assh_kex_keys_s assh_keys_none
Macros [link]
Members detail [link]
const struct assh_algo_kex_s * assh_algo_kex(const struct assh_algo_s *algo) [link]
This function is declared in assh/assh_kex.h source file, line 364.
This function casts and returns the passed pointer if the algorithm class is ASSH_ALGO_KEX. In other cases, NULL is returned.
assh_status_t assh_algo_kex_by_key(struct assh_context_s *c, const struct assh_key_s *key, assh_algo_id_t *pos, const struct assh_algo_kex_s **ka) [link]
This function is declared in assh/assh_kex.h source file, line 399.
This function finds a registered key-exchange algorithm which can be used with the given key.
See also assh_algo_by_key.
assh_status_t assh_algo_kex_by_name(struct assh_context_s *c, const char *name, size_t name_len, const struct assh_algo_kex_s **ka, const struct assh_algo_name_s **namep) [link]
This function is declared in assh/assh_kex.h source file, line 389.
This function finds a registered key-exchange algorithm.
See also assh_algo_by_name.
assh_status_t assh_algo_kex_by_name_static(const struct assh_algo_s **table, const char *name, size_t name_len, const struct assh_algo_kex_s **ka, const struct assh_algo_name_s **namep) [link]
This function is declared in assh/assh_kex.h source file, line 378.
This function finds a key-exchange algorithm in a NULL terminated array of pointers to algorithm descriptors.
See also assh_algo_by_name_static.
struct assh_algo_kex_s [link]
This struct is declared in assh/assh_kex.h source file, line 348.
This struct is the key-exchange algorithm descriptor. It can be casted to the struct assh_algo_s type.
See also coremod.
| Field | Description |
|---|---|
| struct assh_algo_with_key_s algo_wk; | |
| assh_kex_init_t * f_init; | |
| assh_kex_cleanup_t * f_cleanup; | |
| assh_kex_process_t * f_process; | |
| assh_bool_t implicit_auth; |
struct assh_event_kex_done_s [link]
This struct is declared in assh/assh_kex.h source file, line 312.
The ASSH_EVENT_KEX_DONE event is returned when a kex exchange has completed.
The remote software version string is exposed in the ident field as well as selected algorithms in the algo* fields.
The initial field is only set for the first key exchange of the session.
| Field | Description |
|---|---|
| struct assh_key_s *const host_key; | The host key used during the key-exchange. (ro) |
| struct assh_cbuffer_s const ident; | Remote software version string. (ro) |
| const struct assh_algo_kex_s *const algo_kex; | Key-exchange algorithm used. (ro) |
| const struct assh_kex_keys_s *const algos_in; | The set of algorithms used to process incoming packets. (ro) |
| const struct assh_kex_keys_s *const algos_out; | The set of algorithms used to process ougoing packets. (ro) |
| assh_safety_t const safety:8; | Key-exchange overall safety factor. (ro) |
| assh_bool_t const initial; | True when this is the first key-exchange of the session. (ro) |
struct assh_event_kex_hostkey_lookup_s [link]
This struct is declared in assh/assh_kex.h source file, line 290.
The ASSH_EVENT_KEX_HOSTKEY_LOOKUP event is returned when a client needs to lookup a server host key in the local database. The accept field must be updated accordingly before calling the assh_event_done function.
The initial field is only set for the first key exchange of the session.
| Field | Description |
|---|---|
| struct assh_key_s *const key; | Public host key provided by the server. (ro) |
| assh_bool_t accept; | May be updated to acknowledge that the host key is trusted. (rw) |
| assh_bool_t const initial; | Set when this is the first key-exchange of the session. (ro) |
union assh_event_kex_u [link]
This union is declared in assh/assh_kex.h source file, line 337.
This union contains all key-exchange related event structures.
| Field | Description |
|---|---|
| struct assh_event_kex_hostkey_lookup_s hostkey_lookup; | |
| struct assh_event_kex_done_s done; |
struct assh_kex_keys_s [link]
This struct is declared in assh/assh_kex.h source file, line 270.
This object contains the various symmetric cipher algorithm contexts initialized from the shared secret. This is used by the transport layer code to process the ssh packet stream.
| Field | Description |
|---|---|
| const struct assh_algo_cipher_s * cipher_algo; | |
| void * cipher_ctx; | |
| const struct assh_algo_mac_s * mac_algo; | |
| void * mac_ctx; | |
| const struct assh_algo_compress_s * cmp_algo; | |
| void * cmp_ctx; | |
| assh_safety_t safety; |
const struct assh_algo_kex_s assh_kex_none [link]
This constant is declared in assh/assh_kex.h source file, line 406.
Dummy key-exchange algorithm using a not so secret value.
See also kexalgos.
assh_status_t assh_kex_set_order(struct assh_context_s *c, uint_fast8_t safety_weight) [link]
This function is declared in assh/assh_kex.h source file, line 88.
This function sets the algorithm order by defining the weight of the safety factor. This changes how algorithms safety must be favored over speed. Valid range for this parameter is [0, 99].
assh_status_t assh_kex_set_threshold(struct assh_session_s *s, uint32_t bytes) [link]
This function is declared in assh/assh_kex.h source file, line 82.
This function changes the amount of ssh stream that is allowed to flow between the client and server before starting a new key-exchange process.
#define ASSH_KEX_CLEANUP_FCN(n) [link]
This macro is for internal use only.
This macro is declared in assh/assh_kex.h source file, line 233.
This macro expands to:
void (n)(struct assh_session_s *s)See also assh_kex_cleanup_t.
#define ASSH_KEX_INIT_FCN(n) [link]
This macro is for internal use only.
This macro is declared in assh/assh_kex.h source file, line 224.
This macro expands to:
assh_status_t (n)(struct assh_session_s *s,
size_t cipher_key_size)See also assh_kex_init_t.
#define ASSH_KEX_PROCESS_FCN(n) [link]
This macro is for internal use only.
This macro is declared in assh/assh_kex.h source file, line 242.
This macro expands to:
assh_status_t (n)(struct assh_session_s *s,
struct assh_packet_s *p,
struct assh_event_s *e)See also assh_kex_process_t.
typedef void (assh_kex_cleanup_t)(struct assh_session_s *s) [link]
This typedef is for internal use only.
This typedef is declared in assh/assh_kex.h source file, line 240.
This declaration involves expansion of the ASSH_KEX_CLEANUP_FCN macro.
This typedef defines the function type for the cleanup operation of the key-exchange module interface. This typedef is called when the key exchange is over if the assh_session_s::kex_pv field is not NULL. It has to release the key exchange private context and set this field back to NULL.
assh_status_t assh_kex_client_get_key(struct assh_session_s *s, const uint8_t *ks_str, struct assh_event_s *e, assh_status_t (*done)(struct ::assh_session_s *,const struct ::assh_event_s *,enum ::assh_status_e) , void *pv) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 144.
Preprocessor condition: defined( CONFIG_ASSH_CLIENT )
This client side helper function can be used in key-exchange modules to load the host key in assh_session_s::kex_host_key and initialize an host key lookup event.
assh_status_t assh_kex_client_hash1(struct assh_session_s *s, struct assh_hash_ctx_s *hash_ctx, const uint8_t *k_str) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 125.
Preprocessor condition: defined( CONFIG_ASSH_CLIENT )
This client side helper function can be used in key-exchange modules to perform some hashing needed for computing the exchange hash.
See also assh_kex_client_hash2.
assh_status_t assh_kex_client_hash2(struct assh_session_s *s, struct assh_hash_ctx_s *hash_ctx, const uint8_t *secret_str, const uint8_t *h_str) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 133.
Preprocessor condition: defined( CONFIG_ASSH_CLIENT )
This client side helper function can be used in key-exchange modules to the generate exchange hash, check the associated signature and setup the resulting symmetric keys.
See also assh_kex_client_hash2.
void assh_kex_done(struct assh_session_s *s, struct assh_event_s *e) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 222.
This function is called internally by the transport layer in order to report the ASSH_EVENT_KEX_DONE event.
assh_status_t assh_kex_end(struct assh_session_s *s, assh_bool_t accept) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 205.
This function is called by the pluggable key exchange module when the exchange is over. It will call the assh_kex_cleanup_t function of the module and release init packets.
If the accept parameter is not zero, a SSH_MSG_NEWKEYS packet is sent. If the accept parameter is zero, the key exchange fails.
assh_status_t assh_kex_got_init(struct assh_session_s *s, struct assh_packet_s *p) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 108.
This function is called internally by the transport layer when a key exchange init packet is received from the remote host. A copy of the packet is kept in assh_session_s::kex_init_remote for hashing by the kex-exchange algorithm.
This function selects the various algorithms from the client and server advertised lists and then initialize the pluggable key exchange module by calling its assh_kex_init_t function.
typedef assh_status_t (assh_kex_init_t)(struct assh_session_s *s, size_t cipher_key_size) [link]
This typedef is for internal use only.
This typedef is declared in assh/assh_kex.h source file, line 231.
This declaration involves expansion of the ASSH_KEX_INIT_FCN macro.
This typedef defines the function type for the initialization operation of the key-exchange module interface. This typedef is called when a key exchange starts. It may allocate a private context and store it in the assh_session_s::kex_pv field.
void assh_kex_keys_cleanup(struct assh_session_s *s, struct assh_kex_keys_s *keys) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 214.
This function is called internally when a struct assh_kex_keys_s object and its associated resources have to be released.
void assh_kex_lower_safety(struct assh_session_s *s, assh_safety_t safety) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 115.
This function function can be used during the key exchange to lower the safety factor of the current session. This is used when algorithm parameters are further negotiated after the algorithm selection phase.
assh_status_t assh_kex_new_keys(struct assh_session_s *s, const struct assh_hash_algo_s *hash_algo, const uint8_t *ex_hash, const uint8_t *secret_str) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 193.
This function is called by the pluggable key exchange module when the exchange hash and the shared secret are available. It will use the provided hash algorithm to derive the various symmetric cipher keys from these values and then initialize the associated algorithms.
Two new struct assh_kex_keys_s objects will bed ready for use and will replace the old keys when the next SSH_MSG_NEWKEYS packets are processed by the transport layer in each direction.
typedef assh_status_t (assh_kex_process_t)(struct assh_session_s *s, struct assh_packet_s *p, struct assh_event_s *e) [link]
This typedef is for internal use only.
This typedef is declared in assh/assh_kex.h source file, line 264.
This declaration involves expansion of the ASSH_KEX_PROCESS_FCN macro.
This typedef defines the function type for event processing of the key-exchange module interface. This typedef is called from the assh_transport_dispatch function when the current state of the transport layer is ASSH_TR_KEX_RUNNING.
A packet may be passed to the function for processing by the key-exchange protocol. This function must be able to handle some SSH_MSG_UNIMPLEMENTED packets as well as packets with a message id in the range [SSH_MSG_KEXSPEC_FIRST, SSH_MSG_KEXSPEC_LAST]. If no new received packet is available, the parameter is NULL. This is the case on the first call to this function after the key-exchange initialization.
The function may initialize the passed event object, in this case the event will be propagated to the caller of the assh_event_get function.
assh_status_t assh_kex_send_init(struct assh_session_s *s) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 97.
This function is called internally by the transport layer when a key-exchange must be performed.
This function send the kex exchange init packet. A copy of the packet is kept in assh_session_s::kex_init_local for hashing by the kex-exchange algorithm.
assh_status_t assh_kex_server_hash1(struct assh_session_s *s, size_t kex_len, struct assh_hash_ctx_s *hash_ctx, struct assh_packet_s **pout, size_t *sign_len, struct assh_key_s **host_key, enum assh_ssh_msg_e msg) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 162.
Preprocessor condition: defined( CONFIG_ASSH_SERVER )
This server side helper function can be used in key-exchange modules to allocate a SSH_MSG_KEX_DH_REPLY key exchange packet, adds public host key fields and updates the hash context with various values including the host key.
More fields may be added hashed or added to the packet before calling the assh_kex_server_hash2 function.
assh_status_t assh_kex_server_hash2(struct assh_session_s *s, struct assh_hash_ctx_s *hash_ctx, struct assh_packet_s *pout, size_t sign_len, const struct assh_key_s *host_key, const uint8_t *secret_str) [link]
This function is for internal use only.
This function is declared in assh/assh_kex.h source file, line 176.
Preprocessor condition: defined( CONFIG_ASSH_SERVER )
This server side helper function can be used in key-exchange modules to hash the secret key then add the signature to the SSH_MSG_KEX_DH_REPLY packet and finally call assh_kex_new_keys function.
See also assh_kex_server_hash1.
const struct assh_kex_keys_s assh_keys_none [link]
This constant is for internal use only.
This constant is declared in assh/assh_kex.h source file, line 402.
Set of none algortihm contexts used at startup