Pegwit v8 manual ================ Introduction ============ Pegwit is a program for performing public key file encryption and authentication. Encryption means that pegwit allows you to keep the information in files you send by email (or other means) confidential. Eavesdroppers will not be able to read the email. Authentication allows you to check that a file has not been tampered with (changed) since it was signed. Installation ============ There is no installation process - all you need is an executable, e.g. pegwit.exe. Pegwit is a 'command line' program - if you are using Windows 95 you first need to start a DOS shell. Running pegwit with no parameters will cause a brief summary of the command syntax to be output. The summary reads: Pegwit v8.x Usage (init/encrypt/decrypt/sign/verify) : -i public-key -e public-key plain cipher signature -v public-key plain clearsigned-text -V public-key clearsigned-text -f[operation] [type pegwit -f for details] This summary is also output if you supply the wrong number of parameters, or if the first parameter is not correct. Note that -E,-D,-S,-V are distinct from -e,-d,-s,-v. The '<' and '>' characters indicate where pegwit requires standard input, and where it generates standard output. Choosing a secret key ===================== To start with you need decide on a secret key. Your secret key needs to be unguessable by a cracking program even with a very large number of attempts. For the purpose of this manual, the secret key "hello there" (plus a newline) will be used. Obviously "hello there" is a rotten choice for a secret key, it is far too easy to guess. You should use a much better key than this. Note that pegwit (unlike for instance PGP) does not generate secret random keys internally - the secret key is *not* just a pass phrase which protects a stored key. Your secret key should be at least 10 characters, and more if the characters are not random (for example words), or if you might be up against a determined snooper with considerable computing resources. Pegwit reads secret values from standard input. If standard input is not redirected, you will need to terminate input by using CTRL-Z (this may vary on different operating systems). After using your secret key, you should clear the screen, for example by using the cls clear screen command (on DOS/Win95) or by entering several blank lines. Creating your public key ======================== Your public key is created using the pegwit -i command. For example, at a command prompt, try: pegwit -i > my.pub hello there CTRL-Z Now inspect the file my.pub (e.g. type my.pub) It should contain the text pegwit v8 public key =cc23ea8bc28aac71ee19befcb2beba4b349cbdc020965e2411d48f6dfa 28f4fd Encryption ========== To encrypt a file, you need a public key. Normally this will not be your own public key, but for example the public key of a friend who you are emailing a confidential file. There are many possible ways you could obtain this, but it is important to guard against forgery, that is a public key which claims to be for your friend, but actually is generated by someone who wishes to snoop on your mail. If in doubt ( when there is a lot at stake ) check the public key by making telephone call. This should be good enough for most purposes, provided you can recognise your friend over the telephone. If possible, check using multiple methods and sources. There are also more sophisticated ways of checking, using digital signatures of trusted third parties. For the moment though, create a text file which contains the text (say) 'I love you', and try pegwit -e my.pub test.txt text.tx0 any old random junk CTRL-Z Notice that pegwit reads some random input as well as a public key. The reason is that pegwit does not have access to good random numbers (for portability reasons). The junk you type does not have to be different on every occasion, but must be unguessable by an adversary. An attacker needs to guess the junk, the time of encryption and the entire contents of the file being encrypted for a successful 'crack'. [ He may make a very large number of guesses, using a 'cracking' program, possibly aided by well-educated human guesses ]. Alternatively he can guess (or steal) the private key of your friend. Decryption ========== To decrypt a file, you use your secret key, for example pegwit -d test.tx0 test.chk hello there CTRL-Z The contents of test.chk should now be be identical to the contents of test.txt. Signing a file ============== To sign a file, you use your secret key. This means that nobody else can forge your signatures. For example try pegwit -s test.txt >test.sig hello there CTRL-Z Verifying a signature ===================== To verify a signature, you use the public key of the signer. As for encryption (the other public key operation) you need to be sure the public key is not a forgery. For example try pegwit -v my.pub test.txt test.sig pwjunk uses key timings to increase the randomness of the output. For example, you can use pwjunk | pegwit -e my.pub test.txt test.tx0 pwjunk estimates how much 'randomness' has been generated, and does not allow input to be terminated until the estimate reachs 128 bits. More security considerations ( getting paranoid ) ================================================= You should not use your secret key on a computer to which an enemy may have had access, either physically or remotely via modems, networks, viruses etc. In practice this is a risk you may have to live with. You may choose to have several secret keys, using the highest grade secret key only under the most secure conditions. There is no substitute for keeping the computer(s) you use physically secure. Symmetric encryption ==================== -E and -D can be used for conventional (non public-key) encryption. These commands are slightly faster, and the encrypted file is 32 bytes smaller. -E can be useful for distributing a large file to several people. Use pegwit -s to generate a signature for the large file, then use -E to encrypt the file using the signature as the key. The encrypted large file can now be put in a public FTP area. Now send the signature to each person, encrypted with their public key. Note that keys have to be larger to achieve the same level of security as -e, so the use of -E is not recommended for keys which are entered manually. Signing text files ================== When using pegwit with email and usenet, the -S and -V commands may be more convenient. -S reads the input file as text lines, and outputs text with delimiters and the signature appended to the text. Filtering and ascii armoring of encrypted files =============================================== pegwit -fX where X is a normal command gives a set of commands which act as filters. In addition, encrypted output is converted to ascii, and encrypted input is also expected to be in ascii form. Secret values are read from a file, rather than standard input. The manual for the -f variants is output when pegwit is run with just -f, and is as follows: Pegwit v8.x [filter sub-mode] Usage (encrypt/decrypt/sign/verify) : -fe public-key random-junk ascii-cipher -fd secret-key plain -fE key ascii-cipher -fD key plain -fS secret-key clearsigned-text -fV public-key plain Note that 'plain' files read from standard input should not be binary ( this also applies to the -S command ), although on some UNIX-like systems binary files may work OK (but the result will not be portable, especially to Windows/MSDOS, due to CR/LF translation ). George Barwood