1Mask mode is a fast way to produce password candidates given a "mask" that
2describes what the words should look like.
3
4A mask may consist of:
5
6- Static letters.
7- Ranges in [aouei] or [a-z] syntax. Or both, [0-9abcdef] is the same as
8     [0-9a-f].
9- Placeholders that are just a short form for ranges, like ?l which is
10     100% equivalent to [a-z].
11- ?l lower-case ASCII letters
12- ?u upper-case ASCII letters
13- ?d digits
14- ?s specials (all printable ASCII characters not in ?l, ?u or ?d)
15- ?a full 'printable' ASCII. Note that for formats that don't recognize case
16     (eg. LM), this only includes lower-case characters which is a tremendous
17     reduction of keyspace for the win.
18- ?B all 8-bit (0x80-0xff)
19- ?b all (0x01-0xff) (the NULL character is currently not supported by core).
20- ?h lower-case HEX digits (0-9, a-f)
21- ?H upper-case HEX digits (0-9, A-F)
22- ?L lower-case non-ASCII letters
23- ?U upper-case non-ASCII letters
24- ?D non-ASCII "digits"
25- ?S non-ASCII "specials"
26- ?A all valid characters in the current code page (including ASCII). Note
27     that for formats that don't recognize case (eg. LM), this only includes
28     lower-case characters which is a tremendous reduction of keyspace.
29- Placeholders that are custom defined, so we can e.g. define ?1 to mean [?u?l]
30  ?1 .. ?9 user-defined place-holder 1 .. 9
31- Placeholders for Hybrid Mask mode:
32  ?w is a placeholder for the original word produced by the parent mode in
33     Hybrid Mask mode.
34  ?W is just like ?w except the original word is case toggled (so PassWord
35     becomes pASSwORD).
36
37Mask Mode alone produces words from the mask, for example ?u?l?l will generate
38all possible three-letter words, with first character uppercased and the
39remaining in lowercase.
40
41Hybrid (a.k.a Stacked) Mask means we use e.g. a wordlist with or without rules
42(or any other cracking mode), and then apply the mask to each word.  So with a
43mask of ?w?d?d and an input word (from the parent cracking mode) of "pass",
44it will produce "pass00", "pass01" and so on until "pass99".  Hybrid Mask can
45be stacked upon any other mode except single.  Hybrid Mask can even be applied
46after hybrid regex, eg "prince -> regex -> mask".
47
48For most fast GPU formats, mask mode (including hybrid) is several orders of
49magnitude faster than any other cracking mode, as the mask (or part of it) is
50applied on GPU side.  Hybrid mask can thus be used as a GPU accelerator for
51any mode except single.  To benchmark the speed of such format using a mask,
52use "--test --mask" (using some default mask) or optionally with a specific
53mask, eg. "--test --mask=?a?a".  You can list all formats featuring internal
54mask using "--list=formats -format=mask".
55
56External filters can be applied too, and will be applied last of all.  The
57"longest" chain is thus "wordlist -> rules -> regex -> mask -> filter".  Using
58external filters with "GPU side mask" will cause a somewhat undefined behavior
59though: The filter will be applied before the GPU-side mask has finished the
60word!
61
62You can define custom placeholders for ?1 .. ?9 using command line e.g. -1=?l?u
63or in john.conf section [Mask].
64
65There is a default mask in john.conf too (defaulting to same as hashcat).
66This should be used with -max-len (and possibly -min-len) to do any good.
67
68The -max-len=N option will truncate the mask so no words longer than N are
69produced.
70
71The -min-len=N option will skip generation of words shorter than N.
72
73If not in "hybrid mask" mode, and either -min-len or -max-len option was used,
74we will iterate lengths (as in "incremental mask") from -min-len to -max-len
75(or format's min or max length, if one was not given).  So to produce all
76possible words from 3 to 5 letters, use -mask=?l -min-len=3 -max-len=5.  In
77case the specified mask is shorter, the last part of it will be expanded, for
78example "-mask=?u?l -max-len=5" will use an effective mask of ?u?l?l?l?l.
79Whenever using incremental mask, the ETA at any given time shows estimated
80time to complete the *current* length, as opposed to the whole run.
81
82You can escape special characters with \.  So to produce a literal "?l" you
83could say \?l or ?\l and it will not be parsed as a placeholder.  Similarly,
84you can escape dashes or brackets to prevent them from being parsed as
85specials.  To produce a literal backslash, use \\.
86
87There is also a special hex notation, \xHH for specifying any character code.
88For example, \x41 is "A" and \x09 is the code for TAB.
89
90
91Examples:
92
93Mask            custom mask / hybrid input      example output  num candidates
94pass                                            pass            1
95pw?d                                            pw3             10
96?w?d?d?d                password                password123     1000x
97?w?s?w                  Bozo                    Bozo#Bozo       33x
98?w?s?W                  Bozo                    Bozo#bOZO       33x
990x?1?1:?1?1:?1?1        -1=[0-9a-f]             0xde:ad:ca      16777216
100?3?l?l?l                -3=?l?u                 Bozo, hobo      913952
101[Pp][Aa@][Ss5][Ss5][Ww][Oo0][Rr][Dd]            P@55w0rD        1296
102
103We have on-device mask mode support for most fast hash types for which
104we have OpenCL support at all.  Further, such on-device mask support can
105be used along with a host-provided stream of partial candidate passwords
106to form a variety of hybrid modes.  For example, these are all valid:
107
108Test any 7-character printable ASCII strings, with a reasonable number
109of the mask positions being processed on device (JtR decides to
110optimally split the mask between host and device):
111
112--mask='?a?a?a?a?a?a?a'
113
114Ditto:
115
116--mask='?a' --min-length=7 --max-length=7
117
118Ditto, but for range of lengths 1 to 8:
119
120--mask='?a' --min-length=1 --max-length=8
121
122Can also use length ranges with more complex masks, where the last mask
123component would be the one extended to higher lengths:
124
125--mask='start?l?d' --min-length=7 --max-length=14
126
127Use the host's incremental mode to test strings of digits in a smart
128order, then append 3 more digits in a dumber order on device, no
129specific length (so let incremental mode switch lengths back and forth
130like it usually does):
131
132--incremental=digits --mask='?w?d?d?d'
133
134Ditto, but limit this to (total) length of 8 (adjusts incremental mode
135to only produces length 5 for its portion):
136
137--incremental=digits --mask='?w?d?d?d' --min-length=8 --max-length=8
138
139Have the host generate all-lowercase substrings in a smart order, then
140prepend an uppercase letter and append 3 digits, at least some of this
141on device:
142
143--incremental=lower --mask='?u?w?d?d?d'
144
145Read a wordlist on host, apply wordlist rules on host, then append 3
146digits on device:
147
148-w=word.lst --rules=jumbo --mask='?w?d?d?d'
149
150Duplicate words, then append 3 digits on device:
151
152-w=word.lst --mask='?w?w?d?d?d'
153
154Another way to write that:
155
156-w=word.lst --rules=':d' --mask='?w?d?d?d'
157
158Test strings consisting of uppercase words, 4 digits (processed on
159device), then lowercase versions of the same words:
160
161-w=word.lst --mask='?W?d?d?d?d?w'
162
163And so on.  Many of these option names may be abbreviated.
164