diff --git a/docs/HACKING.CRYPTO b/docs/HACKING.CRYPTO index e1c4f38..b78a014 100644 --- a/docs/HACKING.CRYPTO +++ b/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 -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. +3.3) SHA-384 +Mandatory if ECDSA is implemented. Can be omitted otherwise. + +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);