/* -*-c-*-
*
- * $Id: maurer.h,v 1.1 2000/06/17 11:29:49 mdw Exp $
+ * $Id: maurer.h,v 1.3 2004/04/08 01:36:15 mdw Exp $
*
* Maurer's universal statistical test
*
* (c) 2000 Straylight/Edgeware
*/
-/*----- Licensing notice --------------------------------------------------*
+/*----- Licensing notice --------------------------------------------------*
*
* This file is part of Catacomb.
*
* it under the terms of the GNU Library General Public License as
* published by the Free Software Foundation; either version 2 of the
* License, or (at your option) any later version.
- *
+ *
* Catacomb is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Library General Public License for more details.
- *
+ *
* You should have received a copy of the GNU Library General Public
* License along with Catacomb; if not, write to the Free
* Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
* MA 02111-1307, USA.
*/
-/*----- Revision history --------------------------------------------------*
- *
- * $Log: maurer.h,v $
- * Revision 1.1 2000/06/17 11:29:49 mdw
- * Maurer's universal statistical test.
- *
- */
-
#ifndef CATACOMB_MAURER_H
#define CATACOMB_MAURER_H
#include <mLib/bits.h>
+/*----- Data structures ---------------------------------------------------*/
+
+typedef struct maurer_ctx {
+ unsigned l; /* Chunk size, in bits */
+ uint32 a; /* Bitscanner accumulator */
+ unsigned b; /* Number of bits in accumulator */
+ unsigned long n; /* Number of chunks read so far */
+ double x; /* Statistic value */
+ unsigned long *t; /* Offset table */
+} maurer_ctx;
+
/*----- Functions provided ------------------------------------------------*/
+/* --- @maurer_init@ --- *
+ *
+ * Arguments: @maurer_ctx *m@ = pointer to a context to initialize
+ * @unsigned l@ = number of bits to take at a time
+ *
+ * Returns: Minimum recommended amount of data to test.
+ *
+ * Use: Initializes a Maurer testing context. Note that @l@ values
+ * larger than 16 are not supported, and values less than 6 can
+ * give bizarre results.
+ */
+
+extern unsigned long maurer_init(maurer_ctx */*m*/, unsigned /*l*/);
+
+/* --- @maurer_test@ --- *
+ *
+ * Arguments: @maurer_ctx *m@ = pointer to a Maurer testing context
+ * @const void *buf@ = pointer to a buffer of data
+ * @size_t sz@ = size of the buffer
+ *
+ * Returns: ---
+ *
+ * Use: Scans a buffer of data and updates the testing context.
+ */
+
+extern void maurer_test(maurer_ctx */*m*/,
+ const void */*buf*/, size_t /*sz*/);
+
+/* --- @maurer_done@ --- *
+ *
+ * Arguments: @maurer_ctx *m@ = pointer to a Maurer testing context
+ *
+ * Returns: The statistic %$Z_u = (X_u - \mu)/\sigma$%, which should be
+ * normally distributed with a mean of 0 and variance of 1.
+ *
+ * Use: Returns the result of Maurer's universal statistical test.
+ * Also frees the memory allocated during initialization.
+ *
+ * If insufficient data was received, the value @HUGE_VAL@ is
+ * returned.
+ */
+
+extern double maurer_done(maurer_ctx */*m*/);
+
/* --- @maurer@ --- *
*
* Arguments: @const octet *p@ = pointer to a buffer of data
* @size_t sz@ = size of the buffer
* @unsigned l@ = number of bits to take at a time
*
- * Returns: The statistic %$Z_u = (X_u - \mu)/\sigma$%, which should be
- * normally distributed with a mean of zero and standard
- * deviation of 1.
- *
- * Use: Performs Maurer's universal statistical test on a buffer of
- * data. You must ensure that the buffer size @sz@ is larger
- * than %$11 l \cdot 2^l$% bits long, and ideally much larger.
+ * Returns: The statistic %$Z_u$%.
*
- * Note that, under Unix systems, this function requires the
- * maths library.
+ * Use: Simple interface to Maurer's universal statistical test. For
+ * large %$l$% you should use the more complicated restartable
+ * interface.
*/
extern double maurer(const octet */*p*/, size_t /*sz*/, unsigned /*l*/);