#   Copyright
#
#      Copyright (C) 2010 Jari Aalto
#
#   License
#
#       This program is free software; you can redistribute it and/or modify
#       it under the terms of the GNU General Public License as published by
#       the Free Software Foundation; either version 3 of the License, or
#       (at your option) any later version.
#
#       This program is distributed in the hope that it will be useful,
#       but WITHOUT ANY WARRANTY; without even the implied warranty of
#       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
#       GNU General Public License for more details.
#
#       You should have received a copy of the GNU General Public License
#       along with this program. If not, see <http://www.gnu.org/licenses/>.
#
#   Description
#
#	To learn what TOP LEVEL section to use in manual pages,
#	see POSIX/Susv standard and "Utility Description Defaults" at
#	http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11
#
#	This is manual page in Perl POD format. Read more at
#	http://perldoc.perl.org/perlpod.html or run command:
#
#	    perldoc perlpod | less
#
#	To check the syntax:
#
#	    podchecker *.pod
#
#	Create manual page with command:
#
#	    pod2man PAGE.N.pod > PAGE.N

=pod

=head1 NAME

sharand - generate cryptographically secure pseudo random file

=head1 SYNOPSIS

    sharand key
    sharand key count-of-bytes

=head1 DESCRIPTION

SHA1-RANDOM generates cryptographically secure pseudo random files
which should not be compressible by any algorithm that does not know
the key used to generate it. Without knowing the key, it is believed
to be impossible to compress this file.

The command:

   sharand key

prints the SHA1 hash of the key, which can be any ASCII string.
If the string has spaces, then enclose it in quotes.

Command:

   sharand key n

works as above and also creates the file C<sharand.out> with length n
bytes containing cryptographically secure pseudo random numbers. Given
all but one bit of the file, it is not possible to guess the remaining
bit with probability greater than 1/2 unless you know the key.

The output is a series of 20 byte strings, x[1], x[2], ... x[n/20]
such that:

  x[i] = SHA1(x[i-1] + key)

where x[0] is a string of 0 bytes, and + denotes concatenation.

=head1 OPTIONS

None.

=head1 EXAMPLES

Basic use:

  $ sharand abc 50

  Key hash = A9 99 3E 36 47 06 81 6A BA 3E 25 71 78 50 C2 6C 9C D0 D8 9D
  Wrote sharand.out (50 bytes)

The contents of sharnad.out

  $ od -x sharand.out

  7D DF 37 9E  DB 9F 0E 14  1F 6D AD EF  EC 28 F0 60
  2B 2A 76 A8  49 54 13 F2  6E DA 0F 19  CD D9 26 6C
  46 8A 2D 17  8B 76 24 C0  0D D1 80 4F  E7 22 6C 2A
  9A C9

=head1 ENVIRONMENT

None.

=head1 FILES

Program's output is written to C<sharnad.out>.

=head1 STANDARDS

"US Secure Hash Algorithm 1 (SHA1)"
http://www.rfc-editor.org/rfc/rfc3174.txt

=head1 SEE ALSO

crypt(1)

=head1 AUTHORS

Program was written by Matt Mahoney <matmahoney@yahoo.com>

This manual page was written by Jari Aalto <jari.aalto@cante.net>.
Released under license GNU GPL version 2 or (at your option) any later
version. For more information about license, visit
<http://www.gnu.org/copyleft/gpl.html>.

=cut
