chore(user/mw_create_redirect_day_month.sh):Add TODO comment

[BK-2020-03.git] / unitproc / bknpass

diff --git a/unitproc/bknpass b/unitproc/bknpass
index c9643ce7518467496732708fa1b0dc17f3673281..f4930a069b8782cebda61145059034e01c7fc0c3 100755 (executable)
--- a/unitproc/bknpass
+++ b/unitproc/bknpass
@@ -1,12 +1,13 @@
 #!/bin/bash
 #!/bin/bash

-
-# Author: Steven Baltakatei Sandoval (baltakatei.com)
-#
-# License: This bash script, `bknpass`, is licensed under GPLv3 or
-# later by Steven Baltakatei Sandoval:
-#
+# Desc: Generate passphrase with specified number of bits of entropy
+# Usage: bknpass [integer]
+# Example: bknpass 256
+#   Result: 9tnzcl0m4dsm22a95525zj93jj
+# Version: 0.2.1
+# Depends: bash 5.1.8, GNU coreutils 8.32, bc 1.07.1, awk 5.1.0
+# License:

 #    `bknpass`, an alphanumeric password generator
 #    `bknpass`, an alphanumeric password generator

-#    Copyright (C) 2021  Steven Baltakatei Sandoval (baltakatei.com)
+#    Copyright (C) 2022  Steven Baltakatei Sandoval (baltakatei.com)

 #
 #    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
 #
 #    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


@@ -20,99 +21,77 @@
 #
 #    A copy of the GNU General Public License may be found at
 #    <https://www.gnu.org/licenses/>.
 #
 #    A copy of the GNU General Public License may be found at
 #    <https://www.gnu.org/licenses/>.

-#
-# Description: This bash script generates alphanumeric passphrases
-# with a char-count determined by a user-provided number of bits of
-# entropy. The passphrase is then outputted to stdout with a trailing
-# newline. It works as follows:
-# 
-#   - Prompt user for an integer. This integer is the number of bits
-#     of entropy that the generated password should have.
-#
-#   - Check if user-provided string is an integer using `bash` regular
-#     expression test.
-#
-#   - Calculate the minimum number of bech32 base32 characters
-#     required to encode the specified number of bits of entropy.
-#
-#       - This step uses `bc` to calculate a logarithm float string
-#         and `awk` to convert the float into an integer, rounding up.
-#
-#   - Use `tr`, `/dev/urandom`, and `head` to generate a random
-#     alphanumeric string with the length calculated in the previous
-#     step.
-#
-#   - Use `echo` to display the passphrase in stdout with a trailing
-#     newline.
-#
-# Usage: bknpass [int]
-#
-# Example: bknpass 256
-#
-# Dependencies: bash, echo, bc, awk, tr, head. See end of file
-#
-# Tested on:
-#
-#   - GNU/Linux Debian 10
-
-
-#==Initialization==

 
 

-let ALPHABET_SIZE="32" # number of unique chars in bech32 base32 charset, argument fed to `tr -c` in 'Generate passphrase' step)
-LOG_BASE=2 # Set logarithm base to 2
+yell() { echo "$0: $*" >&2; } # print script path and all args to stderr
+die() { yell "$*"; exit 111; } # same as yell() but non-zero exit status
+try() { "$@" || die "cannot $*"; } # runs args as command, reports args if command fails
+showUsage() {
+    # Desc: Display script usage information
+    # Usage: showUsage
+    # Version 0.0.1
+    # Input: none
+    # Output: stdout
+    # Depends: GNU-coreutils 8.30 (cat)
+    cat <<'EOF'
+    USAGE:
+        bknpass [int entropy_bit_count]

 
 

-# Define `echoerr` function which outputs text to stderr
-    # Note: function copied from https://stackoverflow.com/a/2990533
-function echoerr {
-    echo "$@" 1>&2;
-}
+    EXAMPLE:
+        bknpass 128
+EOF
+}; # Display information on how to use this script.
+main() {
+    # Desc: main program
+    # Usage: main "$@"
+    # Input:      $1: integer bits of entropy
+    # Output: stdout: string passphrase
+    # Depends: bash 5.1.8, GNU coreutils 8.32, bc 1.07.1, awk 5.1.0
+    # Ref/Attrib: [1] "Check existence of input argument in a Bash shell script". https://stackoverflow.com/a/6482403
+    #             [2] "How do I test if a variable is a number in Bash?". https://stackoverflow.com/a/806923
+    #             [3] "Round a Number in a Bash Script". https://bits.mdminhazulhaque.io/linux/round-number-in-bash-script.html
+    #             [4] "Logarithms in GNU bc". https://web.archive.org/web/20210211050732/http://phodd.net/gnu-bc/bcfaq.html#bclog
+    #             [5] "BIP 173". Note: bech32 charset. https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki
+    #             [6] "Bash Function to generate random password". https://www.thegeekstuff.com/2010/04/unix-bash-function-examples/
+    charset="qpzry9x8gf2tvdw0s3jn54khce6mua7l"; # bech32. See [5].
+    charset="$(tr -s "$charset" < <(echo -n "$charset"))"; # remove repeat chars
+    alphabet_size="$(echo -n "$charset" | wc -c)"; # number of unique chars
+    log_base=2; # entropy unit base (i.e. 2 for "bits of entropy")

 
 

-# Define `rpass` function which generates a base32 passphrase of length $1 (ex: `rpass 22` generates a 22-char string)
-#   Note: function adapted from https://www.thegeekstuff.com/2010/04/unix-bash-function-examples/
-#   Note: base32 charset uses bech32 charset
-function rpass {
-    cat /dev/urandom | LC_ALL=C tr -cd "qpzry9x8gf2tvdw0s3jn54khce6mua7l" | head -c ${1:-22}
-}
+    # Check inputs
+    if [[ $# -gt 1 ]]; then showUsage; die "ERROR:Too many arguments:$#"; fi;

 
 

+    # Check for bc
+    if ! command -v bc 1>/dev/null 2>&1; then die "ERROR:bc not available"; fi;

 
 

-#==Main Program==
+    ## Get entropy_bit_count
+    if [[ -z "$1" ]]; then
+       ### prompt user
+       showUsage;
+       echo -n "Please specify the required strength of the password in bits of entropy (ex: 256):" 1>&2; # prompt via stderr
+       read -r entropy_bit_count
+    else
+       entropy_bit_count="$1";
+    fi; # See [1].

 
 

-# Define $ENTROPY_BIT_COUNT1 as argument $1 or prompt user if $1 is not defined.
-    # note: argument test adapted from https://stackoverflow.com/a/6482403
-if [ -z "$1" ]
-then
-    echo "Entropy bit count argument (\$1) not supplied."
-    # Get from user the number of bits of entropy.
-    echoerr -n "Please specify the required strength of the password in bits of entropy (ex: 256):" # prompt via stderr
-    read ENTROPY_BIT_COUNT1
-else
-    ENTROPY_BIT_COUNT1="$1"
-fi
+    ## Check entropy_bit_count
+    pattern="^[0-9]+$";
+    if ! [[ $entropy_bit_count =~ $pattern ]] ; then die "ERROR:Not an integer:$entropy_bit_count"; fi; # See [2]

 
 

-# Check if $ENTROPY_BIT_COUNT1 is an non-negative integer
-    # Note: Regular expression test is adapted from https://stackoverflow.com/a/806923
-RETEST1='^[0-9]+$'
-if ! [[ $ENTROPY_BIT_COUNT1 =~ $RETEST1 ]] ; then
-   echo "error: Not an integer." >&2; exit 1    
-fi
+    ## Calculate minimum count of chars needed for passphrase as float using 'bc'
+    ###      Solve ln(a^n)/ln(2)=b for n where:
+    ###      a=$alphabet_size
+    ###      n=$char_count_float
+    ###      b=$entropy_bit_count
+    char_count_float="$(echo "$entropy_bit_count*l($log_base)/l($alphabet_size)" | bc -l)"; # See [4]

 
 

-# Calculate minimum count of chars needed to encode $ENTROPY_BIT_COUNT1 with alphabet size of $ALPHABET_SIZE as float
-    # Solve ln(a^n)/ln(2)=b for n using `bc` where
-      # a=$ALPHABET_SIZE
-      # n=$CHAR_COUNT1_FLOAT
-      # b=$ENTROPY_BIT_COUNT1
-    # Note: `bc` logarithm usage adapted from http://phodd.net/gnu-bc/bcfaq.html#bashlog
-CHAR_COUNT1_FLOAT=$(echo "$ENTROPY_BIT_COUNT1*l($LOG_BASE)/l($ALPHABET_SIZE)" | bc -l)
-    # Note: Float will be of form "21.49744370650136860806". This particular float should be rounded to "22" later.
+    ## Round $char_count_float to next highest integer
+    char_count="$(echo "$char_count_float" | awk '{print ($0-int($0)>0)?int($0)+1:int($0)}')"; # See [3]

 
 

-# Round $CHAR_COUNT1_FLOAT1 up to next highest integer for use as argument in later bash functions.
-    # Note: awk expression from https://bits.mdminhazulhaque.io/linux/round-number-in-bash-script.html
-CHAR_COUNT1=$(echo "$CHAR_COUNT1_FLOAT" | awk '{print ($0-int($0)>0)?int($0)+1:int($0)}') 
-
-# Generate passphrase
-PASS1=$(rpass "$CHAR_COUNT1")
-echo -e "$PASS1"
+    ## Generate and output passphrase
+    echo "$(LC_ALL=C tr -cd "$charset" < /dev/urandom | head -c "$char_count")"; # See [6]
+}; # main program

 
 

+( main "$@" ); # run 'main()' in subshell for 'die()' portability of script as sourced bash function.

 
 #==References==
 #
 
 #==References==
 #


@@ -158,53 +137,53 @@ echo -e "$PASS1"
 #   License: BSD-2-Clause
 #   Date: Accessed: 2021-01-23
 #
 #   License: BSD-2-Clause
 #   Date: Accessed: 2021-01-23
 #

-# - Dependencies: bash, echo, bc, awk, tr, head.
+# - Dependencies: bash, bc, echo, awk, tr, head

 #
 #

-#     - GNU bash, version 5.0.3(1)-release (x86_64-pc-linux-gnu)
-#       Copyright (C) 2019 Free Software Foundation, Inc.
+#     - GNU bash, version 5.1.8(1)-release (x86_64-pc-linux-gnu)
+#       Copyright (C) 2020 Free Software Foundation, Inc.

 #       License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
 #       This is free software; you are free to change and redistribute it.
 #       There is NO WARRANTY, to the extent permitted by law.
 #       License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
 #       This is free software; you are free to change and redistribute it.
 #       There is NO WARRANTY, to the extent permitted by law.

-#    
-#     - echo (GNU coreutils) 8.30
-#       Copyright (C) 2018 Free Software Foundation, Inc.
+#
+#     - bc 1.07.1
+#       Copyright 1991-1994, 1997, 1998, 2000, 2004, 2006, 2008, 2012-2017 Free Software Foundation, Inc.
+#
+#     - echo (GNU coreutils) 8.32
+#       Copyright (C) 2020 Free Software Foundation, Inc.

 #       License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
 #       This is free software: you are free to change and redistribute it.
 #       There is NO WARRANTY, to the extent permitted by law.
 #
 #       Written by Brian Fox and Chet Ramey.
 #       License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
 #       This is free software: you are free to change and redistribute it.
 #       There is NO WARRANTY, to the extent permitted by law.
 #
 #       Written by Brian Fox and Chet Ramey.

-#    
-#     - bc 1.07.1
-#       Copyright 1991-1994, 1997, 1998, 2000, 2004, 2006, 2008, 2012-2017 Free Software Foundation, Inc.
-#    
-#     - GNU Awk 4.2.1, API: 2.0 (GNU MPFR 4.0.2, GNU MP 6.1.2)
-#       Copyright (C) 1989, 1991-2018 Free Software Foundation.
-#    
+#
+#     - GNU Awk 5.1.0, API: 3.0 (GNU MPFR 4.1.0, GNU MP 6.2.1)
+#       Copyright (C) 1989, 1991-2020 Free Software Foundation.
+#       

 #       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 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.
 #       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/.
 #    
 #       You should have received a copy of the GNU General Public License
 #       along with this program. If not, see http://www.gnu.org/licenses/.
 #    

-#     - tr (GNU coreutils) 8.30
-#       Copyright (C) 2018 Free Software Foundation, Inc.
+#     - tr (GNU coreutils) 8.32
+#       Copyright (C) 2020 Free Software Foundation, Inc.

 #       License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
 #       This is free software: you are free to change and redistribute it.
 #       There is NO WARRANTY, to the extent permitted by law.
 #       License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
 #       This is free software: you are free to change and redistribute it.
 #       There is NO WARRANTY, to the extent permitted by law.

-#    
+#       

 #       Written by Jim Meyering.
 #       Written by Jim Meyering.

-#    
-#     - head (GNU coreutils) 8.30
-#       Copyright (C) 2018 Free Software Foundation, Inc.
+#
+#     - head (GNU coreutils) 8.32
+#       Copyright (C) 2020 Free Software Foundation, Inc.

 #       License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
 #       This is free software: you are free to change and redistribute it.
 #       There is NO WARRANTY, to the extent permitted by law.
 #       License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
 #       This is free software: you are free to change and redistribute it.
 #       There is NO WARRANTY, to the extent permitted by law.

-#    
+#       

 #       Written by David MacKenzie and Jim Meyering.
 #       Written by David MacKenzie and Jim Meyering.