chore(user/zeropad.sh):Add some comments

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

#!/bin/bash
# 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
#    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
#    the Free Software Foundation, either version 3 of the License, or
#    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.
#
#    A copy of the GNU General Public License may be found at
#    <https://www.gnu.org/licenses/>.

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]

    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")

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

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

    ## Check entropy_bit_count
    pattern="^[0-9]+$";
    if ! [[ $entropy_bit_count =~ $pattern ]] ; then die "ERROR:Not an integer:$entropy_bit_count"; fi; # See [2]

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

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

    ## 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==
#
# - How to echo a string as stderr instead of stdout.
#   https://stackoverflow.com/a/2990533
#   Author: James Roth
#   Date: 2010-06-07T14:52Z
#   Date Accessed: 2020-01-20
#
# - How to check if script argument exists or not.
#   https://stackoverflow.com/a/6482403
#   Author: phoxix
#   Date: 2011-06-26T05:55Z
#   Date Accessed: 2020-01-20
#
# - How to check that a string is an integer using regular expression test.
#   https://stackoverflow.com/a/806923
#   Author: Charles Duffy
#   Date: 2009-04-30T13:32Z
#   Date Accessed: 2020-01-20
#
# - How to use `bc` to calculate logarithms in Bash
#   http://phodd.net/gnu-bc/bcfaq.html#bashlog
#   Author: unknown
#   Date Accessed: 2020-01-20
#
# - How to use `awk` to convert and round up a float to an integer.
#   https://bits.mdminhazulhaque.io/linux/round-number-in-bash-script.html
#   Author: Md. Minhazul Haque
#   Date: 2015-01-09
#   Date Accessed: 2020-01-20
#
# - How to use `/dev/urandom`, `tr`, and `head` to generate a random password in Bash.
#   https://www.thegeekstuff.com/2010/04/unix-bash-function-examples/
#   Author: SASIKALA, Ramesh Natarajan
#   Date: 2010-04-21
#   Date Accessed: 2020-01-20
#
# - Bech32 base32 charset
#   https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki
#   Author: Pieter Wuille <pieter.wuille@gmail.com>
#   Date: 2017-03-20
#   License: BSD-2-Clause
#   Date: Accessed: 2021-01-23
#
# - Dependencies: bash, bc, echo, awk, tr, head
#
#     - 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.
#
#     - 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.
#
#     - 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 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/.
#    
#     - 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.
#       
#       Written by Jim Meyering.
#
#     - 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.
#       
#       Written by David MacKenzie and Jim Meyering.