1 Definitions needed to implement a specific crypto library 2 3This document offers some hints about implementing a new crypto library 4interface. 5 6A crypto library interface consists of at least a header file, defining 7entities referenced from the libssh2 core modules. 8Real code implementation (if needed), is left at the implementor's choice. 9 10This document lists the entities that must/may be defined in the header file. 11 12Procedures listed as "void" may indeed have a result type: the void indication 13indicates the libssh2 core modules never use the function result. 14 15 160) Build system. 17 18Adding a crypto backend to the autotools build system (./configure) is easy: 19 200.1) Add one new line in configure.ac 21 22m4_set_add([crypto_backends], [newname]) 23 24This automatically creates a --with-crypto=newname option. 25 260.2) Add an m4_case stanza to LIBSSH2_CRYPTO_CHECK in acinclude.m4 27 28This must check for all required libraries, and if found set and AC_SUBST a 29variable with the library linking flags. The recommended method is to use 30LIBSSH2_LIB_HAVE_LINKFLAGS from LIBSSH2_CRYPTO_CHECK, which automatically 31creates and handles a --with-$newname-prefix option and sets an 32LTLIBNEWNAME variable on success. 33 340.3) Create Makefile.newname.inc in the top-level directory 35 36This must set CRYPTO_CSOURCES, CRYPTO_HHEADERS and CRYPTO_LTLIBS. 37Set CRYPTO_CSOURCES and CRYPTO_HHEADERS to the new backend source files 38and set CRYPTO_LTLIBS to the required library linking parameters, e.g. 39$(LTLIBNEWNAME) as generated by by LIBSSH2_LIB_HAVE_LINKFLAGS. 40 410.4) Add a new block in src/Makefile.am 42 43if NEWNAME 44include ../Makefile.newname.inc 45endif 46 47 481) Crypto library initialization/termination. 49 50void libssh2_crypto_init(void); 51Initializes the crypto library. May be an empty macro if not needed. 52 53void libssh2_crypto_exit(void); 54Terminates the crypto library use. May be an empty macro if not needed. 55 56 572) HMAC 58 59libssh2_hmac_ctx 60Type of an HMAC computation context. Generally a struct. 61Used for all hash algorithms. 62 63void libssh2_hmac_ctx_init(libssh2_hmac_ctx ctx); 64Initializes the HMAC computation context ctx. 65Called before setting-up the hash algorithm. 66Note: if the ctx parameter is modified by the underlying code, 67this procedure must be implemented as a macro to map ctx --> &ctx. 68 69void libssh2_hmac_update(libssh2_hmac_ctx ctx, 70 const unsigned char *data, 71 int datalen); 72Continue computation of an HMAC on datalen bytes at data using context ctx. 73Note: if the ctx parameter is modified by the underlying code, 74this procedure must be implemented as a macro to map ctx --> &ctx. 75 76void libssh2_hmac_final(libssh2_hmac_ctx ctx, 77 unsigned char output[]); 78Get the computed HMAC from context ctx into the output buffer. The 79minimum data buffer size depends on the HMAC hash algorithm. 80Note: if the ctx parameter is modified by the underlying code, 81this procedure must be implemented as a macro to map ctx --> &ctx. 82 83void libssh2_hmac_cleanup(libssh2_hmac_ctx *ctx); 84Releases the HMAC computation context at ctx. 85 86 873) Hash algorithms. 88 893.1) SHA-1 90Must always be implemented. 91 92SHA_DIGEST_LENGTH 93#define to 20, the SHA-1 digest length. 94 95libssh2_sha1_ctx 96Type of an SHA-1 computation context. Generally a struct. 97 98int libssh2_sha1_init(libssh2_sha1_ctx *x); 99Initializes the SHA-1 computation context at x. 100Returns 1 for success and 0 for failure 101 102void libssh2_sha1_update(libssh2_sha1_ctx ctx, 103 const unsigned char *data, 104 size_t len); 105Continue computation of SHA-1 on len bytes at data using context ctx. 106Note: if the ctx parameter is modified by the underlying code, 107this procedure must be implemented as a macro to map ctx --> &ctx. 108 109void libssh2_sha1_final(libssh2_sha1_ctx ctx, 110 unsigned char output[SHA_DIGEST_LEN]); 111Get the computed SHA-1 signature from context ctx and store it into the 112output buffer. 113Release the context. 114Note: if the ctx parameter is modified by the underlying code, 115this procedure must be implemented as a macro to map ctx --> &ctx. 116 117void libssh2_hmac_sha1_init(libssh2_hmac_ctx *ctx, 118 const void *key, 119 int keylen); 120Setup the HMAC computation context ctx for an HMAC-SHA-1 computation using the 121keylen-byte key. Is invoked just after libssh2_hmac_ctx_init(). 122 1233.2) SHA-256 124Must always be implemented. 125 126SHA256_DIGEST_LENGTH 127#define to 32, the SHA-256 digest length. 128 129libssh2_sha256_ctx 130Type of an SHA-256 computation context. Generally a struct. 131 132int libssh2_sha256_init(libssh2_sha256_ctx *x); 133Initializes the SHA-256 computation context at x. 134Returns 1 for success and 0 for failure 135 136void libssh2_sha256_update(libssh2_sha256_ctx ctx, 137 const unsigned char *data, 138 size_t len); 139Continue computation of SHA-256 on len bytes at data using context ctx. 140Note: if the ctx parameter is modified by the underlying code, 141this procedure must be implemented as a macro to map ctx --> &ctx. 142 143void libssh2_sha256_final(libssh2_sha256_ctx ctx, 144 unsigned char output[SHA256_DIGEST_LENGTH]); 145Gets the computed SHA-256 signature from context ctx into the output buffer. 146Release the context. 147Note: if the ctx parameter is modified by the underlying code, 148this procedure must be implemented as a macro to map ctx --> &ctx. 149 150int libssh2_sha256(const unsigned char *message, 151 unsigned long len, 152 unsigned char output[SHA256_DIGEST_LENGTH]); 153Computes the SHA-256 signature over the given message of length len and 154store the result into the output buffer. 155Return 1 if error, else 0. 156Note: Seems unused in current code, but defined in each crypto library backend. 157 158LIBSSH2_HMAC_SHA256 159#define as 1 if the crypto library supports HMAC-SHA-256, else 0. 160If defined as 0, the rest of this section can be omitted. 161 162void libssh2_hmac_sha256_init(libssh2_hmac_ctx *ctx, 163 const void *key, 164 int keylen); 165Setup the HMAC computation context ctx for an HMAC-256 computation using the 166keylen-byte key. Is invoked just after libssh2_hmac_ctx_init(). 167 1683.3) SHA-384 169Mandatory if ECDSA is implemented. Can be omitted otherwise. 170 171SHA384_DIGEST_LENGTH 172#define to 48, the SHA-384 digest length. 173 174libssh2_sha384_ctx 175Type of an SHA-384 computation context. Generally a struct. 176 177int libssh2_sha384_init(libssh2_sha384_ctx *x); 178Initializes the SHA-384 computation context at x. 179Returns 1 for success and 0 for failure 180 181void libssh2_sha384_update(libssh2_sha384_ctx ctx, 182 const unsigned char *data, 183 size_t len); 184Continue computation of SHA-384 on len bytes at data using context ctx. 185Note: if the ctx parameter is modified by the underlying code, 186this procedure must be implemented as a macro to map ctx --> &ctx. 187 188void libssh2_sha384_final(libssh2_sha384_ctx ctx, 189 unsigned char output[SHA384_DIGEST_LENGTH]); 190Gets the computed SHA-384 signature from context ctx into the output buffer. 191Release the context. 192Note: if the ctx parameter is modified by the underlying code, 193this procedure must be implemented as a macro to map ctx --> &ctx. 194 195int libssh2_sha384(const unsigned char *message, 196 unsigned long len, 197 unsigned char output[SHA384_DIGEST_LENGTH]); 198Computes the SHA-384 signature over the given message of length len and 199store the result into the output buffer. 200Return 1 if error, else 0. 201 2023.4) SHA-512 203Must always be implemented. 204 205SHA512_DIGEST_LENGTH 206#define to 64, the SHA-512 digest length. 207 208libssh2_sha512_ctx 209Type of an SHA-512 computation context. Generally a struct. 210 211int libssh2_sha512_init(libssh2_sha512_ctx *x); 212Initializes the SHA-512 computation context at x. 213Returns 1 for success and 0 for failure 214 215void libssh2_sha512_update(libssh2_sha512_ctx ctx, 216 const unsigned char *data, 217 size_t len); 218Continue computation of SHA-512 on len bytes at data using context ctx. 219Note: if the ctx parameter is modified by the underlying code, 220this procedure must be implemented as a macro to map ctx --> &ctx. 221 222void libssh2_sha512_final(libssh2_sha512_ctx ctx, 223 unsigned char output[SHA512_DIGEST_LENGTH]); 224Gets the computed SHA-512 signature from context ctx into the output buffer. 225Release the context. 226Note: if the ctx parameter is modified by the underlying code, 227this procedure must be implemented as a macro to map ctx --> &ctx. 228 229int libssh2_sha512(const unsigned char *message, 230 unsigned long len, 231 unsigned char output[SHA512_DIGEST_LENGTH]); 232Computes the SHA-512 signature over the given message of length len and 233store the result into the output buffer. 234Return 1 if error, else 0. 235Note: Seems unused in current code, but defined in each crypto library backend. 236 237LIBSSH2_HMAC_SHA512 238#define as 1 if the crypto library supports HMAC-SHA-512, else 0. 239If defined as 0, the rest of this section can be omitted. 240 241void libssh2_hmac_sha512_init(libssh2_hmac_ctx *ctx, 242 const void *key, 243 int keylen); 244Setup the HMAC computation context ctx for an HMAC-512 computation using the 245keylen-byte key. Is invoked just after libssh2_hmac_ctx_init(). 246 2473.5) MD5 248LIBSSH2_MD5 249#define to 1 if the crypto library supports MD5, else 0. 250If defined as 0, the rest of this section can be omitted. 251 252MD5_DIGEST_LENGTH 253#define to 16, the MD5 digest length. 254 255libssh2_md5_ctx 256Type of an MD5 computation context. Generally a struct. 257 258int libssh2_md5_init(libssh2_md5_ctx *x); 259Initializes the MD5 computation context at x. 260Returns 1 for success and 0 for failure 261 262void libssh2_md5_update(libssh2_md5_ctx ctx, 263 const unsigned char *data, 264 size_t len); 265Continues computation of MD5 on len bytes at data using context ctx. 266Returns 1 for success and 0 for failure. 267Note: if the ctx parameter is modified by the underlying code, 268this procedure must be implemented as a macro to map ctx --> &ctx. 269 270void libssh2_md5_final(libssh2_md5_ctx ctx, 271 unsigned char output[MD5_DIGEST_LENGTH]); 272Gets the computed MD5 signature from context ctx into the output buffer. 273Release the context. 274Note: if the ctx parameter is modified by the underlying code, 275this procedure must be implemented as a macro to map ctx --> &ctx. 276 277void libssh2_hmac_md5_init(libssh2_hmac_ctx *ctx, 278 const void *key, 279 int keylen); 280Setup the HMAC computation context ctx for an HMAC-MD5 computation using the 281keylen-byte key. Is invoked just after libssh2_hmac_ctx_init(). 282 2833.6) RIPEMD-160 284LIBSSH2_HMAC_RIPEMD 285#define as 1 if the crypto library supports HMAC-RIPEMD-160, else 0. 286If defined as 0, the rest of this section can be omitted. 287 288void libssh2_hmac_ripemd160_init(libssh2_hmac_ctx *ctx, 289 const void *key, 290 int keylen); 291Setup the HMAC computation context ctx for an HMAC-RIPEMD-160 computation using 292the keylen-byte key. Is invoked just after libssh2_hmac_ctx_init(). 293Returns 1 for success and 0 for failure. 294 295 2964) Bidirectional key ciphers. 297 298_libssh2_cipher_ctx 299Type of a cipher computation context. 300 301_libssh2_cipher_type(name); 302Macro defining name as storage identifying a cipher algorithm for 303the crypto library interface. No trailing semicolon. 304 305int _libssh2_cipher_init(_libssh2_cipher_ctx *h, 306 _libssh2_cipher_type(algo), 307 unsigned char *iv, 308 unsigned char *secret, 309 int encrypt); 310Creates a cipher context for the given algorithm with the initialization vector 311iv and the secret key secret. Prepare for encryption or decryption depending on 312encrypt. 313Return 0 if OK, else -1. 314This procedure is already prototyped in crypto.h. 315 316int _libssh2_cipher_crypt(_libssh2_cipher_ctx *ctx, 317 _libssh2_cipher_type(algo), 318 int encrypt, 319 unsigned char *block, 320 size_t blocksize); 321Encrypt or decrypt in-place data at (block, blocksize) using the given 322context and/or algorithm. 323Return 0 if OK, else -1. 324This procedure is already prototyped in crypto.h. 325 326void _libssh2_cipher_dtor(_libssh2_cipher_ctx *ctx); 327Release cipher context at ctx. 328 3294.1) AES 3304.1.1) AES in CBC block mode. 331LIBSSH2_AES 332#define as 1 if the crypto library supports AES in CBC mode, else 0. 333If defined as 0, the rest of this section can be omitted. 334 335_libssh2_cipher_aes128 336AES-128-CBC algorithm identifier initializer. 337#define with constant value of type _libssh2_cipher_type(). 338 339_libssh2_cipher_aes192 340AES-192-CBC algorithm identifier initializer. 341#define with constant value of type _libssh2_cipher_type(). 342 343_libssh2_cipher_aes256 344AES-256-CBC algorithm identifier initializer. 345#define with constant value of type _libssh2_cipher_type(). 346 3474.1.2) AES in CTR block mode. 348LIBSSH2_AES_CTR 349#define as 1 if the crypto library supports AES in CTR mode, else 0. 350If defined as 0, the rest of this section can be omitted. 351 352_libssh2_cipher_aes128ctr 353AES-128-CTR algorithm identifier initializer. 354#define with constant value of type _libssh2_cipher_type(). 355 356_libssh2_cipher_aes192ctr 357AES-192-CTR algorithm identifier initializer. 358#define with constant value of type _libssh2_cipher_type(). 359 360_libssh2_cipher_aes256ctr 361AES-256-CTR algorithm identifier initializer. 362#define with constant value of type _libssh2_cipher_type(). 363 3644.2) Blowfish in CBC block mode. 365LIBSSH2_BLOWFISH 366#define as 1 if the crypto library supports blowfish in CBC mode, else 0. 367If defined as 0, the rest of this section can be omitted. 368 369_libssh2_cipher_blowfish 370Blowfish-CBC algorithm identifier initializer. 371#define with constant value of type _libssh2_cipher_type(). 372 3734.3) RC4. 374LIBSSH2_RC4 375#define as 1 if the crypto library supports RC4 (arcfour), else 0. 376If defined as 0, the rest of this section can be omitted. 377 378_libssh2_cipher_arcfour 379RC4 algorithm identifier initializer. 380#define with constant value of type _libssh2_cipher_type(). 381 3824.4) CAST5 in CBC block mode. 383LIBSSH2_CAST 384#define 1 if the crypto library supports cast, else 0. 385If defined as 0, the rest of this section can be omitted. 386 387_libssh2_cipher_cast5 388CAST5-CBC algorithm identifier initializer. 389#define with constant value of type _libssh2_cipher_type(). 390 3914.5) Tripple DES in CBC block mode. 392LIBSSH2_3DES 393#define as 1 if the crypto library supports TripleDES in CBC mode, else 0. 394If defined as 0, the rest of this section can be omitted. 395 396_libssh2_cipher_3des 397TripleDES-CBC algorithm identifier initializer. 398#define with constant value of type _libssh2_cipher_type(). 399 400 4015) Diffie-Hellman support. 402 4035.1) Diffie-Hellman context. 404_libssh2_dh_ctx 405Type of a Diffie-Hellman computation context. 406Must always be defined. 407 4085.2) Diffie-Hellman computation procedures. 409void libssh2_dh_init(_libssh2_dh_ctx *dhctx); 410Initializes the Diffie-Hellman context at `dhctx'. No effective context 411creation needed here. 412 413int libssh2_dh_key_pair(_libssh2_dh_ctx *dhctx, _libssh2_bn *public, 414 _libssh2_bn *g, _libssh2_bn *p, int group_order, 415 _libssh2_bn_ctx *bnctx); 416Generates a Diffie-Hellman key pair using base `g', prime `p' and the given 417`group_order'. Can use the given big number context `bnctx' if needed. 418The private key is stored as opaque in the Diffie-Hellman context `*dhctx' and 419the public key is returned in `public'. 4200 is returned upon success, else -1. 421 422int libssh2_dh_secret(_libssh2_dh_ctx *dhctx, _libssh2_bn *secret, 423 _libssh2_bn *f, _libssh2_bn *p, _libssh2_bn_ctx * bnctx) 424Computes the Diffie-Hellman secret from the previously created context `*dhctx', 425the public key `f' from the other party and the same prime `p' used at 426context creation. The result is stored in `secret'. 4270 is returned upon success, else -1. 428 429void libssh2_dh_dtor(_libssh2_dh_ctx *dhctx) 430Destroys Diffie-Hellman context at `dhctx' and resets its storage. 431 432 4336) Big numbers. 434Positive multi-byte integers support is sufficient. 435 4366.1) Computation contexts. 437This has a real meaning if the big numbers computations need some context 438storage. If not, use a dummy type and functions (macros). 439 440_libssh2_bn_ctx 441Type of multiple precision computation context. May not be empty. if not used, 442#define as char, for example. 443 444_libssh2_bn_ctx _libssh2_bn_ctx_new(void); 445Returns a new multiple precision computation context. 446 447void _libssh2_bn_ctx_free(_libssh2_bn_ctx ctx); 448Releases a multiple precision computation context. 449 4506.2) Computation support. 451_libssh2_bn 452Type of multiple precision numbers (aka bignumbers or huge integers) for the 453crypto library. 454 455_libssh2_bn * _libssh2_bn_init(void); 456Creates a multiple precision number (preset to zero). 457 458_libssh2_bn * _libssh2_bn_init_from_bin(void); 459Create a multiple precision number intended to be set by the 460_libssh2_bn_from_bin() function (see below). Unlike _libssh2_bn_init(), this 461code may be a dummy initializer if the _libssh2_bn_from_bin() actually 462allocates the number. Returns a value of type _libssh2_bn *. 463 464void _libssh2_bn_free(_libssh2_bn *bn); 465Destroys the multiple precision number at bn. 466 467unsigned long _libssh2_bn_bytes(_libssh2_bn *bn); 468Get the number of bytes needed to store the bits of the multiple precision 469number at bn. 470 471unsigned long _libssh2_bn_bits(_libssh2_bn *bn); 472Returns the number of bits of multiple precision number at bn. 473 474int _libssh2_bn_set_word(_libssh2_bn *bn, unsigned long val); 475Sets the value of bn to val. 476Returns 1 on success, 0 otherwise. 477 478_libssh2_bn * _libssh2_bn_from_bin(_libssh2_bn *bn, int len, 479 const unsigned char *val); 480Converts the positive integer in big-endian form of length len at val 481into a _libssh2_bn and place it in bn. If bn is NULL, a new _libssh2_bn is 482created. 483Returns a pointer to target _libssh2_bn or NULL if error. 484 485int _libssh2_bn_to_bin(_libssh2_bn *bn, unsigned char *val); 486Converts the absolute value of bn into big-endian form and store it at 487val. val must point to _libssh2_bn_bytes(bn) bytes of memory. 488Returns the length of the big-endian number. 489 490 4917) Private key algorithms. 492Format of an RSA public key: 493a) "ssh-rsa". 494b) RSA exponent, MSB first, with high order bit = 0. 495c) RSA modulus, MSB first, with high order bit = 0. 496Each item is preceded by its 32-bit byte length, MSB first. 497 498Format of a DSA public key: 499a) "ssh-dss". 500b) p, MSB first, with high order bit = 0. 501c) q, MSB first, with high order bit = 0. 502d) g, MSB first, with high order bit = 0. 503e) pub_key, MSB first, with high order bit = 0. 504Each item is preceded by its 32-bit byte length, MSB first. 505 506Format of an ECDSA public key: 507a) "ecdsa-sha2-nistp256" or "ecdsa-sha2-nistp384" or "ecdsa-sha2-nistp521". 508b) domain: "nistp256", "nistp384" or "nistp521" matching a). 509c) raw public key ("octal"). 510Each item is preceded by its 32-bit byte length, MSB first. 511 512Format of an ED25519 public key: 513a) "ssh-ed25519". 514b) raw key (32 bytes). 515Each item is preceded by its 32-bit byte length, MSB first. 516 517int _libssh2_pub_priv_keyfile(LIBSSH2_SESSION *session, 518 unsigned char **method, 519 size_t *method_len, 520 unsigned char **pubkeydata, 521 size_t *pubkeydata_len, 522 const char *privatekey, 523 const char *passphrase); 524Reads a private key from file privatekey and extract the public key --> 525(pubkeydata, pubkeydata_len). Store the associated method (ssh-rsa or ssh-dss) 526into (method, method_len). 527Both buffers have to be allocated using LIBSSH2_ALLOC(). 528Returns 0 if OK, else -1. 529This procedure is already prototyped in crypto.h. 530 531int _libssh2_pub_priv_keyfilememory(LIBSSH2_SESSION *session, 532 unsigned char **method, 533 size_t *method_len, 534 unsigned char **pubkeydata, 535 size_t *pubkeydata_len, 536 const char *privatekeydata, 537 size_t privatekeydata_len, 538 const char *passphrase); 539Gets a private key from bytes at (privatekeydata, privatekeydata_len) and 540extract the public key --> (pubkeydata, pubkeydata_len). Store the associated 541method (ssh-rsa or ssh-dss) into (method, method_len). 542Both buffers have to be allocated using LIBSSH2_ALLOC(). 543Returns 0 if OK, else -1. 544This procedure is already prototyped in crypto.h. 545 546 5477.1) RSA 548LIBSSH2_RSA 549#define as 1 if the crypto library supports RSA, else 0. 550If defined as 0, the rest of this section can be omitted. 551 552libssh2_rsa_ctx 553Type of an RSA computation context. Generally a struct. 554 555int _libssh2_rsa_new(libssh2_rsa_ctx **rsa, 556 const unsigned char *edata, 557 unsigned long elen, 558 const unsigned char *ndata, 559 unsigned long nlen, 560 const unsigned char *ddata, 561 unsigned long dlen, 562 const unsigned char *pdata, 563 unsigned long plen, 564 const unsigned char *qdata, 565 unsigned long qlen, 566 const unsigned char *e1data, 567 unsigned long e1len, 568 const unsigned char *e2data, 569 unsigned long e2len, 570 const unsigned char *coeffdata, unsigned long coefflen); 571Creates a new context for RSA computations from key source values: 572 pdata, plen Prime number p. Only used if private key known (ddata). 573 qdata, qlen Prime number q. Only used if private key known (ddata). 574 ndata, nlen Modulus n. 575 edata, elen Exponent e. 576 ddata, dlen e^-1 % phi(n) = private key. May be NULL if unknown. 577 e1data, e1len dp = d % (p-1). Only used if private key known (dtata). 578 e2data, e2len dq = d % (q-1). Only used if private key known (dtata). 579 coeffdata, coefflen q^-1 % p. Only used if private key known. 580Returns 0 if OK. 581This procedure is already prototyped in crypto.h. 582Note: the current generic code only calls this function with e and n (public 583key parameters): unless used internally by the backend, it is not needed to 584support the private key and the other parameters here. 585 586int _libssh2_rsa_new_private(libssh2_rsa_ctx **rsa, 587 LIBSSH2_SESSION *session, 588 const char *filename, 589 unsigned const char *passphrase); 590Reads an RSA private key from file filename into a new RSA context. 591Must call _libssh2_init_if_needed(). 592Return 0 if OK, else -1. 593This procedure is already prototyped in crypto.h. 594 595int _libssh2_rsa_new_private_frommemory(libssh2_rsa_ctx **rsa, 596 LIBSSH2_SESSION *session, 597 const char *data, 598 size_t data_len, 599 unsigned const char *passphrase); 600Gets an RSA private key from data into a new RSA context. 601Must call _libssh2_init_if_needed(). 602Return 0 if OK, else -1. 603This procedure is already prototyped in crypto.h. 604 605int _libssh2_rsa_sha1_verify(libssh2_rsa_ctx *rsa, 606 const unsigned char *sig, 607 unsigned long sig_len, 608 const unsigned char *m, unsigned long m_len); 609Verify (sig, sig_len) signature of (m, m_len) using an SHA-1 hash and the 610RSA context. 611Return 0 if OK, else -1. 612This procedure is already prototyped in crypto.h. 613 614int _libssh2_rsa_sha1_signv(LIBSSH2_SESSION *session, 615 unsigned char **sig, size_t *siglen, 616 int count, const struct iovec vector[], 617 libssh2_rsa_ctx *ctx); 618RSA signs the SHA-1 hash computed over the count data chunks in vector. 619Signature is stored at (sig, siglen). 620Signature buffer must be allocated from the given session. 621Returns 0 if OK, else -1. 622Note: this procedure is optional: if provided, it MUST be defined as a macro. 623 624int _libssh2_rsa_sha1_sign(LIBSSH2_SESSION *session, 625 libssh2_rsa_ctx *rsactx, 626 const unsigned char *hash, 627 size_t hash_len, 628 unsigned char **signature, 629 size_t *signature_len); 630RSA signs the (hash, hashlen) SHA-1 hash bytes and stores the allocated 631signature at (signature, signature_len). 632Signature buffer must be allocated from the given session. 633Returns 0 if OK, else -1. 634This procedure is already prototyped in crypto.h. 635Note: this procedure is not used if macro _libssh2_rsa_sha1_signv() is defined. 636 637void _libssh2_rsa_free(libssh2_rsa_ctx *rsactx); 638Releases the RSA computation context at rsactx. 639 640 6417.2) DSA 642LIBSSH2_DSA 643#define as 1 if the crypto library supports DSA, else 0. 644If defined as 0, the rest of this section can be omitted. 645 646 647libssh2_dsa_ctx 648Type of a DSA computation context. Generally a struct. 649 650int _libssh2_dsa_new(libssh2_dsa_ctx **dsa, 651 const unsigned char *pdata, 652 unsigned long plen, 653 const unsigned char *qdata, 654 unsigned long qlen, 655 const unsigned char *gdata, 656 unsigned long glen, 657 const unsigned char *ydata, 658 unsigned long ylen, 659 const unsigned char *x, unsigned long x_len); 660Creates a new context for DSA computations from source key values: 661 pdata, plen Prime number p. Only used if private key known (ddata). 662 qdata, qlen Prime number q. Only used if private key known (ddata). 663 gdata, glen G number. 664 ydata, ylen Public key. 665 xdata, xlen Private key. Only taken if xlen non-zero. 666Returns 0 if OK. 667This procedure is already prototyped in crypto.h. 668 669int _libssh2_dsa_new_private(libssh2_dsa_ctx **dsa, 670 LIBSSH2_SESSION *session, 671 const char *filename, 672 unsigned const char *passphrase); 673Gets a DSA private key from file filename into a new DSA context. 674Must call _libssh2_init_if_needed(). 675Return 0 if OK, else -1. 676This procedure is already prototyped in crypto.h. 677 678int _libssh2_dsa_new_private_frommemory(libssh2_dsa_ctx **dsa, 679 LIBSSH2_SESSION *session, 680 const char *data, 681 size_t data_len, 682 unsigned const char *passphrase); 683Gets a DSA private key from the data_len-bytes data into a new DSA context. 684Must call _libssh2_init_if_needed(). 685Returns 0 if OK, else -1. 686This procedure is already prototyped in crypto.h. 687 688int _libssh2_dsa_sha1_verify(libssh2_dsa_ctx *dsactx, 689 const unsigned char *sig, 690 const unsigned char *m, unsigned long m_len); 691Verify (sig, siglen) signature of (m, m_len) using an SHA-1 hash and the 692DSA context. 693Returns 0 if OK, else -1. 694This procedure is already prototyped in crypto.h. 695 696int _libssh2_dsa_sha1_sign(libssh2_dsa_ctx *dsactx, 697 const unsigned char *hash, 698 unsigned long hash_len, unsigned char *sig); 699DSA signs the (hash, hash_len) data using SHA-1 and store the signature at sig. 700Returns 0 if OK, else -1. 701This procedure is already prototyped in crypto.h. 702 703void _libssh2_dsa_free(libssh2_dsa_ctx *dsactx); 704Releases the DSA computation context at dsactx. 705 706 7077.3) ECDSA 708LIBSSH2_ECDSA 709#define as 1 if the crypto library supports ECDSA, else 0. 710If defined as 0, _libssh2_ec_key should be defined as void and the rest of 711this section can be omitted. 712 713EC_MAX_POINT_LEN 714Maximum point length. Usually defined as ((528 * 2 / 8) + 1) (= 133). 715 716libssh2_ecdsa_ctx 717Type of an ECDSA computation context. Generally a struct. 718 719_libssh2_ec_key 720Type of an elliptic curve key. 721 722libssh2_curve_type 723An enum type defining curve types. Current supported identifiers are: 724 LIBSSH2_EC_CURVE_NISTP256 725 LIBSSH2_EC_CURVE_NISTP384 726 LIBSSH2_EC_CURVE_NISTP521 727 728int _libssh2_ecdsa_create_key(_libssh2_ec_key **out_private_key, 729 unsigned char **out_public_key_octal, 730 size_t *out_public_key_octal_len, 731 libssh2_curve_type curve_type); 732Create a new ECDSA private key of type curve_type and return it at 733out_private_key. If out_public_key_octal is not NULL, store an allocated 734pointer to the associated public key in "octal" form in it and its length 735at out_public_key_octal_len. 736Return 0 if OK, else -1. 737This procedure is already prototyped in crypto.h. 738 739int _libssh2_ecdsa_new_private(libssh2_ecdsa_ctx **ec_ctx, 740 LIBSSH2_SESSION * session, 741 const char *filename, 742 unsigned const char *passphrase); 743Reads an ECDSA private key from PEM file filename into a new ECDSA context. 744Must call _libssh2_init_if_needed(). 745Return 0 if OK, else -1. 746This procedure is already prototyped in crypto.h. 747 748int _libssh2_ecdsa_new_private_frommemory(libssh2_ecdsa_ctx ** ec_ctx, 749 LIBSSH2_SESSION * session, 750 const char *filedata, 751 size_t filedata_len, 752 unsigned const char *passphrase); 753Builds an ECDSA private key from PEM data at filedata of length filedata_len 754into a new ECDSA context stored at ec_ctx. 755Must call _libssh2_init_if_needed(). 756Return 0 if OK, else -1. 757This procedure is already prototyped in crypto.h. 758 759int _libssh2_ecdsa_curve_name_with_octal_new(libssh2_ecdsa_ctx **ecdsactx, 760 const unsigned char *k, 761 size_t k_len, 762 libssh2_curve_type type); 763Stores at ecdsactx a new ECDSA context associated with the given curve type 764and with "octal" form public key (k, k_len). 765Return 0 if OK, else -1. 766This procedure is already prototyped in crypto.h. 767 768int _libssh2_ecdsa_new_openssh_private(libssh2_ecdsa_ctx **ec_ctx, 769 LIBSSH2_SESSION * session, 770 const char *filename, 771 unsigned const char *passphrase); 772Reads a PEM-encoded ECDSA private key from file filename encrypted with 773passphrase and stores at ec_ctx a new ECDSA context for it. 774Return 0 if OK, else -1. 775Currently used only from openssl backend (ought to be private). 776This procedure is already prototyped in crypto.h. 777 778int _libssh2_ecdsa_sign(LIBSSH2_SESSION *session, libssh2_ecdsa_ctx *ec_ctx, 779 const unsigned char *hash, unsigned long hash_len, 780 unsigned char **signature, size_t *signature_len); 781ECDSA signs the (hash, hashlen) hash bytes and stores the allocated 782signature at (signature, signature_len). Hash algorithm used should be 783SHA-256, SHA-384 or SHA-512 depending on type stored in ECDSA context at ec_ctx. 784Signature buffer must be allocated from the given session. 785Returns 0 if OK, else -1. 786This procedure is already prototyped in crypto.h. 787 788int _libssh2_ecdsa_verify(libssh2_ecdsa_ctx *ctx, 789 const unsigned char *r, size_t r_len, 790 const unsigned char *s, size_t s_len, 791 const unsigned char *m, size_t m_len); 792Verify the ECDSA signature made of (r, r_len) and (s, s_len) of (m, m_len) 793using the hash algorithm configured in the ECDSA context ctx. 794Return 0 if OK, else -1. 795This procedure is already prototyped in crypto.h. 796 797libssh2_curve_type _libssh2_ecdsa_get_curve_type(libssh2_ecdsa_ctx *ecdsactx); 798Returns the curve type associated with given context. 799This procedure is already prototyped in crypto.h. 800 801int _libssh2_ecdsa_curve_type_from_name(const char *name, 802 libssh2_curve_type *out_type); 803Stores in out_type the curve type matching string name of the form 804"ecdsa-sha2-nistpxxx". 805Return 0 if OK, else -1. 806Currently used only from openssl backend (ought to be private). 807This procedure is already prototyped in crypto.h. 808 809void _libssh2_ecdsa_free(libssh2_ecdsa_ctx *ecdsactx); 810Releases the ECDSA computation context at ecdsactx. 811 812 8137.4) ED25519 814LIBSSH2_ED25519 815#define as 1 if the crypto library supports ED25519, else 0. 816If defined as 0, the rest of this section can be omitted. 817 818 819libssh2_ed25519_ctx 820Type of an ED25519 computation context. Generally a struct. 821 822int _libssh2_curve25519_new(LIBSSH2_SESSION *session, libssh2_ed25519_ctx **ctx, 823 uint8_t **out_public_key, 824 uint8_t **out_private_key); 825Generates an ED25519 key pair, stores a pointer to them at out_private_key 826and out_public_key respectively and stores at ctx a new ED25519 context for 827this key. 828Argument ctx, out_private_key and out_public key may be NULL to disable storing 829the corresponding value. 830Length of each key is LIBSSH2_ED25519_KEY_LEN (32 bytes). 831Key buffers are allocated and should be released by caller after use. 832Returns 0 if OK, else -1. 833This procedure is already prototyped in crypto.h. 834 835int _libssh2_ed25519_new_private(libssh2_ed25519_ctx **ed_ctx, 836 LIBSSH2_SESSION *session, 837 const char *filename, 838 const uint8_t *passphrase); 839Reads an ED25519 private key from PEM file filename into a new ED25519 context. 840Must call _libssh2_init_if_needed(). 841Return 0 if OK, else -1. 842This procedure is already prototyped in crypto.h. 843 844int _libssh2_ed25519_new_public(libssh2_ed25519_ctx **ed_ctx, 845 LIBSSH2_SESSION *session, 846 const unsigned char *raw_pub_key, 847 const uint8_t key_len); 848Stores at ed_ctx a new ED25519 key context for raw public key (raw_pub_key, 849key_len). 850Return 0 if OK, else -1. 851This procedure is already prototyped in crypto.h. 852 853int _libssh2_ed25519_new_private_frommemory(libssh2_ed25519_ctx **ed_ctx, 854 LIBSSH2_SESSION *session, 855 const char *filedata, 856 size_t filedata_len, 857 unsigned const char *passphrase); 858Builds an ED25519 private key from PEM data at filedata of length filedata_len 859into a new ED25519 context stored at ed_ctx. 860Must call _libssh2_init_if_needed(). 861Return 0 if OK, else -1. 862This procedure is already prototyped in crypto.h. 863 864int _libssh2_ed25519_sign(libssh2_ed25519_ctx *ctx, LIBSSH2_SESSION *session, 865 uint8_t **out_sig, size_t *out_sig_len, 866 const uint8_t *message, size_t message_len); 867ED25519 signs the (message, message_len) bytes and stores the allocated 868signature at (sig, sig_len). 869Signature buffer is allocated from the given session. 870Returns 0 if OK, else -1. 871This procedure is already prototyped in crypto.h. 872 873int _libssh2_ed25519_verify(libssh2_ed25519_ctx *ctx, const uint8_t *s, 874 size_t s_len, const uint8_t *m, size_t m_len); 875Verify (s, s_len) signature of (m, m_len) using the given ED25519 context. 876Return 0 if OK, else -1. 877This procedure is already prototyped in crypto.h. 878 879int _libssh2_curve25519_gen_k(_libssh2_bn **k, 880 uint8_t private_key[LIBSSH2_ED25519_KEY_LEN], 881 uint8_t srvr_public_key[LIBSSH2_ED25519_KEY_LEN]); 882Computes a shared ED25519 secret key from the given raw server public key and 883raw client public key and stores it as a big number in *k. Big number should 884have been initialized before calling this function. 885Returns 0 if OK, else -1. 886This procedure is already prototyped in crypto.h. 887 888void _libssh2_ed25519_free(libssh2_ed25519_ctx *ed25519ctx); 889Releases the ED25519 computation context at ed25519ctx. 890 891 8928) Miscellaneous 893 894void libssh2_prepare_iovec(struct iovec *vector, unsigned int len); 895Prepare len consecutive iovec slots before using them. 896In example, this is needed to preset unused structure slacks on platforms 897requiring it. 898If this is not needed, it should be defined as an empty macro. 899 900int _libssh2_random(unsigned char *buf, int len); 901Store len random bytes at buf. 902Returns 0 if OK, else -1. 903