Go to the documentation of this file.
1 /**
2  * @file shell_client.h
3  * @brief SSH secure shell client
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2019-2024 Oryx Embedded SARL. All rights reserved.
10  *
11  * This file is part of CycloneSSH Open.
12  *
13  * This program is free software; you can redistribute it and/or
14  * modify it under the terms of the GNU General Public License
15  * as published by the Free Software Foundation; either version 2
16  * of the License, or (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
26  *
27  * @author Oryx Embedded SARL (www.oryx-embedded.com)
28  * @version 2.4.4
29  **/
30 
31 #ifndef _SHELL_CLIENT_H
32 #define _SHELL_CLIENT_H
33 
34 //Dependencies
35 #include "ssh/ssh.h"
36 
37 //Shell client support
38 #ifndef SHELL_CLIENT_SUPPORT
39  #define SHELL_CLIENT_SUPPORT DISABLED
40 #elif (SHELL_CLIENT_SUPPORT != ENABLED && SHELL_CLIENT_SUPPORT != DISABLED)
41  #error SHELL_CLIENT_SUPPORT parameter is not valid
42 #endif
43 
44 //Default timeout
45 #ifndef SHELL_CLIENT_DEFAULT_TIMEOUT
46  #define SHELL_CLIENT_DEFAULT_TIMEOUT 20000
47 #elif (SHELL_CLIENT_DEFAULT_TIMEOUT < 1000)
48  #error SHELL_CLIENT_DEFAULT_TIMEOUT parameter is not valid
49 #endif
50 
51 //Size of the buffer for input/output operations
52 #ifndef SHELL_CLIENT_BUFFER_SIZE
53  #define SHELL_CLIENT_BUFFER_SIZE 512
54 #elif (SHELL_CLIENT_BUFFER_SIZE < 256)
55  #error SHELL_CLIENT_BUFFER_SIZE parameter is not valid
56 #endif
57 
58 //Forward declaration of ShellClientContext structure
59 struct _ShellClientContext;
60 #define ShellClientContext struct _ShellClientContext
61 
62 //C++ guard
63 #ifdef __cplusplus
64 extern "C" {
65 #endif
66 
67 
68 /**
69  * @brief Shell client state
70  **/
71 
72 typedef enum
73 {
87 
88 
89 /**
90  * @brief SSH initialization callback function
91  **/
92 
95 
96 
97 /**
98  * @brief Shell client context
99  **/
100 
102 {
103  ShellClientState state; ///<Shell client state
104  NetInterface *interface; ///<Underlying network interface
105  ShellClientSshInitCallback sshInitCallback; ///<SSH initialization callback function
106  systime_t timeout; ///<Timeout value
107  systime_t timestamp; ///<Timestamp to manage timeout
108  char_t buffer[SHELL_CLIENT_BUFFER_SIZE]; ///<Memory buffer for input/output operations
109  size_t bufferLen; ///<Length of the buffer, in bytes
110  size_t bufferPos; ///<Current position in the buffer
111  uint32_t exitStatus; ///<Exit status
112  SshContext sshContext; ///<SSH context
113  SshConnection sshConnection; ///<SSH connection
114  SshChannel sshChannel; ///<SSH channel
115 };
116 
117 
118 //Shell client related functions
120 
122  ShellClientSshInitCallback callback);
123 
125 
127  NetInterface *interface);
128 
130  const IpAddr *serverIpAddr, uint16_t serverPort);
131 
133  const char_t *command, ...);
134 
136  const char_t *command);
137 
139  size_t length, size_t *written, uint_t flags);
140 
142 
144  size_t size, size_t *received, uint_t flags);
145 
148 
151 
153 
154 //C++ guard
155 #ifdef __cplusplus
156 }
157 #endif
158 
159 #endif
@ SHELL_CLIENT_STATE_CHANNEL_CLOSE
Definition: shell_client.h:83
error_t shellClientCloseStream(ShellClientContext *context)
Close stream.
Definition: shell_client.c:737
@ SHELL_CLIENT_STATE_CHANNEL_REQUEST
Definition: shell_client.h:80
SshConnection sshConnection
SSH connection.
Definition: shell_client.h:113
error_t shellClientDisconnect(ShellClientContext *context)
Gracefully disconnect from the SSH server.
Definition: shell_client.c:865
error_t shellClientBindToInterface(ShellClientContext *context, NetInterface *interface)
Bind the shell client to a particular network interface.
Definition: shell_client.c:123
@ SHELL_CLIENT_STATE_CONNECTING_1
Definition: shell_client.h:75
IP network address.
Definition: ip.h:90
@ SHELL_CLIENT_STATE_DISCONNECTED
Definition: shell_client.h:74
@ SHELL_CLIENT_STATE_CHANNEL_INIT
Definition: shell_client.h:78
@ SHELL_CLIENT_STATE_DISCONNECTING_1
Definition: shell_client.h:84
error_t shellClientInit(ShellClientContext *context)
Initialize shell client context.
Definition: shell_client.c:54
uint8_t data[]
Definition: ethernet.h:222
error_t(* ShellClientSshInitCallback)(ShellClientContext *context, SshContext *sshContext)
SSH initialization callback function.
Definition: shell_client.h:93
#define ShellClientContext
Definition: shell_client.h:60
error_t shellClientSetTimeout(ShellClientContext *context, systime_t timeout)
Set communication timeout.
Definition: shell_client.c:102
@ SHELL_CLIENT_STATE_CHANNEL_REPLY
Definition: shell_client.h:81
size_t bufferLen
Length of the buffer, in bytes.
Definition: shell_client.h:109
#define SHELL_CLIENT_BUFFER_SIZE
Definition: shell_client.h:53
error_t shellClientConnect(ShellClientContext *context, const IpAddr *serverIpAddr, uint16_t serverPort)
Establish a connection with the specified SSH server.
Definition: shell_client.c:146
#define SshContext
Definition: ssh.h:870
error_t
Error codes.
Definition: error.h:43
error_t shellClientReadStream(ShellClientContext *context, void *data, size_t size, size_t *received, uint_t flags)
Read from stdout stream.
Definition: shell_client.c:650
Shell client context.
Definition: shell_client.h:102
ShellClientState state
Shell client state.
Definition: shell_client.h:103
error_t shellClientRegisterSshInitCallback(ShellClientContext *context, ShellClientSshInitCallback callback)
Register SSH initialization callback function.
Definition: shell_client.c:80
size_t bufferPos
Current position in the buffer.
Definition: shell_client.h:110
#define NetInterface
Definition: net.h:36
@ SHELL_CLIENT_STATE_CHANNEL_DATA
Definition: shell_client.h:82
NetInterface * interface
Underlying network interface.
Definition: shell_client.h:104
@ SHELL_CLIENT_STATE_CONNECTED
Definition: shell_client.h:77
uint8_t length
Definition: tcp.h:368
systime_t timeout
Timeout value.
Definition: shell_client.h:106
error_t shellClientExecuteCommand(ShellClientContext *context, const char_t *command)
Execute a command line.
Definition: shell_client.c:317
uint32_t systime_t
System time.
uint8_t flags
Definition: tcp.h:351
char char_t
Definition: compiler_port.h:48
@ SHELL_CLIENT_STATE_CHANNEL_OPEN
Definition: shell_client.h:79
#define SshConnection
Definition: ssh.h:874
error_t shellClientClose(ShellClientContext *context)
Close the connection with the SSH server.
Definition: shell_client.c:964
SshChannel sshChannel
SSH channel.
Definition: shell_client.h:114
systime_t timestamp
Timestamp to manage timeout.
Definition: shell_client.h:107
ShellClientSshInitCallback sshInitCallback
SSH initialization callback function.
Definition: shell_client.h:105
error_t shellClientFormatCommand(ShellClientContext *context, const char_t *command,...)
Format a command line.
Definition: shell_client.c:238
SshContext sshContext
SSH context.
Definition: shell_client.h:112
char_t buffer[SHELL_CLIENT_BUFFER_SIZE]
Memory buffer for input/output operations.
Definition: shell_client.h:108
void shellClientDeinit(ShellClientContext *context)
Release shell client context.
Definition: shell_client.c:985
ShellClientState
Shell client state.
Definition: shell_client.h:73
unsigned int uint_t
Definition: compiler_port.h:50
error_t shellClientWriteStream(ShellClientContext *context, const void *data, size_t length, size_t *written, uint_t flags)
Write to stdin stream.
Definition: shell_client.c:520
Secure Shell (SSH)
@ SHELL_CLIENT_STATE_DISCONNECTING_2
Definition: shell_client.h:85
uint32_t shellClientGetExitStatus(ShellClientContext *context)
Retrieve exit status.
Definition: shell_client.c:838
uint32_t exitStatus
Exit status.
Definition: shell_client.h:111
#define SshChannel
Definition: ssh.h:878
error_t shellClientFlushStream(ShellClientContext *context)
Flush stdin stream.
Definition: shell_client.c:612
@ SHELL_CLIENT_STATE_CONNECTING_2
Definition: shell_client.h:76