Update docs

Signed-off-by: Steffen Jaeckel <[email protected]>

doc/crypt.tex

@@ -5812,144 +5812,97 @@ by the size of the hash, or the size of the key, whichever is smaller.  For exam
 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()}
@@ -5977,6 +5930,7 @@ extract the recovery id from such a signature in order to use this function.
 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]
@@ -5985,10 +5939,10 @@ The following signature formats are suported:
 \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}
@@ -6001,6 +5955,8 @@ The \code{LTC\_ECCSIG\_ETH27} format is based on the Ethereum Yellow Paper, see
 (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}.
@@ -10369,6 +10325,56 @@ Since the function is given the entire RSA key (for private keys only) CRT is po
 
 \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