assh/assh_connection.h header reference
Description [link]
This header file defines events and functions which are used when the assh_service_connection service is running. This service module is an implementation of the connection protocol.
Functions declared in this header must not be called when the service is not running.
Functions which support the interactive session and port forwarding features are declared in the assh/helper_interactive.h and assh/helper_portfwd.h header files.
See also connmap and connapi.
Header inclusion [link]
Members [link]
Types [link]
- enum assh_channel_open_reason_e
- struct assh_channel_s
- enum assh_channel_state_e
- enum assh_connection_reply_e
- struct assh_event_channel_abort_s
- struct assh_event_channel_close_s
- struct assh_event_channel_confirmation_s
- struct assh_event_channel_data_s
- struct assh_event_channel_eof_s
- struct assh_event_channel_failure_s
- struct assh_event_channel_open_s
- struct assh_event_channel_window_s
- union assh_event_connection_u
- struct assh_event_request_abort_s
- struct assh_event_request_failure_s
- struct assh_event_request_s
- struct assh_event_request_success_s
- enum assh_request_reason_e
- struct assh_request_s
- enum assh_request_state_e
Functions [link]
- assh_status_t assh_channel_close(struct assh_channel_s *ch)
- assh_status_t assh_channel_data(struct assh_channel_s *ch, const uint8_t *data, size_t *size)
- assh_status_t assh_channel_data_alloc(struct assh_channel_s *ch, uint8_t **data, size_t *size, size_t min_size)
- assh_status_t assh_channel_data_alloc_ext(struct assh_channel_s *ch, uint32_t ext_type, uint8_t **data, size_t *size, size_t min_size)
- assh_status_t assh_channel_data_ext(struct assh_channel_s *ch, uint32_t ext_type, const uint8_t *data, size_t *size)
- assh_status_t assh_channel_data_send(struct assh_channel_s *ch, size_t size)
- assh_status_t assh_channel_dummy(struct assh_channel_s *ch, size_t size)
- assh_status_t assh_channel_eof(struct assh_channel_s *ch)
- void assh_channel_get_pkt_size(const struct assh_channel_s *ch, uint32_t *local, uint32_t *remote)
- void assh_channel_get_win_size(const struct assh_channel_s *ch, uint32_t *local, uint32_t *remote)
- struct assh_channel_s * assh_channel_more_data(struct assh_session_s *s)
- assh_status_t assh_channel_open(struct assh_session_s *s, const char *type, size_t type_len, const uint8_t *data, size_t data_len, int32_t pkt_size, int32_t win_size, struct assh_channel_s **ch)
- assh_status_t assh_channel_open_failed_reply(struct assh_channel_s *ch, enum assh_channel_open_reason_e reason)
- assh_status_t assh_channel_open_success_reply(struct assh_channel_s *ch, const uint8_t *rsp_data, size_t rsp_data_len)
- assh_status_t assh_channel_open_success_reply2(struct assh_channel_s *ch, int32_t pkt_size, int32_t win_size, const uint8_t *rsp_data, size_t rsp_data_len)
- void * assh_channel_pv(const struct assh_channel_s *ch)
- uintptr_t assh_channel_pvi(const struct assh_channel_s *ch)
- struct assh_session_s * assh_channel_session(const struct assh_channel_s *ch)
- void assh_channel_set_pv(struct assh_channel_s *ch, void *pv)
- void assh_channel_set_pvi(struct assh_channel_s *ch, uintptr_t pv)
- enum assh_channel_state_e assh_channel_state(const struct assh_channel_s *ch)
- assh_status_t assh_channel_window_adjust(struct assh_channel_s *ch, size_t add)
- size_t assh_channel_window_size(struct assh_channel_s *ch)
- assh_status_t assh_request(struct assh_session_s *s, struct assh_channel_s *ch, const char *type, size_t type_len, const uint8_t *data, size_t data_len, struct assh_request_s **rq)
- struct assh_channel_s * assh_request_channel(const struct assh_request_s *rq)
- assh_status_t assh_request_failed_reply(struct assh_request_s *rq)
- void * assh_request_pv(const struct assh_request_s *rq)
- uintptr_t assh_request_pvi(const struct assh_request_s *rq)
- struct assh_session_s * assh_request_session(const struct assh_request_s *rq)
- void assh_request_set_pv(struct assh_request_s *rq, void *pv)
- void assh_request_set_pvi(struct assh_request_s *rq, uintptr_t pv)
- enum assh_request_state_e assh_request_state(struct assh_request_s *rq)
- assh_status_t assh_request_success_reply(struct assh_request_s *rq, const uint8_t *rsp_data, size_t rsp_data_len)
Constant [link]
- const struct assh_service_s assh_service_connection
Macro [link]
Members detail [link]
#define ASSH_CHANNEL_MAX_PKTSIZE [link]
This macro is declared in assh/assh_connection.h source file, line 161.
This macro specifies the maximum payload size usable to transfer data with struct assh_channel_s objects. This is 12 bytes less than the value of the CONFIG_ASSH_MAX_PAYLOAD macro.
This macro expands to:
(CONFIG_ASSH_MAX_PAYLOAD
- /* extended data message header */ 3 * 4)assh_status_t assh_channel_close(struct assh_channel_s *ch) [link]
This function is declared in assh/assh_connection.h source file, line 961.
This function sends an SSH_MSG_CHANNEL_CLOSE message to the remote host.
When this function is successful, the channel is not released until the ASSH_EVENT_CHANNEL_CLOSE event acknowledges this call. In the mean time, some request and data related events can still be reported for the channel.
This function must not be called if the last event has not been acknowledged by calling the assh_event_done function.
See also connapi.
assh_status_t assh_channel_data(struct assh_channel_s *ch, const uint8_t *data, size_t *size) [link]
This function is declared in assh/assh_connection.h source file, line 846.
This function transmits data to the remote host through an open channel. It's a convenience function which calls assh_channel_data_alloc then memcpy and finally assh_channel_data_send.
This size parameter is updated with the actually transmitted size.
This function must not be called if the last event has not been acknowledged by calling the assh_event_done function.
See also assh_channel_data_ext.
assh_status_t assh_channel_data_alloc(struct assh_channel_s *ch, uint8_t **data, size_t *size, size_t min_size) [link]
This function is declared in assh/assh_connection.h source file, line 800.
This function internally pre-allocates a data packet suitable to transmit at least min_size bytes and up to *size bytes through an open channel.
If the function is successful, the size parameter is updated with the actual size of the available data buffer and the data parameter is updated with the address of the buffer. The data will be sent when calling the assh_channel_data_send function.
This function returns ASSH_NO_DATA if min_size is either larger than the maximum packet size for the channel or larger than the current channel remote window. In this case no packet is allocated but the size parameter is still updated with the current largest possible size. The largest possible size is 0 either if there is no window space left or if the channel is closing.
It's ok to call this function more than once without actually sending the packet in order to change the requested packet size.
The user does not have to release the allocated data packet explicitly.
Unlike most functions of this module, it is ok to call this function between calls to the assh_event_get and assh_event_done functions. This allows forging a reply while the incoming data are still available.
See also assh_channel_window_size and assh_channel_data_alloc_ext.
assh_status_t assh_channel_data_alloc_ext(struct assh_channel_s *ch, uint32_t ext_type, uint8_t **data, size_t *size, size_t min_size) [link]
This function is declared in assh/assh_connection.h source file, line 813.
This function is similar to the assh_channel_data_alloc function. It prepares an SSH_MSG_CHANNEL_EXTENDED_DATA message instead of an SSH_MSG_CHANNEL_DATA message
See also assh_channel_data_alloc.
assh_status_t assh_channel_data_ext(struct assh_channel_s *ch, uint32_t ext_type, const uint8_t *data, size_t *size) [link]
This function is declared in assh/assh_connection.h source file, line 865.
This function is similar to the assh_channel_data function. It sends an SSH_MSG_CHANNEL_EXTENDED_DATA message instead of an SSH_MSG_CHANNEL_DATA message
See also assh_channel_data.
assh_status_t assh_channel_data_send(struct assh_channel_s *ch, size_t size) [link]
This function is declared in assh/assh_connection.h source file, line 827.
This function sends the data packet previously allocated by the assh_channel_data_alloc function. The size parameter must not be greater than what has been pre-allocated.
If this function is called on a closing channel, ASSH_NO_DATA is returned to indicate that it was not able to send data.
This function must not be called if the last event has not been acknowledged by calling the assh_event_done function.
assh_status_t assh_channel_dummy(struct assh_channel_s *ch, size_t size) [link]
This function is declared in assh/assh_connection.h source file, line 889.
This function allocates and transmits a dummy packet ignored by the remote host. Once enciphered, the packet looks similar to a channel data packet of the specified size.
This function must not be called if the last event has not been acknowledged by calling the assh_event_done function.
assh_status_t assh_channel_eof(struct assh_channel_s *ch) [link]
This function is declared in assh/assh_connection.h source file, line 944.
This function sends an SSH_MSG_CHANNEL_EOF message and marks the channel as half-closed. The assh_channel_data function can not be called successfully on the channel once this function has been called.
If the channel is already half-closed in the other direction, this function acts as the assh_channel_close function.
This function must not be called if the last event has not been acknowledged by calling the assh_event_done function.
See also connapi.
void assh_channel_get_pkt_size(const struct assh_channel_s *ch, uint32_t *local, uint32_t *remote) [link]
This function is declared in assh/assh_connection.h source file, line 195.
This function returns the maximum packet size for a channel.
void assh_channel_get_win_size(const struct assh_channel_s *ch, uint32_t *local, uint32_t *remote) [link]
This function is declared in assh/assh_connection.h source file, line 191.
This function returns the size of the channel local and remote windows in bytes.
struct assh_channel_s * assh_channel_more_data(struct assh_session_s *s) [link]
This function is declared in assh/assh_connection.h source file, line 727.
This function returns a pointer to a channel with pending data. This occurs when the ASSH_EVENT_CHANNEL_DATA event will be reported again because the assh_event_channel_data_s::transferred field of the previous event has not been set to the maximum value.
It returns NULL when there is no channel with pending data.
assh_status_t assh_channel_open(struct assh_session_s *s, const char *type, size_t type_len, const uint8_t *data, size_t data_len, int32_t pkt_size, int32_t win_size, struct assh_channel_s **ch) [link]
This function is declared in assh/assh_connection.h source file, line 672.
This function allocates an struct assh_channel_s object and send a SSH_MSG_CHANNEL_OPEN message to the remote host.
When this function is successful, either an ASSH_EVENT_CHANNEL_CONFIRMATION event or an ASSH_EVENT_CHANNEL_FAILURE event will be reported at some point by the assh_event_get function.
The data and data_len parameters allow sending channel type specific data along with the channel open message, as allowed by the protocol.
The maximum packet size and the initial size of the channel local window may be specified. When the pkt_size parameter is negative, a default value is used. When the win_size parameter is negative, automatic local window adjustment is enabled for the channel. When a positive value is used instead, it specifies the initial size of the local window. In the later case, calls to the assh_channel_window_adjust function have to be performed in order to keep the size of the local window above 0.
If this function is called after disconnection, this function returns ASSH_NO_DATA to indicate that it was not able to open the channel.
This function must not be called if the last event has not been acknowledged by calling the assh_event_done function.
See also connapi.
assh_status_t assh_channel_open_failed_reply(struct assh_channel_s *ch, enum assh_channel_open_reason_e reason) [link]
This function is declared in assh/assh_connection.h source file, line 581.
This function acknowledges a channel open message which has not been replied yet due to the use of the ASSH_CONNECTION_REPLY_POSTPONED value in the reply field of the ASSH_EVENT_CHANNEL_OPEN event.
Channel open replies can be sent in any order.
If this function is called on a closing channel which has not yet been reported by an ASSH_EVENT_CHANNEL_CLOSE event, this function returns ASSH_NO_DATA to indicate that it was not able to send the reply. This occurs on disconnection.
The struct assh_channel_s object is released if the function reports no error.
This function must not be called if the last event has not been acknowledged by calling the assh_event_done function.
See also assh_channel_open_success_reply and connapi.
enum assh_channel_open_reason_e [link]
This enum is declared in assh/assh_connection.h source file, line 130.
This enum specifies standard values for channel open failure reason code as defined in rfc4254 section 5.1 .
| Identifier | Value | Description |
|---|---|---|
| SSH_OPEN_SESSION_DISCONNECTED | -1 | |
| SSH_OPEN_SUCCESS | 0 | |
| SSH_OPEN_ADMINISTRATIVELY_PROHIBITED | 1 | |
| SSH_OPEN_CONNECT_FAILED | 2 | |
| SSH_OPEN_UNKNOWN_CHANNEL_TYPE | 3 | |
| SSH_OPEN_RESOURCE_SHORTAGE | 4 |
assh_status_t assh_channel_open_success_reply(struct assh_channel_s *ch, const uint8_t *rsp_data, size_t rsp_data_len) [link]
This function is declared in assh/assh_connection.h source file, line 556.
This function acknowledges a channel open message which has not been replied yet due to the use of the ASSH_CONNECTION_REPLY_POSTPONED value in the reply field of the ASSH_EVENT_CHANNEL_OPEN event.
Response data may optionally be included by using the rsp_data and rsp_data_len parameters, as allowed by the protocol.
Channel open replies can be send in any order.
If this function is called on a closing channel which has not yet been reported by an ASSH_EVENT_CHANNEL_CLOSE event, this function returns ASSH_NO_DATA to indicate that it was not able to send the reply. This occurs on disconnection.
This function must not be called if the last event has not been acknowledged by calling the assh_event_done function.
See also assh_channel_open_failed_reply and connapi.
assh_status_t assh_channel_open_success_reply2(struct assh_channel_s *ch, int32_t pkt_size, int32_t win_size, const uint8_t *rsp_data, size_t rsp_data_len) [link]
This function is declared in assh/assh_connection.h source file, line 530.
This function is similar to assh_channel_open_success_reply but allows overriding the maximum packet size and the initial local window size specified when the ASSH_EVENT_CHANNEL_OPEN event has been reported.
See also assh_channel_open_success_reply and connapi.
void * assh_channel_pv(const struct assh_channel_s *ch) [link]
This function is declared in assh/assh_connection.h source file, line 171.
This function returns the value of the channel private pointer.
uintptr_t assh_channel_pvi(const struct assh_channel_s *ch) [link]
This function is declared in assh/assh_connection.h source file, line 179.
This function returns the value of the channel private integer.
struct assh_channel_s [link]
This struct is declared in assh/assh_connection.h source file, line 125.
This struct is the ssh-connection service channel object.
Channels are created either by calling the assh_channel_open function or when the ASSH_EVENT_CHANNEL_OPEN event is reported. The library user does not have to destroy channel objects explicitly.
See also connapi.
struct assh_session_s * assh_channel_session(const struct assh_channel_s *ch) [link]
This function is declared in assh/assh_connection.h source file, line 183.
This function returns the session associated to a channel.
void assh_channel_set_pv(struct assh_channel_s *ch, void *pv) [link]
This function is declared in assh/assh_connection.h source file, line 168.
This function sets the value of the channel private pointer. This shares the storage with the private integer.
See also assh_channel_set_pvi.
void assh_channel_set_pvi(struct assh_channel_s *ch, uintptr_t pv) [link]
This function is declared in assh/assh_connection.h source file, line 176.
This function sets the value of the channel private integer. This shares the storage with the private pointer.
See also assh_channel_set_pv.
enum assh_channel_state_e assh_channel_state(const struct assh_channel_s *ch) [link]
This function is declared in assh/assh_connection.h source file, line 187.
This function returns the current channel status.
enum assh_channel_state_e [link]
This enum is declared in assh/assh_connection.h source file, line 85.
This enum specifies struct assh_channel_s status.
See also connapi.
| Identifier | Value | Description |
|---|---|---|
| ASSH_CHANNEL_ST_OPEN_SENT | 0 | An open message has been sent to the remote host |
| ASSH_CHANNEL_ST_OPEN_RECEIVED | 1 | An open reply message has been received, action must be taken in order to acknowledge the channel open. |
| ASSH_CHANNEL_ST_OPEN | 2 | The channel is open. |
| ASSH_CHANNEL_ST_EOF_SENT | 3 | The channel is open half way. |
| ASSH_CHANNEL_ST_EOF_RECEIVED | 4 | The channel is open half way. |
| ASSH_CHANNEL_ST_EOF_CLOSE | 5 | A pair of channel EOF messages has been exchanged, a channel close message was sent. |
| ASSH_CHANNEL_ST_CLOSE_CALLED | 6 | The assh_channel_close function has been called and a close message was sent but the remote host has not replied yet. |
| ASSH_CHANNEL_ST_CLOSING | 7 | A channel close message has been received and a reply was sent. Some request/data related events may still be reported before the channel object is released. |
| ASSH_CHANNEL_ST_FORCE_CLOSE | 8 | The connection is ending, an ASSH_EVENT_CHANNEL_CLOSE event will be reported for this channel. |
| ASSH_CHANNEL_ST_OPEN_SENT_FORCE_CLOSE | 9 | The connection is ending, an ASSH_EVENT_CHANNEL_FAILURE event will be reported for this channel. |
| ASSH_CHANNEL_ST_OPEN_RECEIVED_FORCE_CLOSE | 10 | The connection is ending, an ASSH_EVENT_CHANNEL_ABORT event will be reported for this channel. |
assh_status_t assh_channel_window_adjust(struct assh_channel_s *ch, size_t add) [link]
This function is declared in assh/assh_connection.h source file, line 739.
This function can be used to advertise the remote host that we are ready to receive more data over the channel.
This function increases the local window size and sends an SSH_MSG_CHANNEL_WINDOW_ADJUST message to the remote host.
This must be used when automatic local window adjustment is not enabled for the channel, as explained in assh_channel_open.
size_t assh_channel_window_size(struct assh_channel_s *ch) [link]
This function is declared in assh/assh_connection.h source file, line 878.
This function returns the amount of data size that can be written to the channel.
enum assh_connection_reply_e [link]
This enum is declared in assh/assh_connection.h source file, line 148.
This enum specifies reply codes used by request and channel events.
| Identifier | Value | Description |
|---|---|---|
| ASSH_CONNECTION_REPLY_FAILED | 0 | Failure report by/to remote host. |
| ASSH_CONNECTION_REPLY_SUCCESS | 1 | Success report by/to remote host. |
| ASSH_CONNECTION_REPLY_POSTPONED | 2 | Reply will be sent later |
| ASSH_CONNECTION_REPLY_CLOSED | 3 | The remote host has closed the channel/connection |
struct assh_event_channel_abort_s [link]
This struct is declared in assh/assh_connection.h source file, line 512.
This event is reported when the connection is ending and some channel open have been postponed.
The struct assh_channel_s object will be released when calling the assh_event_done function.
See also ASSH_EVENT_CHANNEL_ABORT and connapi.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the channel object. (ro) |
struct assh_event_channel_close_s [link]
This struct is declared in assh/assh_connection.h source file, line 922.
This event is reported for open channels when the channel is in ASSH_CHANNEL_ST_CLOSING state and all data and requests associated with the channel have been reported using appropriate events.
See also ASSH_EVENT_CHANNEL_CLOSE and connapi.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the channel object. (ro) |
struct assh_event_channel_confirmation_s [link]
This struct is declared in assh/assh_connection.h source file, line 602.
This event is reported after a successful call to the assh_channel_open function when the channel open is accepted by the remote host.
Some response specific data may be available in the rsp_data field. The rwin_size and rpkt_size fields also contain the initially available window size and the packet size advertised by the remote host for sending to data through the channel.
If the open has failed, the ASSH_EVENT_CHANNEL_FAILURE event is reported instead.
See also ASSH_EVENT_CHANNEL_CONFIRMATION and connapi.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the channel object. (ro) |
| const struct assh_cbuffer_s rsp_data; | The associated data if any. (ro) |
| const uint32_t rwin_size; | The remote window size. (ro) |
| const uint32_t rpkt_size; | The remote packet size. (ro) |
struct assh_event_channel_data_s [link]
This struct is declared in assh/assh_connection.h source file, line 702.
This event is reported when the assh_service_connection service is running and some incoming channel data are available.
The transferred field should be set to the amount of consumed data. The event will be reported again if the field is not updated or if the value is less than data.size. In the other case, the data buffers will not remain valid after the call to assh_event_done.
The size of the local window for the channel is decreased by the amount of received bytes when the event is first reported. When automatic local window adjustment is not enabled for the channel, the assh_channel_window_adjust function must be called as soon as it becomes possible to receive more data.
It's not possible to receive data from other channels until all data provided by the event are consumed. When this is a problem, automatic adjustment of the local window must not be used so that the amount of data sent by the remote host can be kept under control for all channels.
See also ASSH_EVENT_CHANNEL_DATA and assh_channel_more_data.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the channel object. (ro) |
| const assh_bool_t ext; | Indicate extended data. (ro) |
| const uint32_t ext_type; | The type of extended data. (ro) |
| const struct assh_cbuffer_s data; | The actual data transmitted over the channel. (ro) |
| size_t transferred; | Must be set to the amount of data copied from the buffer. (rw) |
struct assh_event_channel_eof_s [link]
This struct is declared in assh/assh_connection.h source file, line 906.
This event is reported when the assh_service_connection service is running and the remote host has sent the SSH_MSG_CHANNEL_EOF message.
If the channel has already been half-closed in the other direction when receiving this messages, an SSH_MSG_CHANNEL_CLOSE message is sent and the channel state changes to ASSH_CHANNEL_ST_CLOSING.
See also ASSH_EVENT_CHANNEL_EOF and connapi.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the channel object. (ro) |
struct assh_event_channel_failure_s [link]
This struct is declared in assh/assh_connection.h source file, line 628.
This event is reported after a successful call to the assh_channel_open function when the channel open is rejected by the remote host.
The associated struct assh_channel_s object is released when the assh_event_done function is called.
See also ASSH_EVENT_CHANNEL_FAILURE and connapi.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the channel object. (ro) |
| const enum assh_channel_open_reason_e reason; | The channel open failure reason. (ro) |
struct assh_event_channel_open_s [link]
This struct is declared in assh/assh_connection.h source file, line 469.
This event is reported when the assh_service_connection service is running and an SSH_MSG_CHANNEL_OPEN message is received from the remote host. The channel type name and specific data are available in the type and rq_data fields. These buffers will not remain valid after the call to assh_event_done.
The reply field can be set to ASSH_CONNECTION_REPLY_SUCCESS in order to successfully acknowledge the channel open. In this case, response data may optionally be passed in the rsp_data field, as allowed by the protocol.
The default value of the reply field is ASSH_CONNECTION_REPLY_FAILED. If an open failure is sent, the struct assh_channel_s object will be release when calling the assh_event_done function.
When it's not possible to decide if the channel open is accepted before calling the assh_event_done function, the ASSH_CONNECTION_REPLY_POSTPONED value can be used. In this case, either the assh_channel_open_success_reply or the assh_channel_open_failed_reply function must be called later to send the reply expected by the remote host. Care should be taken not to postpone or accept too many channel open requests in order to avoid resource-exhaustion attacks.
If some channel open are left postponed when the connection is ending, related ASSH_EVENT_CHANNEL_ABORT events are reported.
Ths rpkt_size and rwin_size fields contains the initially available window size and the packet size advertised by the remote host for sending data through the channel.
The pkt_size and win_size fields are used to advertise our receive window and packet size and can be modified. The meaning of these fields is as described in assh_channel_open. They are initially set to -1.
See also ASSH_EVENT_CHANNEL_OPEN and connapi.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the channel object. (ro) |
| const struct assh_cbuffer_s type; | The textual type of the channel. (ro) |
| const struct assh_cbuffer_s rq_data; | The associated data if any. (ro) |
| enum assh_connection_reply_e reply; | Used to store the channel open reply. (rw) |
| enum assh_channel_open_reason_e reason; | Used to store the channel open failure reason. (rw) |
| int32_t win_size; | The requested initial window size. (rw) |
| int32_t pkt_size; | The requested packet size. (rw) |
| const uint32_t rwin_size; | The remote window size. (ro) |
| const uint32_t rpkt_size; | The remote packet size. (ro) |
| struct assh_cbuffer_s rsp_data; | Used to store the reply data if any. (rw) |
struct assh_event_channel_window_s [link]
This struct is declared in assh/assh_connection.h source file, line 752.
This event is reported when the assh_service_connection service is running and an SSH_MSG_CHANNEL_WINDOW_ADJUST message has been received.
This event indicates that the size of the remote window has increased. This means that more data can be sent over the channel.
See also ASSH_EVENT_CHANNEL_WINDOW.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the channel object. (ro) |
| const uint32_t old_size; | The previous window size. (ro) |
| const uint32_t new_size; | The new window size. (ro) |
union assh_event_connection_u [link]
This union is declared in assh/assh_event.h source file, line 141.
This union contains all assh_service_connection service related event structures.
| Field | Description |
|---|---|
| struct assh_event_request_s request; | |
| struct assh_event_request_abort_s request_abort; | |
| struct assh_event_request_success_s request_success; | |
| struct assh_event_request_failure_s request_failure; | |
| struct assh_event_channel_open_s channel_open; | |
| struct assh_event_channel_confirmation_s channel_confirmation; | |
| struct assh_event_channel_failure_s channel_failure; | |
| struct assh_event_channel_data_s channel_data; | |
| struct assh_event_channel_window_s channel_window; | |
| struct assh_event_channel_eof_s channel_eof; | |
| struct assh_event_channel_close_s channel_close; | |
| struct assh_event_channel_abort_s channel_abort; |
struct assh_event_request_abort_s [link]
This struct is declared in assh/assh_connection.h source file, line 298.
This event is reported when a channel is closing or the connection is ending and some associated requests have been postponed.
The struct assh_request_s object will be released when calling the assh_event_done function.
See also ASSH_EVENT_REQUEST_ABORT.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the associated channel object if any. (ro) |
| struct assh_request_s *const rq; | A pointer to the request object. (ro) |
struct assh_event_request_failure_s [link]
This struct is declared in assh/assh_connection.h source file, line 385.
This event is reported after a successful call to the assh_request function when the want_reply parameter was set and the remote host replied with a failure message.
The ch field is NULL for global requests.
The request object is released when the assh_event_done function is called.
See also ASSH_EVENT_REQUEST_FAILURE.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the associated channel object if any. (ro) |
| struct assh_request_s *const rq; | A pointer to the request object. (ro) |
| const enum assh_request_reason_e reason; | The request failure reason. (ro) |
struct assh_event_request_s [link]
This struct is declared in assh/assh_connection.h source file, line 268.
This event is reported when the assh_service_connection service is running and an SSH_MSG_GLOBAL_REQUEST message or an SSH_MSG_CHANNEL_REQUEST message has been received. The request type name and associated specific request data are available in the type and rq_data fields. These buffers will not remain valid after the call to assh_event_done.
The ch field is NULL for global requests.
If the rq pointer field is not NULL, the remote host excepts a reply for this request. In this case, the reply field can be set to ASSH_CONNECTION_REPLY_SUCCESS in order to successfully acknowledge the request and some response data may optionally be passed in the rsp_data field. The default value of the reply field is ASSH_CONNECTION_REPLY_FAILED. In both cases, the struct assh_request_s object will be release when calling the assh_event_done function.
When it's not possible decide how to acknowledge the request before calling the assh_event_done function, the ASSH_CONNECTION_REPLY_POSTPONED value can be used. In this case, either the assh_request_success_reply function or the assh_request_failed_reply function must be called later in order to release the struct assh_request_s object and send the reply expected by the remote host. Care should be taken not to postpone too many requests in order to avoid resource-exhaustion attacks.
Unlike channel open messages, the protocol requires that request replies are sent in order. This means that a postponed request reply will prevent subsequent request reply messages on the same channel from being transmitted to the remote host.
When some incoming requests are left unreplied when the channel is closing or the connection is ending, ASSH_EVENT_REQUEST_ABORT events are reported.
See also ASSH_EVENT_REQUEST.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the associated channel object if any. (ro) |
| struct assh_request_s *const rq; | A pointer to the request object. (ro) |
| const struct assh_cbuffer_s type; | The textual type of the request. (ro) |
| const struct assh_cbuffer_s rq_data; | The associated data if any. (ro) |
| enum assh_connection_reply_e reply; | Used to store the request reply. (rw) |
| struct assh_cbuffer_s rsp_data; | Used to store the request reply data if any. (rw) |
struct assh_event_request_success_s [link]
This struct is declared in assh/assh_connection.h source file, line 361.
This event is reported after a successful call to the assh_request function when the want_reply parameter was set and the remote host replied with a success message.
Some response specific data may be available in the rsp_data field.
The ch field is NULL for global requests.
The request object is released when the assh_event_done function is called.
See also ASSH_EVENT_REQUEST_SUCCESS.
| Field | Description |
|---|---|
| struct assh_channel_s *const ch; | A pointer to the associated channel object if any. (ro) |
| struct assh_request_s *const rq; | A pointer to the request object. (ro) |
| const struct assh_cbuffer_s rsp_data; | The request reply associated data if any. (ro) |
assh_status_t assh_request(struct assh_session_s *s, struct assh_channel_s *ch, const char *type, size_t type_len, const uint8_t *data, size_t data_len, struct assh_request_s **rq) [link]
This function is declared in assh/assh_connection.h source file, line 423.
This function sends either an SSH_MSG_GLOBAL_REQUEST message or an SSH_MSG_CHANNEL_REQUEST message to the remote host. If the ch parameter is NULL, a global request is sent.
If the rq parameter is not NULL, a reply from the remote host is expected.
If this function is called after disconnection or on a closing channel which has not yet been reported by the appropriate event, this function returns ASSH_NO_DATA to indicate that it was not able to send the request.
When this function is successful and the request expects a reply, either an ASSH_EVENT_REQUEST_SUCCESS event or an ASSH_EVENT_REQUEST_FAILURE event will be reported at some point by the assh_event_get function.
This function must not be called if the last event has not been acknowledged by calling the assh_event_done function.
struct assh_channel_s * assh_request_channel(const struct assh_request_s *rq) [link]
This function is declared in assh/assh_connection.h source file, line 220.
This function returns the channel associated to a request. It returns NULL for global requests.
assh_status_t assh_request_failed_reply(struct assh_request_s *rq) [link]
This function is declared in assh/assh_connection.h source file, line 341.
This function has the same behavior as assh_request_success_reply but reports a request failure to the remote host.
void * assh_request_pv(const struct assh_request_s *rq) [link]
This function is declared in assh/assh_connection.h source file, line 203.
This function returns the value of the request private pointer.
uintptr_t assh_request_pvi(const struct assh_request_s *rq) [link]
This function is declared in assh/assh_connection.h source file, line 211.
This function returns the value of the request private integer.
enum assh_request_reason_e [link]
This enum is declared in assh/assh_connection.h source file, line 141.
This enum specifies request reply failure reasons.
| Identifier | Value | Description |
|---|---|---|
| ASSH_REQUEST_SESSION_DISCONNECTED | 0 | |
| ASSH_REQUEST_FAILED | 1 |
struct assh_request_s [link]
This struct is declared in assh/assh_connection.h source file, line 69.
This struct is the ssh-connection service request object.
Requests are created either by calling the assh_request function or when the ASSH_EVENT_REQUEST event is reported.
The library user does not have to destroy request objects explicitly.
See also connapi.
struct assh_session_s * assh_request_session(const struct assh_request_s *rq) [link]
This function is declared in assh/assh_connection.h source file, line 215.
This function returns the session associated to a request.
void assh_request_set_pv(struct assh_request_s *rq, void *pv) [link]
This function is declared in assh/assh_connection.h source file, line 200.
This function sets the value of the request private pointer. This shares the storage with the private integer.
See also assh_request_set_pvi.
void assh_request_set_pvi(struct assh_request_s *rq, uintptr_t pv) [link]
This function is declared in assh/assh_connection.h source file, line 208.
This function sets the value of the request private integer. This shares the storage with the private pointer.
See also assh_request_set_pv.
enum assh_request_state_e assh_request_state(struct assh_request_s *rq) [link]
This function is declared in assh/assh_connection.h source file, line 224.
This function returns the current channel status
enum assh_request_state_e [link]
This enum is declared in assh/assh_connection.h source file, line 73.
This enum specifies struct assh_request_s status.
| Identifier | Value | Description |
|---|---|---|
| ASSH_REQUEST_ST_WAIT_REPLY | 0 | Outgoing request; not replied by remote host. |
| ASSH_REQUEST_ST_REPLY_POSTPONED | 1 | Incoming request; reply postponed by the library user. |
| ASSH_REQUEST_ST_REPLY_READY | 2 | Incoming request; blocked by previous requests in the queue. |
assh_status_t assh_request_success_reply(struct assh_request_s *rq, const uint8_t *rsp_data, size_t rsp_data_len) [link]
This function is declared in assh/assh_connection.h source file, line 334.
This function acknowledges and releases a previously received global or channel request which has not been replied yet due to the use of the ASSH_CONNECTION_REPLY_POSTPONED value in the reply field of the ASSH_EVENT_REQUEST event.
Response data may optionally be included in the response by using the rsp_data and rsp_data_len parameters, as allowed by the protocol.
If multiple requests on the same queue (global or per channel) are waiting for a reply, the replies will be sent in the received order as required by the ssh protocol. This function can be called in any order but any unreplied request will further postpone replies to subsequent requests.
If this function is called on a closing channel which has not yet been reported by the appropriate event, this function returns ASSH_NO_DATA to indicate that it was not able to send the reply.
This function must not be called if the last event has not been acknowledged by calling the assh_event_done function.
See also assh_request_failed_reply.
const struct assh_service_s assh_service_connection [link]
This constant is declared in assh/assh_connection.h source file, line 985.
This constant is the connection protocol service module descriptor.
See also coremod.