NetBurner 3.1
nbssh.h
1 /* Revision: 2.8.7 */
2 
3 /******************************************************************************
4 * Copyright 1998-2018 NetBurner, Inc. ALL RIGHTS RESERVED
5 *
6 * Permission is hereby granted to purchasers of NetBurner Hardware to use or
7 * modify this computer program for any use as long as the resultant program
8 * is only executed on NetBurner provided hardware.
9 *
10 * No other rights to use this program or its derivatives in part or in
11 * whole are granted.
12 *
13 * It may be possible to license this or other NetBurner software for use on
14 * non-NetBurner Hardware. Contact sales@Netburner.com for more information.
15 *
16 * NetBurner makes no representation or warranties with respect to the
17 * performance of this computer program, and specifically disclaims any
18 * responsibility for any damages, special or consequential, connected with
19 * the use of this program.
20 *
21 * NetBurner
22 * 5405 Morehouse Dr.
23 * San Diego, CA 92121
24 * www.netburner.com
25 ******************************************************************************/
26 
27 #ifndef _NB_SSH_H_
28 #define _NB_SSH_H_
29 
30 /*
31  ******************************************************************************
32  *
33  * Definitions
34  *
35  ******************************************************************************
36  */
37 /* Default SSH Server Port*/
38 #define SSH_SECURE_SHELL_IANA_ASSIGNED_PORT ( 22 )
39 
40 /* Connection timeout */
41 #ifdef _DEBUG
42  #define SSH_CONNECTION_TIMEOUT_IN_SECS ( 360 )
43 #else /* #ifdef _DEBUG */
44  #define SSH_CONNECTION_TIMEOUT_IN_SECS ( 180 )
45 #endif /* #ifdef _DEBUG */
46 
47 /* Default static key size, no choice is 1024 */
48 /* #define SSH_RSA_KEY_DEFAULT_512 ( 512 ) */
49 #define SSH_RSA_KEY_DEFAULT_1024 ( 1024 )
50 /* #define SSH_RSA_KEY_DEFAULT_2048 ( 2048 ) */
51 
52 #define SSH_DSS_KEY_DEFAULT_512 ( 512 )
53 /* #define SSH_DSS_KEY_DEFAULT_1024 ( 1024 ) */
54 /* #define SSH_DSS_KEY_DEFAULT_2048 ( 2048 ) */
55 
56 /* SSH Unigue Errors */
57 #define SSH_ERROR_FAILED_NEGOTIATION (-301)
58 #define SSH_ERROR_FAILED_SESSION_FAILED (-300)
59 
60 /* SSH Key */
61 #define SSH_KEY_RSA ( 1 )
62 #define SSH_KEY_DSS ( 2 )
63 
64 /*
65  ******************************************************************************
66  *
67  * SSH "C" Library Interface
68  *
69  ******************************************************************************
70  */
71 #ifdef __cplusplus
72 extern "C" {
73 #endif
74 /*
75  ******************************************************************************
76 
77  User provided SSH username and passuint16_t authenticate routine.
78 
79  Parameters:
80  usernamePtr - Username in plain text
81  passuint16_tPtr - Passuint16_t in plain text
82 
83  Return:
84  1 - Authenticated, all else error
85 
86  Notes:
87  None
88 
89  ******************************************************************************
90  */
91 typedef int ( *sshUserAuthenticateFn )( const char* usernamePtr,
92  const char* passuint16_tPtr );
93 
94 /*
95  ******************************************************************************
96 
97  Set/Get user provided SSH username and passuint16_t authenticate routine.
98 
99  Parameters:
100  sshUserAuthenticateFnPtr - User provided user authentication routine
101 
102  Return:
103  None
104 
105  Notes:
106  If not provided any user name and passuint16_t provided will succeed.
107 
108  ******************************************************************************
109  */
110 void SshSetUserAuthenticate( sshUserAuthenticateFn sshUserAuthenticateFnPtr );
111 sshUserAuthenticateFn SshGetUserAuthenticate( void );
112 
113 /*
114  ******************************************************************************
115 
116  User provided SSH key
117 
118  Parameters:
119  keyRequested - Type key requested
120  SSH_KEY_RSA
121  SSH_KEY_DSS
122  keyBufferPtr - Key from user storage
123  keyLengthPtr - Size of key in 8 bit uint8_ts
124 
125  Return:
126  0 - key and length is valid, -1 - key requested not available
127 
128  Notes:
129  openSS(L|H) key pair, PEM encoded, no encrypted or with passphrase.
130  Key must be valid. Each type asked for once at at startup.
131  The buffer containing the key will NOT be deallocated.
132  Server will disable task scheduling calling OSLock, copy contents, then
133  call OSUnlock
134 
135  ******************************************************************************
136  */
137 typedef int ( *sshUserGetKeyFn )( int keyRequested,
138  const unsigned char** keyBufferPtr, int* keyLengthPtr );
139 
140 /*
141  ******************************************************************************
142 
143  Set/Get user provided SSH key provision routine.
144 
145  Parameters:
146  sshUserGetKeyFnPtr - User provided key provision routine
147 
148  Return:
149  None
150 
151  Notes:
152  If not installed the default key will be used.
153 
154  ******************************************************************************
155  */
156 void SshSetUserGetKey( sshUserGetKeyFn sshUserGetKeyFnPtr );
157 sshUserGetKeyFn SshGetUserGetKey( void );
158 
159 /*
160  ******************************************************************************
161 
162  Convert PEM decoded openSSL key to dropbear SSH format
163 
164  Parameters:
165  dropbearKeyPtr - dropbear key buffer
166  openKeyPtr - openSSL key
167  openKeyLength - openSSL key length
168  keyTypePtr - Type key detected.
169  0 - None
170  1 - RSA
171  2 - DSA
172  Return:
173  >0 successfully decoded, 0 problems
174 
175  Notes:
176  None
177 
178  ******************************************************************************
179  */
180 int SshConvertDecodedOpenSSLKey( unsigned char* dropbearKeyPtr,
181  const unsigned char* openKeyPtr, unsigned int openKeyLength,
182  int keyType );
183 
184 /*
185  ******************************************************************************
186 
187  Validate PEM encoded openSS(L|H) key
188 
189  Parameters:
190  candidateKey - PEM encoded key in buffer
191  candidateKeySize - Size of key in uint8_ts
192  keyTypePtr - Type key detected.
193  0 - None
194  1 - RSA
195  2 - DSA
196  Return:
197  TRUE - Valid RSA or DSA key
198 
199  Notes:
200  None
201 
202  ******************************************************************************
203  */
204 BOOL SshValidateKey( const char* candidateKey, int candidateKeySize,
205  int* keyTypePtr );
206 
207 /*
208  ******************************************************************************
209 
210  Write public key to file descriptor
211 
212  Parameters:
213  publicKeyFd - Open target file descriptor
214  candidateKey - Binary key in buffer
215  candidateKeySize - Size of key in uint8_ts
216 
217  Return:
218  TRUE - Valid RSA or DSA key written to fd, else error message
219 
220  Notes:
221  None
222 
223  ******************************************************************************
224  */
225 BOOL SshWritePublicKey(int publicKeyFd, unsigned char *candidateKey,
226  int candidateKeySize );
227 
228 /*
229  ******************************************************************************
230 
231  User provided SSH channel session request routine
232 
233  Parameters:
234  requestTypePtr - Channel request
235  "pty-req"
236  "shell"
237 
238  Return:
239  0 - OK send channel success message SSH_MSG_CHANNEL_SUCCESS (99)
240  all else send channel failure message SSH_MSG_CHANNEL_FAILURE (100)
241 
242  Notes:
243  Called for channel request SSH_MSG_CHANNEL_REQUEST (98)
244  See RFC 4250 for pty-req parameters
245 
246  ******************************************************************************
247  */
248 typedef int ( *sshChannelSessionRequestFn )( const char* requestTypePtr );
249 
250 /*
251  ******************************************************************************
252 
253  Install user provided SSH session request routine
254 
255  Parameters:
256  chanessionrequestFnPtr - Channel request routine
257 
258  Return:
259  None
260 
261  Notes:
262  If not provided the "shell" request will result in a negotiated session
263  all others ignored.
264 
265  ******************************************************************************
266  */
267 void SshSetchansessionrequest( sshChannelSessionRequestFn FnPtr );
268 
269 /*
270  ******************************************************************************
271 
272  Accepts and negotiates SSH session
273 
274  Parameters:
275  listenFd - fd of listening socket
276  clientAddress - Address of client
277  securePort - Secure port of negotiated socket
278  timeout - Ticks to wait for connection, 0 is infinite
279 
280  Return:
281  >0 the secure file descriptor, <0 problems
282 
283  Notes:
284  TCP_ERR_TIMEOUT Underlying TCP system timed out
285  TCP_ERR_NOCON Confused
286  TCP_ERR_CLOSING The underlying tcp fd was closing.
287  TCP_ERR_NOSUCH_SOCKET The fd listen socket was invalid.
288  TCP_ERR_NONE_AVAIL No free sockets to return.
289  TCP_ERR_CON_RESET The connection was reset by the remote device.
290  TCP_ERR_CON_ABORT The connection was aborted by the remote device.
291  SSH_ERROR_FAILED_NEGOTIATION The SSL system failed to successfully negotiate a connection.
292 
293  ******************************************************************************
294  */
295 int SshAccept( int listenFd, IPADDR* clientAddress, uint16_t* securePort,
296  uint16_t timeout );
297 
298 /*
299  ******************************************************************************
300 
301  Negotiates SSH session
302 
303  Parameters:
304  acceptedSocketFILEptr - Not yet secure socket FILE pointer
305 
306 
307  Return:
308  Pointer to sshSession object, NULL for unsuccessful
309 
310  Notes:
311  Successful negotiation results in resetting FILE file descriptor to
312  secure file descriptor.
313 
314  ******************************************************************************
315  */
316 void* SshNegotiateSession( FILE* acceptedSocketFILEptr );
317 
318 /*
319  ******************************************************************************
320 
321  Print SSH Statistics using iprintf
322 
323  Parameters:
324  secureFd - Secure file descriptor
325 
326 
327  Return:
328  None
329 
330  Notes:
331  None
332 
333  ******************************************************************************
334  */
335 void SshPrintStatistics( int secureFd );
336 
337 /*
338  ******************************************************************************
339 
340  Detected key size
341 
342  Parameters:
343  keyType - SSH_KEY_RSA or SSH_KEY_DSS
344 
345  Return:
346  Key size
347 
348  Notes:
349  After key is in use (SshConnect) or successfully validated
350  (SshValidateKey), key size is set to the last key used of each type.
351 
352  ******************************************************************************
353  */
354 int SshGetKeySize( int keyType );
355 
356 /*
357  ******************************************************************************
358 
359  Change SSH session task priority
360 
361  Parameters:
362  taskPriority - Must be greater than MAIN_PRIO and less than 64
363 
364  Return:
365  TRUE - success, FALSE - problems
366 
367  Notes:
368  All used priorities are defined in constants.h.
369  All task priorities have to be unique.
370  The default priority for the SSH session task is SSH_TASK_PRIORITY
371 
372  ******************************************************************************
373  */
374 BOOL SshSetTaskPriority(uint8_t taskPriority);
375 
376 #ifdef __cplusplus
377 };
378 #endif
379 #endif /* _NB_SSH_H_ */
380 
381 
Used to hold and manipulate IPv4 and IPv6 addresses in dual stack mode.
Definition: ipv6_addr.h:28