Debian Codegraph @

docs/HACKING-CRYPTO

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