Add a few explanatory comments

Author: codesections

README.md

@@ -89,13 +89,4 @@ There are many alternative passphrase generators.  I believe they all have some
 
 ## Bug reports and contributing 
 
-pass-gen is under active development (see the roadmap, below) and would welcome new contributors.  pass-gen is currently co-hosted on both GitLab and GitHub, so please feel free to file issues, make pull requests, or otherwise contribute through either site.  Also feel free to submit bug reports or patches via email, either to [email protected] or to [email protected].
-
-## Roadmap
-
-Planned future features:
-
-* Encrypted configuration file
-* Support for using multiple wordlist files in the same passphrase
-* Additional built-in wordlist files (especially non-English files)
-* Additional error handling
+pass-gen is under active development and would welcome additional contributors.  pass-gen is currently co-hosted on both GitLab and GitHub, so please feel free to file issues, make pull requests, or otherwise contribute through either site.  Also feel free to submit bug reports or patches via email, either to [email protected] or to [email protected].

pass-gen

@@ -3,17 +3,28 @@
 #  Copyright 2018 Daniel Long Sockwell <[email protected]>.  
 #  All rights reserved.  This file is licensed under the GPLv3+.
 #  Please see COPYING for more information.
+#  Please see man pass-gen(1) for usage and configuration instructions
 
 
 #  Default settings (unless overridden by command-line options or .passgenrc)
 WORDLIST=/usr/local/lib/pass-gen/wordlists/EFF_wordlist_total
-SIZE_OF_WORDLIST="not set"
+SIZE_OF_WORDLIST="not set"  # Not a user-set value; computed based on supplied list
 CHARLIST=/usr/local/lib/pass-gen/character-lists/default_character_list
-SIZE_OF_CHARLIST="not set"
+SIZE_OF_CHARLIST="not set"  # Not a user-set value; computed based on supplied list
 PADDING_LENGTH_BEFORE=0
 PADDING_LENGTH_AFTER=3
 NUMBER_OF_WORDS=6
-CAPITAL_COUNTER="$(( $(od -An -N2 -i /dev/urandom) % (2) ))" #randomly 1 or 2
+CAPITAL_COUNTER="$(( $(od --address-radix=n --read-bytes=2 -i /dev/urandom) \
+  % (3) ))" 
+  # This generates a cryptographically lecture random number between 0 
+  #   and 2 inclusive.  
+  #
+  # This uses /dev/urandom as its secure source of entropy.  See
+  #  https://sockpuppet.org/blog/2014/02/25/safely-generate-random-numbers/
+  # The way dev/urandom works is by producing a random number.  We use 
+  #  od ("octal dump", though we're not using the "octal" part) to output
+  #  two bytes of that random number and then take the remainder when divided
+  #  by three.  This gets us a secure, random number that is 0-2 inclusive
 CAPITALIZATION_MODE="both"
 CAPITALIZATION_OPTIONS_PER_WORD=3
 DISPLAY_PASSWORD=false
@@ -27,12 +38,13 @@ if [ -f /home/$USER/.passgenrc ]; then
   ## Find the `current_project` key, and get the quoted string value 
   if [ $(grep word-list $CONFIG_FILE) ]; then
     WORDLIST=$(grep word-list $CONFIG_FILE | cut --delimiter== --fields=2)
-    WORDLIST=$(echo $WORDLIST | sed -e "s_~_/home/${USER}_")
+    # `delimiter= ` sets the delimiter to <SPACE>
+    WORDLIST=$(echo $WORDLIST | sed --expression="s_~_/home/${USER}_")
   fi
 
   if [ $(grep character-list $CONFIG_FILE) ]; then
     CHARLIST=$(grep character-list $CONFIG_FILE | cut --delimiter== --fields=2)
-    CHARLIST=$(echo $CHARLIST | sed -e "s_~_/home/${USER}_")
+    CHARLIST=$(echo $CHARLIST | sed --expression="s_~_/home/${USER}_")
   fi
 
   if [ $(grep capital-mode $CONFIG_FILE) ]; then
@@ -66,7 +78,9 @@ fi
 ## OPTION COMMANDS
 ##
 
+# We parse commands manually to avoid dependencies on getopt or similar
 cmd_version() {
+  # Display the version information
   >&2 cat <<-_EOF
 pass-gen v.0.5.1
 Copyright (C) 2018 Daniel Long Sockwell, www.codesections.com
@@ -81,6 +95,7 @@ Written by Daniel Long Sockwell
 
 
 cmd_help() {
+  # Display usage information
   >&2 cat <<-_EOF
 Usage: pass-gen [OPTION]
 
@@ -104,23 +119,29 @@ Full documentation avalible in the pass-gen(1) man page.
   exit 0
 }
 
+
 cmd_error() {
+  # Display error information
     >&2 cat <<-_EOF
   pass-gen: unrecognized option '$1'
   Try 'pass-gen --help' for more information.
 	_EOF
     exit 1
 }
 
+
 cmd_echo() {
+  # Display the password
   DISPLAY_PASSWORD=true 
   case $1 in
     ''|*[!0-9]*)             NUMBER_TO_DISPLAY=1; return 1;;
     *)                       NUMBER_TO_DISPLAY=$1;;
   esac
 }
 
+
 cmd_length() {
+  # Set the number of words in the generated password
   case $1 in
     ''|*[!0-9]*)             >&2 cat <<-_EOF 
   "$1" is not a valid length.  
@@ -131,7 +152,9 @@ cmd_length() {
    esac
 }
 
+
 cmd_wordlist() {
+  # Set the wordlist to be used
   if [ ! -f $1 ]; then
     echo "Wordlist file could not be found.  Does it exist?"
     exit 1
@@ -143,7 +166,9 @@ cmd_wordlist() {
   fi
 }
 
+
 cmd_charlist() {
+  # Set the character list to be used
   if [ ! -f $1 ]; then
     echo "Character-list file could not be found.  Does it exist?"
     exit 1
@@ -155,7 +180,9 @@ cmd_charlist() {
   fi
 }
 
+
 cmd_padding_length_before() {
+  # Set how many numbers should be used as padding before the generated words
   case $1 in
     ''|*[!0-9]*)             >&2 cat <<-_EOF 
   "$1" is not a valid amount of padding.
@@ -166,7 +193,9 @@ cmd_padding_length_before() {
    esac
 }
 
+
 cmd_padding_length_after() {
+  # Set how many numbers should be used as padding after the generated words
   case $1 in
     ''|*[!0-9]*)             >&2 cat <<-_EOF 
   "$1" is not a valid amount of padding.
@@ -177,7 +206,9 @@ cmd_padding_length_after() {
    esac
 }
 
+
 cmd_capital_mode() {
+  # Set the capitalization mode
   case $1 in
     all|initial|both)         CAPITALIZATION_MODE=$1;;
     *)                        >&2 cat <<-_EOF 
@@ -191,12 +222,14 @@ cmd_capital_mode() {
    fi
 }
 
+
 cmd_report_entrophy() { 
   REPORT_ENTROPY=true
 }
 
-#  Pick a random symbol from CHARLIST
+
 generate_random_symbol() {
+  # Pick a random symbol from CHARLIST
   MIN=1
   SIZE_OF_CHARLIST=$(cat $CHARLIST | wc -l)
   #  Generate a random number between MAX and MIN
@@ -205,32 +238,34 @@ generate_random_symbol() {
 }
 
 
-#  Generate a random word from WORDLIST
 generate_random_word() {
+  # Generate a random word from WORDLIST
   MIN=1
   SIZE_OF_WORDLIST=$(cat $WORDLIST | wc -l)
   #  Generate a random number between MAX and MIN
-  RANDOM_NUM="$(( $MIN + $(od -An -N2 -i /dev/urandom) % ($SIZE_OF_WORDLIST - $MIN + 1) ))"
+  RANDOM_NUM="$(( $MIN + $(od --address-radix=n --read-bytes=2 -i /dev/urandom) % ($SIZE_OF_WORDLIST - $MIN + 1) ))"
 
   RANDOM_WORD="$(sed -n ${RANDOM_NUM}p $WORDLIST)"
 }
 
 
-#  Capitalize the word if necessary
 capitalize_all() {
+  # Capitalize the word if necessary
   if [ $(( ($CAPITAL_COUNTER - 1) % 2 )) -eq "0" ]; then
     RANDOM_WORD="$(echo $RANDOM_WORD | tr '[:lower:]' '[:upper:]')"
   fi
   CAPITAL_COUNTER=$(( $CAPITAL_COUNTER + 1 ))
 }
 
+
 capitalize_initial() {
   if [ $(( $CAPITAL_COUNTER % 2 )) -eq "0" ]; then
     RANDOM_WORD="$(echo $RANDOM_WORD | sed 's/./\U&/')"
   fi
   CAPITAL_COUNTER=$(( $CAPITAL_COUNTER + 1 ))
 }
 
+
 capitalize_both() {
   if [ $(( ($CAPITAL_COUNTER - 1) % 3 )) -eq "0" ]; then
     RANDOM_WORD="$(echo $RANDOM_WORD | tr '[:lower:]' '[:upper:]')"
@@ -242,8 +277,8 @@ capitalize_both() {
 }
 
 
-#  Generate random numbers to pad the passphrase
 generate_padding() {
+  # Generate random numbers to pad the passphrase
   for i in $(seq 1 $PADDING_LENGTH_AFTER); do
     RANDOM_NUM="$(( 0 + $(od -An -N2 -i /dev/urandom) % (9 - 0 + 1) ))"
     PADDING_AFTER=${PADDING_AFTER}${RANDOM_NUM}
@@ -254,8 +289,9 @@ generate_padding() {
   done
 }
 
-#  Generate passphrase by combining random words with the chosen character
+
 generate_passphrase() {
+  # Generate passphrase by combining random words with the chosen character
   generate_random_symbol
   for i in $(seq 1 $NUMBER_OF_WORDS); do
     generate_random_word
@@ -278,13 +314,15 @@ generate_passphrase() {
 }
 
 clear_passphrase() {
+  # Clears the passphrase from memory.  Likely over-cautious, but intended
+  #  as an extra security measure against out-of-process access
   RANDOM_PASS=""
   PADDING_BEFORE=""
   PADDING_AFTER=""
 }
 
 
-#  Process command-line options and update settings as required
+# Process command-line options and update settings as required
 if [[ "$1" ]]; then     
   while [[ "$1" ]]; do
     currentParamater=$1
@@ -347,6 +385,8 @@ by the EFF Dice password tool contain 77 bits of entropy
 	_EOF
 fi
 
+# As a final, paranoid security practice, overwrite the generated passwords
+#  (again, to prevent out-of-process access)
 RANDOM_PASS="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 WORDLIST="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 CHARLIST="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"