Skip to content

New ECC API #705

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Nov 18, 2025
Merged

New ECC API #705

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
35a4a5f
Move RFC6979 hash alg to a new ecc signature options struct
sjaeckel Oct 9, 2025
b46c695
Add tests for deprecated APIs
sjaeckel Oct 16, 2025
a642e69
Update makefiles
sjaeckel Oct 16, 2025
7f73f83
Update docs
sjaeckel Nov 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/main.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ jobs:
- { BUILDNAME: 'NO_FAST', BUILDOPTIONS: '-DLTC_NO_FAST', BUILDSCRIPT: '.ci/run.sh' }
- { BUILDNAME: 'NO_FAST+SMALL+NO_TABLES', BUILDOPTIONS: '-DLTC_NO_FAST -DLTC_SMALL_CODE -DLTC_NO_TABLES', BUILDSCRIPT: '.ci/run.sh' }
- { BUILDNAME: 'NO_ASM', BUILDOPTIONS: '-DLTC_NO_ASM', BUILDSCRIPT: '.ci/run.sh' }
- { BUILDNAME: 'NO_DEPRECATED_APIS', BUILDOPTIONS: '-DLTC_NO_DEPRECATED_APIS', BUILDSCRIPT: '.ci/run.sh' }
- { BUILDNAME: 'NO_TIMING_RESISTANCE', BUILDOPTIONS: '-DLTC_NO_ECC_TIMING_RESISTANT -DLTC_NO_RSA_BLINDING', BUILDSCRIPT: '.ci/run.sh' }
- { BUILDNAME: 'FORTUNA_CUSTOM_OPTIONS', BUILDOPTIONS: '-DLTC_FORTUNA_USE_ENCRYPT_ONLY -DLTC_FORTUNA_RESEED_RATELIMIT_STATIC', BUILDSCRIPT: '.ci/run.sh' }
- { BUILDNAME: 'PTHREAD', BUILDOPTIONS: '-DLTC_PTHREAD', BUILDSCRIPT: '.ci/run.sh' }
Expand Down
12 changes: 8 additions & 4 deletions demos/timing.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -872,7 +872,7 @@ static void time_ecc(void)
unsigned char buf[2][256] = { 0 };
unsigned long i, w, x, y, z;
int err, stat;
static unsigned long sizes[] = {
const unsigned long sizes[] = {
#ifdef LTC_ECC_SECP112R1
112/8,
#endif
Expand All @@ -898,6 +898,11 @@ static void time_ecc(void)
521/8,
#endif
100000};
ltc_ecc_sig_opts sig_opts = {
.type = LTC_ECCSIG_RFC7518,
.prng = &yarrow_prng,
.wprng = find_prng ("yarrow")
};

if (ltc_mp.name == NULL) return;

Expand Down Expand Up @@ -969,8 +974,7 @@ static void time_ecc(void)
t_start();
t1 = t_read();
z = sizeof(buf[1]);
if ((err = ecc_sign_hash(buf[0], 20, buf[1], &z, &yarrow_prng,
find_prng("yarrow"), &key)) != CRYPT_OK) {
if ((err = ecc_sign_hash_v2(buf[0], 20, buf[1], &z, &sig_opts, &key)) != CRYPT_OK) {
fprintf(stderr, "\n\necc_sign_hash says %s, wait...no it should say %s...damn you!\n", error_to_string(err), error_to_string(CRYPT_OK));
exit(EXIT_FAILURE);
}
Expand All @@ -988,7 +992,7 @@ static void time_ecc(void)
for (y = 0; y < 256; y++) {
t_start();
t1 = t_read();
if ((err = ecc_verify_hash(buf[1], z, buf[0], 20, &stat, &key)) != CRYPT_OK) {
if ((err = ecc_verify_hash_v2(buf[1], z, buf[0], 20, &sig_opts, &stat, &key)) != CRYPT_OK) {
fprintf(stderr, "\n\necc_verify_hash says %s, wait...no it should say %s...damn you!\n", error_to_string(err), error_to_string(CRYPT_OK));
exit(EXIT_FAILURE);
}
Expand Down
240 changes: 123 additions & 117 deletions doc/crypt.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5812,144 +5812,97 @@ \subsection{ANSI X9.63 Import (deprecated)}
P--192 key, you have in effect 96--bits of security. The library will not warn you if you make this mistake, so it
is important to check yourself before using the signatures.

\subsection{Signature Generation}
To sign a message digest (hash) use the following function:
\subsection{Signature Options}

\index{ecc\_sign\_hash()}
\index{ECC\_SET\_RFC6979\_HASH\_ALG()}
The library supports ECDSA signatures in the following formats.

\index{ecc\_signature\_type}
\begin{small}
\begin{verbatim}
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);
typedef enum ecc_signature_type {
/* ASN.1 encoded, ANSI X9.62 */
LTC_ECCSIG_ANSIX962 = 0x0,
/* raw R, S values */
LTC_ECCSIG_RFC7518 = 0x1,
/* raw R, S, V (+27) values */
LTC_ECCSIG_ETH27 = 0x2,
/* SSH + ECDSA signature format defined by RFC5656 */
LTC_ECCSIG_RFC5656 = 0x3,
} ecc_signature_type;
\end{verbatim}
\end{small}

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

In order to execute standard \textit{ECDSA} it requires a properly seeded \textit{PRNG} which gets passed via \code{prng} and \code{wprng}.

The deterministic signature mechanism according to \textit{RFC6979} is also supported. This does not require a \textit{PRNG}, but
instead a valid hash function shall be set via the macro

\code{ECC\_SET\_RFC6979\_HASH\_ALG(key, hash\_alg)}
c.f. Chapter \ref{sigformat} for further details.

The expected types of the arguments to that macro are \code{(ecc\_key*, const char*)}.
To parametrize the signature API, a specific type \code{ltc\_ecc\_sig\_opts} exists, which must be populated with the desired values.

\index{ecc\_sign\_hash\_rfc7518()}
\index{ltc\_ecc\_sig\_opts}
\begin{small}
\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,
const ecc_key *key);
\end{verbatim}
typedef struct ltc_ecc_sig_opts {
/** Signature type */
ecc_signature_type type;
/** The PRNG to use.
* This must be set in case deterministic signature generation
* according to RFC6979 is not enabled.
*/
prng_state *prng;
int wprng;

This function creates the same \textit{ECDSA} signature as \code{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.
/** Enable generation of a recovery ID.
* This must be set in case one requires the recovery ID of a
* signature operation.
*/
int *recid;

\index{ecc\_sign\_hash\_rfc7518\_ex()}
\begin{verbatim}
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);
/** The hash algorithm to use when creating a signature.
* Setting this will enable RFC6979 compatible signature generation.
*/
const char *rfc6979_hash_alg;
} ltc_ecc_sig_opts;
\end{verbatim}
\end{small}

This function is an extended version of the \textit{ECDSA} signature in \code{ecc\_sign\_hash\_rfc7518()}, but with an additional output of the recovery ID
for use with \code{ecc\_recover\_key()}.
\subsection{Signature Generation}
\label{ecc-sign}
To sign a message digest (hash) use the following function:

\index{ecc\_sign\_hash\_rfc5656()}
\index{ecc\_sign\_hash\_v2()}
\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);
int ecc_sign_hash_v2(const unsigned char *in,
unsigned long inlen,
unsigned char *out,
unsigned long *outlen,
ltc_ecc_sig_opts *opts,
const ecc_key *key);
\end{verbatim}

This function creates an \textit{ECDSA} signature and the output format is according to \textit{RFC5656}, i.e. \textit{SSH} compatible.
This function will \textit{ECDSA} sign the message digest stored in the array pointed to by \code{in} of length \code{inlen} octets. The signature
will be stored in the array pointed to by \code{out} of length \code{outlen} octets. The function requires that the \textit{ECC}
\code{key} provided must be a private key.

\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}
In order to execute standard \textit{ECDSA} it requires a properly seeded \textit{PRNG} which gets passed via \code{opts.prng} and \code{opts.wprng}.

This function creates an \textit{ECDSA} signature and the output format is according to the Ethereum format.
With this API the curve is limited to \textit{secp256k1}.
The deterministic signature mechanism according to \textit{RFC6979} is also supported. This does not require a \textit{PRNG}, but
instead a valid hash function name shall be set in the options' field \code{opts.rfc6979\_hash\_alg}.

\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,
const ecc_key *key);
\label{ecc-verify}
\index{ecc\_verify\_hash\_v2()}
\begin{verbatim}
int ecc_verify_hash_v2(const unsigned char *sig,
unsigned long siglen,
const unsigned char *hash,
unsigned long hashlen,
ltc_ecc_sig_opts *opts,
int *stat,
const ecc_key *key);
\end{verbatim}

This function will verify the \textit{ECDSA} signature in the array pointed to by \code{sig} of length \code{siglen} octets, against the message digest
pointed to by the array \code{hash} of length \code{hashlen}. It will store a non--zero value in \code{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 \textit{ECC} \code{key} must be the public (or private) \textit{ECC} key corresponding to the key that performed the signature.
The function \code{ecc\_verify\_hash()} implements signature format according to \textit{ANSI X9.62} EC\textit{DSA}, 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,
const ecc_key *key);
\end{verbatim}

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

\index{ecc\_verify\_hash\_rfc5656()}
\begin{verbatim}
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 \textit{ECDSA} signature according to the format defined in \textit{RFC5656}, i.e. \textit{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 the \textit{ECDSA} signature according to the Ethereum format.

\subsection{Public Key Recovery}
\index{ecc\_recover\_key()}
Expand Down Expand Up @@ -5977,6 +5930,7 @@ \subsection{Public Key Recovery}
The function \code{ecc\_recover\_key()} implements multiple signature formats, and the output is compliant for GF(p) curves.

\subsection{Signature Formats}
\label{sigformat}
The following signature formats are suported:

\begin{figure}[hpbt]
Expand All @@ -5985,10 +5939,10 @@ \subsection{Signature Formats}
\begin{center}
\begin{tabular}{|l|l|}
\hline \textbf{sigformat} & \textbf{description} \\
\hline LTC\_ECCSIG\_ANSIX962 & ASN.1 encoded, \textit{ANSI X9.62} \\
\hline LTC\_ECCSIG\_RFC7518 & raw R, S values as defined in \textit{RFC7518} \\
\hline LTC\_ECCSIG\_ETH27 & raw R, S, V values (V has 27 added) \\
\hline LTC\_ECCSIG\_RFC5656 & \textit{SSH+ECDSA} format as defined in \textit{RFC5656} \\
\hline \code{LTC\_ECCSIG\_ANSIX962} & ASN.1 encoded, \textit{ANSI X9.62} \\
\hline \code{LTC\_ECCSIG\_RFC7518} & raw R, S values as defined in \textit{RFC7518} \\
\hline \code{LTC\_ECCSIG\_ETH27} & raw R, S, V values (V has 27 added) \\
\hline \code{LTC\_ECCSIG\_RFC5656} & \textit{SSH+ECDSA} format as defined in \textit{RFC5656} \\
\hline
\end{tabular}
\end{center}
Expand All @@ -6001,6 +5955,8 @@ \subsection{Signature Formats}
(Appendix F). However, convention allows the use of v=0,1 as equivalent to v=27,28 and both are accepted by
\code{ecc\_recover\_key()}.

When using \code{LTC\_ECCSIG\_ETH27} the curve is limited to \textit{secp256k1}.

\textbf{NOTE:} If you're using a tailored version of libtomcrypt, it is possible to disable \code{LTC\_DER} which will disable
the option to use \code{LTC\_ECCSIG\_ANSIX962}. Also it is possible to disable \code{LTC\_SSH} which will disable
the option to use \code{LTC\_ECCSIG\_RFC5656}.
Expand Down Expand Up @@ -10369,6 +10325,56 @@ \subsection{RSA Functions}

\mysection{Deprecated API functions}

\subsection{Elliptic Curve Cryptography - $GF(p)$}

\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,
const ecc_key *key);
\end{verbatim}

\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,
const ecc_key *key);
\end{verbatim}

These two ECC sign functions have been deprecated in favor of \code{ecc\_sign\_hash\_v2()}.
Please check Chapter \ref{ecc-sign} for details.

\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,
const ecc_key *key);
\end{verbatim}

\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,
const ecc_key *key);
\end{verbatim}

These two ECC verify functions have been deprecated in favor of \code{ecc\_verify\_hash\_v2()}.
Please check Chapter \ref{ecc-verify} for details.

\clearpage
\addcontentsline{toc}{chapter}{Index}
\printindex
Expand Down
12 changes: 12 additions & 0 deletions libtomcrypt_VS2008.vcproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1387,6 +1387,10 @@
RelativePath="src\misc\crc32.c"
>
</File>
<File
RelativePath="src\misc\deprecated.c"
>
</File>
<File
RelativePath="src\misc\error_to_string.c"
>
Expand Down Expand Up @@ -2530,6 +2534,10 @@
RelativePath="src\pk\ecc\ecc_sign_hash_rfc7518.c"
>
</File>
<File
RelativePath="src\pk\ecc\ecc_sign_hash_x962.c"
>
</File>
<File
RelativePath="src\pk\ecc\ecc_sizes.c"
>
Expand Down Expand Up @@ -2558,6 +2566,10 @@
RelativePath="src\pk\ecc\ecc_verify_hash_rfc7518.c"
>
</File>
<File
RelativePath="src\pk\ecc\ecc_verify_hash_x962.c"
>
</File>
<File
RelativePath="src\pk\ecc\ltc_ecc_export_point.c"
>
Expand Down
Loading