/* -*-c-*-
*
- * $Id: mp.h,v 1.7 2000/06/17 11:45:09 mdw Exp $
+ * $Id: mp.h,v 1.12 2001/06/16 12:57:43 mdw Exp $
*
* Simple multiprecision arithmetic
*
/*----- Revision history --------------------------------------------------*
*
* $Log: mp.h,v $
+ * Revision 1.12 2001/06/16 12:57:43 mdw
+ * Move the @mpmont_factor@ structure and rename it now that it's used for
+ * Barrett simultaneous exponentiation too.
+ *
+ * Revision 1.11 2001/04/03 19:36:05 mdw
+ * Add some simple bitwise operations so that Perl can use them.
+ *
+ * Revision 1.10 2000/10/08 12:03:16 mdw
+ * Provide @mp_eq@ and @MP_EQ@ for rapidly testing equality of two
+ * integers.
+ *
+ * Revision 1.9 2000/07/29 17:03:31 mdw
+ * Add support for left-to-right bitscanning, for use in modular
+ * exponentiation.
+ *
+ * Revision 1.8 2000/06/22 19:02:01 mdw
+ * Add new functions.
+ *
* Revision 1.7 2000/06/17 11:45:09 mdw
* Major memory management overhaul. Added arena support. Use the secure
* arena for secret integers. Replace and improve the MP management macros
/*----- Data structures ---------------------------------------------------*/
+/* --- A multiprecision integer --- */
+
typedef struct mp {
- mpw *v, *vl;
- size_t sz;
- mparena *a;
- unsigned f;
- unsigned ref;
+ mpw *v, *vl; /* Vector of digits, current limit */
+ size_t sz; /* Size of digit buffer in words */
+ mparena *a; /* Arena for buffer allocation */
+ unsigned f; /* Flags (see below) */
+ unsigned ref; /* Reference counter */
} mp;
-#define MP_NEG 1u
-#define MP_BURN 2u
-#define MP_CONST 4u
-#define MP_UNDEF 8u
-#define MP_DESTROYED 16u
+#define MP_NEG 1u /* Negative (signed magnitude) */
+#define MP_BURN 2u /* Secret (viral flag) */
+#define MP_CONST 4u /* Uses strange memory allocation */
+#define MP_UNDEF 8u /* Contains nothing interesting */
+#define MP_DESTROYED 16u /* Has been destroyed */
+
+/* --- A factor for simultaneous exponentation --- *
+ *
+ * Used by the Montgomery and Barrett exponentiators.
+ */
+
+typedef struct mp_expfactor {
+ mp *base;
+ mp *exp;
+} mp_expfactor;
/*----- Useful constants --------------------------------------------------*/
MPSCAN_INITX(_sc, _mm->v, _mm->vl); \
} while (0)
+/* --- @mp_rscan@ --- *
+ *
+ * Arguments: @mpscan *sc@ = pointer to bitscanner block
+ * @const mp *m@ = pointer to a multiprecision integer
+ *
+ * Returns: ---
+ *
+ * Use: Initializes a reverse bitscanner on a multiprecision
+ * integer.
+ */
+
+extern void mp_rscan(mpscan */*sc*/, const mp */*m*/);
+
+#define MP_RSCAN(sc, m) do { \
+ const mp *_mm = (m); \
+ mpscan *_sc = (sc); \
+ MPSCAN_RINITX(_sc, _mm->v, _mm->vl); \
+} while (0)
+
/* --- Other bitscanning aliases --- */
#define mp_step mpscan_step
#define mp_bit mpscan_bit
+#define mp_rstep mpscan_rstep
+#define mp_rbit mpscan_rbit
#define MP_STEP MPSCAN_STEP
#define MP_BIT MPSCAN_BIT
+#define MP_RSTEP MPSCAN_RSTEP
+#define MP_RBIT MPSCAN_RBIT
/*----- Loading and storing -----------------------------------------------*/
extern mp *mp_lsr(mp */*d*/, mp */*a*/, size_t /*n*/);
+/* --- @mp_eq@ --- *
+ *
+ * Arguments: @const mp *a, *b@ = two numbers
+ *
+ * Returns: Nonzero if the numbers are equal.
+ */
+
+extern int mp_eq(const mp */*a*/, const mp */*b*/);
+
+#define MP_EQ(a, b) \
+ ((((a)->f ^ (b)->f) & MP_NEG) == 0 && \
+ mpx_ueq((a)->v, (a)->vl, (b)->v, (b)->vl))
+
/* --- @mp_cmp@ --- *
*
* Arguments: @const mp *a, *b@ = two numbers
#define MP_CMP(a, op, b) (mp_cmp((a), (b)) op 0)
+/* --- @mpx_and@, @mpx_or@, @mpx_xor@, @mpx_not@ --- *
+ *
+ * Arguments: @mp *d@ = destination
+ * @mp *a, *b@ = sources
+ *
+ * Returns: The result of the obvious bitwise operation.
+ */
+
+extern mp *mp_and(mp */*d*/, mp */*a*/, mp */*b*/);
+extern mp *mp_or(mp */*d*/, mp */*a*/, mp */*b*/);
+extern mp *mp_xor(mp */*d*/, mp */*a*/, mp */*b*/);
+extern mp *mp_not(mp */*d*/, mp */*a*/);
+
/* --- @mp_add@ --- *
*
* Arguments: @mp *d@ = destination
extern void mp_div(mp **/*qq*/, mp **/*rr*/, mp */*a*/, mp */*b*/);
+/* --- @mp_odd@ --- *
+ *
+ * Arguments: @mp *d@ = pointer to destination integer
+ * @mp *m@ = pointer to source integer
+ * @size_t *s@ = where to store the power of 2
+ *
+ * Returns: An odd integer integer %$t$% such that %$m = 2^s t$%.
+ *
+ * Use: Computes a power of two and an odd integer which, when
+ * multiplied, give a specified result. This sort of thing is
+ * useful in number theory quite often.
+ */
+
+extern mp *mp_odd(mp */*d*/, mp */*m*/, size_t */*s*/);
+
/*----- More advanced algorithms ------------------------------------------*/
+/* --- @mp_sqrt@ --- *
+ *
+ * Arguments: @mp *d@ = pointer to destination integer
+ * @mp *a@ = (nonnegative) integer to take square root of
+ *
+ * Returns: The largest integer %$x$% such that %$x^2 \le a$%.
+ *
+ * Use: Computes integer square roots.
+ *
+ * The current implementation isn't very good: it uses the
+ * Newton-Raphson method to find an approximation to %$a$%. If
+ * there's any demand for a better version, I'll write one.
+ */
+
+extern mp *mp_sqrt(mp */*d*/, mp */*a*/);
+
/* --- @mp_gcd@ --- *
*
* Arguments: @mp **gcd, **xx, **yy@ = where to write the results
* @a@ and @n@ have a common factor greater than one.
*/
-int mp_jacobi(mp */*a*/, mp */*n*/);
+extern int mp_jacobi(mp */*a*/, mp */*n*/);
+
+/* --- @mp_modsqrt@ --- *
+ *
+ * Arguments: @mp *d@ = destination integer
+ * @mp *a@ = source integer
+ * @mp *p@ = modulus (must be prime)
+ *
+ * Returns: If %$a$% is a quadratic residue, a square root of %$a$%; else
+ * a null pointer.
+ *
+ * Use: Returns an integer %$x$% such that %$x^2 \equiv a \pmod{p}$%,
+ * if one exists; else a null pointer. This function will not
+ * work if %$p$% is composite: you must factor the modulus, take
+ * a square root mod each factor, and recombine the results
+ * using the Chinese Remainder Theorem.
+ */
+
+extern mp *mp_modsqrt(mp */*d*/, mp */*a*/, mp */*p*/);
/*----- Test harness support ----------------------------------------------*/