assh/assh_session.h header reference
Description [link]
This header file provides declaration of the struct assh_session_s structure and related functions, used to create and manage ssh2 sessions.
Header inclusion [link]
Members [link]
Types [link]
- struct assh_event_session_error_s
- union assh_event_session_u
- typedef assh_bool_t (assh_kex_filter_t)(struct assh_session_s *s, const struct assh_algo_s *algo, const struct assh_algo_name_s *name, assh_bool_t out)
- struct assh_session_s
Functions [link]
- assh_status_t assh_session_algo_filter(struct assh_session_s *s, assh_kex_filter_t *filter)
- void assh_session_cleanup(struct assh_session_s *s)
- assh_bool_t assh_session_closed(const struct assh_session_s *s)
- struct assh_context_s * assh_session_context(struct assh_session_s *s)
- assh_status_t assh_session_create(struct assh_context_s *c, struct assh_session_s **s)
- assh_time_t assh_session_deadline(const struct assh_session_s *s)
- assh_time_t assh_session_delay(const struct assh_session_s *s, assh_time_t time)
- assh_status_t assh_session_disconnect(struct assh_session_s *s, enum assh_ssh_disconnect_e reason, const char *desc)
- void * assh_session_get_pv(const struct assh_session_s *ctx)
- assh_status_t assh_session_init(struct assh_context_s *c, struct assh_session_s *s)
- void assh_session_release(struct assh_session_s *s)
- assh_safety_t assh_session_safety(const struct assh_session_s *s)
- void assh_session_set_pv(struct assh_session_s *ctx, void *private)
- void assh_session_userauth_done(struct assh_session_s *s)
- void assh_session_error(struct assh_session_s *s, assh_status_t err)
Macro [link]
Members detail [link]
#define ASSH_KEX_FILTER_FCN(n) [link]
This macro is declared in assh/assh_session.h source file, line 42.
This macro expands to:
assh_bool_t (n)(struct assh_session_s *s,
const struct assh_algo_s *algo,
const struct assh_algo_name_s *name,
assh_bool_t out)See also assh_kex_filter_t.
struct assh_event_session_error_s [link]
This struct is declared in assh/assh_session.h source file, line 234.
The ASSH_EVENT_SESSION_ERROR event is reported when an error occurs. Because not all errors are fatal, the event may be reported multiple times during a single session.
See also ASSH_STATUS and ASSH_SEVERITY.
| Field | Description |
|---|---|
| const assh_status_t code; | The error code reported by the library. (ro) |
union assh_event_session_u [link]
This union is declared in assh/assh_session.h source file, line 241.
This union contains all session related event structures.
| Field | Description |
|---|---|
| struct assh_event_session_error_s error; |
typedef assh_bool_t (assh_kex_filter_t)(struct assh_session_s *s, const struct assh_algo_s *algo, const struct assh_algo_name_s *name, assh_bool_t out) [link]
This typedef is declared in assh/assh_session.h source file, line 64.
This declaration involves expansion of the ASSH_KEX_FILTER_FCN macro.
This is a per session algorithm filtering function.
1 must be returned in order to make the algorithm available for the session key-exchange. This can not be used to prevent registered signature algorithms from being used during the user authentication process.
The result of this function must not vary between calls for a given algorithm, unless the assh_session_algo_filter function has been called successfully.
The out parameter specifies the direction and is relevant for cipher, mac and compression algorithms.
See also suppalgos.
assh_status_t assh_session_algo_filter(struct assh_session_s *s, assh_kex_filter_t *filter) [link]
This function is declared in assh/assh_session.h source file, line 319.
This function setups a per session algorithm filter for the key-exchange. The filter parameter may be NULL to disable filtering. It will fail if a key exchange is currently running.
See also suppalgos.
void assh_session_cleanup(struct assh_session_s *s) [link]
This function is declared in assh/assh_session.h source file, line 275.
This function releases the resources associated with an user allocated struct assh_session_s instance.
assh_bool_t assh_session_closed(const struct assh_session_s *s) [link]
This function is declared in assh/assh_session.h source file, line 344.
This function returns true when the assh_event_get function will not report more events.
struct assh_context_s * assh_session_context(struct assh_session_s *s) [link]
This function is declared in assh/assh_session.h source file, line 354.
This function returns the context associated to the given session.
assh_status_t assh_session_create(struct assh_context_s *c, struct assh_session_s **s) [link]
This function is declared in assh/assh_session.h source file, line 270.
This function allocates and initializes an struct assh_session_s instance.
See also assh_session_release.
assh_time_t assh_session_deadline(const struct assh_session_s *s) [link]
This function is declared in assh/assh_session.h source file, line 329.
This function returns the next protocol deadline. In order for the library to handle protocol timeouts properly, the process must not wait forever on a blocking io operation. The assh_event_get function must be called again when the deadline is reached.
See also assh_session_delay.
assh_time_t assh_session_delay(const struct assh_session_s *s, assh_time_t time) [link]
This function is declared in assh/assh_session.h source file, line 339.
This function returns the delay between the next protocol deadline and the current time. The current time must be passed to the function in second units. If the next deadline is in the past, the function returns 0.
See also assh_session_deadline.
assh_status_t assh_session_disconnect(struct assh_session_s *s, enum assh_ssh_disconnect_e reason, const char *desc) [link]
This function is declared in assh/assh_session.h source file, line 305.
This function schedules the end of the session and sends an SSH_MSG_DISCONNECT message to the remote host. The assh_event_get function must still be called until no more events are available.
void * assh_session_get_pv(const struct assh_session_s *ctx) [link]
This function is declared in assh/assh_session.h source file, line 252.
This function retrieves the user private pointer of the session.
See also assh_session_set_pv.
assh_status_t assh_session_init(struct assh_context_s *c, struct assh_session_s *s) [link]
This function is declared in assh/assh_session.h source file, line 262.
This function initializes an user allocated session instance. When a stable ABI is needed, the assh_session_create function muse be used instead.
See also assh_session_cleanup.
void assh_session_release(struct assh_session_s *s) [link]
This function is declared in assh/assh_session.h source file, line 280.
This function releases an struct assh_session_s instance created by the assh_session_create function as well as associated resources.
struct assh_session_s [link]
This struct is declared in assh/assh_session.h source file, line 79.
This struct is the ssh2 session state structure.
A session instance is associated to an struct assh_context_s object which holds resources shared between multiple sessions.
It is not related to interactive sessions which are part of the connection protocol.
| Field | Description |
|---|---|
| void * user_pv; | User private pointer |
| struct assh_context_s * ctx; | Pointer to associated main context. |
| const struct assh_algo_kex_s * kex_algo; | Key exchange algorithm. This pointer is setup when the assh_kex_got_init function select a new key exchange algorithm. |
| void * kex_pv; | Key exchange private context used during key exchange only. |
| struct assh_packet_s * kex_init_local; | Pointer to the last key exechange packet sent by client. Valid during key exechange. |
| struct assh_packet_s * kex_init_remote; | Pointer to the last key exechange packet sent by client. Valid during key exechange. |
| const struct assh_algo_s * kex_preferred[2]; | remote side prefered kex and host signature algorithms |
| assh_kex_filter_t * kex_filter; | per session algorithm filter |
| uint32_t kex_bytes; | amount of data transfered since last kex |
| uint32_t kex_max_bytes; | kex re-exchange threshold |
| const struct assh_algo_sign_s * host_sign_algo; | Host keys signature algorithm |
| const struct assh_service_s * srv; | Current service. |
| void * srv_pv; | Current service private data. |
| struct assh_key_s * kex_host_key; | Host key sent by the server. The key released when the ASSH_EVENT_KEX_DONE event is acknowledged. |
| struct assh_queue_s out_queue; | Queue of ssh output packets. Packets in this queue will be enciphered and sent. |
| struct assh_queue_s alt_queue; | Alternate queue of ssh output packets, used to store services packets during a key exchange. |
| struct assh_kex_keys_s * cur_keys_out; | Pointer to output keys and algorithms in current use. |
| struct assh_kex_keys_s * new_keys_out; | Pointer to next output keys and algorithms on SSH_MSG_NEWKEYS transmitted. |
| struct assh_packet_s * stream_in_pck; | Current input ssh stream packet. This packet is currently being read from the input ssh stream and has not yet been deciphered. |
| struct assh_packet_s * in_pck; | Current ssh input packet. This packet is the last deciphered packets and is waiting for dispatch and processing. |
| struct assh_kex_keys_s * cur_keys_in; | Pointer to input keys and algorithms in current use. |
| struct assh_kex_keys_s * new_keys_in; | Pointer to next input keys and algorithms on SSH_MSG_NEWKEYS received. |
| assh_status_t last_err; | last error reported to assh_session_error. This will be reported as an ASSH_EVENT_SESSION_ERROR event. |
| assh_time_t time; | Current date as reported by the last IO request. |
| assh_time_t tr_deadline; | The session will terminate with the ASSH_ERR_TIMEOUT error if this field contains a value less than the time field. It is updated by the transport layer. |
| assh_time_t srv_deadline; | The running service may update this field and check when this field contains a value less than the time field. When not used, it must be set to 0 so that it is excluded from the computation of the next protocol timeout reported to the application. |
| assh_time_t rekex_deadline; | The key-exchange process will be stated again when this field contains a value less then the time field and the transport state is ASSH_TR_SERVICE. |
| size_t stream_in_size:32; | Size of valid data in the stream_in_pck packet |
| size_t stream_out_size:32; | Size of already sent data of the top packet in the out_queue queue. |
| uint32_t in_seq; | Input packet sequence number |
| uint32_t out_seq; | Output packet sequence number |
| union <anonymous> { | Current input ssh stream header buffer. |
| uint8_t data[16]; | |
| struct assh_packet_head_s head; | |
| } stream_in_stub; | |
| uint8_t session_id[64]; | Session id is first "exchange hash" H |
| size_t session_id_len:8; | Session id length |
| uint8_t ident_str[CONFIG_ASSH_IDENT_SIZE]; | Copy of the ident string sent by the remote host. |
| size_t ident_len:8; | Size of the ident string sent by the remote host. |
| size_t srv_index:5; | Index of the next service to request in the context services array. |
| assh_bool_t tr_user_auth_done:1; | user authentication success packet has been handled by the transport layer |
| assh_bool_t user_auth_done:1; | user authentication success |
| assh_bool_t kex_done:1; | initial key exchange done. |
| enum assh_stream_out_state_e stream_out_st:3; | Currrent output ssh stream generator state. |
| enum assh_stream_in_state_e stream_in_st:3; | Current input ssh stream parser state. |
| enum assh_transport_state_e tr_st:4; | Current state of the transport layer. |
| enum assh_service_state_e srv_st:3; | Current state of service execution. |
| assh_bool_t event_done:1; |
assh_safety_t assh_session_safety(const struct assh_session_s *s) [link]
This function is declared in assh/assh_session.h source file, line 311.
This function returns the current session safety factor which depends on algorithms and keys involved in the last key-exchange process. The safety factor may change during the session lifetime.
See also assh_algo_register_va.
void assh_session_set_pv(struct assh_session_s *ctx, void *private) [link]
This function is declared in assh/assh_session.h source file, line 248.
This function sets the user private pointer of the session.
See also assh_session_get_pv.
void assh_session_userauth_done(struct assh_session_s *s) [link]
This function is declared in assh/assh_session.h source file, line 350.
This function marks the user as authenticated. This is usually called by the user authentication services. On rare cases when one of these services is not used, it may be called directly by the application.
void assh_session_error(struct assh_session_s *s, assh_status_t err) [link]
This function is for internal use only.
This function is declared in assh/assh_session.h source file, line 296.
This function changes the session state according to the provided error code and associated severity level.
This function returns the original error code but the error severity level may be increased. This function is responsible for sending the session close message to the remote hsot.
This function is called from the assh_event_get, assh_event_done function. It is also called from other functions of the public API which can modify the session state.
See also enum assh_status_e and enum assh_severity_e.