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 } ZxcTypeMatch_t;
  74
  75 /* Linked list of information returned in the Info arg to ZxcvbnMatch */
  76 struct ZxcMatch
  77 {
  78     int             Begin;   /* Char position of begining of match */
  79     int             Length;  /* Number of chars in the match */
  80     double          Entrpy;  /* The entropy of the match */
  81     ZxcTypeMatch_t  Type;    /* Type of match (Spatial/Dictionary/Order/Repeat) */
  82     struct ZxcMatch *Next;
  83 };
  84 typedef struct ZxcMatch ZxcMatch_t;
  85
  86
  87 #ifdef __cplusplus
  88 extern "C" {
  89 #endif
  90
  91 #ifdef USE_DICT_FILE
  92
  93 /**********************************************************************************
  94  * Read the dictionnary data from the given file. Returns 1 if OK, 0 if error.
  95  * Called once at program startup.
  96  */
  97 int ZxcvbnInit(const char *);
  98
  99 /**********************************************************************************
 100  * Free the dictionnary data after use. Called once at program shutdown.
 101  */
 102 void ZxcvbnUnInit();
 103
 104 #else
 105
 106 /* As the dictionary data is included in the source, define these functions to do nothing. */
 107 #define ZxcvbnInit(s) 1
 108 #define ZxcvbnUnInit() do {} while(0)
 109
 110 #endif
 111
 112 /**********************************************************************************
 113  * The main password matching function. May be called multiple times.
 114  * The parameters are:
 115  *  Passwd      The password to be tested. Null terminated string.
 116  *  UserDict    User supplied dictionary words to be considered particulary bad. Passed
 117  *               as a pointer to array of string pointers, with null last entry (like
 118  *               the argv parameter to main()). May be null or point to empty array when
 119  *               there are no user dictionary words.
 120  *  Info        The address of a pointer variable to receive information on the parts
 121  *               of the password. This parameter can be null if no information is wanted.
 122  *               The data should be freed by calling ZxcvbnFreeInfo().
 123  *
 124  * Returns the entropy of the password (in bits).
 125  */
 126 double ZxcvbnMatch(const char *Passwd, const char *UserDict[], ZxcMatch_t **Info);
 127
 128 /**********************************************************************************
 129  * Free the data returned in the Info parameter to ZxcvbnMatch().
 130  */
 131 void ZxcvbnFreeInfo(ZxcMatch_t *Info);
 132
 133 #ifdef __cplusplus
 134 }
 135 #endif
 136
 137 #endif