Skip to content

Ed448 + X448 #722

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

Open
karel-m wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

Ed448 + X448 #722

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7354d01
Ed448 + X448
karel-m Apr 12, 2026
2c494d5
Update makefiles
karel-m Apr 14, 2026
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
262 changes: 251 additions & 11 deletions doc/crypt.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6094,16 +6094,21 @@ \chapter{Elliptic Curve Cryptography - $Montgomery/Twisted Edwards$}
\mysection{Introduction}

The library provides functionality for \textit{Curve25519}-based \textit{X25519} Diffie-Hellman shared secrets
and \textit{EdDSA} a.k.a \textit{Ed25519} signature schemes.
and \textit{EdDSA} a.k.a \textit{Ed25519} signature schemes as well as the corresponding
\textit{Curve448}/\textit{ec448}-based \textit{X448} and \textit{Ed448} algorithms.

The implementation is based on the \textit{tweetnacl}\footnote{\url{https://tweetnacl.cr.yp.to/}} reference implementation
The Curve25519 implementation is based on the \textit{tweetnacl}\footnote{\url{https://tweetnacl.cr.yp.to/}} reference implementation
as provided by Daniel J. Bernstein et.al. and only slightly modified to better fit in the library.
The Curve448/\textit{ec448} implementation follows the same overall code structure and arithmetic layout pattern.

Both algorithms share the key structure called \textit{curve25519\_key} which is used by all Curve25519 functions.
The Curve25519 family shares the key structure called \textit{curve25519\_key} which is used by all
Curve25519 functions. The Curve448 family uses the \textit{curve448\_key} structure.

As Curve25519 and Ed25519 are based on the same elliptic curve, but use different mathematics, the keys are not
compatible to each other.

Likewise X448 and Ed448 keys are not compatible to each other.

It is possible to convert a Curve-Key to an Ed-Key and vice-versa, but this is not provided (yet).


Expand All @@ -6122,7 +6127,7 @@ \subsection{X25519 Key Operations}
curve25519_key *key);
\end{verbatim}

To generate a fresh X25529 key, one can use \textit{x25519\_make\_key} which will create a private\&public key-pair.
To generate a fresh X25519 key, one can use \textit{x25519\_make\_key} which will create a private\&public key-pair.
\index{x25519\_import}
\begin{verbatim}
int x25519_import(const unsigned char *in,
Expand Down Expand Up @@ -6217,7 +6222,7 @@ \subsection{EdDSA Key Operations}
curve25519_key *key);
\end{verbatim}

To generate a fresh Ed25529 key, one can use \textit{ed25519\_make\_key} which will create a private\&public key-pair.
To generate a fresh Ed25519 key, one can use \textit{ed25519\_make\_key} which will create a private\&public key-pair.

\index{ed25519\_import}
\begin{verbatim}
Expand Down Expand Up @@ -6333,6 +6338,232 @@ \subsection{EdDSA Cryptographic Operations}
pointed to by the array \textit{msg} of length \textit{msglen}. It will store a non--zero value in \textit{stat} if the signature is valid. Note:
the function will not return an error if the signature is invalid. It will only return an error if the actual signature payload is an invalid format.

\mysection{Curve448-based Diffie-Hellman Key Exchange - X448}

The library provides the Diffie-Hellman Key Exchange algorithm \textit{X448} for curve448 as specified in RFC 7748.

\subsection{X448 Key Operations}

The \textit{X448} algorithm API provides the following set of functions to create, import and export keys.

\index{x448\_make\_key}
\begin{verbatim}
int x448_make_key( prng_state *prng,
int wprng,
curve448_key *key);
\end{verbatim}

To generate a fresh X448 key, one can use \textit{x448\_make\_key} which will create a private\&public key-pair.
\index{x448\_import}
\begin{verbatim}
int x448_import(const unsigned char *in,
unsigned long inlen,
curve448_key *key);
\end{verbatim}

The \textit{x448\_import} function can be used to import a public key in DER-encoded \textit{SubjectPublicKeyInfo} format.

\index{x448\_import\_raw}
\begin{verbatim}
int x448_import_raw(const unsigned char *in,
unsigned long inlen,
int which,
curve448_key *key);
\end{verbatim}

To import a public or private key in raw format, one can use the function \textit{x448\_import\_raw}.

\index{x448\_import\_x509}
\begin{verbatim}
int x448_import_x509(const unsigned char *in,
unsigned long inlen,
curve448_key *key);
\end{verbatim}

To import a public key from a DER-encoded \textit{X.509} certificate, one can use the function \textit{x448\_import\_x509}.

\index{x448\_import\_pkcs8}
\begin{verbatim}
int x448_import_pkcs8(const unsigned char *in,
unsigned long inlen,
const password_ctx *pw_ctx,
curve448_key *key);
\end{verbatim}

To import a private key in the \textit{OneAsymmetricKey} a.k.a \textit{PKCS \#8} format, either plain or PBES encrypted,
one can use the function \textit{x448\_import\_pkcs8}.

\index{x448\_export}
\begin{verbatim}
int x448_export( unsigned char *out,
unsigned long *outlen,
int which,
const curve448_key *key);
\end{verbatim}

To export a key, the function \textit{x448\_export} is provided.

It has support for the following output formats:

\begin{figure}[H]
\begin{center}
\begin{tabular}{|c|c|}
\hline \textbf{which} & \textbf{output format} \\
\hline PK\_PRIVATE & Raw \\
\hline PK\_PRIVATE \& PK\_STD & PKCS \#8 \\
\hline PK\_PUBLIC & Raw \\
\hline PK\_PUBLIC \& PK\_STD & SubjectPublicKeyInfo \\
\hline
\end{tabular}
\end{center}
\caption{Possible x448\_export() output formats}
\end{figure}

\subsection{X448 Cryptographic Operations}

To construct a Diffie-Hellman shared secret with a private and a public X448 key, use the following function:

\index{x448\_shared\_secret}
\begin{verbatim}
int x448_shared_secret(const curve448_key *private_key,
const curve448_key *public_key,
unsigned char *out,
unsigned long *outlen);
\end{verbatim}

This will construct the shared secret between the private- and the public-key and store the result in \textit{out} of length \textit{outlen}.

\mysection{Curve448-based EdDSA Signature Scheme - Ed448}

The library provides the EdDSA algorithm for the edwards448 curve in the PureEdDSA variant as specified in RFC 8032.

\subsection{Ed448 Key Operations}

The \textit{Ed448} algorithm API provides the following set of functions to create, import and export keys.

\index{ed448\_make\_key}
\begin{verbatim}
int ed448_make_key( prng_state *prng,
int wprng,
curve448_key *key);
\end{verbatim}

To generate a fresh Ed448 key, one can use \textit{ed448\_make\_key} which will create a private\&public key-pair.

\index{ed448\_import}
\begin{verbatim}
int ed448_import(const unsigned char *in,
unsigned long inlen,
curve448_key *key);
\end{verbatim}

The \textit{ed448\_import} function can be used to import a public key in DER-encoded \textit{SubjectPublicKeyInfo} format.

\index{ed448\_import\_raw}
\begin{verbatim}
int ed448_import_raw(const unsigned char *in,
unsigned long inlen,
int which,
curve448_key *key);
\end{verbatim}

To import a public or private key in raw format, one can use the function \textit{ed448\_import\_raw}.

\index{ed448\_import\_x509}
\begin{verbatim}
int ed448_import_x509(const unsigned char *in,
unsigned long inlen,
curve448_key *key);
\end{verbatim}

To import a public key from a DER-encoded \textit{X.509} certificate, one can use the function \textit{ed448\_import\_x509}.

\index{ed448\_import\_pkcs8}
\begin{verbatim}
int ed448_import_pkcs8(const unsigned char *in,
unsigned long inlen,
const password_ctx *pw_ctx,
curve448_key *key);
\end{verbatim}

To import a private key in the \textit{OneAsymmetricKey} a.k.a \textit{PKCS \#8} format, either plain or PBES encrypted,
one can use the function \textit{ed448\_import\_pkcs8}.

\index{ed448\_export}
\begin{verbatim}
int ed448_export( unsigned char *out,
unsigned long *outlen,
int which,
const curve448_key *key);
\end{verbatim}

To export a key, the function \textit{ed448\_export} is provided.

It has support for the following output formats:

\begin{figure}[H]
\begin{center}
\begin{tabular}{|c|c|}
\hline \textbf{which} & \textbf{output format} \\
\hline PK\_PRIVATE & Raw \\
\hline PK\_PRIVATE \& PK\_STD & PKCS \#8 \\
\hline PK\_PUBLIC & Raw \\
\hline PK\_PUBLIC \& PK\_STD & SubjectPublicKeyInfo \\
\hline
\end{tabular}
\end{center}
\caption{Possible ed448\_export() output formats}
\end{figure}

\subsection{Ed448 Cryptographic Operations}

To sign and/or verify a message use the following functions:

\index{ed448\_sign}
\index{ed448ctx\_sign}
\index{ed448ph\_sign}
\begin{verbatim}
int ed448_sign(const unsigned char *msg, unsigned long msglen,
unsigned char *sig, unsigned long *siglen,
const curve448_key *private_key);
int ed448ctx_sign(const unsigned char *msg, unsigned long msglen,
unsigned char *sig, unsigned long *siglen,
const unsigned char *ctx, unsigned long ctxlen,
const curve448_key *private_key);
int ed448ph_sign(const unsigned char *msg, unsigned long msglen,
unsigned char *sig, unsigned long *siglen,
const unsigned char *ctx, unsigned long ctxlen,
const curve448_key *private_key);
\end{verbatim}

These functions will EdDSA sign the message stored in the array pointed to by \textit{msg} of length \textit{msglen} octets. The signature
will be stored in the array pointed to by \textit{sig} of length \textit{siglen} octets. The \texttt{ctx} and \texttt{ph} variants also
allow passing a context \textit{ctx} of length \textit{ctxlen} octets. This context is allowed to be max. 255 octets long.

\index{ed448\_verify}
\index{ed448ctx\_verify}
\index{ed448ph\_verify}
\begin{verbatim}
int ed448_verify(const unsigned char *msg, unsigned long msglen,
const unsigned char *sig, unsigned long siglen,
int *stat,
const curve448_key *public_key);
int ed448ctx_verify(const unsigned char *msg, unsigned long msglen,
const unsigned char *sig, unsigned long siglen,
const unsigned char *ctx, unsigned long ctxlen,
int *stat,
const curve448_key *public_key);
int ed448ph_verify(const unsigned char *msg, unsigned long msglen,
const unsigned char *sig, unsigned long siglen,
const unsigned char *ctx, unsigned long ctxlen,
int *stat,
const curve448_key *public_key);
\end{verbatim}

These functions will verify the EdDSA signature in the array pointed to by \textit{sig} of length \textit{siglen} octets, against the message
pointed to by the array \textit{msg} of length \textit{msglen}. It will store a non--zero value in \textit{stat} if the signature is valid. Note:
the function will not return an error if the signature is invalid. It will only return an error if the actual signature payload is an invalid format.


\chapter{Digital Signature Algorithm}
\mysection{Introduction}
Expand Down Expand Up @@ -6638,6 +6869,8 @@ \chapter{The PKA Union}
LTC_PKA_X25519,
LTC_PKA_ED25519,
LTC_PKA_DH,
LTC_PKA_X448,
LTC_PKA_ED448,
};

typedef struct {
Expand All @@ -6646,6 +6879,10 @@ \chapter{The PKA Union}
curve25519_key x25519;
curve25519_key ed25519;
#endif
#ifdef LTC_CURVE448
curve448_key x448;
curve448_key ed448;
#endif
#ifdef LTC_MDH
dh_key dh;
#endif
Expand Down Expand Up @@ -7927,14 +8164,14 @@ \subsection{PKCS PEM files}
\begin{table}[H]
\begin{minipage}{\textwidth}
\begin{small}
\begin{tabular}{|l|l|l|l|l|}
\begin{tabular}{|l|l|l|l|p{4.1cm}|}
\hline \textbf{Identifier} & \textbf{Key type} & \textbf{File content} & \textbf{Standard} & \textbf{Algorithm} \\
\hline \texttt{BEGIN CERTIFICATE} & Public & Plain & \texttt{X.509} & DH, DSA, ECC, Ed25519, RSA, X25519 \\
\hline \texttt{BEGIN CERTIFICATE} & Public & Plain & \texttt{X.509} & DH, DSA, ECC, Ed25519, Ed448, RSA, X25519, X448 \\
\hline \texttt{BEGIN DSA PRIVATE KEY} & Private & Maybe encrypted & \texttt{OpenSSL\footnote{There are two de-facto standard for DSA private key structures, LibTomCrypt implements OpenSSL's}} & DSA \\
\hline \texttt{BEGIN EC PRIVATE KEY} & Private & Maybe encrypted & \texttt{RFC 5915} & ECC \\
\hline \texttt{BEGIN ENCRYPTED PRIVATE KEY} & Private & Encrypted & \texttt{PKCS \#8} & DH, DSA, ECC, Ed25519, RSA, X25519 \\
\hline \texttt{BEGIN PRIVATE KEY} & Private & Plain & \texttt{PKCS \#8} & DH, DSA, ECC, Ed25519, RSA, X25519 \\
\hline \texttt{BEGIN PUBLIC KEY} & Public & Plain & \texttt{X.509\footnote{Specifically, SubjectPublicKeyInfo}} & DH, DSA, ECC, Ed25519, RSA, X25519 \\
\hline \texttt{BEGIN ENCRYPTED PRIVATE KEY} & Private & Encrypted & \texttt{PKCS \#8} & DH, DSA, ECC, Ed25519, Ed448, RSA, X25519, X448 \\
\hline \texttt{BEGIN PRIVATE KEY} & Private & Plain & \texttt{PKCS \#8} & DH, DSA, ECC, Ed25519, Ed448, RSA, X25519, X448 \\
\hline \texttt{BEGIN PUBLIC KEY} & Public & Plain & \texttt{X.509\footnote{Specifically, SubjectPublicKeyInfo}} & DH, DSA, ECC, Ed25519, Ed448, RSA, X25519, X448 \\
\hline \texttt{BEGIN RSA PRIVATE KEY} & Private & Maybe encrypted & \texttt{PKCS \#1} & RSA \\
\hline \texttt{BEGIN RSA PUBLIC KEY} & Public & Plain & \texttt{PKCS \#1} & RSA \\
\hline
Expand Down Expand Up @@ -8401,8 +8638,11 @@ \subsection{Depadding}
"RSA",
"DSA",
"ECC",
"Curve25519",
"X25519",
"Ed25519",
"DH",
"X448",
"Ed448",
};

static int password_get(void **p, unsigned long *l, void *u)
Expand Down
Loading
Loading