libssh2.h (58692B)
1/* Copyright (c) 2004-2009, Sara Golemon <sarag@libssh2.org> 2 * Copyright (c) 2009-2021 Daniel Stenberg 3 * Copyright (c) 2010 Simon Josefsson <simon@josefsson.org> 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, 7 * with or without modification, are permitted provided 8 * that the following conditions are met: 9 * 10 * Redistributions of source code must retain the above 11 * copyright notice, this list of conditions and the 12 * following disclaimer. 13 * 14 * Redistributions in binary form must reproduce the above 15 * copyright notice, this list of conditions and the following 16 * disclaimer in the documentation and/or other materials 17 * provided with the distribution. 18 * 19 * Neither the name of the copyright holder nor the names 20 * of any other contributors may be used to endorse or 21 * promote products derived from this software without 22 * specific prior written permission. 23 * 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 25 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 26 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 27 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 29 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 30 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 31 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 32 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 34 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 35 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 36 * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 37 * OF SUCH DAMAGE. 38 */ 39 40#ifndef LIBSSH2_H 41#define LIBSSH2_H 1 42 43#define LIBSSH2_COPYRIGHT "2004-2023 The libssh2 project and its contributors." 44 45/* We use underscore instead of dash when appending DEV in dev versions just 46 to make the BANNER define (used by src/session.c) be a valid SSH 47 banner. Release versions have no appended strings and may of course not 48 have dashes either. */ 49#define LIBSSH2_VERSION "1.11.0" 50 51/* The numeric version number is also available "in parts" by using these 52 defines: */ 53#define LIBSSH2_VERSION_MAJOR 1 54#define LIBSSH2_VERSION_MINOR 11 55#define LIBSSH2_VERSION_PATCH 0 56 57/* This is the numeric version of the libssh2 version number, meant for easier 58 parsing and comparisons by programs. The LIBSSH2_VERSION_NUM define will 59 always follow this syntax: 60 61 0xXXYYZZ 62 63 Where XX, YY and ZZ are the main version, release and patch numbers in 64 hexadecimal (using 8 bits each). All three numbers are always represented 65 using two digits. 1.2 would appear as "0x010200" while version 9.11.7 66 appears as "0x090b07". 67 68 This 6-digit (24 bits) hexadecimal number does not show pre-release number, 69 and it is always a greater number in a more recent release. It makes 70 comparisons with greater than and less than work. 71*/ 72#define LIBSSH2_VERSION_NUM 0x010b00 73 74/* 75 * This is the date and time when the full source package was created. The 76 * timestamp is not stored in the source code repo, as the timestamp is 77 * properly set in the tarballs by the maketgz script. 78 * 79 * The format of the date should follow this template: 80 * 81 * "Mon Feb 12 11:35:33 UTC 2007" 82 */ 83#define LIBSSH2_TIMESTAMP "DEV" 84 85#ifndef RC_INVOKED 86 87#ifdef __cplusplus 88extern "C" { 89#endif 90 91#if defined(_WIN32) || defined(WIN32) 92#define LIBSSH2_WIN32 93#endif 94 95#ifdef LIBSSH2_WIN32 96# include <basetsd.h> 97# include <winsock2.h> 98#endif 99 100#include <stddef.h> 101#include <string.h> 102#include <sys/stat.h> 103#include <sys/types.h> 104 105/* Allow alternate API prefix from CFLAGS or calling app */ 106#ifndef LIBSSH2_API 107# ifdef LIBSSH2_WIN32 108# if defined(LIBSSH2_EXPORTS) || defined(DLL_EXPORT) || defined(_WINDLL) 109# ifdef LIBSSH2_LIBRARY 110# define LIBSSH2_API __declspec(dllexport) 111# else 112# define LIBSSH2_API __declspec(dllimport) 113# endif /* LIBSSH2_LIBRARY */ 114# else 115# define LIBSSH2_API 116# endif 117# else /* !LIBSSH2_WIN32 */ 118# define LIBSSH2_API 119# endif /* LIBSSH2_WIN32 */ 120#endif /* LIBSSH2_API */ 121 122#ifdef HAVE_SYS_UIO_H 123# include <sys/uio.h> 124#endif 125 126#ifdef _MSC_VER 127typedef unsigned char uint8_t; 128typedef unsigned short int uint16_t; 129typedef unsigned int uint32_t; 130typedef __int32 int32_t; 131typedef __int64 int64_t; 132typedef unsigned __int64 uint64_t; 133typedef unsigned __int64 libssh2_uint64_t; 134typedef __int64 libssh2_int64_t; 135#if (!defined(HAVE_SSIZE_T) && !defined(ssize_t)) 136typedef SSIZE_T ssize_t; 137#define HAVE_SSIZE_T 138#endif 139#else 140#include <stdint.h> 141typedef unsigned long long libssh2_uint64_t; 142typedef long long libssh2_int64_t; 143#endif 144 145#ifdef LIBSSH2_WIN32 146typedef SOCKET libssh2_socket_t; 147#define LIBSSH2_INVALID_SOCKET INVALID_SOCKET 148#else /* !LIBSSH2_WIN32 */ 149typedef int libssh2_socket_t; 150#define LIBSSH2_INVALID_SOCKET -1 151#endif /* LIBSSH2_WIN32 */ 152 153/* 154 * Determine whether there is small or large file support on windows. 155 */ 156 157#if defined(_MSC_VER) && !defined(_WIN32_WCE) 158# if (_MSC_VER >= 900) && (_INTEGRAL_MAX_BITS >= 64) 159# define LIBSSH2_USE_WIN32_LARGE_FILES 160# else 161# define LIBSSH2_USE_WIN32_SMALL_FILES 162# endif 163#endif 164 165#if defined(__MINGW32__) && !defined(LIBSSH2_USE_WIN32_LARGE_FILES) 166# define LIBSSH2_USE_WIN32_LARGE_FILES 167#endif 168 169#if defined(__WATCOMC__) && !defined(LIBSSH2_USE_WIN32_LARGE_FILES) 170# define LIBSSH2_USE_WIN32_LARGE_FILES 171#endif 172 173#if defined(__POCC__) 174# undef LIBSSH2_USE_WIN32_LARGE_FILES 175#endif 176 177#if defined(LIBSSH2_WIN32) && !defined(LIBSSH2_USE_WIN32_LARGE_FILES) && \ 178 !defined(LIBSSH2_USE_WIN32_SMALL_FILES) 179# define LIBSSH2_USE_WIN32_SMALL_FILES 180#endif 181 182/* 183 * Large file (>2Gb) support using WIN32 functions. 184 */ 185 186#ifdef LIBSSH2_USE_WIN32_LARGE_FILES 187# include <io.h> 188# define LIBSSH2_STRUCT_STAT_SIZE_FORMAT "%I64d" 189typedef struct _stati64 libssh2_struct_stat; 190typedef __int64 libssh2_struct_stat_size; 191#endif 192 193/* 194 * Small file (<2Gb) support using WIN32 functions. 195 */ 196 197#ifdef LIBSSH2_USE_WIN32_SMALL_FILES 198# ifndef _WIN32_WCE 199# define LIBSSH2_STRUCT_STAT_SIZE_FORMAT "%d" 200typedef struct _stat libssh2_struct_stat; 201typedef off_t libssh2_struct_stat_size; 202# endif 203#endif 204 205#ifndef LIBSSH2_STRUCT_STAT_SIZE_FORMAT 206# ifdef __VMS 207/* We have to roll our own format here because %z is a C99-ism we don't 208 have. */ 209# if __USE_OFF64_T || __USING_STD_STAT 210# define LIBSSH2_STRUCT_STAT_SIZE_FORMAT "%Ld" 211# else 212# define LIBSSH2_STRUCT_STAT_SIZE_FORMAT "%d" 213# endif 214# else 215# define LIBSSH2_STRUCT_STAT_SIZE_FORMAT "%zd" 216# endif 217typedef struct stat libssh2_struct_stat; 218typedef off_t libssh2_struct_stat_size; 219#endif 220 221/* Part of every banner, user specified or not */ 222#define LIBSSH2_SSH_BANNER "SSH-2.0-libssh2_" LIBSSH2_VERSION 223 224#define LIBSSH2_SSH_DEFAULT_BANNER LIBSSH2_SSH_BANNER 225#define LIBSSH2_SSH_DEFAULT_BANNER_WITH_CRLF LIBSSH2_SSH_DEFAULT_BANNER "\r\n" 226 227/* Defaults for pty requests */ 228#define LIBSSH2_TERM_WIDTH 80 229#define LIBSSH2_TERM_HEIGHT 24 230#define LIBSSH2_TERM_WIDTH_PX 0 231#define LIBSSH2_TERM_HEIGHT_PX 0 232 233/* 1/4 second */ 234#define LIBSSH2_SOCKET_POLL_UDELAY 250000 235/* 0.25 * 120 == 30 seconds */ 236#define LIBSSH2_SOCKET_POLL_MAXLOOPS 120 237 238/* Maximum size to allow a payload to compress to, plays it safe by falling 239 short of spec limits */ 240#define LIBSSH2_PACKET_MAXCOMP 32000 241 242/* Maximum size to allow a payload to deccompress to, plays it safe by 243 allowing more than spec requires */ 244#define LIBSSH2_PACKET_MAXDECOMP 40000 245 246/* Maximum size for an inbound compressed payload, plays it safe by 247 overshooting spec limits */ 248#define LIBSSH2_PACKET_MAXPAYLOAD 40000 249 250/* Malloc callbacks */ 251#define LIBSSH2_ALLOC_FUNC(name) void *name(size_t count, void **abstract) 252#define LIBSSH2_REALLOC_FUNC(name) void *name(void *ptr, size_t count, \ 253 void **abstract) 254#define LIBSSH2_FREE_FUNC(name) void name(void *ptr, void **abstract) 255 256typedef struct _LIBSSH2_USERAUTH_KBDINT_PROMPT 257{ 258 unsigned char *text; 259 size_t length; 260 unsigned char echo; 261} LIBSSH2_USERAUTH_KBDINT_PROMPT; 262 263typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE 264{ 265 char *text; 266 unsigned int length; 267} LIBSSH2_USERAUTH_KBDINT_RESPONSE; 268 269typedef struct _LIBSSH2_SK_SIG_INFO { 270 uint8_t flags; 271 uint32_t counter; 272 unsigned char *sig_r; 273 size_t sig_r_len; 274 unsigned char *sig_s; 275 size_t sig_s_len; 276} LIBSSH2_SK_SIG_INFO; 277 278/* 'publickey' authentication callback */ 279#define LIBSSH2_USERAUTH_PUBLICKEY_SIGN_FUNC(name) \ 280 int name(LIBSSH2_SESSION *session, unsigned char **sig, size_t *sig_len, \ 281 const unsigned char *data, size_t data_len, void **abstract) 282 283/* 'keyboard-interactive' authentication callback */ 284#define LIBSSH2_USERAUTH_KBDINT_RESPONSE_FUNC(name_) \ 285 void name_(const char *name, int name_len, const char *instruction, \ 286 int instruction_len, int num_prompts, \ 287 const LIBSSH2_USERAUTH_KBDINT_PROMPT *prompts, \ 288 LIBSSH2_USERAUTH_KBDINT_RESPONSE *responses, void **abstract) 289 290/* SK authentication callback */ 291#define LIBSSH2_USERAUTH_SK_SIGN_FUNC(name) \ 292 int name(LIBSSH2_SESSION *session, LIBSSH2_SK_SIG_INFO *sig_info, \ 293 const unsigned char *data, size_t data_len, \ 294 int algorithm, uint8_t flags, \ 295 const char *application, const unsigned char *key_handle, \ 296 size_t handle_len, \ 297 void **abstract) 298 299/* Flags for SK authentication */ 300#define LIBSSH2_SK_PRESENCE_REQUIRED 0x01 301#define LIBSSH2_SK_VERIFICATION_REQUIRED 0x04 302 303/* Callbacks for special SSH packets */ 304#define LIBSSH2_IGNORE_FUNC(name) \ 305 void name(LIBSSH2_SESSION *session, const char *message, int message_len, \ 306 void **abstract) 307 308#define LIBSSH2_DEBUG_FUNC(name) \ 309 void name(LIBSSH2_SESSION *session, int always_display, \ 310 const char *message, int message_len, \ 311 const char *language, int language_len, \ 312 void **abstract) 313 314#define LIBSSH2_DISCONNECT_FUNC(name) \ 315 void name(LIBSSH2_SESSION *session, int reason, \ 316 const char *message, int message_len, \ 317 const char *language, int language_len, \ 318 void **abstract) 319 320#define LIBSSH2_PASSWD_CHANGEREQ_FUNC(name) \ 321 void name(LIBSSH2_SESSION *session, char **newpw, int *newpw_len, \ 322 void **abstract) 323 324#define LIBSSH2_MACERROR_FUNC(name) \ 325 int name(LIBSSH2_SESSION *session, const char *packet, int packet_len, \ 326 void **abstract) 327 328#define LIBSSH2_X11_OPEN_FUNC(name) \ 329 void name(LIBSSH2_SESSION *session, LIBSSH2_CHANNEL *channel, \ 330 const char *shost, int sport, void **abstract) 331 332#define LIBSSH2_AUTHAGENT_FUNC(name) \ 333 void name(LIBSSH2_SESSION *session, LIBSSH2_CHANNEL *channel, \ 334 void **abstract) 335 336#define LIBSSH2_ADD_IDENTITIES_FUNC(name) \ 337 void name(LIBSSH2_SESSION *session, void *buffer, \ 338 const char *agent_path, void **abstract) 339 340#define LIBSSH2_AUTHAGENT_SIGN_FUNC(name) \ 341 int name(LIBSSH2_SESSION* session, \ 342 unsigned char *blob, unsigned int blen, \ 343 const unsigned char *data, unsigned int dlen, \ 344 unsigned char **signature, unsigned int *sigLen, \ 345 const char *agentPath, \ 346 void **abstract) 347 348#define LIBSSH2_CHANNEL_CLOSE_FUNC(name) \ 349 void name(LIBSSH2_SESSION *session, void **session_abstract, \ 350 LIBSSH2_CHANNEL *channel, void **channel_abstract) 351 352/* I/O callbacks */ 353#define LIBSSH2_RECV_FUNC(name) \ 354 ssize_t name(libssh2_socket_t socket, \ 355 void *buffer, size_t length, \ 356 int flags, void **abstract) 357#define LIBSSH2_SEND_FUNC(name) \ 358 ssize_t name(libssh2_socket_t socket, \ 359 const void *buffer, size_t length, \ 360 int flags, void **abstract) 361 362/* libssh2_session_callback_set() constants */ 363#define LIBSSH2_CALLBACK_IGNORE 0 364#define LIBSSH2_CALLBACK_DEBUG 1 365#define LIBSSH2_CALLBACK_DISCONNECT 2 366#define LIBSSH2_CALLBACK_MACERROR 3 367#define LIBSSH2_CALLBACK_X11 4 368#define LIBSSH2_CALLBACK_SEND 5 369#define LIBSSH2_CALLBACK_RECV 6 370#define LIBSSH2_CALLBACK_AUTHAGENT 7 371#define LIBSSH2_CALLBACK_AUTHAGENT_IDENTITIES 8 372#define LIBSSH2_CALLBACK_AUTHAGENT_SIGN 9 373 374/* libssh2_session_method_pref() constants */ 375#define LIBSSH2_METHOD_KEX 0 376#define LIBSSH2_METHOD_HOSTKEY 1 377#define LIBSSH2_METHOD_CRYPT_CS 2 378#define LIBSSH2_METHOD_CRYPT_SC 3 379#define LIBSSH2_METHOD_MAC_CS 4 380#define LIBSSH2_METHOD_MAC_SC 5 381#define LIBSSH2_METHOD_COMP_CS 6 382#define LIBSSH2_METHOD_COMP_SC 7 383#define LIBSSH2_METHOD_LANG_CS 8 384#define LIBSSH2_METHOD_LANG_SC 9 385#define LIBSSH2_METHOD_SIGN_ALGO 10 386 387/* flags */ 388#define LIBSSH2_FLAG_SIGPIPE 1 389#define LIBSSH2_FLAG_COMPRESS 2 390#define LIBSSH2_FLAG_QUOTE_PATHS 3 391 392typedef struct _LIBSSH2_SESSION LIBSSH2_SESSION; 393typedef struct _LIBSSH2_CHANNEL LIBSSH2_CHANNEL; 394typedef struct _LIBSSH2_LISTENER LIBSSH2_LISTENER; 395typedef struct _LIBSSH2_KNOWNHOSTS LIBSSH2_KNOWNHOSTS; 396typedef struct _LIBSSH2_AGENT LIBSSH2_AGENT; 397 398/* SK signature callback */ 399typedef struct _LIBSSH2_PRIVKEY_SK { 400 int algorithm; 401 uint8_t flags; 402 const char *application; 403 const unsigned char *key_handle; 404 size_t handle_len; 405 LIBSSH2_USERAUTH_SK_SIGN_FUNC((*sign_callback)); 406 void **orig_abstract; 407} LIBSSH2_PRIVKEY_SK; 408 409int 410libssh2_sign_sk(LIBSSH2_SESSION *session, 411 unsigned char **sig, 412 size_t *sig_len, 413 const unsigned char *data, 414 size_t data_len, 415 void **abstract); 416 417typedef struct _LIBSSH2_POLLFD { 418 unsigned char type; /* LIBSSH2_POLLFD_* below */ 419 420 union { 421 libssh2_socket_t socket; /* File descriptors -- examined with 422 system select() call */ 423 LIBSSH2_CHANNEL *channel; /* Examined by checking internal state */ 424 LIBSSH2_LISTENER *listener; /* Read polls only -- are inbound 425 connections waiting to be accepted? */ 426 } fd; 427 428 unsigned long events; /* Requested Events */ 429 unsigned long revents; /* Returned Events */ 430} LIBSSH2_POLLFD; 431 432/* Poll FD Descriptor Types */ 433#define LIBSSH2_POLLFD_SOCKET 1 434#define LIBSSH2_POLLFD_CHANNEL 2 435#define LIBSSH2_POLLFD_LISTENER 3 436 437/* Note: Win32 Doesn't actually have a poll() implementation, so some of these 438 values are faked with select() data */ 439/* Poll FD events/revents -- Match sys/poll.h where possible */ 440#define LIBSSH2_POLLFD_POLLIN 0x0001 /* Data available to be read or 441 connection available -- 442 All */ 443#define LIBSSH2_POLLFD_POLLPRI 0x0002 /* Priority data available to 444 be read -- Socket only */ 445#define LIBSSH2_POLLFD_POLLEXT 0x0002 /* Extended data available to 446 be read -- Channel only */ 447#define LIBSSH2_POLLFD_POLLOUT 0x0004 /* Can may be written -- 448 Socket/Channel */ 449/* revents only */ 450#define LIBSSH2_POLLFD_POLLERR 0x0008 /* Error Condition -- Socket */ 451#define LIBSSH2_POLLFD_POLLHUP 0x0010 /* HangUp/EOF -- Socket */ 452#define LIBSSH2_POLLFD_SESSION_CLOSED 0x0010 /* Session Disconnect */ 453#define LIBSSH2_POLLFD_POLLNVAL 0x0020 /* Invalid request -- Socket 454 Only */ 455#define LIBSSH2_POLLFD_POLLEX 0x0040 /* Exception Condition -- 456 Socket/Win32 */ 457#define LIBSSH2_POLLFD_CHANNEL_CLOSED 0x0080 /* Channel Disconnect */ 458#define LIBSSH2_POLLFD_LISTENER_CLOSED 0x0080 /* Listener Disconnect */ 459 460#define HAVE_LIBSSH2_SESSION_BLOCK_DIRECTION 461/* Block Direction Types */ 462#define LIBSSH2_SESSION_BLOCK_INBOUND 0x0001 463#define LIBSSH2_SESSION_BLOCK_OUTBOUND 0x0002 464 465/* Hash Types */ 466#define LIBSSH2_HOSTKEY_HASH_MD5 1 467#define LIBSSH2_HOSTKEY_HASH_SHA1 2 468#define LIBSSH2_HOSTKEY_HASH_SHA256 3 469 470/* Hostkey Types */ 471#define LIBSSH2_HOSTKEY_TYPE_UNKNOWN 0 472#define LIBSSH2_HOSTKEY_TYPE_RSA 1 473#define LIBSSH2_HOSTKEY_TYPE_DSS 2 474#define LIBSSH2_HOSTKEY_TYPE_ECDSA_256 3 475#define LIBSSH2_HOSTKEY_TYPE_ECDSA_384 4 476#define LIBSSH2_HOSTKEY_TYPE_ECDSA_521 5 477#define LIBSSH2_HOSTKEY_TYPE_ED25519 6 478 479/* Disconnect Codes (defined by SSH protocol) */ 480#define SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1 481#define SSH_DISCONNECT_PROTOCOL_ERROR 2 482#define SSH_DISCONNECT_KEY_EXCHANGE_FAILED 3 483#define SSH_DISCONNECT_RESERVED 4 484#define SSH_DISCONNECT_MAC_ERROR 5 485#define SSH_DISCONNECT_COMPRESSION_ERROR 6 486#define SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 7 487#define SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 8 488#define SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE 9 489#define SSH_DISCONNECT_CONNECTION_LOST 10 490#define SSH_DISCONNECT_BY_APPLICATION 11 491#define SSH_DISCONNECT_TOO_MANY_CONNECTIONS 12 492#define SSH_DISCONNECT_AUTH_CANCELLED_BY_USER 13 493#define SSH_DISCONNECT_NO_MORE_AUTH_METHODS_AVAILABLE 14 494#define SSH_DISCONNECT_ILLEGAL_USER_NAME 15 495 496/* Error Codes (defined by libssh2) */ 497#define LIBSSH2_ERROR_NONE 0 498 499/* The library once used -1 as a generic error return value on numerous places 500 through the code, which subsequently was converted to 501 LIBSSH2_ERROR_SOCKET_NONE uses over time. As this is a generic error code, 502 the goal is to never ever return this code but instead make sure that a 503 more accurate and descriptive error code is used. */ 504#define LIBSSH2_ERROR_SOCKET_NONE -1 505 506#define LIBSSH2_ERROR_BANNER_RECV -2 507#define LIBSSH2_ERROR_BANNER_SEND -3 508#define LIBSSH2_ERROR_INVALID_MAC -4 509#define LIBSSH2_ERROR_KEX_FAILURE -5 510#define LIBSSH2_ERROR_ALLOC -6 511#define LIBSSH2_ERROR_SOCKET_SEND -7 512#define LIBSSH2_ERROR_KEY_EXCHANGE_FAILURE -8 513#define LIBSSH2_ERROR_TIMEOUT -9 514#define LIBSSH2_ERROR_HOSTKEY_INIT -10 515#define LIBSSH2_ERROR_HOSTKEY_SIGN -11 516#define LIBSSH2_ERROR_DECRYPT -12 517#define LIBSSH2_ERROR_SOCKET_DISCONNECT -13 518#define LIBSSH2_ERROR_PROTO -14 519#define LIBSSH2_ERROR_PASSWORD_EXPIRED -15 520#define LIBSSH2_ERROR_FILE -16 521#define LIBSSH2_ERROR_METHOD_NONE -17 522#define LIBSSH2_ERROR_AUTHENTICATION_FAILED -18 523#define LIBSSH2_ERROR_PUBLICKEY_UNRECOGNIZED \ 524 LIBSSH2_ERROR_AUTHENTICATION_FAILED 525#define LIBSSH2_ERROR_PUBLICKEY_UNVERIFIED -19 526#define LIBSSH2_ERROR_CHANNEL_OUTOFORDER -20 527#define LIBSSH2_ERROR_CHANNEL_FAILURE -21 528#define LIBSSH2_ERROR_CHANNEL_REQUEST_DENIED -22 529#define LIBSSH2_ERROR_CHANNEL_UNKNOWN -23 530#define LIBSSH2_ERROR_CHANNEL_WINDOW_EXCEEDED -24 531#define LIBSSH2_ERROR_CHANNEL_PACKET_EXCEEDED -25 532#define LIBSSH2_ERROR_CHANNEL_CLOSED -26 533#define LIBSSH2_ERROR_CHANNEL_EOF_SENT -27 534#define LIBSSH2_ERROR_SCP_PROTOCOL -28 535#define LIBSSH2_ERROR_ZLIB -29 536#define LIBSSH2_ERROR_SOCKET_TIMEOUT -30 537#define LIBSSH2_ERROR_SFTP_PROTOCOL -31 538#define LIBSSH2_ERROR_REQUEST_DENIED -32 539#define LIBSSH2_ERROR_METHOD_NOT_SUPPORTED -33 540#define LIBSSH2_ERROR_INVAL -34 541#define LIBSSH2_ERROR_INVALID_POLL_TYPE -35 542#define LIBSSH2_ERROR_PUBLICKEY_PROTOCOL -36 543#define LIBSSH2_ERROR_EAGAIN -37 544#define LIBSSH2_ERROR_BUFFER_TOO_SMALL -38 545#define LIBSSH2_ERROR_BAD_USE -39 546#define LIBSSH2_ERROR_COMPRESS -40 547#define LIBSSH2_ERROR_OUT_OF_BOUNDARY -41 548#define LIBSSH2_ERROR_AGENT_PROTOCOL -42 549#define LIBSSH2_ERROR_SOCKET_RECV -43 550#define LIBSSH2_ERROR_ENCRYPT -44 551#define LIBSSH2_ERROR_BAD_SOCKET -45 552#define LIBSSH2_ERROR_KNOWN_HOSTS -46 553#define LIBSSH2_ERROR_CHANNEL_WINDOW_FULL -47 554#define LIBSSH2_ERROR_KEYFILE_AUTH_FAILED -48 555#define LIBSSH2_ERROR_RANDGEN -49 556#define LIBSSH2_ERROR_MISSING_USERAUTH_BANNER -50 557#define LIBSSH2_ERROR_ALGO_UNSUPPORTED -51 558 559/* this is a define to provide the old (<= 1.2.7) name */ 560#define LIBSSH2_ERROR_BANNER_NONE LIBSSH2_ERROR_BANNER_RECV 561 562/* Global API */ 563#define LIBSSH2_INIT_NO_CRYPTO 0x0001 564 565/* 566 * libssh2_init() 567 * 568 * Initialize the libssh2 functions. This typically initialize the 569 * crypto library. It uses a global state, and is not thread safe -- 570 * you must make sure this function is not called concurrently. 571 * 572 * Flags can be: 573 * 0: Normal initialize 574 * LIBSSH2_INIT_NO_CRYPTO: Do not initialize the crypto library (ie. 575 * OPENSSL_add_cipher_algoritms() for OpenSSL 576 * 577 * Returns 0 if succeeded, or a negative value for error. 578 */ 579LIBSSH2_API int libssh2_init(int flags); 580 581/* 582 * libssh2_exit() 583 * 584 * Exit the libssh2 functions and free's all memory used internal. 585 */ 586LIBSSH2_API void libssh2_exit(void); 587 588/* 589 * libssh2_free() 590 * 591 * Deallocate memory allocated by earlier call to libssh2 functions. 592 */ 593LIBSSH2_API void libssh2_free(LIBSSH2_SESSION *session, void *ptr); 594 595/* 596 * libssh2_session_supported_algs() 597 * 598 * Fills algs with a list of supported acryptographic algorithms. Returns a 599 * non-negative number (number of supported algorithms) on success or a 600 * negative number (an error code) on failure. 601 * 602 * NOTE: on success, algs must be deallocated (by calling libssh2_free) when 603 * not needed anymore 604 */ 605LIBSSH2_API int libssh2_session_supported_algs(LIBSSH2_SESSION* session, 606 int method_type, 607 const char ***algs); 608 609/* Session API */ 610LIBSSH2_API LIBSSH2_SESSION * 611libssh2_session_init_ex(LIBSSH2_ALLOC_FUNC((*my_alloc)), 612 LIBSSH2_FREE_FUNC((*my_free)), 613 LIBSSH2_REALLOC_FUNC((*my_realloc)), void *abstract); 614#define libssh2_session_init() libssh2_session_init_ex(NULL, NULL, NULL, NULL) 615 616LIBSSH2_API void **libssh2_session_abstract(LIBSSH2_SESSION *session); 617 618LIBSSH2_API void *libssh2_session_callback_set(LIBSSH2_SESSION *session, 619 int cbtype, void *callback); 620LIBSSH2_API int libssh2_session_banner_set(LIBSSH2_SESSION *session, 621 const char *banner); 622LIBSSH2_API int libssh2_banner_set(LIBSSH2_SESSION *session, 623 const char *banner); 624 625LIBSSH2_API int libssh2_session_startup(LIBSSH2_SESSION *session, int sock); 626LIBSSH2_API int libssh2_session_handshake(LIBSSH2_SESSION *session, 627 libssh2_socket_t sock); 628LIBSSH2_API int libssh2_session_disconnect_ex(LIBSSH2_SESSION *session, 629 int reason, 630 const char *description, 631 const char *lang); 632#define libssh2_session_disconnect(session, description) \ 633 libssh2_session_disconnect_ex((session), SSH_DISCONNECT_BY_APPLICATION, \ 634 (description), "") 635 636LIBSSH2_API int libssh2_session_free(LIBSSH2_SESSION *session); 637 638LIBSSH2_API const char *libssh2_hostkey_hash(LIBSSH2_SESSION *session, 639 int hash_type); 640 641LIBSSH2_API const char *libssh2_session_hostkey(LIBSSH2_SESSION *session, 642 size_t *len, int *type); 643 644LIBSSH2_API int libssh2_session_method_pref(LIBSSH2_SESSION *session, 645 int method_type, 646 const char *prefs); 647LIBSSH2_API const char *libssh2_session_methods(LIBSSH2_SESSION *session, 648 int method_type); 649LIBSSH2_API int libssh2_session_last_error(LIBSSH2_SESSION *session, 650 char **errmsg, 651 int *errmsg_len, int want_buf); 652LIBSSH2_API int libssh2_session_last_errno(LIBSSH2_SESSION *session); 653LIBSSH2_API int libssh2_session_set_last_error(LIBSSH2_SESSION* session, 654 int errcode, 655 const char *errmsg); 656LIBSSH2_API int libssh2_session_block_directions(LIBSSH2_SESSION *session); 657 658LIBSSH2_API int libssh2_session_flag(LIBSSH2_SESSION *session, int flag, 659 int value); 660LIBSSH2_API const char *libssh2_session_banner_get(LIBSSH2_SESSION *session); 661 662/* Userauth API */ 663LIBSSH2_API char *libssh2_userauth_list(LIBSSH2_SESSION *session, 664 const char *username, 665 unsigned int username_len); 666LIBSSH2_API int libssh2_userauth_banner(LIBSSH2_SESSION *session, 667 char **banner); 668LIBSSH2_API int libssh2_userauth_authenticated(LIBSSH2_SESSION *session); 669 670LIBSSH2_API int 671libssh2_userauth_password_ex(LIBSSH2_SESSION *session, 672 const char *username, 673 unsigned int username_len, 674 const char *password, 675 unsigned int password_len, 676 LIBSSH2_PASSWD_CHANGEREQ_FUNC 677 ((*passwd_change_cb))); 678 679#define libssh2_userauth_password(session, username, password) \ 680 libssh2_userauth_password_ex((session), (username), \ 681 (unsigned int)strlen(username), \ 682 (password), (unsigned int)strlen(password), \ 683 NULL) 684 685LIBSSH2_API int 686libssh2_userauth_publickey_fromfile_ex(LIBSSH2_SESSION *session, 687 const char *username, 688 unsigned int username_len, 689 const char *publickey, 690 const char *privatekey, 691 const char *passphrase); 692 693#define libssh2_userauth_publickey_fromfile(session, username, publickey, \ 694 privatekey, passphrase) \ 695 libssh2_userauth_publickey_fromfile_ex((session), (username), \ 696 (unsigned int)strlen(username), \ 697 (publickey), \ 698 (privatekey), (passphrase)) 699 700LIBSSH2_API int 701libssh2_userauth_publickey(LIBSSH2_SESSION *session, 702 const char *username, 703 const unsigned char *pubkeydata, 704 size_t pubkeydata_len, 705 LIBSSH2_USERAUTH_PUBLICKEY_SIGN_FUNC 706 ((*sign_callback)), 707 void **abstract); 708 709LIBSSH2_API int 710libssh2_userauth_hostbased_fromfile_ex(LIBSSH2_SESSION *session, 711 const char *username, 712 unsigned int username_len, 713 const char *publickey, 714 const char *privatekey, 715 const char *passphrase, 716 const char *hostname, 717 unsigned int hostname_len, 718 const char *local_username, 719 unsigned int local_username_len); 720 721#define libssh2_userauth_hostbased_fromfile(session, username, publickey, \ 722 privatekey, passphrase, hostname) \ 723 libssh2_userauth_hostbased_fromfile_ex((session), (username), \ 724 (unsigned int)strlen(username), \ 725 (publickey), \ 726 (privatekey), (passphrase), \ 727 (hostname), \ 728 (unsigned int)strlen(hostname), \ 729 (username), \ 730 (unsigned int)strlen(username)) 731 732LIBSSH2_API int 733libssh2_userauth_publickey_frommemory(LIBSSH2_SESSION *session, 734 const char *username, 735 size_t username_len, 736 const char *publickeyfiledata, 737 size_t publickeyfiledata_len, 738 const char *privatekeyfiledata, 739 size_t privatekeyfiledata_len, 740 const char *passphrase); 741 742/* 743 * response_callback is provided with filled by library prompts array, 744 * but client must allocate and fill individual responses. Responses 745 * array is already allocated. Responses data will be freed by libssh2 746 * after callback return, but before subsequent callback invocation. 747 */ 748LIBSSH2_API int 749libssh2_userauth_keyboard_interactive_ex(LIBSSH2_SESSION* session, 750 const char *username, 751 unsigned int username_len, 752 LIBSSH2_USERAUTH_KBDINT_RESPONSE_FUNC 753 ((*response_callback))); 754 755#define libssh2_userauth_keyboard_interactive(session, username, \ 756 response_callback) \ 757 libssh2_userauth_keyboard_interactive_ex((session), (username), \ 758 (unsigned int)strlen(username), \ 759 (response_callback)) 760 761LIBSSH2_API int 762libssh2_userauth_publickey_sk(LIBSSH2_SESSION *session, 763 const char *username, 764 size_t username_len, 765 const unsigned char *pubkeydata, 766 size_t pubkeydata_len, 767 const char *privatekeydata, 768 size_t privatekeydata_len, 769 const char *passphrase, 770 LIBSSH2_USERAUTH_SK_SIGN_FUNC 771 ((*sign_callback)), 772 void **abstract); 773 774LIBSSH2_API int libssh2_poll(LIBSSH2_POLLFD *fds, unsigned int nfds, 775 long timeout); 776 777/* Channel API */ 778#define LIBSSH2_CHANNEL_WINDOW_DEFAULT (2*1024*1024) 779#define LIBSSH2_CHANNEL_PACKET_DEFAULT 32768 780#define LIBSSH2_CHANNEL_MINADJUST 1024 781 782/* Extended Data Handling */ 783#define LIBSSH2_CHANNEL_EXTENDED_DATA_NORMAL 0 784#define LIBSSH2_CHANNEL_EXTENDED_DATA_IGNORE 1 785#define LIBSSH2_CHANNEL_EXTENDED_DATA_MERGE 2 786 787#define SSH_EXTENDED_DATA_STDERR 1 788 789/* Returned by any function that would block during a read/write operation */ 790#define LIBSSH2CHANNEL_EAGAIN LIBSSH2_ERROR_EAGAIN 791 792LIBSSH2_API LIBSSH2_CHANNEL * 793libssh2_channel_open_ex(LIBSSH2_SESSION *session, const char *channel_type, 794 unsigned int channel_type_len, 795 unsigned int window_size, unsigned int packet_size, 796 const char *message, unsigned int message_len); 797 798#define libssh2_channel_open_session(session) \ 799 libssh2_channel_open_ex((session), "session", sizeof("session") - 1, \ 800 LIBSSH2_CHANNEL_WINDOW_DEFAULT, \ 801 LIBSSH2_CHANNEL_PACKET_DEFAULT, NULL, 0) 802 803LIBSSH2_API LIBSSH2_CHANNEL * 804libssh2_channel_direct_tcpip_ex(LIBSSH2_SESSION *session, const char *host, 805 int port, const char *shost, int sport); 806#define libssh2_channel_direct_tcpip(session, host, port) \ 807 libssh2_channel_direct_tcpip_ex((session), (host), (port), "127.0.0.1", 22) 808 809LIBSSH2_API LIBSSH2_CHANNEL * 810libssh2_channel_direct_streamlocal_ex(LIBSSH2_SESSION * session, 811 const char *socket_path, 812 const char *shost, int sport); 813 814LIBSSH2_API LIBSSH2_LISTENER * 815libssh2_channel_forward_listen_ex(LIBSSH2_SESSION *session, const char *host, 816 int port, int *bound_port, 817 int queue_maxsize); 818#define libssh2_channel_forward_listen(session, port) \ 819 libssh2_channel_forward_listen_ex((session), NULL, (port), NULL, 16) 820 821LIBSSH2_API int libssh2_channel_forward_cancel(LIBSSH2_LISTENER *listener); 822 823LIBSSH2_API LIBSSH2_CHANNEL * 824libssh2_channel_forward_accept(LIBSSH2_LISTENER *listener); 825 826LIBSSH2_API int libssh2_channel_setenv_ex(LIBSSH2_CHANNEL *channel, 827 const char *varname, 828 unsigned int varname_len, 829 const char *value, 830 unsigned int value_len); 831 832#define libssh2_channel_setenv(channel, varname, value) \ 833 libssh2_channel_setenv_ex((channel), (varname), \ 834 (unsigned int)strlen(varname), (value), \ 835 (unsigned int)strlen(value)) 836 837LIBSSH2_API int libssh2_channel_request_auth_agent(LIBSSH2_CHANNEL *channel); 838 839LIBSSH2_API int libssh2_channel_request_pty_ex(LIBSSH2_CHANNEL *channel, 840 const char *term, 841 unsigned int term_len, 842 const char *modes, 843 unsigned int modes_len, 844 int width, int height, 845 int width_px, int height_px); 846#define libssh2_channel_request_pty(channel, term) \ 847 libssh2_channel_request_pty_ex((channel), (term), \ 848 (unsigned int)strlen(term), \ 849 NULL, 0, \ 850 LIBSSH2_TERM_WIDTH, \ 851 LIBSSH2_TERM_HEIGHT, \ 852 LIBSSH2_TERM_WIDTH_PX, \ 853 LIBSSH2_TERM_HEIGHT_PX) 854 855LIBSSH2_API int libssh2_channel_request_pty_size_ex(LIBSSH2_CHANNEL *channel, 856 int width, int height, 857 int width_px, 858 int height_px); 859#define libssh2_channel_request_pty_size(channel, width, height) \ 860 libssh2_channel_request_pty_size_ex((channel), (width), (height), 0, 0) 861 862LIBSSH2_API int libssh2_channel_x11_req_ex(LIBSSH2_CHANNEL *channel, 863 int single_connection, 864 const char *auth_proto, 865 const char *auth_cookie, 866 int screen_number); 867#define libssh2_channel_x11_req(channel, screen_number) \ 868 libssh2_channel_x11_req_ex((channel), 0, NULL, NULL, (screen_number)) 869 870LIBSSH2_API int libssh2_channel_signal_ex(LIBSSH2_CHANNEL *channel, 871 const char *signame, 872 size_t signame_len); 873#define libssh2_channel_signal(channel, signame) \ 874 libssh2_channel_signal_ex((channel), signame, strlen(signame)) 875 876LIBSSH2_API int libssh2_channel_process_startup(LIBSSH2_CHANNEL *channel, 877 const char *request, 878 unsigned int request_len, 879 const char *message, 880 unsigned int message_len); 881#define libssh2_channel_shell(channel) \ 882 libssh2_channel_process_startup((channel), "shell", sizeof("shell") - 1, \ 883 NULL, 0) 884#define libssh2_channel_exec(channel, command) \ 885 libssh2_channel_process_startup((channel), "exec", sizeof("exec") - 1, \ 886 (command), (unsigned int)strlen(command)) 887#define libssh2_channel_subsystem(channel, subsystem) \ 888 libssh2_channel_process_startup((channel), "subsystem", \ 889 sizeof("subsystem") - 1, (subsystem), \ 890 (unsigned int)strlen(subsystem)) 891 892LIBSSH2_API ssize_t libssh2_channel_read_ex(LIBSSH2_CHANNEL *channel, 893 int stream_id, char *buf, 894 size_t buflen); 895#define libssh2_channel_read(channel, buf, buflen) \ 896 libssh2_channel_read_ex((channel), 0, \ 897 (buf), (buflen)) 898#define libssh2_channel_read_stderr(channel, buf, buflen) \ 899 libssh2_channel_read_ex((channel), SSH_EXTENDED_DATA_STDERR, \ 900 (buf), (buflen)) 901 902LIBSSH2_API int libssh2_poll_channel_read(LIBSSH2_CHANNEL *channel, 903 int extended); 904 905LIBSSH2_API unsigned long 906libssh2_channel_window_read_ex(LIBSSH2_CHANNEL *channel, 907 unsigned long *read_avail, 908 unsigned long *window_size_initial); 909#define libssh2_channel_window_read(channel) \ 910 libssh2_channel_window_read_ex((channel), NULL, NULL) 911 912/* libssh2_channel_receive_window_adjust() is DEPRECATED, do not use! */ 913LIBSSH2_API unsigned long 914libssh2_channel_receive_window_adjust(LIBSSH2_CHANNEL *channel, 915 unsigned long adjustment, 916 unsigned char force); 917 918LIBSSH2_API int 919libssh2_channel_receive_window_adjust2(LIBSSH2_CHANNEL *channel, 920 unsigned long adjustment, 921 unsigned char force, 922 unsigned int *storewindow); 923 924LIBSSH2_API ssize_t libssh2_channel_write_ex(LIBSSH2_CHANNEL *channel, 925 int stream_id, const char *buf, 926 size_t buflen); 927 928#define libssh2_channel_write(channel, buf, buflen) \ 929 libssh2_channel_write_ex((channel), 0, \ 930 (buf), (buflen)) 931#define libssh2_channel_write_stderr(channel, buf, buflen) \ 932 libssh2_channel_write_ex((channel), SSH_EXTENDED_DATA_STDERR, \ 933 (buf), (buflen)) 934 935LIBSSH2_API unsigned long 936libssh2_channel_window_write_ex(LIBSSH2_CHANNEL *channel, 937 unsigned long *window_size_initial); 938#define libssh2_channel_window_write(channel) \ 939 libssh2_channel_window_write_ex((channel), NULL) 940 941LIBSSH2_API void libssh2_session_set_blocking(LIBSSH2_SESSION* session, 942 int blocking); 943LIBSSH2_API int libssh2_session_get_blocking(LIBSSH2_SESSION* session); 944 945LIBSSH2_API void libssh2_channel_set_blocking(LIBSSH2_CHANNEL *channel, 946 int blocking); 947 948LIBSSH2_API void libssh2_session_set_timeout(LIBSSH2_SESSION* session, 949 long timeout); 950LIBSSH2_API long libssh2_session_get_timeout(LIBSSH2_SESSION* session); 951 952LIBSSH2_API void libssh2_session_set_read_timeout(LIBSSH2_SESSION* session, 953 long timeout); 954LIBSSH2_API long libssh2_session_get_read_timeout(LIBSSH2_SESSION* session); 955 956/* libssh2_channel_handle_extended_data() is DEPRECATED, do not use! */ 957LIBSSH2_API void libssh2_channel_handle_extended_data(LIBSSH2_CHANNEL *channel, 958 int ignore_mode); 959LIBSSH2_API int libssh2_channel_handle_extended_data2(LIBSSH2_CHANNEL *channel, 960 int ignore_mode); 961 962/* libssh2_channel_ignore_extended_data() is defined below for BC with version 963 * 0.1 964 * 965 * Future uses should use libssh2_channel_handle_extended_data() directly if 966 * LIBSSH2_CHANNEL_EXTENDED_DATA_MERGE is passed, extended data will be read 967 * (FIFO) from the standard data channel 968 */ 969/* DEPRECATED */ 970#define libssh2_channel_ignore_extended_data(channel, ignore) \ 971 libssh2_channel_handle_extended_data((channel), (ignore) ? \ 972 LIBSSH2_CHANNEL_EXTENDED_DATA_IGNORE : \ 973 LIBSSH2_CHANNEL_EXTENDED_DATA_NORMAL) 974 975#define LIBSSH2_CHANNEL_FLUSH_EXTENDED_DATA -1 976#define LIBSSH2_CHANNEL_FLUSH_ALL -2 977LIBSSH2_API int libssh2_channel_flush_ex(LIBSSH2_CHANNEL *channel, 978 int streamid); 979#define libssh2_channel_flush(channel) libssh2_channel_flush_ex((channel), 0) 980#define libssh2_channel_flush_stderr(channel) \ 981 libssh2_channel_flush_ex((channel), SSH_EXTENDED_DATA_STDERR) 982 983LIBSSH2_API int libssh2_channel_get_exit_status(LIBSSH2_CHANNEL* channel); 984LIBSSH2_API int libssh2_channel_get_exit_signal(LIBSSH2_CHANNEL* channel, 985 char **exitsignal, 986 size_t *exitsignal_len, 987 char **errmsg, 988 size_t *errmsg_len, 989 char **langtag, 990 size_t *langtag_len); 991LIBSSH2_API int libssh2_channel_send_eof(LIBSSH2_CHANNEL *channel); 992LIBSSH2_API int libssh2_channel_eof(LIBSSH2_CHANNEL *channel); 993LIBSSH2_API int libssh2_channel_wait_eof(LIBSSH2_CHANNEL *channel); 994LIBSSH2_API int libssh2_channel_close(LIBSSH2_CHANNEL *channel); 995LIBSSH2_API int libssh2_channel_wait_closed(LIBSSH2_CHANNEL *channel); 996LIBSSH2_API int libssh2_channel_free(LIBSSH2_CHANNEL *channel); 997 998/* libssh2_scp_recv is DEPRECATED, do not use! */ 999LIBSSH2_API LIBSSH2_CHANNEL *libssh2_scp_recv(LIBSSH2_SESSION *session, 1000 const char *path, 1001 struct stat *sb); 1002/* Use libssh2_scp_recv2() for large (> 2GB) file support on windows */ 1003LIBSSH2_API LIBSSH2_CHANNEL *libssh2_scp_recv2(LIBSSH2_SESSION *session, 1004 const char *path, 1005 libssh2_struct_stat *sb); 1006LIBSSH2_API LIBSSH2_CHANNEL *libssh2_scp_send_ex(LIBSSH2_SESSION *session, 1007 const char *path, int mode, 1008 size_t size, long mtime, 1009 long atime); 1010LIBSSH2_API LIBSSH2_CHANNEL * 1011libssh2_scp_send64(LIBSSH2_SESSION *session, const char *path, int mode, 1012 libssh2_int64_t size, time_t mtime, time_t atime); 1013 1014#define libssh2_scp_send(session, path, mode, size) \ 1015 libssh2_scp_send_ex((session), (path), (mode), (size), 0, 0) 1016 1017/* DEPRECATED */ 1018LIBSSH2_API int libssh2_base64_decode(LIBSSH2_SESSION *session, char **dest, 1019 unsigned int *dest_len, 1020 const char *src, unsigned int src_len); 1021 1022LIBSSH2_API 1023const char *libssh2_version(int req_version_num); 1024 1025typedef enum { 1026 libssh2_no_crypto = 0, 1027 libssh2_openssl, 1028 libssh2_gcrypt, 1029 libssh2_mbedtls, 1030 libssh2_wincng, 1031 libssh2_os400qc3 1032} libssh2_crypto_engine_t; 1033 1034LIBSSH2_API 1035libssh2_crypto_engine_t libssh2_crypto_engine(void); 1036 1037#define HAVE_LIBSSH2_KNOWNHOST_API 0x010101 /* since 1.1.1 */ 1038#define HAVE_LIBSSH2_VERSION_API 0x010100 /* libssh2_version since 1.1 */ 1039#define HAVE_LIBSSH2_CRYPTOENGINE_API 0x011100 /* libssh2_crypto_engine 1040 since 1.11 */ 1041 1042struct libssh2_knownhost { 1043 unsigned int magic; /* magic stored by the library */ 1044 void *node; /* handle to the internal representation of this host */ 1045 char *name; /* this is NULL if no plain text host name exists */ 1046 char *key; /* key in base64/printable format */ 1047 int typemask; 1048}; 1049 1050/* 1051 * libssh2_knownhost_init() 1052 * 1053 * Init a collection of known hosts. Returns the pointer to a collection. 1054 * 1055 */ 1056LIBSSH2_API LIBSSH2_KNOWNHOSTS * 1057libssh2_knownhost_init(LIBSSH2_SESSION *session); 1058 1059/* 1060 * libssh2_knownhost_add() 1061 * 1062 * Add a host and its associated key to the collection of known hosts. 1063 * 1064 * The 'type' argument specifies on what format the given host and keys are: 1065 * 1066 * plain - ascii "hostname.domain.tld" 1067 * sha1 - SHA1(<salt> <host>) base64-encoded! 1068 * custom - another hash 1069 * 1070 * If 'sha1' is selected as type, the salt must be provided to the salt 1071 * argument. This too base64 encoded. 1072 * 1073 * The SHA-1 hash is what OpenSSH can be told to use in known_hosts files. If 1074 * a custom type is used, salt is ignored and you must provide the host 1075 * pre-hashed when checking for it in the libssh2_knownhost_check() function. 1076 * 1077 * The keylen parameter may be omitted (zero) if the key is provided as a 1078 * NULL-terminated base64-encoded string. 1079 */ 1080 1081/* host format (2 bits) */ 1082#define LIBSSH2_KNOWNHOST_TYPE_MASK 0xffff 1083#define LIBSSH2_KNOWNHOST_TYPE_PLAIN 1 1084#define LIBSSH2_KNOWNHOST_TYPE_SHA1 2 /* always base64 encoded */ 1085#define LIBSSH2_KNOWNHOST_TYPE_CUSTOM 3 1086 1087/* key format (2 bits) */ 1088#define LIBSSH2_KNOWNHOST_KEYENC_MASK (3<<16) 1089#define LIBSSH2_KNOWNHOST_KEYENC_RAW (1<<16) 1090#define LIBSSH2_KNOWNHOST_KEYENC_BASE64 (2<<16) 1091 1092/* type of key (4 bits) */ 1093#define LIBSSH2_KNOWNHOST_KEY_MASK (15<<18) 1094#define LIBSSH2_KNOWNHOST_KEY_SHIFT 18 1095#define LIBSSH2_KNOWNHOST_KEY_RSA1 (1<<18) 1096#define LIBSSH2_KNOWNHOST_KEY_SSHRSA (2<<18) 1097#define LIBSSH2_KNOWNHOST_KEY_SSHDSS (3<<18) 1098#define LIBSSH2_KNOWNHOST_KEY_ECDSA_256 (4<<18) 1099#define LIBSSH2_KNOWNHOST_KEY_ECDSA_384 (5<<18) 1100#define LIBSSH2_KNOWNHOST_KEY_ECDSA_521 (6<<18) 1101#define LIBSSH2_KNOWNHOST_KEY_ED25519 (7<<18) 1102#define LIBSSH2_KNOWNHOST_KEY_UNKNOWN (15<<18) 1103 1104LIBSSH2_API int 1105libssh2_knownhost_add(LIBSSH2_KNOWNHOSTS *hosts, 1106 const char *host, 1107 const char *salt, 1108 const char *key, size_t keylen, int typemask, 1109 struct libssh2_knownhost **store); 1110 1111/* 1112 * libssh2_knownhost_addc() 1113 * 1114 * Add a host and its associated key to the collection of known hosts. 1115 * 1116 * Takes a comment argument that may be NULL. A NULL comment indicates 1117 * there is no comment and the entry will end directly after the key 1118 * when written out to a file. An empty string "" comment will indicate an 1119 * empty comment which will cause a single space to be written after the key. 1120 * 1121 * The 'type' argument specifies on what format the given host and keys are: 1122 * 1123 * plain - ascii "hostname.domain.tld" 1124 * sha1 - SHA1(<salt> <host>) base64-encoded! 1125 * custom - another hash 1126 * 1127 * If 'sha1' is selected as type, the salt must be provided to the salt 1128 * argument. This too base64 encoded. 1129 * 1130 * The SHA-1 hash is what OpenSSH can be told to use in known_hosts files. 1131 * If a custom type is used, salt is ignored and you must provide the host 1132 * pre-hashed when checking for it in the libssh2_knownhost_check() function. 1133 * 1134 * The keylen parameter may be omitted (zero) if the key is provided as a 1135 * NULL-terminated base64-encoded string. 1136 */ 1137 1138LIBSSH2_API int 1139libssh2_knownhost_addc(LIBSSH2_KNOWNHOSTS *hosts, 1140 const char *host, 1141 const char *salt, 1142 const char *key, size_t keylen, 1143 const char *comment, size_t commentlen, int typemask, 1144 struct libssh2_knownhost **store); 1145 1146/* 1147 * libssh2_knownhost_check() 1148 * 1149 * Check a host and its associated key against the collection of known hosts. 1150 * 1151 * The type is the type/format of the given host name. 1152 * 1153 * plain - ascii "hostname.domain.tld" 1154 * custom - prehashed base64 encoded. Note that this cannot use any salts. 1155 * 1156 * 1157 * 'knownhost' may be set to NULL if you don't care about that info. 1158 * 1159 * Returns: 1160 * 1161 * LIBSSH2_KNOWNHOST_CHECK_* values, see below 1162 * 1163 */ 1164 1165#define LIBSSH2_KNOWNHOST_CHECK_MATCH 0 1166#define LIBSSH2_KNOWNHOST_CHECK_MISMATCH 1 1167#define LIBSSH2_KNOWNHOST_CHECK_NOTFOUND 2 1168#define LIBSSH2_KNOWNHOST_CHECK_FAILURE 3 1169 1170LIBSSH2_API int 1171libssh2_knownhost_check(LIBSSH2_KNOWNHOSTS *hosts, 1172 const char *host, const char *key, size_t keylen, 1173 int typemask, 1174 struct libssh2_knownhost **knownhost); 1175 1176/* this function is identital to the above one, but also takes a port 1177 argument that allows libssh2 to do a better check */ 1178LIBSSH2_API int 1179libssh2_knownhost_checkp(LIBSSH2_KNOWNHOSTS *hosts, 1180 const char *host, int port, 1181 const char *key, size_t keylen, 1182 int typemask, 1183 struct libssh2_knownhost **knownhost); 1184 1185/* 1186 * libssh2_knownhost_del() 1187 * 1188 * Remove a host from the collection of known hosts. The 'entry' struct is 1189 * retrieved by a call to libssh2_knownhost_check(). 1190 * 1191 */ 1192LIBSSH2_API int 1193libssh2_knownhost_del(LIBSSH2_KNOWNHOSTS *hosts, 1194 struct libssh2_knownhost *entry); 1195 1196/* 1197 * libssh2_knownhost_free() 1198 * 1199 * Free an entire collection of known hosts. 1200 * 1201 */ 1202LIBSSH2_API void 1203libssh2_knownhost_free(LIBSSH2_KNOWNHOSTS *hosts); 1204 1205/* 1206 * libssh2_knownhost_readline() 1207 * 1208 * Pass in a line of a file of 'type'. It makes libssh2 read this line. 1209 * 1210 * LIBSSH2_KNOWNHOST_FILE_OPENSSH is the only supported type. 1211 * 1212 */ 1213LIBSSH2_API int 1214libssh2_knownhost_readline(LIBSSH2_KNOWNHOSTS *hosts, 1215 const char *line, size_t len, int type); 1216 1217/* 1218 * libssh2_knownhost_readfile() 1219 * 1220 * Add hosts+key pairs from a given file. 1221 * 1222 * Returns a negative value for error or number of successfully added hosts. 1223 * 1224 * This implementation currently only knows one 'type' (openssh), all others 1225 * are reserved for future use. 1226 */ 1227 1228#define LIBSSH2_KNOWNHOST_FILE_OPENSSH 1 1229 1230LIBSSH2_API int 1231libssh2_knownhost_readfile(LIBSSH2_KNOWNHOSTS *hosts, 1232 const char *filename, int type); 1233 1234/* 1235 * libssh2_knownhost_writeline() 1236 * 1237 * Ask libssh2 to convert a known host to an output line for storage. 1238 * 1239 * Note that this function returns LIBSSH2_ERROR_BUFFER_TOO_SMALL if the given 1240 * output buffer is too small to hold the desired output. 1241 * 1242 * This implementation currently only knows one 'type' (openssh), all others 1243 * are reserved for future use. 1244 * 1245 */ 1246LIBSSH2_API int 1247libssh2_knownhost_writeline(LIBSSH2_KNOWNHOSTS *hosts, 1248 struct libssh2_knownhost *known, 1249 char *buffer, size_t buflen, 1250 size_t *outlen, /* the amount of written data */ 1251 int type); 1252 1253/* 1254 * libssh2_knownhost_writefile() 1255 * 1256 * Write hosts+key pairs to a given file. 1257 * 1258 * This implementation currently only knows one 'type' (openssh), all others 1259 * are reserved for future use. 1260 */ 1261 1262LIBSSH2_API int 1263libssh2_knownhost_writefile(LIBSSH2_KNOWNHOSTS *hosts, 1264 const char *filename, int type); 1265 1266/* 1267 * libssh2_knownhost_get() 1268 * 1269 * Traverse the internal list of known hosts. Pass NULL to 'prev' to get 1270 * the first one. Or pass a pointer to the previously returned one to get the 1271 * next. 1272 * 1273 * Returns: 1274 * 0 if a fine host was stored in 'store' 1275 * 1 if end of hosts 1276 * [negative] on errors 1277 */ 1278LIBSSH2_API int 1279libssh2_knownhost_get(LIBSSH2_KNOWNHOSTS *hosts, 1280 struct libssh2_knownhost **store, 1281 struct libssh2_knownhost *prev); 1282 1283#define HAVE_LIBSSH2_AGENT_API 0x010202 /* since 1.2.2 */ 1284 1285struct libssh2_agent_publickey { 1286 unsigned int magic; /* magic stored by the library */ 1287 void *node; /* handle to the internal representation of key */ 1288 unsigned char *blob; /* public key blob */ 1289 size_t blob_len; /* length of the public key blob */ 1290 char *comment; /* comment in printable format */ 1291}; 1292 1293/* 1294 * libssh2_agent_init() 1295 * 1296 * Init an ssh-agent handle. Returns the pointer to the handle. 1297 * 1298 */ 1299LIBSSH2_API LIBSSH2_AGENT * 1300libssh2_agent_init(LIBSSH2_SESSION *session); 1301 1302/* 1303 * libssh2_agent_connect() 1304 * 1305 * Connect to an ssh-agent. 1306 * 1307 * Returns 0 if succeeded, or a negative value for error. 1308 */ 1309LIBSSH2_API int 1310libssh2_agent_connect(LIBSSH2_AGENT *agent); 1311 1312/* 1313 * libssh2_agent_list_identities() 1314 * 1315 * Request an ssh-agent to list identities. 1316 * 1317 * Returns 0 if succeeded, or a negative value for error. 1318 */ 1319LIBSSH2_API int 1320libssh2_agent_list_identities(LIBSSH2_AGENT *agent); 1321 1322/* 1323 * libssh2_agent_get_identity() 1324 * 1325 * Traverse the internal list of public keys. Pass NULL to 'prev' to get 1326 * the first one. Or pass a pointer to the previously returned one to get the 1327 * next. 1328 * 1329 * Returns: 1330 * 0 if a fine public key was stored in 'store' 1331 * 1 if end of public keys 1332 * [negative] on errors 1333 */ 1334LIBSSH2_API int 1335libssh2_agent_get_identity(LIBSSH2_AGENT *agent, 1336 struct libssh2_agent_publickey **store, 1337 struct libssh2_agent_publickey *prev); 1338 1339/* 1340 * libssh2_agent_userauth() 1341 * 1342 * Do publickey user authentication with the help of ssh-agent. 1343 * 1344 * Returns 0 if succeeded, or a negative value for error. 1345 */ 1346LIBSSH2_API int 1347libssh2_agent_userauth(LIBSSH2_AGENT *agent, 1348 const char *username, 1349 struct libssh2_agent_publickey *identity); 1350 1351/* 1352 * libssh2_agent_sign() 1353 * 1354 * Sign a payload using a system-installed ssh-agent. 1355 * 1356 * Returns 0 if succeeded, or a negative value for error. 1357 */ 1358LIBSSH2_API int 1359libssh2_agent_sign(LIBSSH2_AGENT *agent, 1360 struct libssh2_agent_publickey *identity, 1361 unsigned char **sig, 1362 size_t *s_len, 1363 const unsigned char *data, 1364 size_t d_len, 1365 const char *method, 1366 unsigned int method_len); 1367 1368/* 1369 * libssh2_agent_disconnect() 1370 * 1371 * Close a connection to an ssh-agent. 1372 * 1373 * Returns 0 if succeeded, or a negative value for error. 1374 */ 1375LIBSSH2_API int 1376libssh2_agent_disconnect(LIBSSH2_AGENT *agent); 1377 1378/* 1379 * libssh2_agent_free() 1380 * 1381 * Free an ssh-agent handle. This function also frees the internal 1382 * collection of public keys. 1383 */ 1384LIBSSH2_API void 1385libssh2_agent_free(LIBSSH2_AGENT *agent); 1386 1387/* 1388 * libssh2_agent_set_identity_path() 1389 * 1390 * Allows a custom agent identity socket path beyond SSH_AUTH_SOCK env 1391 * 1392 */ 1393LIBSSH2_API void 1394libssh2_agent_set_identity_path(LIBSSH2_AGENT *agent, 1395 const char *path); 1396 1397/* 1398 * libssh2_agent_get_identity_path() 1399 * 1400 * Returns the custom agent identity socket path if set 1401 * 1402 */ 1403LIBSSH2_API const char * 1404libssh2_agent_get_identity_path(LIBSSH2_AGENT *agent); 1405 1406/* 1407 * libssh2_keepalive_config() 1408 * 1409 * Set how often keepalive messages should be sent. WANT_REPLY 1410 * indicates whether the keepalive messages should request a response 1411 * from the server. INTERVAL is number of seconds that can pass 1412 * without any I/O, use 0 (the default) to disable keepalives. To 1413 * avoid some busy-loop corner-cases, if you specify an interval of 1 1414 * it will be treated as 2. 1415 * 1416 * Note that non-blocking applications are responsible for sending the 1417 * keepalive messages using libssh2_keepalive_send(). 1418 */ 1419LIBSSH2_API void libssh2_keepalive_config(LIBSSH2_SESSION *session, 1420 int want_reply, 1421 unsigned interval); 1422 1423/* 1424 * libssh2_keepalive_send() 1425 * 1426 * Send a keepalive message if needed. SECONDS_TO_NEXT indicates how 1427 * many seconds you can sleep after this call before you need to call 1428 * it again. Returns 0 on success, or LIBSSH2_ERROR_SOCKET_SEND on 1429 * I/O errors. 1430 */ 1431LIBSSH2_API int libssh2_keepalive_send(LIBSSH2_SESSION *session, 1432 int *seconds_to_next); 1433 1434/* NOTE NOTE NOTE 1435 libssh2_trace() has no function in builds that aren't built with debug 1436 enabled 1437 */ 1438LIBSSH2_API int libssh2_trace(LIBSSH2_SESSION *session, int bitmask); 1439#define LIBSSH2_TRACE_TRANS (1<<1) 1440#define LIBSSH2_TRACE_KEX (1<<2) 1441#define LIBSSH2_TRACE_AUTH (1<<3) 1442#define LIBSSH2_TRACE_CONN (1<<4) 1443#define LIBSSH2_TRACE_SCP (1<<5) 1444#define LIBSSH2_TRACE_SFTP (1<<6) 1445#define LIBSSH2_TRACE_ERROR (1<<7) 1446#define LIBSSH2_TRACE_PUBLICKEY (1<<8) 1447#define LIBSSH2_TRACE_SOCKET (1<<9) 1448 1449typedef void (*libssh2_trace_handler_func)(LIBSSH2_SESSION*, 1450 void *, 1451 const char *, 1452 size_t); 1453LIBSSH2_API int libssh2_trace_sethandler(LIBSSH2_SESSION *session, 1454 void *context, 1455 libssh2_trace_handler_func callback); 1456 1457#ifdef __cplusplus 1458} /* extern "C" */ 1459#endif 1460 1461#endif /* !RC_INVOKED */ 1462 1463#endif /* LIBSSH2_H */