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
Этот коммит содержится в:
monnerat
GitHub
родитель
1a082247a7
Коммит
6e0f17f672
@ -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);
|
||||
|
||||
Загрузка…
x
Ссылка в новой задаче
Block a user