improve MPI providers section in documentation

.. also add a checkbox regarding MPI providers to the issue template

This closes #605

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

Author: sjaeckel

.github/ISSUE_TEMPLATE.md

@@ -10,6 +10,7 @@ This is a very generic template, remove items that do not apply. For completed i
 
 * [ ] Checked the developer manual
 * [ ] Checked that your issue isn't already filed: https://github.com/issues?utf8=✓&q=repo%3Alibtom%2Flibtomcrypt
+* [ ] Checked that your issue isn't due to the fact that you're using asymmetric cryptography and you forgot linking in and/or setting an MPI provider (usually this causes either random crashes or runtime errors like `LTC_ARGCHK 'ltc_mp.name != NULL' failure ...`). c.f. Ch. "Math Descriptors" of the developer manual.
 * [ ] Checked that your issue isn't related to TomsFastMath's limitation that PK operations can by default only be done with max. 2048bit keys
 
 ### Description

doc/crypt.tex

@@ -7744,18 +7744,6 @@ \subsection{Radix to binary conversion}
 where each name and value is separated by a comma, the pairs are separated
 by newlines, and the list is null terminated.
 
-\index{crypt\_mp\_init()}
-\begin{verbatim}
-int crypt_mp_init(const char* mpi);
-\end{verbatim}
-
-To ease the setup of a specific math descriptor, in cases where the library was compiled with support for multiple MPI libraries,
-the function \textit{crypt\_mp\_init()} is provided.
-It takes a string to the desired MPI library to use as an argument.
-The three default MPI libraries are identified as follows, \textit{LibTomMath} as \texttt{"ltm"}, \textit{TomsFastmath} as \texttt{"tfm"}
-and the \textit{GNU Multi Precision Arithmetic Library} as \texttt{"gmp"}.
-The identification happens case-insensitive and only on the first character.
-
 Here is a Python program demonstrating how to call various LTC dynamic
 language support functions.
 
@@ -8293,6 +8281,40 @@ \subsection{Math Descriptors}
 
 That will build and install the library with all descriptors (and link against all), but only use TomsFastMath in the timing demo.
 
+To avoid random crashes and run--time errors in the form \texttt{LTC\_ARGCHK 'ltc\_mp.name != NULL' failure ...}, one has to
+initialise the \texttt{ltc\_mp} struct. This can be done in multiple ways as shown below.
+
+\index{crypt\_mp\_init()}
+\begin{verbatim}
+int crypt_mp_init(const char* mpi);
+\end{verbatim}
+
+To ease the setup of a specific math descriptor, in cases where the library was compiled with support for multiple MPI libraries,
+the function \textit{crypt\_mp\_init()} is provided.
+It takes a string to the desired MPI library to use as an argument.
+The three default MPI libraries are identified as follows, \textit{LibTomMath} as \texttt{"ltm"}, \textit{TomsFastmath} as \texttt{"tfm"}
+and the \textit{GNU Multi Precision Arithmetic Library} as \texttt{"gmp"}.
+The identification happens case-insensitive and only on the first character.
+
+
+\begin{verbatim}
+#include <tomcrypt.h>
+
+int main(void)
+{
+   /* set it by hand */
+   ltc_mp = gmp_desc;
+   ltc_mp = ltm_desc;
+   ltc_mp = tfm_desc;
+
+   /* use the provided API */
+   crypt_mp_init("GMP");
+   crypt_mp_init("LibTomMath");
+   crypt_mp_init("TomsFastMath");
+}
+\end{verbatim}
+
+
 \chapter{Optimizations}
 \mysection{Introduction}
 The entire API was designed with plug and play in mind at the low level.  That is you can swap out any cipher, hash, PRNG or bignum library and the dependent API will not