Update docs.

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

Author: sjaeckel

doc/crypt.tex

@@ -5803,8 +5803,14 @@ \subsection{ANSI X9.63 Import (deprecated)}
 
 
 \mysection{Signatures (ECDSA)}
-There are also functions to sign and verify messages. They use the ANSI X9.62 ECDSA algorithm to generate and verify signatures in the
-ANSI X9.62 format.
+There are also functions to sign and verify messages. They use the \textit{ANSI X9.62} \textit{ECDSA} algorithm to generate and verify signatures in the
+\textit{ANSI X9.62} format.
+
+\textbf{BEWARE:} With \textit{ECC} if you try to sign a hash that is bigger than your \textit{ECC} key you can run into problems. The math
+will still work, and in effect the signature will still work.  With \textit{ECC} keys the strength of the signature is limited
+by the size of the hash, or the size of the key, whichever is smaller.  For example, if you sign with SHA256 and a
+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:
@@ -5817,12 +5823,12 @@ \subsection{Signature Generation}
                         unsigned long *outlen,
                            prng_state *prng,
                                   int  wprng,
-                              ecc_key *key);
+                  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 \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 a properly seeded \textit{PRNG}, and
+the \textit{ECC} \code{key} provided must be a private key.
 
 \index{ecc\_sign\_hash\_rfc7518()}
 \begin{verbatim}
@@ -5832,27 +5838,53 @@ \subsection{Signature Generation}
                                 unsigned long *outlen,
                                    prng_state *prng,
                                           int  wprng,
-                                      ecc_key *key);
+                          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 \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.
 
-\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 \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 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()}.
+
+\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 creates an \textit{ECDSA} signature and the output format is according to \textit{RFC5656}, i.e. \textit{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 \textit{ECDSA} signature and the output format is according to the Ethereum format.
+With this API the curve is limited to \textit{secp256k1}.
 
 \subsection{Signature Verification}
 \index{ecc\_verify\_hash()}
@@ -5862,14 +5894,14 @@ \subsection{Signature Verification}
                     const unsigned char *hash,
                           unsigned long  hashlen,
                                     int *stat,
-                                ecc_key *key);
+                    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 \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 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 \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}
@@ -5878,30 +5910,36 @@ \subsection{Signature Verification}
                             const unsigned char *hash,
                                   unsigned long  hashlen,
                                             int *stat,
-                                        ecc_key *key);
+                            const       ecc_key *key);
 \end{verbatim}
 
-This function validate the ECDSA signature as \textit{ecc\_verify\_hash} only the signature input format
+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\_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 an ECDSA signature as \textit{ecc\_verify\_hash} but with a choice of signature formats.
+This function validates the \textit{ECDSA} signature according to the format defined in \textit{RFC5656}, i.e. \textit{SSH} compatible.
 
-{\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
-by the size of the hash, or the size of the key, whichever is smaller.  For example, if you sign with SHA256 and a
-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.
+
+\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()}
@@ -5937,10 +5975,10 @@ \subsection{Signature Formats}
 \begin{center}
 \begin{tabular}{|l|l|}
 \hline \textbf{sigformat} & \textbf{description} \\
-\hline LTC\_ECCSIG\_ANSIX962 & ASN.1 encoded, ANSI X9.62 \\
-\hline LTC\_ECCSIG\_RFC7518 & raw R, S values as defined in RFC7518 \\
+\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 & SSH+ECDSA format as defined in RFC5656 \\
+\hline LTC\_ECCSIG\_RFC5656 & \textit{SSH+ECDSA} format as defined in \textit{RFC5656} \\
 \hline
 \end{tabular}
 \end{center}

src/headers/tomcrypt_pk.h

@@ -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);
 
@@ -342,53 +340,85 @@ int  ecc_decrypt_key(const unsigned char *in,  unsigned long  inlen,
                            unsigned char *out, unsigned long *outlen,
                            const 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);
-#endif
-
-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);
-
-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);
-
-#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);
+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_verify_hash_rfc7518(const unsigned char *sig,  unsigned long siglen,
-                            const unsigned char *hash, unsigned long hashlen,
-                            int *stat, const 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);
+
+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);
+
+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_verify_hash_rfc5656(const unsigned char *sig,  unsigned long siglen,
-                            const unsigned char *hash, unsigned long hashlen,
-                            int *stat, const ecc_key *key);
+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_verify_hash_eth27(const unsigned char *sig,  unsigned long siglen,
-                          const unsigned char *hash, unsigned long hashlen,
-                          int *stat, const ecc_key *key);
-
-int  ecc_recover_key(const unsigned char *sig,  unsigned long siglen,
-                     const unsigned char *hash, unsigned long hashlen,
-                     int recid, ecc_signature_type sigformat, ecc_key *key);
+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);
+
+int  ecc_recover_key(const unsigned char *sig,
+                           unsigned long  siglen,
+                     const unsigned char *hash,
+                           unsigned long  hashlen,
+                                     int  recid,
+                      ecc_signature_type  sigformat,
+                                 ecc_key *key);
 
 #endif