src/zxcvbn.h

   1 #ifndef ZXCVBN_H_F98183CE2A01_INCLUDED
   2 #define ZXCVBN_H_F98183CE2A01_INCLUDED
   3 /**********************************************************************************
   4  * C implementation of the zxcvbn password strength estimation method.
   5  * Copyright (c) 2015, Tony Evans
   6  * All rights reserved.
   7  *
   8  * Redistribution and use in source and binary forms, with or without modification, are
   9  * permitted provided that the following conditions are met:
  10  *
  11  * 1. Redistributions of source code must retain the above copyright notice, this list
  12  *    of conditions and the following disclaimer.
  13  *
  14  * 2. Redistributions in binary form must reproduce the above copyright notice, this
  15  *    list of conditions and the following disclaimer in the documentation and/or other
  16  *    materials provided with the distribution.
  17  *
  18  * 3. Neither the name of the copyright holder nor the names of its contributors may be
  19  *    used to endorse or promote products derived from this software without specific
  20  *    prior written permission.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
  23  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  24  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
  25  * SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  26  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  27  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  28  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  29  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  30  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  31  * DAMAGE.
  32  *
  33  **********************************************************************************/
  34
  35 /* If this is defined, the dictiononary data is read from file. When undefined */
  36 /* dictionary data is included in the source code. */
  37 /*#define USE_DICT_FILE */
  38
  39 /* If this is defined, C++ builds which read dictionary data from file will use */
  40 /* stdio FILE streams (and fopen,fread,fclose). When undefined, C++ builds will */
  41 /* use std::ifstream to read dictionary data. Ignored for C builds (stdio FILE  */
  42 /* streams are always used). */
  43 /*#define USE_FILE_IO */
  44
  45 #ifndef __cplusplus
  46 /* C build. Use the standard malloc/free for heap memory */
  47 #include <stdlib.h>
  48 #define MallocFn(T,N) ((T *)malloc((N) * sizeof(T)))
  49 #define FreeFn(P)      free(P)
  50
  51 #else
  52
  53 /* C++ build. Use the new/delete operators for heap memory */
  54 #define MallocFn(T,N)   (new T[N])
  55 #define FreeFn(P)       (delete [] P)
  56
  57 #endif
  58
  59 /* Enum for the types of match returned in the Info arg to ZxcvbnMatch */
  60 typedef enum
  61 {
  62     NON_MATCH,          /* 0 */
  63     BRUTE_MATCH,        /* 1 */
  64     DICTIONARY_MATCH,   /* 2 */
  65     DICT_LEET_MATCH,    /* 3 */
  66     USER_MATCH,         /* 4 */
  67     USER_LEET_MATCH,    /* 5 */
  68     REPEATS_MATCH,      /* 6 */
  69     SEQUENCE_MATCH,     /* 7 */
  70     SPATIAL_MATCH,      /* 8 */
  71     DATE_MATCH,         /* 9 */
  72     YEAR_MATCH,         /* 10 */
  73     MULTIPLE_MATCH = 32 /* Added to above to indicate matching part has been repeated */
  74 } ZxcTypeMatch_t;
  75
  76 /* Linked list of information returned in the Info arg to ZxcvbnMatch */
  77 struct ZxcMatch
  78 {
  79     int             Begin;   /* Char position of begining of match */
  80     int             Length;  /* Number of chars in the match */
  81     double          Entrpy;  /* The entropy of the match */
  82     double          MltEnpy; /* Entropy with additional allowance for multipart password */
  83     ZxcTypeMatch_t  Type;    /* Type of match (Spatial/Dictionary/Order/Repeat) */
  84     struct ZxcMatch *Next;
  85 };
  86 typedef struct ZxcMatch ZxcMatch_t;
  87
  88
  89 #ifdef __cplusplus
  90 extern "C" {
  91 #endif
  92
  93 #ifdef USE_DICT_FILE
  94
  95 /**********************************************************************************
  96  * Read the dictionnary data from the given file. Returns 1 if OK, 0 if error.
  97  * Called once at program startup.
  98  */
  99 int ZxcvbnInit(const char *);
 100
 101 /**********************************************************************************
 102  * Free the dictionnary data after use. Called once at program shutdown.
 103  */
 104 void ZxcvbnUnInit();
 105
 106 #else
 107
 108 /* As the dictionary data is included in the source, define these functions to do nothing. */
 109 #define ZxcvbnInit(s) 1
 110 #define ZxcvbnUnInit() do {} while(0)
 111
 112 #endif
 113
 114 /**********************************************************************************
 115  * The main password matching function. May be called multiple times.
 116  * The parameters are:
 117  *  Passwd      The password to be tested. Null terminated string.
 118  *  UserDict    User supplied dictionary words to be considered particulary bad. Passed
 119  *               as a pointer to array of string pointers, with null last entry (like
 120  *               the argv parameter to main()). May be null or point to empty array when
 121  *               there are no user dictionary words.
 122  *  Info        The address of a pointer variable to receive information on the parts
 123  *               of the password. This parameter can be null if no information is wanted.
 124  *               The data should be freed by calling ZxcvbnFreeInfo().
 125  *
 126  * Returns the entropy of the password (in bits).
 127  */
 128 double ZxcvbnMatch(const char *Passwd, const char *UserDict[], ZxcMatch_t **Info);
 129
 130 /**********************************************************************************
 131  * Free the data returned in the Info parameter to ZxcvbnMatch().
 132  */
 133 void ZxcvbnFreeInfo(ZxcMatch_t *Info);
 134
 135 #ifdef __cplusplus
 136 }
 137 #endif
 138
 139 #endif