#lang scribble/doc
@; THIS FILE IS GENERATED
@(require scribble/manual)
@(require (for-label (planet neil/randtok:1:0)))
@title[#:version "0.1"]{@bold{randtok}: Random Token String Generation in Scheme}
@author{Neil Van Dyke}


License: @seclink["Legal" #:underline? #f]{LGPL 3} @(hspace 1) Web: @link["http://www.neilvandyke.org/randtok-scheme/" #:underline? #f]{http://www.neilvandyke.org/randtok-scheme/}

@defmodule[(planet neil/randtok:1:0)]

      

@section{Introduction}


      

The @bold{randtok} library is intended for generating random strings such as for secure authentication tokens for Web site session cookies.


      

@bold{randtok} makes fairly efficient use of bits in a scarce random byte source like @tt{/dev/random}.  For example, an 8-character token consisting of only the lower-case Latin letters consumes only 5 random bytes, rather than 8.  In a security sensitive application, efficient use of the source might be important when using effectively random data rather than a possibly predictable pseudorandom number generator (PRNG).


      

Note that this code has not been tested heavily.


      

@defproc[(make-random-token-string-maker (port any/c) (str any/c) (len any/c)) any/c]{
          

Returns a procedure that generats random token strings of length @schemevarfont{len}, using characters from string @schemevarfont{str}, with random numbers drawn from input port @schemevarfont{port}.


          

@SCHEMEBLOCK[
(define random-in (open-input-file "/dev/random"))

(define f (make-random-token-string-maker
           random-in "0123456789abcdef" 10))

f   ==> <procedure:<random-token-string-maker>>
(f) ==> "7dd73b9ec0"
(f) ==> "1f7bc42210"

(close-input-port random-in)
]


          

This is useful for using a single open file of @tt{/dev/random} to generate multiple random token strings throughout the execution of a program.  For example:


          

@SCHEMEBLOCK[
(call-with-input-file "/dev/random"
  (lambda (random-in)
    (file-stream-buffer-mode random-in 'none)
    (let ((randtok (make-random-token-string-maker
                    random-in "ABCD" 10)))
      ...
      (printf "Here is a random token: ~S\n" (randtok))
      ...
      (printf "Here is another random token: ~S\n" (randtok))
      ...)))
]


          

Note that you may wish to disable buffering of the input port, as is done above.


        }

      

@defparam[current-random-byte-file x any/c]{
          

This parameter is a filename for a source of random bytes.  It is used by procedure @tt{random-token-string}.  The default value is @tt{"/dev/random"}.


        }

      

@defproc[(random-token-string (len any/c)) any/c]{
          

This is a convenient procedure for generating alphanumeric random token strings, using upper-case and lower-case Latin letters and Arabic digits. The length defaults to 8.  For example:


          

@SCHEMEBLOCK[
(random-token-string)    ==> "SW6gu2gw"
(random-token-string)    ==> "9RjdZxyj"
(random-token-string 20) ==> "thCOmSte6OXWByxtn0G5"
]


          

Note that reusing the output of @tt{make-random-token-string-maker} will be more efficient in some cases.


        }

    
      

@section{History}


      

@itemize[

@item{Version 0.1 -- 2009-06-07 -- PLaneT @tt{(1 0)}
            

First release.


          }



]


    

@section[#:tag "Legal"]{Legal}



Copyright (c) 2009 Neil Van Dyke.  This program is Free Software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License (LGPL 3), 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 http://www.gnu.org/licenses/ for details.  For other licenses and consulting, please contact the author.