Skip to content

Commit

Permalink
Update docs.
Browse files Browse the repository at this point in the history 
Signed-off-by: Steffen Jaeckel <s@jaeckel.eu>
  • Loading branch information
@sjaeckel
sjaeckel committed Feb 24, 2025
1 parent 49d8206 commit a611b27
Show file tree
Hide file tree
Showing 2 changed files with 82 additions and 82 deletions.
118 changes: 62 additions & 56 deletions doc/crypt.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5809,91 +5809,97 @@ \subsection{Signature Generation}

\index{ecc\_sign\_hash()}
\begin{verbatim}
int ecc_sign_hash(const unsigned char *in,
unsigned long inlen,
unsigned char *out,
unsigned long *outlen,
prng_state *prng,
int wprng,
ecc_key *key);
int ecc_sign_hash(const unsigned char *in, unsigned long inlen,
unsigned char *out, unsigned long *outlen,
prng_state *prng, int wprng, const ecc_key *key);
\end{verbatim}

This function will ECDSA sign the message digest stored in the array pointed to by \textit{in} of length \textit{inlen} octets. The signature
will be stored in the array pointed to by \textit{out} of length \textit{outlen} octets. The function requires a properly seeded PRNG, and
the ECC \textit{key} provided must be a private key.
This function will ECDSA sign the message digest stored in the array pointed to by \texttt{in} of length \texttt{inlen} octets. The signature
will be stored in the array pointed to by \texttt{out} of length \texttt{outlen} octets. The function requires a properly seeded PRNG, and
the ECC \texttt{key} provided must be a private key.

\index{ecc\_sign\_hash\_rfc7518()}
\begin{verbatim}
int ecc_sign_hash_rfc7518(const unsigned char *in,
unsigned long inlen,
unsigned char *out,
unsigned long *outlen,
prng_state *prng,
int wprng,
ecc_key *key);
int ecc_sign_hash_rfc7518(const unsigned char *in, unsigned long inlen,
unsigned char *out, unsigned long *outlen,
prng_state *prng, int wprng, const ecc_key *key);
\end{verbatim}

This function creates the same ECDSA signature as \textit{ecc\_sign\_hash} only the output format is different.
This function creates the same ECDSA signature as \texttt{ecc\_sign\_hash()} only the output format is different.
The format follows \url{https://tools.ietf.org/html/rfc7518#section-3.4}, sometimes it is also called plain signature.

\index{ecc\_sign\_hash\_ex()}
\index{ecc\_sign\_hash\_rfc7518\_ex()}
\begin{verbatim}
int ecc_sign_hash_ex(const unsigned char *in,
unsigned long inlen,
unsigned char *out,
unsigned long *outlen,
prng_state *prng,
int wprng,
ecc_signature_type sigformat,
int *recid,
ecc_key *key);
int ecc_sign_hash_rfc7518_ex(const unsigned char *in, unsigned long inlen,
unsigned char *out, unsigned long *outlen,
prng_state *prng, int wprng,
int *recid, const ecc_key *key);
\end{verbatim}

This function is an extended version of the ECDSA signature in \texttt{ecc\_sign\_hash\_rfc7518()}, but with an additional output of the recovery ID
for use with \texttt{ecc\_recover\_key()}.

\index{ecc\_sign\_hash\_rfc5656()}
\begin{verbatim}
int ecc_sign_hash_rfc5656(const unsigned char *in, unsigned long inlen,
unsigned char *out, unsigned long *outlen,
prng_state *prng, int wprng, const ecc_key *key);
\end{verbatim}

This function is an extended version of the ECDSA signature in \textit{ecc\_sign\_hash}, but with a choice of output formats
and an optional output of the recovery ID for use with \textit{ecc\_recover\_key}.
This function creates an ECDSA signature and the output format is according to RFC5656, i.e. SSH compatible.

\index{ecc\_sign\_hash\_eth27()}
\begin{verbatim}
int ecc_sign_hash_eth27(const unsigned char *in, unsigned long inlen,
unsigned char *out, unsigned long *outlen,
prng_state *prng, int wprng, const ecc_key *key);
\end{verbatim}

This function creates an ECDSA signature and the output format is according to the Ethereum format.
With this API the curve is limited to secp256k1.

\subsection{Signature Verification}
\index{ecc\_verify\_hash()}
\begin{verbatim}
int ecc_verify_hash(const unsigned char *sig,
unsigned long siglen,
const unsigned char *hash,
unsigned long hashlen,
int *stat,
ecc_key *key);
int ecc_verify_hash(const unsigned char *sig, unsigned long siglen,
const unsigned char *hash, unsigned long hashlen,
int *stat, const ecc_key *key);
\end{verbatim}

This function will verify the ECDSA signature in the array pointed to by \textit{sig} of length \textit{siglen} octets, against the message digest
pointed to by the array \textit{hash} of length \textit{hashlen}. It will store a non--zero value in \textit{stat} if the signature is valid. Note:
This function will verify the ECDSA signature in the array pointed to by \texttt{sig} of length \texttt{siglen} octets, against the message digest
pointed to by the array \texttt{hash} of length \texttt{hashlen}. It will store a non--zero value in \texttt{stat} if the signature is valid. Note:
the function will not return an error if the signature is invalid. It will return an error, if the actual signature payload is an invalid format.
The ECC \textit{key} must be the public (or private) ECC key corresponding to the key that performed the signature.
The function \textit{ecc\_verify\_hash} implements signature format according to X9.62 ECDSA, and the output is compliant for GF(p) curves.
The ECC \texttt{key} must be the public (or private) ECC key corresponding to the key that performed the signature.
The function \texttt{ecc\_verify\_hash()} implements signature format according to X9.62 ECDSA, and the output is compliant for GF(p) curves.

\index{ecc\_verify\_hash\_rfc7518()}
\begin{verbatim}
int ecc_verify_hash_rfc7518(const unsigned char *sig,
unsigned long siglen,
const unsigned char *hash,
unsigned long hashlen,
int *stat,
ecc_key *key);
int ecc_verify_hash_rfc7518(const unsigned char *sig, unsigned long siglen,
const unsigned char *hash, unsigned long hashlen,
int *stat, const ecc_key *key);
\end{verbatim}

This function validate the ECDSA signature as \textit{ecc\_verify\_hash} only the signature input format
This function validate the ECDSA signature as \texttt{ecc\_verify\_hash()} only the signature input format
follows \url{https://tools.ietf.org/html/rfc7518#section-3.4}.

\index{ecc\_verify\_hash\_ex()}
\index{ecc\_verify\_hash\_rfc5656()}
\begin{verbatim}
int ecc_verify_hash_ex(const unsigned char *sig,
unsigned long siglen,
const unsigned char *hash,
unsigned long hashlen,
ecc_signature_type sigformat,
int *stat,
ecc_key *key);
int ecc_verify_hash_rfc5656(const unsigned char *sig, unsigned long siglen,
const unsigned char *hash, unsigned long hashlen,
int *stat, const ecc_key *key);
\end{verbatim}

This function validates the ECDSA signature according to the format defined in RFC5656, i.e. SSH compatible.


\index{ecc\_verify\_hash\_eth27()}
\begin{verbatim}
int ecc_verify_hash_eth27(const unsigned char *sig, unsigned long siglen,
const unsigned char *hash, unsigned long hashlen,
int *stat, const ecc_key *key);
\end{verbatim}

This function validates an ECDSA signature as \textit{ecc\_verify\_hash} but with a choice of signature formats.
This function validates the ECDSA signature according to the Ethereum format.

{\bf BEWARE:} With ECC if you try to sign a hash that is bigger than your ECC key you can run into problems. The math
will still work, and in effect the signature will still work. With ECC keys the strength of the signature is limited
Expand Down
46 changes: 20 additions & 26 deletions src/headers/tomcrypt_pk.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -316,19 +316,17 @@ void ecc_free(ecc_key *key);
int ecc_export(unsigned char *out, unsigned long *outlen, int type, const ecc_key *key);
int ecc_import(const unsigned char *in, unsigned long inlen, ecc_key *key);
int ecc_import_ex(const unsigned char *in, unsigned long inlen, ecc_key *key, const ltc_ecc_curve *cu);
#endif

int ecc_ansi_x963_export(const ecc_key *key, unsigned char *out, unsigned long *outlen);
int ecc_ansi_x963_import(const unsigned char *in, unsigned long inlen, ecc_key *key);
int ecc_ansi_x963_import_ex(const unsigned char *in, unsigned long inlen, ecc_key *key, const ltc_ecc_curve *cu);

#if defined(LTC_DER)
int ecc_export_openssl(unsigned char *out, unsigned long *outlen, int type, const ecc_key *key);
int ecc_import_openssl(const unsigned char *in, unsigned long inlen, ecc_key *key);
int ecc_import_pkcs8(const unsigned char *in, unsigned long inlen, const password_ctx *pw_ctx, ecc_key *key);
int ecc_import_x509(const unsigned char *in, unsigned long inlen, ecc_key *key);
int ecc_export_openssl(unsigned char *out, unsigned long *outlen, int type, const ecc_key *key);
int ecc_import_openssl(const unsigned char *in, unsigned long inlen, ecc_key *key);
int ecc_import_pkcs8(const unsigned char *in, unsigned long inlen, const password_ctx *pw_ctx, ecc_key *key);
int ecc_import_x509(const unsigned char *in, unsigned long inlen, ecc_key *key);
#endif

int ecc_ansi_x963_export(const ecc_key *key, unsigned char *out, unsigned long *outlen);
int ecc_ansi_x963_import(const unsigned char *in, unsigned long inlen, ecc_key *key);
int ecc_ansi_x963_import_ex(const unsigned char *in, unsigned long inlen, ecc_key *key, const ltc_ecc_curve *cu);

int ecc_shared_secret(const ecc_key *private_key, const ecc_key *public_key,
unsigned char *out, unsigned long *outlen);

Expand All @@ -345,6 +343,10 @@ int ecc_decrypt_key(const unsigned char *in, unsigned long inlen,
int ecc_sign_hash(const unsigned char *in, unsigned long inlen,
unsigned char *out, unsigned long *outlen,
prng_state *prng, int wprng, const ecc_key *key);

int ecc_verify_hash(const unsigned char *sig, unsigned long siglen,
const unsigned char *hash, unsigned long hashlen,
int *stat, const ecc_key *key);
#endif

int ecc_sign_hash_rfc7518(const unsigned char *in, unsigned long inlen,
Expand All @@ -356,32 +358,24 @@ int ecc_sign_hash_rfc7518_ex(const unsigned char *in, unsigned long inlen,
prng_state *prng, int wprng,
int *recid, const ecc_key *key);

#if defined(LTC_SSH)
int ecc_sign_hash_rfc5656(const unsigned char *in, unsigned long inlen,
unsigned char *out, unsigned long *outlen,
prng_state *prng, int wprng, const ecc_key *key);
#endif

int ecc_sign_hash_eth27(const unsigned char *in, unsigned long inlen,
unsigned char *out, unsigned long *outlen,
prng_state *prng, int wprng, const ecc_key *key);

#if defined(LTC_DER)
int ecc_verify_hash(const unsigned char *sig, unsigned long siglen,
const unsigned char *hash, unsigned long hashlen,
int *stat, const ecc_key *key);
#endif

int ecc_verify_hash_rfc7518(const unsigned char *sig, unsigned long siglen,
const unsigned char *hash, unsigned long hashlen,
int *stat, const ecc_key *key);

#if defined(LTC_SSH)
int ecc_sign_hash_rfc5656(const unsigned char *in, unsigned long inlen,
unsigned char *out, unsigned long *outlen,
prng_state *prng, int wprng, const ecc_key *key);

int ecc_verify_hash_rfc5656(const unsigned char *sig, unsigned long siglen,
const unsigned char *hash, unsigned long hashlen,
int *stat, const ecc_key *key);
#endif

int ecc_sign_hash_eth27(const unsigned char *in, unsigned long inlen,
unsigned char *out, unsigned long *outlen,
prng_state *prng, int wprng, const ecc_key *key);

int ecc_verify_hash_eth27(const unsigned char *sig, unsigned long siglen,
const unsigned char *hash, unsigned long hashlen,
int *stat, const ecc_key *key);
Expand Down

0 comments on commit a611b27

Please sign in to comment.