ssh.h

Go to the documentation of this file.

/*
 * ssh.h
 *
 * SSH Developer API
 *
 * Copyright 2019-2024 DigiCert, Inc. All Rights Reserved.
 * Proprietary and Confidential Material.
 *
 */

/*------------------------------------------------------------------*/

#ifndef __SSH_HEADER__
#define __SSH_HEADER__

#include "../common/mtcp.h"
#ifdef __cplusplus
extern "C" {
#endif

#if !defined( __ENABLE_MOCANA_SSH_SERVER__ ) && defined( __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__ )
#define __ENABLE_MOCANA_SSH_SERVER__
#endif


/*------------------------------------------------------------------*/

/* message types */
enum sshSessionTypes
{
    SSH_SESSION_NOTHING,
    SSH_SESSION_OPEN,
    SSH_SESSION_OPEN_PF,
    SSH_SESSION_PTY_REQUEST,
    SSH_SESSION_OPEN_SHELL,
    SSH_SESSION_OPEN_SFTP,
    SSH_SESSION_OPEN_EXEC,
    SSH_SESSION_WINDOW_CHANGE,
    SSH_SESSION_DATA,
    SSH_SESSION_STDERR,
    SSH_SESSION_EOF,
    SSH_SESSION_CLOSED,
    SSH_SESSION_CHANNEL_CLOSED,
    SSH_PF_CLOSED,
    SSH_PF_EOF,
    SSH_SESSION_BREAK_OP,
    SSH_SESSION_PING_REPLY,
    SSH_PF_DATA
};


/*------------------------------------------------------------------*/

enum asyncWaitEvents
{
    kNotWaiting = 0,
    kWaitingForAuth,
    kWaitingForHwOffload
};


/*------------------------------------------------------------------*/

/* timeouts in milliseconds (zero indicates no timeout) */
#ifndef TIMEOUT_SSH_OPEN
#define TIMEOUT_SSH_OPEN                        (2000)
#endif

#ifndef TIMEOUT_SSH_KEX
#ifdef __ENABLE_MOCANA_QS__
 #define TIMEOUT_SSH_KEX                         (120000)
#else
 #define TIMEOUT_SSH_KEX                         (10000)
#endif
#endif

#ifndef TIMEOUT_SSH_NEWKEYS
#ifdef __ENABLE_MOCANA_QS__
 #define TIMEOUT_SSH_NEWKEYS                     (120000)
#else
 #define TIMEOUT_SSH_NEWKEYS                     (15000)
#endif
#endif

#ifndef TIMEOUT_SSH_SERVICE_REQUEST
#ifdef __ENABLE_MOCANA_QS__
 #define TIMEOUT_SSH_SERVICE_REQUEST             (120000)
#else
 #define TIMEOUT_SSH_SERVICE_REQUEST             (4000)
#endif
#endif

#ifndef TIMEOUT_SSH_OPEN_STATE
#define TIMEOUT_SSH_OPEN_STATE                  (0)
#endif

/* the most interesting of these values, the amount of time we allow the user to authenticate */
#ifndef TIMEOUT_SSH_AUTH_LOGON
#ifdef __ENABLE_MOCANA_QS__
 #define TIMEOUT_SSH_AUTH_LOGON                  (1000 * 60 * 200)
#else
 #define TIMEOUT_SSH_AUTH_LOGON                  (1000 * 60 * 10)
#endif
#endif

/* suggested by SSHv2 standard, max number of authentication attempts */
#ifndef MAX_SSH_AUTH_ATTEMPTS
#define MAX_SSH_AUTH_ATTEMPTS                   (20)
#endif

/* sizes */
#ifndef SSH_MAX_BUFFER_SIZE
#ifdef __ENABLE_MOCANA_QS__
#define SSH_MAX_BUFFER_SIZE                     (2097152)
#else
#define SSH_MAX_BUFFER_SIZE                     (1024*4)
#endif
#endif

#ifndef MAX_SESSION_WINDOW_SIZE
#define MAX_SESSION_WINDOW_SIZE                 (1024*2)
#endif

#ifndef SSH_SYNC_BUFFER_SIZE
#define SSH_SYNC_BUFFER_SIZE                    (512)
#endif

#ifndef MOCANA_SSH_SOCKET_STREAM_SIZE
#define MOCANA_SSH_SOCKET_STREAM_SIZE           (4096)
#endif

#if (MAX_SESSION_WINDOW_SIZE > SSH_MAX_BUFFER_SIZE)
#error ssh.h: SSH_MAX_BUFFER_SIZE must be greater than MAX_SESSION_WINDOW_SIZE
#endif

/* SSH Key Blob Types */
#define SSH_PUBLIC_KEY_BLOB                     1
#define SSH_PRIVATE_KEY_BLOB                    2

/* SSH Advertised Authentication Methods (OR for multiple types) */
#define MOCANA_SSH_AUTH_NONE                    0x10
#define MOCANA_SSH_AUTH_PUBLIC_KEY              0x80
#define MOCANA_SSH_AUTH_PASSWORD                0x40
#define MOCANA_SSH_AUTH_KEYBOARD_INTERACTIVE    0x20

#define SSH_DEFAULT_TCPIP_PORT                  (22)

/* authentication results */
#define AUTH_FAIL                               (0)
#define AUTH_PASS                               (1)
#define AUTH_MORE                               (2)
#define AUTH_WAIT                               (3)
#define AUTH_FAIL_MORE                          (4)

/* authentication keyboard interactive */
#define AUTH_ECHO                               (1)
#define AUTH_NO_ECHO                            (0)

#ifndef AUTH_MAX_NUM_PROMPTS
#define AUTH_MAX_NUM_PROMPTS                    3
#endif

/* stream buffer sizes */
#ifndef SFTP_SERVER_STREAM_BUF_SIZE
#define SFTP_SERVER_STREAM_BUF_SIZE             (4096)
#endif

#ifdef __ENABLE_MOCANA_SSH_PORT_FORWARDING__
#define MOCANA_SSH_ALLOW_DIRECT_TCPIP             (0x00010000)
#define MOCANA_SSH_ALLOW_FORWARDED_TCPIP          (0x00020000)
#define MOCANA_SSH_ALLOW_PRIVILEGED_DIRECT_TCPIP  (0x00040000)
#define MOCANA_SSH_ALLOW_PRIVILEGED_FORWARD_TCPIP (0x00080000)
#define MOCANA_SSH_REVERSE_PORT_FWD_PORT_VALUE    (25000)
#endif

/* SSH ioctls */
#define SET_SSH_MAX_SESSION_TIME_LIMIT           (1)


/*------------------------------------------------------------------*/

typedef struct
{
    ubyte4          width;
    ubyte4          height;
    ubyte4          pixelWidth;
    ubyte4          pixelHeight;

    sbyte*          pTerminalEnvironment;
    ubyte4          terminalEnvironmentLength;

    sbyte*          pEncodedTerminalModes;
    ubyte4          encodedTerminalModes;

    ubyte4          breakLength;

} terminalState;

typedef struct
{
    sbyte*          pPrompt;
    ubyte4          promptLen;
    ubyte4          echo;

} keyIntPrompt;

typedef struct keyIntInfoReq
{
    sbyte4          cookie;                             /* for flexiblity, useful for marking things as static or dynamic, etc */

    sbyte*          pName;
    ubyte4          nameLen;
    sbyte*          pInstruction;
    ubyte4          instructionLen;

    ubyte4          numPrompts;
    keyIntPrompt*   prompts[AUTH_MAX_NUM_PROMPTS];

} keyIntInfoReq;

typedef struct
{
    ubyte*          pResponse;
    ubyte4          responseLen;

} keyIntResp;

typedef struct
{
    ubyte4          numResponses;
    keyIntResp*     responses[AUTH_MAX_NUM_PROMPTS];    /* contains responses to prompts */

} keyIntInfoResp;

struct certChain;
typedef struct certChain* certChainPtr;

typedef struct
{
    sbyte4          sshMaxConnections;

    ubyte4          sshListenPort;

    ubyte4          sshMaxAuthAttempts;

    ubyte4          sshTimeOutOpen;

    ubyte4          sshTimeOutKeyExchange;

    ubyte4          sshTimeOutNewKeys;

    ubyte4          sshTimeOutServiceRequest;

    ubyte4          sshTimeOutAuthentication;

    ubyte4          sshTimeOutDefaultOpenState;

#if ((defined(__ENABLE_MOCANA_SSH_OCSP_SUPPORT__)) && (defined(__ENABLE_MOCANA_OCSP_CLIENT__)))
    sbyte *         pOcspResponderUrl;
#if (defined(__ENABLE_MOCANA_OCSP_TIMEOUT_CONFIG__))
    ubyte4          ocspTimeout;
#endif
#endif

    /* protocol specific upcalls */

    sbyte4(*funcPtrSessionOpen)   (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrPtyRequest)    (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrOpenShell)     (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrOpenSftp)      (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrWindowChange)  (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrReceivedData)  (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrStdErr)        (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrEof)           (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrClosed)        (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrCloseChannel)        (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrBreakOp)       (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrExec)          (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    sbyte4(*funcPtrReplyPing)     (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen);

    /* general purpose upcalls */
#ifndef __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

    void(*funcPtrPostAccept)     (sbyte4 connectionInstance, TCP_SOCKET tcpAcceptSocket);

    void(*funcPtrConnection)     (sbyte4 connectionInstance);
#else

    void(*funcPtrStartTimer)     (sbyte4 connectionInstance, ubyte4 msTimerExpire, sbyte4 boolUserAuthenticated);
#endif /* __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__ */

    sbyte4(*funcPtrPasswordAuth)    (sbyte4 connectionInstance, const ubyte *pUser, ubyte4 userLength, const ubyte *pPassword, ubyte4 passwordLength);

    sbyte4(*funcPtrNoneAuth)    (sbyte4 connectionInstance, const ubyte *pUser, ubyte4 userLength);

    sbyte*  pBannerString;

    sbyte4(*funcPtrPubKeyAuth)      (sbyte4 connectionInstance, const ubyte *pUser, ubyte4 userLength, const ubyte *pPubKey, ubyte4 pubKeyLength, ubyte4 keyType);

    sbyte4(*funcPtrCertStatus)      (sbyte4 connectionInstance,
                         const ubyte *pUser,   ubyte4 userLength,
                         sbyte4 cert_status, ubyte *pCertificate, ubyte4 certLen,
                         certChainPtr pCertChain, const ubyte *pAnchorCert, ubyte4 anchorCertLen);

    sbyte4(*funcPtrKeyIntAuthReq)   (sbyte4 connectionInstance, const ubyte* pUser, ubyte4 userLength, keyIntInfoResp* pResponseInfo, keyIntInfoReq* pRequestInfo, sbyte4 *pAuthState);

    sbyte4(*funcPtrReleaseKeyIntReq)(sbyte4 connectionInstance, keyIntInfoReq* request);

    sbyte4(*funcPtrGetAuthAdvertizedMethods)  (sbyte4 connectionInstance);

#ifdef __ENABLE_MOCANA_SSH_PORT_FORWARDING__

    sbyte4(*funcPtrConnect)      (sbyte4 connectionInstance, sbyte4 sessionNum, ubyte *pConnectHost, ubyte2 port, sbyte4 *pIgnoreRequest, sbyte4 channel);

    sbyte4(*funcPortFwdReceivedData)  (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen, ubyte4 channel);



    sbyte4(*funcPortFwdPtrClosed)        (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen, ubyte4 channel);

    sbyte4 (*funcPortFwdPtrEof)       (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte *pMesg, ubyte4 mesgLen, ubyte4 channel);

    sbyte4 (*funcCheckPort)           (ubyte4 dstPort);

    sbyte4 (*funcStartTcpIpForward)   (sbyte4 connectionInstance,ubyte* pSrc, ubyte4 dstport, ubyte4 orgPort);

    sbyte4 (*funcCancelTcpIpForward)  (sbyte4 connectionInstance, ubyte4 dstPort);

    sbyte4 (*funcPtrRemotePortFwdSessionOpen) (sbyte4 connectionInstance, ubyte4 channel, ubyte4 myChannel);
#endif /* __ENABLE_MOCANA_SSH_PORT_FORWARDING__ */

  sbyte4(*funcPtrSessionReKey)   (sbyte4 connectionInstance, intBoolean initiatedByRemote);

} sshSettings;


/*------------------------------------------------------------------*/

#ifdef __ENABLE_MOCANA_SSH_SERVER__

MOC_EXTERN sbyte4 SSH_assignCertificateStore(sbyte4 connectionInstance, certStorePtr pCertStore);

#ifndef __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

MOC_EXTERN sbyte4 SSH_init(sbyte4 sshMaxConnections);

MOC_EXTERN sbyte4 SSH_acceptConnection(TCP_SOCKET socket);

MOC_EXTERN sbyte4 SSH_negotiateConnection(sbyte4 connectionInstance);

#ifndef __ENABLE_MOCANA_SSH_STREAM_API__

MOC_EXTERN sbyte4 SSH_recvMessage(sbyte4 connectionInstance, sbyte4 *pMessageType, sbyte *pRetMessage, sbyte4 *pNumBytesReceived, ubyte4 timeout);
#else

MOC_EXTERN sbyte4 SSH_recv(sbyte4 connectionInstance, sbyte4 *pMessageType, ubyte *pRetBuffer, ubyte4 bufferSize, sbyte4 *pNumBytesReceived, ubyte4 timeout);

MOC_EXTERN sbyte4 SSH_recvPending(sbyte4 connectionInstance, sbyte4 *pRetBooleanIsPending);
#endif

MOC_EXTERN sbyte4 SSH_sendMessage(sbyte4 connectionInstance, sbyte *pBuffer, sbyte4 bufferSize, sbyte4 *pBytesSent);

MOC_EXTERN sbyte4 SSH_sendErrMessage(sbyte4 connectionInstance, sbyte *pBuffer, sbyte4 bufferSize, sbyte4 *pBytesSent);

MOC_EXTERN sbyte4 SSH_closeConnection(sbyte4 connectionInstance);

#ifdef __ENABLE_MOCANA_SSH_PING__

MOC_EXTERN sbyte4 SSH_sendPing(sbyte4 connectionInstance);
#endif
#endif /* __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__ */

#if (defined(__ENABLE_MOCANA_SSH_OLD_DSA_CONVERSION__) && defined(__ENABLE_MOCANA_DSA__))

MOC_EXTERN sbyte4 SSH_convertOldKeyBlobToNew(ubyte *pOldDsaPublicKeyBlob, ubyte4 oldDsaPublicKeyBlobLength, ubyte *pOldDsaPrivateKeyBlob, ubyte4 oldDsaPrivateKeyBlobLength, ubyte **ppRetNewKeyBlob, ubyte4 *pRetNewKeyBlobLength);
#endif

MOC_EXTERN sbyte4 SSH_getTerminalSettingDescr(sbyte4 connectionInstance, terminalState **ppTerminalSettings);

MOC_EXTERN sbyte4 SSH_getCookie(sbyte4 connectionInstance, sbyte4 *pCookie);

MOC_EXTERN sbyte4 SSH_setCookie(sbyte4 connectionInstance, sbyte4 cookie);

MOC_EXTERN sbyte4 SSH_getInstanceFromSocket(TCP_SOCKET socket);

MOC_EXTERN sbyte4 SSH_getSessionCryptoInfo(sbyte4 connectionInstance, sbyte **ppInCipherName,  sbyte **ppInMacName, sbyte **ppOutCipherName, sbyte **ppOutMacName);

MOC_EXTERN sbyte4 SSH_getNextConnectionInstance(sbyte4 connectionInstance);

MOC_EXTERN sbyte4 SSH_getSocketId(sbyte4 connectionInstance, TCP_SOCKET *pRetSocket);

MOC_EXTERN sbyte4 SSH_setErrorCode(sbyte4 connectionInstance, sbyte4 errorCode);

MOC_EXTERN sbyte4 SSH_useThisCipherList(sbyte4 connectionInstance, ubyte *pCipherList);

MOC_EXTERN sbyte4 SSH_useThisHmacList(sbyte4 connectionInstance, ubyte *pHmacList);

MOC_EXTERN sbyte4 SSH_ioctl(sbyte4 connectionInstance, ubyte4 ioctlSelector, ubyte4 ioctlValue);

MOC_EXTERN sbyte4 SSH_initiateReKey(sbyte4 connectionInstance, ubyte4 msAllowToComply);

MOC_EXTERN sbyte4 SSH_numBytesTransmitted(sbyte4 connectionInstance, ubyte8 *pRetNumBytes);

#ifndef __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__
#ifdef __USE_MOCANA_SSH_SERVER__

MOC_EXTERN sbyte4  SSH_startServer(void);

MOC_EXTERN void SSH_stopServer (void);

MOC_EXTERN void SSH_disconnectAllClients(void);
#endif /* __USE_MOCANA_SSH_SERVER__ */
#endif /* __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__ */

MOC_EXTERN sbyte4  SSH_compareAuthKeys(const ubyte *pPubKey,  ubyte4 pubKeyLength,
                                const ubyte *pFileKey, ubyte4 fileKeyLength,
                                sbyte4 *pRetIsMatch);

MOC_EXTERN sbyte4  SSH_verifyPublicKeyFile(sbyte *pKeyFileData, ubyte4 fileSize);

MOC_EXTERN sbyte4 SSH_shutdown(void);

MOC_EXTERN sbyte4 SSH_releaseTables(void);

MOC_EXTERN sshSettings* SSH_sshSettings(void);

#ifdef __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

MOC_EXTERN sbyte4 SSH_ASYNC_init(sbyte4 sshMaxConnections);

MOC_EXTERN sbyte4 SSH_ASYNC_setListeningPort(ubyte4 listeningPort);

MOC_EXTERN sbyte4 SSH_ASYNC_acceptConnection(TCP_SOCKET tempSocket, ubyte *pClientHelloString, ubyte4 clientHelloStringLength, ubyte *pServerHelloString, ubyte4 serverHelloStringLength);

MOC_EXTERN sbyte4 SSH_ASYNC_startProtocolV2(sbyte4 connectionInstance);

MOC_EXTERN sbyte4 SSH_ASYNC_recvMessage(sbyte4 connectionInstance, ubyte *pBytesReceived, ubyte4 numBytesReceived);

MOC_EXTERN sbyte4 SSH_ASYNC_ackReceivedMessageBytes(sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte4 numBytesAck);

MOC_EXTERN sbyte4 SSH_ASYNC_recvContinueMessage(sbyte4 connectionInstance, sbyte4 result);

MOC_EXTERN sbyte4 SSH_ASYNC_sendMessage(sbyte4 connectionInstance, sbyte *pBuffer, sbyte4 bufferSize, sbyte4 *pBytesSent);

MOC_EXTERN sbyte4 SSH_ASYNC_sendMessagePending(sbyte4 connectionInstance, ubyte4 *pRetNumBytesPending);

MOC_EXTERN sbyte4 SSH_ASYNC_closeConnection(sbyte4 connectionInstance);
#endif /* __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__ */

#ifdef __ENABLE_MOCANA_SSH_PORT_FORWARDING__

MOC_EXTERN sbyte4 SSH_setUserPortForwardingPermissions(sbyte4 connectionInstance, ubyte4 memberGroups);

MOC_EXTERN sbyte4 SSH_sendPortForwardMessage(sbyte4 connectionInstance, sbyte4 channel, sbyte *pBuffer, sbyte4 bufferSize, sbyte4 *pBytesSent);

MOC_EXTERN sbyte4 SSH_sendPortFwdOpen(sbyte4 connectionInstance, ubyte* pConnectHost,ubyte4 connectPort,ubyte* pSrc, ubyte4 srcPort,ubyte4 *myChannel);

MOC_EXTERN sbyte4 SSH_sendPortForwardClose(sbyte4 connectionInstance, sbyte4 channel);

MOC_EXTERN sbyte4 SSH_ackPortFwdReceivedMessageBytes(sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte4 numBytesAck, ubyte4 channel);
#endif /* __ENABLE_MOCANA_SSH_PORT_FORWARDING__ */

#else

/* stub functions */
#define SSH_init(X)                     (-1)
#define SSH_acceptConnection(X)         (-1)
#define SSH_negotiateConnection(X)      (-1)
#define SSH_recvMessage(X)              (-1)
#define SSH_sendMessage(X)              (-1)
#define SSH_closeConnection(X)          (-1)
#define SSH_getTerminalSettingDescr(X)  (-1)
#define SSH_getCookie(X)                (-1)
#define SSH_setCookie(X)                (-1)
#define SSH_startServer(X)              (-1)
#define SSH_stopServer(X)
#define SSH_disconnectAllClients(X)
#define SSH_compareAuthKeys(X)          (-1)
#define SSH_shutdown(X)                 (-1)
#define SSH_releaseTables(X)            (-1)
#define SSH_verifyPublicKeyFile(X)      (-1)
#define SSH_sshSettings(X)              (0)
#define SSH_sftpSettings(X)             (0)

#endif /* __ENABLE_MOCANA_SSH_SERVER__ */

#ifdef __cplusplus
}
#endif

#endif /* __SSH_HEADER__ */