From 39650b4a086e3647c8c0fff709f82486879e75f4 Mon Sep 17 00:00:00 2001
From: Steffen Jaeckel <s@jaeckel.eu>
Date: Mon, 17 Jul 2017 13:33:37 +0200
Subject: [PATCH] add doc of new RSA API functions

---
 doc/crypt.tex | 79 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 75 insertions(+), 4 deletions(-)

diff --git a/doc/crypt.tex b/doc/crypt.tex
index b3d3d4f..76b1737 100644
--- a/doc/crypt.tex
+++ b/doc/crypt.tex
@@ -3834,7 +3834,15 @@ By OR'ing \textbf{PK\_STD} and \textbf{PK\_PUBLIC} the public key will be export
 in the SubjectPublicKeyInfo (X.509 type) format.
 
 \subsection{RSA Key Import}
-To import a RSA key use the following function.
+To import a RSA key use one of the following function.
+
+\subsubsection{Import from standard formats}
+
+This will import the key stored in \textit{in} of length inlen and import it to \textit{key}.
+
+These formats are normally distributed in the PEM format, consisting of a label defining the content and base64 encoded DER-serialized data.
+
+All the import functions expect binary DER data.
 
 \index{rsa\_import()}
 \begin{verbatim}
@@ -3843,12 +3851,75 @@ int rsa_import(const unsigned char *in,
                            rsa_key *key);
 \end{verbatim}
 
-This will import the key stored in \textit{inlen} and import it to \textit{key}.  If the function fails it will automatically free any allocated memory.  This
-function can import both RSAPublicKey and RSAPrivateKey formats.
+This function can import both RSAPublicKey and RSAPrivateKey formats.
 
 As of v1.06 this function can also import OpenSSL DER formatted public RSA keys.  They are essentially encapsulated RSAPublicKeys.  LibTomCrypt will
-import the key, strip off the additional data and fill in the rsa\_key structure.
+import the key, strip off the additional data and fill in the \textit{rsa\_key} structure.
 
+\index{rsa\_import\_pkcs8()}
+\begin{verbatim}
+int rsa_import_pkcs8(const unsigned char *in,
+                           unsigned long inlen,
+                              const void *passwd,
+                           unsigned long passwdlen,
+                                rsa_key *key);
+\end{verbatim}
+
+This function can import RSA private keys serialized in PKCS#8 format.
+
+It provides a \textit{password} parameter for the encrypted PKCS#8 format, but this functionality is currently NOT implemented.
+
+\index{rsa\_import\_x509()}
+\begin{verbatim}
+int rsa_import_x509(const unsigned char *in,
+                          unsigned long inlen,
+                                rsa_key *key);
+\end{verbatim}
+
+This function can import the RSA public key from a X.509 certificate.
+
+\subsubsection{Import from plain big numbers}
+
+\index{rsa\_set\_key()}
+\begin{verbatim}
+int rsa_set_key(const unsigned char *N,
+                      unsigned long Nlen,
+                const unsigned char *e,
+                      unsigned long elen,
+                const unsigned char *d,
+                      unsigned long dlen,
+                rsa_key *key);
+\end{verbatim}
+
+This function can import the plain RSA key parameters \texit{N}, \texit{e} and \texit{d}.
+The parameter \texit{d} is optional and only required when importing a private key.
+
+\index{rsa\_set\_factors()}
+\begin{verbatim}
+int rsa_set_factors(const unsigned char *p,
+                          unsigned long plen,
+                    const unsigned char *q,
+                          unsigned long qlen,
+                    rsa_key *key);
+\end{verbatim}
+
+This function can import the plain RSA key factors \texit{p} and \texit{q}.
+
+\index{rsa\_set\_crt\_params()}
+\begin{verbatim}
+int rsa_set_crt_params(const unsigned char *dP,
+                             unsigned long dPlen,
+                       const unsigned char *dQ,
+                             unsigned long dQlen,
+                       const unsigned char *qP,
+                             unsigned long qPlen,
+                       rsa_key *key);
+\end{verbatim}
+
+This function can import the plain RSA CRT (chinese remainder theorem) parameters \texit{dP}, \texit{dQ} and \texit{qP}.
+
+After importing \texit{p}, \texit{q}, \texit{dP}, \texit{dQ} and \texit{qP}
+the library can perfrom the optimized CRT calculations on private key operations.
 
 \chapter{Diffie-Hellman Key Exchange}