RFC, 'usage 101' documentation

We seem to get a lot of 'how do I brute force XYZ' ? Often we direct the user to use inc mode (which is great). But for really doing a brute test, the user really wants 'mask' mode.

Now, we could do this by still keeping the terminology of 'mask', but by proper documentation (usage, ./john output, etc), listing that mask really 'means' brute force.

Now, to 'us' john developers, the 'meaning' of mask mode is very clear. BUT to johnny-come-lately end user, mask mode is certainly not clear. The terminology 'brute force' seems to be well known, so end users are looking for how it is done in john. All that this 'issue' (just an RFC) really is, is just asking if developers have any interest at all in this, or see this as beneficial at all for bumping up the signal to noise ratio on places like john-users mailing lists.

The 2 areas where john really 'does' have a brute force, are inc and mask. within inc, it is highly (hopefully) weighted, so that only the best of the best low hanging fruit passwords are tested, netting a large percentage of cracks. The mask mode is more unordered brute force, BUT allows additional 'gained intelligence' to be used also (such as pre-filling known parts, running against a wordlist, similar to rules, etc). They each are certainly a method of brute force under the hood, but wrapped with business logic that hopefully makes them a much better brute forcer.

So really all we might need to do, is to build a 'Brute Force' section or something in one of the usage files, demonstrate how to brute force all lower case, all lower/digits, all lower/digits/wordcap, and a custom. Then even within that section, point them to the 'full blown' documentation on mask.

I would think this would help alleviate some of the repetitive mail list replys, if nothing more than telling a user to 'see the "Brute Force" section of OPTIONS document or something like that.

If others deem this to be a non-issue, I will not be Bu77-hurt at all if this issue simply gets rejected and closed. I know there is feelings of education pointing a new user 'in the right direction'. But to me, it seems like too often a lot of time is spent handing this.

At a minimum, I can see benefit from these type locations (if we keep the mask mode name, but simply add 'Brute Force' in a documentation manner:

• ./john
  • usage screen. It should be a VERY short and sweet tiny change).
• FAQ
  • we should possibly update FAQ or generate a FAQ-jumbo)
• README
  • possibly, but since there is little help here, other than just ./john or ./john -w=xxx usage, possibly not)
• OPTIONS
  • almost certainly. But here, would keep the --mask=???? syntax, and just list that this 'is' or can be used as the 'brute force' mode.
  • The same type comment 'could' also be placed in -inc, but there to explain that its brute force where the permutation is not the 'human readable' order.
• EXAMPLES
  • almost certainly should be placed here in some manner, or at least wherever mask is listed, brute force talked about.

Start by reviewing the existing OPTIONS and EXAMPLES documentation, then inspect the ./john usage screen, FAQ, and README references to mask and incremental modes. The issue is complete when the relevant documentation consistently explains brute-force usage, includes the requested examples, and points readers to fuller mask documentation.