Skip to content

Commit c145b59

Browse files
sjaeckelsjaeckel
committed
Update docs
Signed-off-by: Steffen Jaeckel <[email protected]>
1 parent c7936bb commit c145b59

File tree

1 file changed

+123
-117
lines changed

1 file changed

+123
-117
lines changed

‎doc/crypt.tex‎

Lines changed: 123 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -5812,144 +5812,97 @@ \subsection{ANSI X9.63 Import (deprecated)}
58125812
P--192 key, you have in effect 96--bits of security. The library will not warn you if you make this mistake, so it
58135813
is important to check yourself before using the signatures.
58145814

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

5818-
\index{ecc\_sign\_hash()}
5819-
\index{ECC\_SET\_RFC6979\_HASH\_ALG()}
5817+
The library supports ECDSA signatures in the following formats.
5818+
5819+
\index{ecc\_signature\_type}
5820+
\begin{small}
58205821
\begin{verbatim}
5821-
int ecc_sign_hash(const unsigned char *in,
5822-
unsigned long inlen,
5823-
unsigned char *out,
5824-
unsigned long *outlen,
5825-
prng_state *prng,
5826-
int wprng,
5827-
const ecc_key *key);
5822+
typedef enum ecc_signature_type {
5823+
/* ASN.1 encoded, ANSI X9.62 */
5824+
LTC_ECCSIG_ANSIX962 = 0x0,
5825+
/* raw R, S values */
5826+
LTC_ECCSIG_RFC7518 = 0x1,
5827+
/* raw R, S, V (+27) values */
5828+
LTC_ECCSIG_ETH27 = 0x2,
5829+
/* SSH + ECDSA signature format defined by RFC5656 */
5830+
LTC_ECCSIG_RFC5656 = 0x3,
5831+
} ecc_signature_type;
58285832
\end{verbatim}
5833+
\end{small}
58295834

5830-
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
5831-
will be stored in the array pointed to by \code{out} of length \code{outlen} octets. The function requires that the \textit{ECC}
5832-
\code{key} provided must be a private key.
5833-
5834-
In order to execute standard \textit{ECDSA} it requires a properly seeded \textit{PRNG} which gets passed via \code{prng} and \code{wprng}.
5835-
5836-
The deterministic signature mechanism according to \textit{RFC6979} is also supported. This does not require a \textit{PRNG}, but
5837-
instead a valid hash function shall be set via the macro
5838-
5839-
\code{ECC\_SET\_RFC6979\_HASH\_ALG(key, hash\_alg)}
5835+
c.f. Chapter \ref{sigformat} for further details.
58405836

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

5843-
\index{ecc\_sign\_hash\_rfc7518()}
5839+
\index{ltc\_ecc\_sig\_opts}
5840+
\begin{small}
58445841
\begin{verbatim}
5845-
int ecc_sign_hash_rfc7518(const unsigned char *in,
5846-
unsigned long inlen,
5847-
unsigned char *out,
5848-
unsigned long *outlen,
5849-
prng_state *prng,
5850-
int wprng,
5851-
const ecc_key *key);
5852-
\end{verbatim}
5842+
typedef struct ltc_ecc_sig_opts {
5843+
/** Signature type */
5844+
ecc_signature_type type;
5845+
/** The PRNG to use.
5846+
* This must be set in case deterministic signature generation
5847+
* according to RFC6979 is not enabled.
5848+
*/
5849+
prng_state *prng;
5850+
int wprng;
58535851
5854-
This function creates the same \textit{ECDSA} signature as \code{ecc\_sign\_hash()} only the output format is different.
5855-
The format follows \url{https://tools.ietf.org/html/rfc7518#section-3.4}, sometimes it is also called plain signature.
5852+
/** Enable generation of a recovery ID.
5853+
* This must be set in case one requires the recovery ID of a
5854+
* signature operation.
5855+
*/
5856+
int *recid;
58565857
5857-
\index{ecc\_sign\_hash\_rfc7518\_ex()}
5858-
\begin{verbatim}
5859-
int ecc_sign_hash_rfc7518_ex(const unsigned char *in,
5860-
unsigned long inlen,
5861-
unsigned char *out,
5862-
unsigned long *outlen,
5863-
prng_state *prng,
5864-
int wprng,
5865-
int *recid,
5866-
const ecc_key *key);
5858+
/** The hash algorithm to use when creating a signature.
5859+
* Setting this will enable RFC6979 compatible signature generation.
5860+
*/
5861+
const char *rfc6979_hash_alg;
5862+
} ltc_ecc_sig_opts;
58675863
\end{verbatim}
5864+
\end{small}
58685865

5869-
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
5870-
for use with \code{ecc\_recover\_key()}.
5866+
\subsection{Signature Generation}
5867+
\label{ecc-sign}
5868+
To sign a message digest (hash) use the following function:
58715869

5872-
\index{ecc\_sign\_hash\_rfc5656()}
5870+
\index{ecc\_sign\_hash\_v2()}
58735871
\begin{verbatim}
5874-
int ecc_sign_hash_rfc5656(const unsigned char *in,
5875-
unsigned long inlen,
5876-
unsigned char *out,
5877-
unsigned long *outlen,
5878-
prng_state *prng,
5879-
int wprng,
5880-
const ecc_key *key);
5872+
int ecc_sign_hash_v2(const unsigned char *in,
5873+
unsigned long inlen,
5874+
unsigned char *out,
5875+
unsigned long *outlen,
5876+
ltc_ecc_sig_opts *opts,
5877+
const ecc_key *key);
58815878
\end{verbatim}
58825879

5883-
This function creates an \textit{ECDSA} signature and the output format is according to \textit{RFC5656}, i.e. \textit{SSH} compatible.
5880+
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
5881+
will be stored in the array pointed to by \code{out} of length \code{outlen} octets. The function requires that the \textit{ECC}
5882+
\code{key} provided must be a private key.
58845883

5885-
\index{ecc\_sign\_hash\_eth27()}
5886-
\begin{verbatim}
5887-
int ecc_sign_hash_eth27(const unsigned char *in,
5888-
unsigned long inlen,
5889-
unsigned char *out,
5890-
unsigned long *outlen,
5891-
prng_state *prng,
5892-
int wprng,
5893-
const ecc_key *key);
5894-
\end{verbatim}
5884+
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}.
58955885

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

58995889
\subsection{Signature Verification}
5900-
\index{ecc\_verify\_hash()}
5901-
\begin{verbatim}
5902-
int ecc_verify_hash(const unsigned char *sig,
5903-
unsigned long siglen,
5904-
const unsigned char *hash,
5905-
unsigned long hashlen,
5906-
int *stat,
5907-
const ecc_key *key);
5890+
\label{ecc-verify}
5891+
\index{ecc\_verify\_hash\_v2()}
5892+
\begin{verbatim}
5893+
int ecc_verify_hash_v2(const unsigned char *sig,
5894+
unsigned long siglen,
5895+
const unsigned char *hash,
5896+
unsigned long hashlen,
5897+
ltc_ecc_sig_opts *opts,
5898+
int *stat,
5899+
const ecc_key *key);
59085900
\end{verbatim}
59095901

59105902
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
59115903
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:
59125904
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.
59135905
The \textit{ECC} \code{key} must be the public (or private) \textit{ECC} key corresponding to the key that performed the signature.
5914-
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.
5915-
5916-
\index{ecc\_verify\_hash\_rfc7518()}
5917-
\begin{verbatim}
5918-
int ecc_verify_hash_rfc7518(const unsigned char *sig,
5919-
unsigned long siglen,
5920-
const unsigned char *hash,
5921-
unsigned long hashlen,
5922-
int *stat,
5923-
const ecc_key *key);
5924-
\end{verbatim}
5925-
5926-
This function validates the \textit{ECDSA} signature as \code{ecc\_verify\_hash()}, only the signature input format
5927-
follows \url{https://tools.ietf.org/html/rfc7518#section-3.4}.
5928-
5929-
\index{ecc\_verify\_hash\_rfc5656()}
5930-
\begin{verbatim}
5931-
int ecc_verify_hash_rfc5656(const unsigned char *sig,
5932-
unsigned long siglen,
5933-
const unsigned char *hash,
5934-
unsigned long hashlen,
5935-
int *stat,
5936-
const ecc_key *key);
5937-
\end{verbatim}
5938-
5939-
This function validates the \textit{ECDSA} signature according to the format defined in \textit{RFC5656}, i.e. \textit{SSH} compatible.
5940-
5941-
5942-
\index{ecc\_verify\_hash\_eth27()}
5943-
\begin{verbatim}
5944-
int ecc_verify_hash_eth27(const unsigned char *sig,
5945-
unsigned long siglen,
5946-
const unsigned char *hash,
5947-
unsigned long hashlen,
5948-
int *stat,
5949-
const ecc_key *key);
5950-
\end{verbatim}
5951-
5952-
This function validates the \textit{ECDSA} signature according to the Ethereum format.
59535906

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

59795932
\subsection{Signature Formats}
5933+
\label{sigformat}
59805934
The following signature formats are suported:
59815935

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

5958+
When using \code{LTC\_ECCSIG\_ETH27} the curve is limited to \textit{secp256k1}.
5959+
60045960
\textbf{NOTE:} If you're using a tailored version of libtomcrypt, it is possible to disable \code{LTC\_DER} which will disable
60055961
the option to use \code{LTC\_ECCSIG\_ANSIX962}. Also it is possible to disable \code{LTC\_SSH} which will disable
60065962
the option to use \code{LTC\_ECCSIG\_RFC5656}.
@@ -10369,6 +10325,56 @@ \subsection{RSA Functions}
1036910325

1037010326
\mysection{Deprecated API functions}
1037110327

10328+
\subsection{Elliptic Curve Cryptography - $GF(p)$}
10329+
10330+
\index{ecc\_sign\_hash()}
10331+
\begin{verbatim}
10332+
int ecc_sign_hash(const unsigned char *in,
10333+
unsigned long inlen,
10334+
unsigned char *out,
10335+
unsigned long *outlen,
10336+
prng_state *prng,
10337+
int wprng,
10338+
const ecc_key *key);
10339+
\end{verbatim}
10340+
10341+
\index{ecc\_sign\_hash\_rfc7518()}
10342+
\begin{verbatim}
10343+
int ecc_sign_hash_rfc7518(const unsigned char *in,
10344+
unsigned long inlen,
10345+
unsigned char *out,
10346+
unsigned long *outlen,
10347+
prng_state *prng,
10348+
int wprng,
10349+
const ecc_key *key);
10350+
\end{verbatim}
10351+
10352+
These two ECC sign functions have been deprecated in favor of \code{ecc\_sign\_hash\_v2()}.
10353+
Please check Chapter \ref{ecc-sign} for details.
10354+
10355+
\index{ecc\_verify\_hash()}
10356+
\begin{verbatim}
10357+
int ecc_verify_hash(const unsigned char *sig,
10358+
unsigned long siglen,
10359+
const unsigned char *hash,
10360+
unsigned long hashlen,
10361+
int *stat,
10362+
const ecc_key *key);
10363+
\end{verbatim}
10364+
10365+
\index{ecc\_verify\_hash\_rfc7518()}
10366+
\begin{verbatim}
10367+
int ecc_verify_hash_rfc7518(const unsigned char *sig,
10368+
unsigned long siglen,
10369+
const unsigned char *hash,
10370+
unsigned long hashlen,
10371+
int *stat,
10372+
const ecc_key *key);
10373+
\end{verbatim}
10374+
10375+
These two ECC verify functions have been deprecated in favor of \code{ecc\_verify\_hash\_v2()}.
10376+
Please check Chapter \ref{ecc-verify} for details.
10377+
1037210378
\clearpage
1037310379
\addcontentsline{toc}{chapter}{Index}
1037410380
\printindex

0 commit comments

Comments
 (0)