ssh.c File Reference

Secure Shell (SSH) More...

#include "ssh/ssh.h"
#include "ssh/ssh_algorithms.h"
#include "ssh/ssh_channel.h"
#include "ssh/ssh_key_import.h"
#include "ssh/ssh_cert_import.h"
#include "ssh/ssh_misc.h"
#include "pkix/pem_import.h"
#include "debug.h"

Go to the source code of this file.

Macros

#define TRACE_LEVEL   SSH_TRACE_LEVEL
 

Functions

error_t sshInit (SshContext *context, SshConnection *connections, uint_t numConnections, SshChannel *channels, uint_t numChannels)
 SSH context initialization. More...
 
error_t sshSetOperationMode (SshContext *context, SshOperationMode mode)
 Set operation mode (client or server) More...
 
error_t sshSetPrng (SshContext *context, const PrngAlgo *prngAlgo, void *prngContext)
 Set the pseudo-random number generator to be used. More...
 
error_t sshSetUsername (SshContext *context, const char_t *username)
 Set the user name to be used for authentication. More...
 
error_t sshSetPassword (SshContext *context, const char_t *password)
 Set the password to be used for authentication. More...
 
error_t sshRegisterHostKeyVerifyCallback (SshContext *context, SshHostKeyVerifyCallback callback)
 Register host key verification callback function. More...
 
error_t sshRegisterCertVerifyCallback (SshContext *context, SshCertVerifyCallback callback)
 Register certificate verification callback function. More...
 
error_t sshRegisterCaPublicKeyVerifyCallback (SshContext *context, SshCaPublicKeyVerifyCallback callback)
 Register CA public key verification callback function. More...
 
error_t sshRegisterPublicKeyAuthCallback (SshContext *context, SshPublicKeyAuthCallback callback)
 Register public key authentication callback function. More...
 
error_t sshRegisterCertAuthCallback (SshContext *context, SshCertAuthCallback callback)
 Register certificate authentication callback function. More...
 
error_t sshRegisterPasswordAuthCallback (SshContext *context, SshPasswordAuthCallback callback)
 Register password authentication callback function. More...
 
error_t sshRegisterPasswordChangeCallback (SshContext *context, SshPasswordChangeCallback callback)
 Register password change callback function. More...
 
error_t sshRegisterSignGenCallback (SshContext *context, SshSignGenCallback callback)
 Register signature generation callback function. More...
 
error_t sshRegisterSignVerifyCallback (SshContext *context, SshSignVerifyCallback callback)
 Register signature verification callback function. More...
 
error_t sshRegisterEcdhKeyPairGenCallback (SshContext *context, SshEcdhKeyPairGenCallback callback)
 Register ECDH key pair generation callback function. More...
 
error_t sshRegisterEcdhSharedSecretCalcCallback (SshContext *context, SshEcdhSharedSecretCalcCallback callback)
 Register ECDH shared secret calculation callback function. More...
 
error_t sshRegisterGlobalRequestCallback (SshContext *context, SshGlobalReqCallback callback, void *param)
 Register global request callback function. More...
 
error_t sshUnregisterGlobalRequestCallback (SshContext *context, SshGlobalReqCallback callback)
 Unregister global request callback function. More...
 
error_t sshRegisterChannelRequestCallback (SshContext *context, SshChannelReqCallback callback, void *param)
 Register channel request callback function. More...
 
error_t sshUnregisterChannelRequestCallback (SshContext *context, SshChannelReqCallback callback)
 Unregister channel request callback function. More...
 
error_t sshRegisterChannelOpenCallback (SshContext *context, SshChannelOpenCallback callback, void *param)
 Register channel open callback function. More...
 
error_t sshUnregisterChannelOpenCallback (SshContext *context, SshChannelOpenCallback callback)
 Unregister channel open callback function. More...
 
error_t sshRegisterConnectionOpenCallback (SshContext *context, SshConnectionOpenCallback callback, void *param)
 Register connection open callback function. More...
 
error_t sshUnregisterConnectionOpenCallback (SshContext *context, SshConnectionOpenCallback callback)
 Unregister connection open callback function. More...
 
error_t sshRegisterConnectionCloseCallback (SshContext *context, SshConnectionCloseCallback callback, void *param)
 Register connection close callback function. More...
 
error_t sshUnregisterConnectionCloseCallback (SshContext *context, SshConnectionCloseCallback callback)
 Unregister connection close callback function. More...
 
error_t sshRegisterKeyLogCallback (SshContext *context, SshKeyLogCallback callback)
 Register key logging callback function (for debugging purpose only) More...
 
error_t sshLoadRsaKey (SshContext *context, uint_t index, const char_t *publicKey, size_t publicKeyLen, const char_t *privateKey, size_t privateKeyLen, const char_t *password)
 Load transient RSA key (for RSA key exchange) More...
 
error_t sshUnloadRsaKey (SshContext *context, uint_t index)
 Unload transient RSA key (for RSA key exchange) More...
 
error_t sshLoadDhGexGroup (SshContext *context, uint_t index, const char_t *dhParams, size_t dhParamsLen)
 Load Diffie-Hellman group. More...
 
error_t sshUnloadDhGexGroup (SshContext *context, uint_t index)
 Unload Diffie-Hellman group. More...
 
error_t sshLoadHostKey (SshContext *context, uint_t index, const char_t *publicKey, size_t publicKeyLen, const char_t *privateKey, size_t privateKeyLen, const char_t *password)
 Load entity's host key. More...
 
error_t sshUnloadHostKey (SshContext *context, uint_t index)
 Unload entity's host key. More...
 
error_t sshLoadCertificate (SshContext *context, uint_t index, const char_t *cert, size_t certLen, const char_t *privateKey, size_t privateKeyLen, const char_t *password)
 Load entity's certificate. More...
 
error_t sshUnloadCertificate (SshContext *context, uint_t index)
 Unload entity's certificate. More...
 
error_t sshSetPasswordChangePrompt (SshConnection *connection, const char_t *prompt)
 Set password change prompt message. More...
 
SshChannelsshCreateChannel (SshConnection *connection)
 Create a new SSH channel. More...
 
error_t sshSetChannelTimeout (SshChannel *channel, systime_t timeout)
 Set timeout for read/write operations. More...
 
error_t sshWriteChannel (SshChannel *channel, const void *data, size_t length, size_t *written, uint_t flags)
 Write data to the specified channel. More...
 
error_t sshReadChannel (SshChannel *channel, void *data, size_t size, size_t *received, uint_t flags)
 Receive data from the specified channel. More...
 
error_t sshPollChannels (SshChannelEventDesc *eventDesc, uint_t size, OsEvent *extEvent, systime_t timeout)
 Wait for one of a set of channels to become ready to perform I/O. More...
 
error_t sshCloseChannel (SshChannel *channel)
 Close channel. More...
 
void sshDeleteChannel (SshChannel *channel)
 Release channel. More...
 
void sshDeinit (SshContext *context)
 Release SSH context. More...
 

Detailed Description

Secure Shell (SSH)

License

SPDX-License-Identifier: GPL-2.0-or-later

Copyright (C) 2019-2024 Oryx Embedded SARL. All rights reserved.

This file is part of CycloneSSH Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Author
Oryx Embedded SARL (www.oryx-embedded.com)
Version
2.4.0

Definition in file ssh.c.

Macro Definition Documentation

◆ TRACE_LEVEL

#define TRACE_LEVEL   SSH_TRACE_LEVEL

Definition at line 32 of file ssh.c.

Function Documentation

◆ sshCloseChannel()

error_t sshCloseChannel ( SshChannel channel)

Close channel.

Parameters
[in]channelSSH channel handle
Returns
Error code

Definition at line 2465 of file ssh.c.

◆ sshCreateChannel()

SshChannel* sshCreateChannel ( SshConnection connection)

Create a new SSH channel.

Parameters
[in]connectionPointer to the SSH connection
Returns
Handle referencing the newly created SSH channel

Definition at line 1964 of file ssh.c.

◆ sshDeinit()

void sshDeinit ( SshContext context)

Release SSH context.

Parameters
[in]contextPointer to the SSH context

Definition at line 2556 of file ssh.c.

◆ sshDeleteChannel()

void sshDeleteChannel ( SshChannel channel)

Release channel.

Parameters
[in]channelSSH channel handle

Definition at line 2536 of file ssh.c.

◆ sshInit()

error_t sshInit ( SshContext context,
SshConnection connections,
uint_t  numConnections,
SshChannel channels,
uint_t  numChannels 
)

SSH context initialization.

Parameters
[in]contextPointer to the SSH context
[in]connectionsSSH connections
[in]numConnectionsMaximum number of SSH connections
[in]channelsSSH channels
[in]numChannelsMaximum number of SSH channels
Returns
Error code

Definition at line 58 of file ssh.c.

◆ sshLoadCertificate()

error_t sshLoadCertificate ( SshContext context,
uint_t  index,
const char_t cert,
size_t  certLen,
const char_t privateKey,
size_t  privateKeyLen,
const char_t password 
)

Load entity's certificate.

Parameters
[in]contextPointer to the SSH context
[in]indexZero-based index identifying a slot
[in]certCertificate (OpenSSH format). This parameter is taken as reference
[in]certLenLength of the certificate
[in]privateKeyPrivate key (PEM or OpenSSH format). This parameter is taken as reference
[in]privateKeyLenLength of the private key
[in]passwordNULL-terminated string containing the password. This parameter is required if the private key is encrypted
Returns
Error code

Definition at line 1682 of file ssh.c.

◆ sshLoadDhGexGroup()

error_t sshLoadDhGexGroup ( SshContext context,
uint_t  index,
const char_t dhParams,
size_t  dhParamsLen 
)

Load Diffie-Hellman group.

Parameters
[in]contextPointer to the SSH context
[in]indexZero-based index identifying a slot
[in]dhParamsDiffie-Hellman parameters (PEM format). This parameter is taken as reference
[in]dhParamsLenLength of the Diffie-Hellman parameters
Returns
Error code

Definition at line 1234 of file ssh.c.

◆ sshLoadHostKey()

error_t sshLoadHostKey ( SshContext context,
uint_t  index,
const char_t publicKey,
size_t  publicKeyLen,
const char_t privateKey,
size_t  privateKeyLen,
const char_t password 
)

Load entity's host key.

Parameters
[in]contextPointer to the SSH context
[in]indexZero-based index identifying a slot
[in]publicKeyPublic key (PEM, SSH2 or OpenSSH format). This parameter is taken as reference
[in]publicKeyLenLength of the public key
[in]privateKeyPrivate key (PEM or OpenSSH format). This parameter is taken as reference
[in]privateKeyLenLength of the private key
[in]passwordNULL-terminated string containing the password. This parameter is required if the private key is encrypted
Returns
Error code

Definition at line 1353 of file ssh.c.

◆ sshLoadRsaKey()

error_t sshLoadRsaKey ( SshContext context,
uint_t  index,
const char_t publicKey,
size_t  publicKeyLen,
const char_t privateKey,
size_t  privateKeyLen,
const char_t password 
)

Load transient RSA key (for RSA key exchange)

Parameters
[in]contextPointer to the SSH context
[in]indexZero-based index identifying a slot
[in]publicKeyRSA public key (PEM, SSH2 or OpenSSH format). This parameter is taken as reference
[in]publicKeyLenLength of the RSA public key
[in]privateKeyRSA private key (PEM or OpenSSH format). This parameter is taken as reference
[in]passwordNULL-terminated string containing the password. This parameter is required if the private key is encrypted
[in]privateKeyLenLength of the RSA private key
Returns
Error code

Definition at line 1087 of file ssh.c.

◆ sshPollChannels()

error_t sshPollChannels ( SshChannelEventDesc eventDesc,
uint_t  size,
OsEvent extEvent,
systime_t  timeout 
)

Wait for one of a set of channels to become ready to perform I/O.

This function determines the status of one or more channels, waiting if necessary, to perform synchronous I/O

Parameters
[in,out]eventDescSet of entries specifying the events the user is interested in
[in]sizeNumber of entries in the descriptor set
[in]extEventExternal event that can abort the wait if necessary (optional)
[in]timeoutMaximum time to wait before returning
Returns
Error code

Definition at line 2376 of file ssh.c.

◆ sshReadChannel()

error_t sshReadChannel ( SshChannel channel,
void *  data,
size_t  size,
size_t *  received,
uint_t  flags 
)

Receive data from the specified channel.

Parameters
[in]channelSSH channel handle
[out]dataBuffer where to store the incoming data
[in]sizeMaximum number of bytes that can be received
[out]receivedNumber of bytes that have been received
[in]flagsSet of flags that influences the behavior of this function
Returns
Error code

Definition at line 2180 of file ssh.c.

◆ sshRegisterCaPublicKeyVerifyCallback()

error_t sshRegisterCaPublicKeyVerifyCallback ( SshContext context,
SshCaPublicKeyVerifyCallback  callback 
)

Register CA public key verification callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackCA public key verification callback function
Returns
Error code

Definition at line 338 of file ssh.c.

◆ sshRegisterCertAuthCallback()

error_t sshRegisterCertAuthCallback ( SshContext context,
SshCertAuthCallback  callback 
)

Register certificate authentication callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackCertificate authentication callback function
Returns
Error code

Definition at line 400 of file ssh.c.

◆ sshRegisterCertVerifyCallback()

error_t sshRegisterCertVerifyCallback ( SshContext context,
SshCertVerifyCallback  callback 
)

Register certificate verification callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackCertificate verification callback function
Returns
Error code

Definition at line 307 of file ssh.c.

◆ sshRegisterChannelOpenCallback()

error_t sshRegisterChannelOpenCallback ( SshContext context,
SshChannelOpenCallback  callback,
void *  param 
)

Register channel open callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackChannel open callback function
[in]paramAn opaque pointer passed to the callback function
Returns
Error code

Definition at line 792 of file ssh.c.

◆ sshRegisterChannelRequestCallback()

error_t sshRegisterChannelRequestCallback ( SshContext context,
SshChannelReqCallback  callback,
void *  param 
)

Register channel request callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackChannel request callback function
[in]paramAn opaque pointer passed to the callback function
Returns
Error code

Definition at line 705 of file ssh.c.

◆ sshRegisterConnectionCloseCallback()

error_t sshRegisterConnectionCloseCallback ( SshContext context,
SshConnectionCloseCallback  callback,
void *  param 
)

Register connection close callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackConnection close callback function
[in]paramAn opaque pointer passed to the callback function
Returns
Error code

Definition at line 966 of file ssh.c.

◆ sshRegisterConnectionOpenCallback()

error_t sshRegisterConnectionOpenCallback ( SshContext context,
SshConnectionOpenCallback  callback,
void *  param 
)

Register connection open callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackConnection open callback function
[in]paramAn opaque pointer passed to the callback function
Returns
Error code

Definition at line 879 of file ssh.c.

◆ sshRegisterEcdhKeyPairGenCallback()

error_t sshRegisterEcdhKeyPairGenCallback ( SshContext context,
SshEcdhKeyPairGenCallback  callback 
)

Register ECDH key pair generation callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackECDH key pair generation callback function
Returns
Error code

Definition at line 555 of file ssh.c.

◆ sshRegisterEcdhSharedSecretCalcCallback()

error_t sshRegisterEcdhSharedSecretCalcCallback ( SshContext context,
SshEcdhSharedSecretCalcCallback  callback 
)

Register ECDH shared secret calculation callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackECDH shared secret calculation callback function
Returns
Error code

Definition at line 586 of file ssh.c.

◆ sshRegisterGlobalRequestCallback()

error_t sshRegisterGlobalRequestCallback ( SshContext context,
SshGlobalReqCallback  callback,
void *  param 
)

Register global request callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackGlobal request callback function
[in]paramAn opaque pointer passed to the callback function
Returns
Error code

Definition at line 618 of file ssh.c.

◆ sshRegisterHostKeyVerifyCallback()

error_t sshRegisterHostKeyVerifyCallback ( SshContext context,
SshHostKeyVerifyCallback  callback 
)

Register host key verification callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackHost key verification callback function
Returns
Error code

Definition at line 281 of file ssh.c.

◆ sshRegisterKeyLogCallback()

error_t sshRegisterKeyLogCallback ( SshContext context,
SshKeyLogCallback  callback 
)

Register key logging callback function (for debugging purpose only)

Parameters
[in]contextPointer to the SSH context
[in]callbackKey logging callback function
Returns
Error code

Definition at line 1052 of file ssh.c.

◆ sshRegisterPasswordAuthCallback()

error_t sshRegisterPasswordAuthCallback ( SshContext context,
SshPasswordAuthCallback  callback 
)

Register password authentication callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackPassword authentication callback function
Returns
Error code

Definition at line 431 of file ssh.c.

◆ sshRegisterPasswordChangeCallback()

error_t sshRegisterPasswordChangeCallback ( SshContext context,
SshPasswordChangeCallback  callback 
)

Register password change callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackPassword change callback function
Returns
Error code

Definition at line 462 of file ssh.c.

◆ sshRegisterPublicKeyAuthCallback()

error_t sshRegisterPublicKeyAuthCallback ( SshContext context,
SshPublicKeyAuthCallback  callback 
)

Register public key authentication callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackPublic key authentication callback function
Returns
Error code

Definition at line 369 of file ssh.c.

◆ sshRegisterSignGenCallback()

error_t sshRegisterSignGenCallback ( SshContext context,
SshSignGenCallback  callback 
)

Register signature generation callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackSignature generation callback function
Returns
Error code

Definition at line 493 of file ssh.c.

◆ sshRegisterSignVerifyCallback()

error_t sshRegisterSignVerifyCallback ( SshContext context,
SshSignVerifyCallback  callback 
)

Register signature verification callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackSignature verification callback function
Returns
Error code

Definition at line 524 of file ssh.c.

◆ sshSetChannelTimeout()

error_t sshSetChannelTimeout ( SshChannel channel,
systime_t  timeout 
)

Set timeout for read/write operations.

Parameters
[in]channelSSH channel handle
[in]timeoutMaximum time to wait
Returns
Error code

Definition at line 2027 of file ssh.c.

◆ sshSetOperationMode()

error_t sshSetOperationMode ( SshContext context,
SshOperationMode  mode 
)

Set operation mode (client or server)

Parameters
[in]contextPointer to the SSH context
[in]modeSpecifies whether this entity is considered a client or a server
Returns
Error code

Definition at line 167 of file ssh.c.

◆ sshSetPassword()

error_t sshSetPassword ( SshContext context,
const char_t password 
)

Set the password to be used for authentication.

Parameters
[in]contextPointer to the SSH context
[in]passwordNULL-terminated string containing the password
Returns
Error code

Definition at line 251 of file ssh.c.

◆ sshSetPasswordChangePrompt()

error_t sshSetPasswordChangePrompt ( SshConnection connection,
const char_t prompt 
)

Set password change prompt message.

Parameters
[in]connectionPointer to the SSH connection
[in]promptNULL-terminated string containing the prompt message
Returns
Error code

Definition at line 1934 of file ssh.c.

◆ sshSetPrng()

error_t sshSetPrng ( SshContext context,
const PrngAlgo prngAlgo,
void *  prngContext 
)

Set the pseudo-random number generator to be used.

Parameters
[in]contextPointer to the SSH context
[in]prngAlgoPRNG algorithm
[in]prngContextPointer to the PRNG context
Returns
Error code

Definition at line 193 of file ssh.c.

◆ sshSetUsername()

error_t sshSetUsername ( SshContext context,
const char_t username 
)

Set the user name to be used for authentication.

Parameters
[in]contextPointer to the SSH context
[in]usernameNULL-terminated string containing the user name
Returns
Error code

Definition at line 221 of file ssh.c.

◆ sshUnloadCertificate()

error_t sshUnloadCertificate ( SshContext context,
uint_t  index 
)

Unload entity's certificate.

Parameters
[in]contextPointer to the SSH context
[in]indexZero-based index identifying a slot
Returns
Error code

Definition at line 1874 of file ssh.c.

◆ sshUnloadDhGexGroup()

error_t sshUnloadDhGexGroup ( SshContext context,
uint_t  index 
)

Unload Diffie-Hellman group.

Parameters
[in]contextPointer to the SSH context
[in]indexZero-based index identifying a slot
Returns
Error code

Definition at line 1311 of file ssh.c.

◆ sshUnloadHostKey()

error_t sshUnloadHostKey ( SshContext context,
uint_t  index 
)

Unload entity's host key.

Parameters
[in]contextPointer to the SSH context
[in]indexZero-based index identifying a slot
Returns
Error code

Definition at line 1619 of file ssh.c.

◆ sshUnloadRsaKey()

error_t sshUnloadRsaKey ( SshContext context,
uint_t  index 
)

Unload transient RSA key (for RSA key exchange)

Parameters
[in]contextPointer to the SSH context
[in]indexZero-based index identifying a slot
Returns
Error code

Definition at line 1197 of file ssh.c.

◆ sshUnregisterChannelOpenCallback()

error_t sshUnregisterChannelOpenCallback ( SshContext context,
SshChannelOpenCallback  callback 
)

Unregister channel open callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackPreviously registered callback function
Returns
Error code

Definition at line 839 of file ssh.c.

◆ sshUnregisterChannelRequestCallback()

error_t sshUnregisterChannelRequestCallback ( SshContext context,
SshChannelReqCallback  callback 
)

Unregister channel request callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackPreviously registered callback function
Returns
Error code

Definition at line 752 of file ssh.c.

◆ sshUnregisterConnectionCloseCallback()

error_t sshUnregisterConnectionCloseCallback ( SshContext context,
SshConnectionCloseCallback  callback 
)

Unregister connection close callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackPreviously registered callback function
Returns
Error code

Definition at line 1013 of file ssh.c.

◆ sshUnregisterConnectionOpenCallback()

error_t sshUnregisterConnectionOpenCallback ( SshContext context,
SshConnectionOpenCallback  callback 
)

Unregister connection open callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackPreviously registered callback function
Returns
Error code

Definition at line 926 of file ssh.c.

◆ sshUnregisterGlobalRequestCallback()

error_t sshUnregisterGlobalRequestCallback ( SshContext context,
SshGlobalReqCallback  callback 
)

Unregister global request callback function.

Parameters
[in]contextPointer to the SSH context
[in]callbackPreviously registered callback function
Returns
Error code

Definition at line 665 of file ssh.c.

◆ sshWriteChannel()

error_t sshWriteChannel ( SshChannel channel,
const void *  data,
size_t  length,
size_t *  written,
uint_t  flags 
)

Write data to the specified channel.

Parameters
[in]channelSSH channel handle
[in]dataPointer to the buffer containing the data to be transmitted
[in]lengthNumber of data bytes to send
[out]writtenActual number of bytes written (optional parameter)
[in]flagsSet of flags that influences the behavior of this function
Returns
Error code

Definition at line 2051 of file ssh.c.