NAME

       rephrase - Specialized passphrase recovery tool for GnuPG

DESCRIPTION

       rephrase  is  a specialized passphrase recovery tool for GnuPG. If you can nearly remember
       your GnuPG passphrase - but not quite - then Rephrase may be able to help.

       Tell Rephrase the parts of the passphrase you know, and any number of alternatives for the
       parts  you're  not sure about; and Rephrase will try all the alternatives, in all possible
       combinations, and tell you which combination (if any) gives you  the  correct  passphrase.
       You  could  try  all  the combinations yourself, of course, if there are just a handful of
       them; but if there are more, that might be impractical.

       On the other hand, if you need to try a huge  number  of  possible  passphrases,  Rephrase
       might  be  too  slow; it is far from being an efficient passphrase cracker.  E.g. Rephrase
       can try out about 2600 possible passphrases per minute  on  my  1GHz  Athlon  (with  other
       processes  doing  nothing very heavy at the same time).  How many passphrases Rephrase can
       try depends on how long you are prepared to wait!  Rephrase can reasonably be  run  for  a
       long time; e.g. it *won't* use more memory the longer it runs.

       It  would  be  a Bad Thing to leave your passphrase (or part of it, or your guesses at it)
       lying around on your hard drive; since a passphrase is supposed to be  an  extra  line  of
       defence  if  an  attacker obtains access to your secret keyring (which you presumably *do*
       keep on your hard drive).  That's why  Rephrase  keeps  all  the  information  about  your
       passphrase that you give it in secure memory (and then pipes each possible passphrase to a
       child gpg process).   For  this  reason,  Rephrase  is  likely  to  be  more  secure  than
       alternative solutions that involve generating a list of possible passphrases in a file and
       then testing them.

       [1] For more information about GnuPG, see http://www.gnupg.org/ .

USAGE

       rephrase <key>

       where <key> is the key whose passphrase you want to recover; you can identify the  key  in
       any  of  the ways that GnuPG understands.  (To make sure you're using a sensible value for
       <key>, you could first try

           gpg --list-secret-keys <key>

       which should list exactly 1 key.)

       You will be prompted to enter a pattern (the pattern is not echoed to the  screen  as  you
       type  it).  So what's a pattern?  Suppose you know that your passphrase was something like
       "super-secret", but you're not sure if you changed some (or all) of the "e"s into "3"s, or
       any  of  the consonants into upper case, or indeed changed the "c" into "k" or "K" or even
       "|<", or changed the "-" into " " or just omitted it.  Then you could enter this pattern:

           (s|S)u(p|P)(e|3)(r|R)(-| |)(s|S)(e|3)(c|C|k|K|\|<)(r|R)(e|3)(t|T)

       The pattern is your passphrase - except that 4 characters have special meanings.  Brackets
       -  "("  and  ")" - are used to group alternatives wherever you're not sure what characters
       are correct; "|" is used inside a pair of brackets to separate the alternatives;  and  "\"
       is used to escape any of the 4 special characters when you need to use it literally.

       Rephrase will tell you if your pattern contains a syntax error.  That happens if there are
       unbalanced brackets (i.e. they aren't in proper pairs); or if the pattern  ends  with  "\"
       (because  then  there's  nothing  for it to escape).  It also happens (and these cases are
       limitations in Rephrase's simple pattern parser) if you try to nest pairs of brackets;  or
       if you try to use "|" anywhere that's not inside a pair of brackets.

       If  the  pattern  contains  no  syntax  errors, Rephrase will try each possible passphrase
       matching the pattern in turn.  If the correct passphrase is found, Rephrase won't actually
       tell  you  what  it is (in case someone's looking over your shoulder), but will tell you a
       string of numbers: you can work out the correct passphrase  from  these  numbers  and  the
       pattern you entered.  E.g.

                  2 1 2 1 2 1 1 5 1 2 2

       The first number - 2 - means that at the first pair of brackets in the pattern - "(s|S)" -
       you must take the second alternative - viz. "S".  The second number - 1 -  means  that  at
       the  seconds  pair of brackets - "(p|P)" - you must take the first alternative - viz. "p".
       And so forth.  So in this case the correct passphrase is "Sup3r se|<r3T".

       If the correct passphrase is not found from the pattern, Rephrase  tells  you  so.   (Note
       that  you  will  also get this result if you specified <key> incorretly; how to check that
       the value of <key> is OK is explained above.)

       Rephrase's exit status is 0 is the passphrase is found, 1 if  it's  not  found,  or  other
       values if an error occurs.

SECURITY

       The  good  news  is  that  Rephrase  uses  mlock()  in order to keep the information about
       passphrases that it's given as secure as possible.  The bad news  is  that  using  mlock()
       requires root privileges, so Rephrase needs to be setuid root.  However, it does drop root
       privileges very quickly, as soon as it has called mlock().

       It's also debatable whether mlock() is a proper  way  to  protect  sensitive  information.
       According  to  POSIX,  mlock()ing  a  page  guarantees  that it *is* in memory (useful for
       realtime  applications),  not  that  it  *isn't*  in  the  swap   (useful   for   security
       applications).   Possibly  an  encrypted swap partition (or no swap partition) is a better
       solution.  Anyway, GnuPG itself uses mlock(), which makes  it  sensible  for  Rephrase  to
       follow suit.

BUGS

       Portability is untested: I have only used Rephrase on a GNU/Linux system (Linux 2.4.21 and
       Glibc 2.3.2; building with GNU Make 3.79.1, bash 2.05 (as /bin/sh) and either  GCC  2.95.3
       or  GCC  3.3).   I  believe setreuid() is a BSD-ism, so it may not exist on more SysV-like
       systems.  There are probably many other issues.

       If mlock() fails (probably because Rephrase is  not  setuid  root),  Rephrase  refuses  to
       proceed: it would be better to issue a warning and continue, since that's what GnuPG does.

       Before  it asks you to enter a pattern, Rephrase should check that the <key> argument does
       refer to exactly 1 key and that that key is available.

       If you'd like Rephrase to be faster, then it's too slow.  (But if you're  happy  with  it,
       then it's fast enough.)

       The standard --version and --help options are unimplemented.

AUTHOR

       This  manual  page  was prepared by Tiago Bortoletto Vaz <tiago@debian.org> for the Debian
       GNU/Linux system (but may be used by others). Most of the text used here  comes  from  the
       original README file by Phil Lanch's <phil@subtle.clara.co.uk>.