HACKING.CRYPTO: keep up to date with new crypto definitions from code. (#466)

File: HACKING.CRYPTO

Notes:
This commit updates the HACKING.CRYPTO documentation file in an attempt to make it in sync with current code.
New documented features are:

SHA384
SHA512
ECDSA
ED25519

Credit:
monnerat

docs/HACKING.CRYPTO

@@ -165,21 +165,86 @@ void libssh2_hmac_sha256_init(libssh2_hmac_ctx *ctx,
 Setup the HMAC computation context ctx for an HMAC-256 computation using the
 keylen-byte key. Is invoked just after libssh2_hmac_ctx_init().
 
-3.3) SHA-512
+3.3) SHA-384
-LIBSSH2_HMAC_SHA512
+Mandatory if ECDSA is implemented. Can be omitted otherwise.
-#define as 1 if the crypto library supports HMAC-SHA-512, else 0.
+
-If defined as 0, the rest of this section can be omitted.
+SHA384_DIGEST_LENGTH
+#define to 48, the SHA-384 digest length.
+
+libssh2_sha384_ctx
+Type of an SHA-384 computation context. Generally a struct.
+
+int libssh2_sha384_init(libssh2_sha384_ctx *x);
+Initializes the SHA-384 computation context at x.
+Returns 1 for success and 0 for failure
+
+void libssh2_sha384_update(libssh2_sha384_ctx ctx,
+	                   const unsigned char *data,
+	                   size_t len);
+Continue computation of SHA-384 on len bytes at data using context ctx.
+Note: if the ctx parameter is modified by the underlying code,
+this procedure must be implemented as a macro to map ctx --> &ctx.
+
+void libssh2_sha384_final(libssh2_sha384_ctx ctx,
+	                  unsigned char output[SHA384_DIGEST_LENGTH]);
+Gets the computed SHA-384 signature from context ctx into the output buffer.
+Release the context.
+Note: if the ctx parameter is modified by the underlying code,
+this procedure must be implemented as a macro to map ctx --> &ctx.
+
+int libssh2_sha384(const unsigned char *message,
+                   unsigned long len,
+                   unsigned char output[SHA384_DIGEST_LENGTH]);
+Computes the SHA-384 signature over the given message of length len and
+store the result into the output buffer.
+Return 1 if error, else 0.
+
+3.4) SHA-512
+Must always be implemented.
 
 SHA512_DIGEST_LENGTH
 #define to 64, the SHA-512 digest length.
 
+libssh2_sha512_ctx
+Type of an SHA-512 computation context. Generally a struct.
+
+int libssh2_sha512_init(libssh2_sha512_ctx *x);
+Initializes the SHA-512 computation context at x.
+Returns 1 for success and 0 for failure
+
+void libssh2_sha512_update(libssh2_sha512_ctx ctx,
+	                   const unsigned char *data,
+	                   size_t len);
+Continue computation of SHA-512 on len bytes at data using context ctx.
+Note: if the ctx parameter is modified by the underlying code,
+this procedure must be implemented as a macro to map ctx --> &ctx.
+
+void libssh2_sha512_final(libssh2_sha512_ctx ctx,
+	                  unsigned char output[SHA512_DIGEST_LENGTH]);
+Gets the computed SHA-512 signature from context ctx into the output buffer.
+Release the context.
+Note: if the ctx parameter is modified by the underlying code,
+this procedure must be implemented as a macro to map ctx --> &ctx.
+
+int libssh2_sha512(const unsigned char *message,
+                   unsigned long len,
+                   unsigned char output[SHA512_DIGEST_LENGTH]);
+Computes the SHA-512 signature over the given message of length len and
+store the result into the output buffer.
+Return 1 if error, else 0.
+Note: Seems unused in current code, but defined in each crypto library backend.
+
+LIBSSH2_HMAC_SHA512
+#define as 1 if the crypto library supports HMAC-SHA-512, else 0.
+If defined as 0, the rest of this section can be omitted.
+
 void libssh2_hmac_sha512_init(libssh2_hmac_ctx *ctx,
 	                      const void *key,
 	                      int keylen);
 Setup the HMAC computation context ctx for an HMAC-512 computation using the
 keylen-byte key. Is invoked just after libssh2_hmac_ctx_init().
 
-3.4) MD5
+3.5) MD5
 LIBSSH2_MD5
 #define to 1 if the crypto library supports MD5, else 0.
 If defined as 0, the rest of this section can be omitted.
@@ -215,7 +280,7 @@ void libssh2_hmac_md5_init(libssh2_hmac_ctx *ctx,
 Setup the HMAC computation context ctx for an HMAC-MD5 computation using the
 keylen-byte key. Is invoked just after libssh2_hmac_ctx_init().
 
-3.5) RIPEMD-160
+3.6) RIPEMD-160
 LIBSSH2_HMAC_RIPEMD
 #define as 1 if the crypto library supports HMAC-RIPEMD-160, else 0.
 If defined as 0, the rest of this section can be omitted.
@@ -438,6 +503,17 @@ d) g, MSB first, with high order bit = 0.
 e) pub_key, MSB first, with high order bit = 0.
 Each item is preceded by its 32-bit byte length, MSB first.
 
+Format of an ECDSA public key:
+a) "ecdsa-sha2-nistp256" or "ecdsa-sha2-nistp384" or "ecdsa-sha2-nistp521".
+b) domain: "nistp256", "nistp384" or "nistp521" matching a).
+c) raw public key ("octal").
+Each item is preceded by its 32-bit byte length, MSB first.
+
+Format of an ED25519 public key:
+a) "ssh-ed25519".
+b) raw key (32 bytes).
+Each item is preceded by its 32-bit byte length, MSB first.
+
 int _libssh2_pub_priv_keyfile(LIBSSH2_SESSION *session,
                               unsigned char **method,
                               size_t *method_len,
@@ -467,6 +543,7 @@ Both buffers have to be allocated using LIBSSH2_ALLOC().
 Returns 0 if OK, else -1.
 This procedure is already prototyped in crypto.h.
 
+
 7.1) RSA
 LIBSSH2_RSA
 #define as 1 if the crypto library supports RSA, else 0.
@@ -529,7 +606,7 @@ int _libssh2_rsa_sha1_verify(libssh2_rsa_ctx *rsa,
                              const unsigned char *sig,
                              unsigned long sig_len,
                              const unsigned char *m, unsigned long m_len);
-Verify (sig, siglen) signature of (m, m_len) using an SHA-1 hash and the
+Verify (sig, sig_len) signature of (m, m_len) using an SHA-1 hash and the
 RSA context.
 Return 0 if OK, else -1.
 This procedure is already prototyped in crypto.h.
@@ -627,6 +704,191 @@ void _libssh2_dsa_free(libssh2_dsa_ctx *dsactx);
 Releases the DSA computation context at dsactx.
 
 
+7.3) ECDSA
+LIBSSH2_ECDSA
+#define as 1 if the crypto library supports ECDSA, else 0.
+If defined as 0, _libssh2_ec_key should be defined as void and the rest of
+this section can be omitted.
+
+EC_MAX_POINT_LEN
+Maximum point length. Usually defined as ((528 * 2 / 8) + 1) (= 133).
+
+libssh2_ecdsa_ctx
+Type of an ECDSA computation context. Generally a struct.
+
+_libssh2_ec_key
+Type of an elliptic curve key.
+
+libssh2_curve_type
+An enum type defining curve types. Current supported identifiers are:
+	LIBSSH2_EC_CURVE_NISTP256
+	LIBSSH2_EC_CURVE_NISTP384
+	LIBSSH2_EC_CURVE_NISTP521
+
+int _libssh2_ecdsa_create_key(_libssh2_ec_key **out_private_key,
+                              unsigned char **out_public_key_octal,
+                              size_t *out_public_key_octal_len,
+                              libssh2_curve_type curve_type);
+Create a new ECDSA private key of type curve_type and return it at
+out_private_key. If out_public_key_octal is not NULL, store an allocated
+pointer to the associated public key in "octal" form in it and its length
+at out_public_key_octal_len.
+Return 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ecdsa_new_private(libssh2_ecdsa_ctx **ec_ctx,
+                               LIBSSH2_SESSION * session,
+                               const char *filename,
+                               unsigned const char *passphrase);
+Reads an ECDSA private key from PEM file filename into a new ECDSA context.
+Must call _libssh2_init_if_needed().
+Return 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ecdsa_new_private_frommemory(libssh2_ecdsa_ctx ** ec_ctx,
+                                        LIBSSH2_SESSION * session,
+                                        const char *filedata,
+                                        size_t filedata_len,
+                                        unsigned const char *passphrase);
+Builds an ECDSA private key from PEM data at filedata of length filedata_len
+into a new ECDSA context stored at ec_ctx.
+Must call _libssh2_init_if_needed().
+Return 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ecdsa_curve_name_with_octal_new(libssh2_ecdsa_ctx **ecdsactx,
+                                             const unsigned char *k,
+                                             size_t k_len,
+                                             libssh2_curve_type type);
+Stores at ecdsactx a new ECDSA context associated with the given curve type
+and with "octal" form public key (k, k_len).
+Return 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ecdsa_new_openssh_private(libssh2_ecdsa_ctx **ec_ctx,
+                                       LIBSSH2_SESSION * session,
+                                       const char *filename,
+                                       unsigned const char *passphrase);
+Reads a PEM-encoded ECDSA private key from file filename encrypted with
+passphrase and stores at ec_ctx a new ECDSA context for it.
+Return 0 if OK, else -1.
+Currently used only from openssl backend (ought to be private).
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ecdsa_sign(LIBSSH2_SESSION *session, libssh2_ecdsa_ctx *ec_ctx,
+                        const unsigned char *hash, unsigned long hash_len,
+                        unsigned char **signature, size_t *signature_len);
+ECDSA signs the (hash, hashlen) hash bytes and stores the allocated
+signature at (signature, signature_len). Hash algorithm used should be
+SHA-256, SHA-384 or SHA-512 depending on type stored in ECDSA context at ec_ctx.
+Signature buffer must be allocated from the given session.
+Returns 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ecdsa_verify(libssh2_ecdsa_ctx *ctx,
+                          const unsigned char *r, size_t r_len,
+                          const unsigned char *s, size_t s_len,
+                          const unsigned char *m, size_t m_len);
+Verify the ECDSA signature made of (r, r_len) and (s, s_len) of (m, m_len)
+using the hash algorithm configured in the ECDSA context ctx.
+Return 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+libssh2_curve_type _libssh2_ecdsa_get_curve_type(libssh2_ecdsa_ctx *ecdsactx);
+Returns the curve type associated with given context.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ecdsa_curve_type_from_name(const char *name,
+                                        libssh2_curve_type *out_type);
+Stores in out_type the curve type matching string name of the form
+"ecdsa-sha2-nistpxxx".
+Return 0 if OK, else -1.
+Currently used only from openssl backend (ought to be private).
+This procedure is already prototyped in crypto.h.
+
+void _libssh2_ecdsa_free(libssh2_ecdsa_ctx *ecdsactx);
+Releases the ECDSA computation context at ecdsactx.
+
+
+7.4) ED25519
+LIBSSH2_ED25519
+#define as 1 if the crypto library supports ED25519, else 0.
+If defined as 0, the rest of this section can be omitted.
+
+
+libssh2_ed25519_ctx
+Type of an ED25519 computation context. Generally a struct.
+
+int _libssh2_curve25519_new(LIBSSH2_SESSION *session, libssh2_ed25519_ctx **ctx,
+                            uint8_t **out_public_key,
+                            uint8_t **out_private_key);
+Generates an ED25519 key pair, stores a pointer to them at out_private_key
+and out_public_key respectively and stores at ctx a new ED25519 context for
+this key.
+Argument ctx, out_private_key and out_public key may be NULL to disable storing
+the corresponding value.
+Length of each key is LIBSSH2_ED25519_KEY_LEN (32 bytes).
+Key buffers are allocated and should be released by caller after use.
+Returns 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ed25519_new_private(libssh2_ed25519_ctx **ed_ctx,
+                                 LIBSSH2_SESSION *session,
+                                 const char *filename,
+                                 const uint8_t *passphrase);
+Reads an ED25519 private key from PEM file filename into a new ED25519 context.
+Must call _libssh2_init_if_needed().
+Return 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ed25519_new_public(libssh2_ed25519_ctx **ed_ctx,
+                                LIBSSH2_SESSION *session,
+                                const unsigned char *raw_pub_key,
+                                 const uint8_t key_len);
+Stores at ed_ctx a new ED25519 key context for raw public key (raw_pub_key,
+key_len).
+Return 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ed25519_new_private_frommemory(libssh2_ed25519_ctx **ed_ctx,
+                                            LIBSSH2_SESSION *session,
+                                            const char *filedata,
+                                            size_t filedata_len,
+                                            unsigned const char *passphrase);
+Builds an ED25519 private key from PEM data at filedata of length filedata_len
+into a new ED25519 context stored at ed_ctx.
+Must call _libssh2_init_if_needed().
+Return 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ed25519_sign(libssh2_ed25519_ctx *ctx, LIBSSH2_SESSION *session,
+                          uint8_t **out_sig, size_t *out_sig_len,
+                          const uint8_t *message, size_t message_len);
+ED25519 signs the (message, message_len) bytes and stores the allocated
+signature at (sig, sig_len).
+Signature buffer is allocated from the given session.
+Returns 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_ed25519_verify(libssh2_ed25519_ctx *ctx, const uint8_t *s,
+                            size_t s_len, const uint8_t *m, size_t m_len);
+Verify (s, s_len) signature of (m, m_len) using the given ED25519 context.
+Return 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+int _libssh2_curve25519_gen_k(_libssh2_bn **k,
+                              uint8_t private_key[LIBSSH2_ED25519_KEY_LEN],
+                              uint8_t srvr_public_key[LIBSSH2_ED25519_KEY_LEN]);
+Computes a shared ED25519 secret key from the given raw server public key and 
+raw client public key and stores it as a big number in *k. Big number should
+have been initialized before calling this function.
+Returns 0 if OK, else -1.
+This procedure is already prototyped in crypto.h.
+
+void _libssh2_ed25519_free(libssh2_ed25519_ctx *ed25519ctx);
+Releases the ED25519 computation context at ed25519ctx.
+
+
 8) Miscellaneous
 
 void libssh2_prepare_iovec(struct iovec *vector, unsigned int len);