From c27495bf1fe278d5e149edefda0bedfbb5098cd1 Mon Sep 17 00:00:00 2001 From: nginsburg Date: Thu, 3 Oct 2019 10:00:13 -0400 Subject: [PATCH] adding generate_commands helper script, it generates 90% of the Commands.rst file, updating other docs --- docs/generate_commands.sh | 32 +++++++++ docs/source/Commands.rst | 140 ++++++++++++++++++++++++++++++-------- docs/source/Python2.rst | 2 +- docs/source/Setup.rst | 2 + docs/source/conf.py | 4 +- 5 files changed, 150 insertions(+), 30 deletions(-) create mode 100755 docs/generate_commands.sh diff --git a/docs/generate_commands.sh b/docs/generate_commands.sh new file mode 100755 index 0000000..aae7f21 --- /dev/null +++ b/docs/generate_commands.sh @@ -0,0 +1,32 @@ +#!/bin/bash + +commands="$(python ../pkpass.py -h | grep '{.*}' | head -1 | tr -d '[:space:]{}')" +IFS="," + +cat << EOF > /tmp/test +Commands +======== +The Commands can be listed out by passing the help flag to pkpass as seen below + +EOF + +{ + echo ".. code-block:: bash + +" + python ../pkpass.py -h | awk '{ print " "$0 }' +} >> /tmp/test + +for com in $commands; do + { +echo " +${com^}" +awk "BEGIN{for(c=0;c<${#com};c++) printf \"-\"}" +echo " +Blurb + +.. code-block:: bash +" + python ../pkpass.py "$com" -h | awk '{ print " "$0 }' +} >> /tmp/test +done diff --git a/docs/source/Commands.rst b/docs/source/Commands.rst index fb359b9..307544f 100644 --- a/docs/source/Commands.rst +++ b/docs/source/Commands.rst @@ -4,16 +4,18 @@ The Commands can be listed out by passing the help flag to pkpass as seen below .. code-block:: bash - python pkpass.py -h + usage: pkpass.py [-h] [--config CONFIG] - {clip,create,delete,distribute,export,generate,import,list,listrecipients,recover,rename,show,update} + {card,clip,create,delete,distribute,export,generate,import,interpreter,list,listrecipients,recover,rename,show,update} ... Public Key Password Manager positional arguments: - {clip,create,delete,distribute,export,generate,import,list,listrecipients,recover,rename,show,update} + {card,clip,create,delete,distribute,export,generate,import,interpreter,list,listrecipients,recover,rename,show,update} sub-commands + card List the available cards and which card you have + selected clip Copy a password to clipboard create Create a new password entry and encrypt it for yourself @@ -25,6 +27,7 @@ The Commands can be listed out by passing the help flag to pkpass as seen below generate Generate a new password entry and encrypt it for yourself import Import passwords that you have saved to a file + interpreter Interactive mode for pkpass list List passwords you have access to listrecipients List the recipients that pkpass knows about recover Recover a password that has been distributed using @@ -38,6 +41,24 @@ The Commands can be listed out by passing the help flag to pkpass as seen below --config CONFIG Path to a PKPass configuration file. Defaults to '~/.pkpassrc' +Card +---- +Card lists out available card slots and the currently chosen one + +.. code-block:: bash + + usage: pkpass.py card [-h] [--cabundle CABUNDLE] [--certpath CERTPATH] + [-i IDENTITY] [-q] [-v] + + optional arguments: + -h, --help show this help message and exit + --cabundle CABUNDLE Path to CA certificate bundle file + --certpath CERTPATH Path to directory containing public keys. Certificates + must end in '.cert' + -i IDENTITY, --identity IDENTITY + Override identity of user running the program + -q, --quiet quiet output (show errors only) + -v, --verbose verbose output (repeat for increased verbosity) Clip ---- @@ -47,8 +68,8 @@ The intent of clip is to copy a password to your clipboard on the unlock event, usage: pkpass.py clip [-h] [--cabundle CABUNDLE] [-c CARD_SLOT] [--certpath CERTPATH] [-i IDENTITY] [--keypath KEYPATH] - [--nopassphrase] [--noverify] [--pwstore PWSTORE] - [--stdin] [-t TIME] + [--nopassphrase] [--noverify] [--pwstore PWSTORE] [-q] + [--stdin] [-t TIME] [-v] [pwname] positional arguments: @@ -72,9 +93,11 @@ The intent of clip is to copy a password to your clipboard on the unlock event, --pwstore PWSTORE, --srcpwstore PWSTORE Path to the source password store. Defaults to "./passwords" + -q, --quiet quiet output (show errors only) --stdin Take all password input from stdin instead of from a user input prompt -t TIME, --time TIME Number of seconds to keep password in paste buffer + -v, --verbose verbose output (repeat for increased verbosity) Create ------ @@ -86,7 +109,7 @@ Create is used to create a password in the configured password repository [--certpath CERTPATH] [-e ESCROW_USERS] [-i IDENTITY] [--keypath KEYPATH] [-m MIN_ESCROW] [--noescrow] [--nopassphrase] [--nosign] [--overwrite] - [--pwstore PWSTORE] [--stdin] + [--pwstore PWSTORE] [-q] [--stdin] [-v] [pwname] positional arguments: @@ -120,8 +143,10 @@ Create is used to create a password in the configured password repository --pwstore PWSTORE, --srcpwstore PWSTORE Path to the source password store. Defaults to "./passwords" + -q, --quiet quiet output (show errors only) --stdin Take all password input from stdin instead of from a user input prompt + -v, --verbose verbose output (repeat for increased verbosity) Delete ------ @@ -132,8 +157,8 @@ This is mostly just to allow testing to be a little faster usage: pkpass.py delete [-h] [--cabundle CABUNDLE] [-c CARD_SLOT] [--certpath CERTPATH] [-i IDENTITY] - [--keypath KEYPATH] [--nopassphrase] [--overwrite] - [--pwstore PWSTORE] [--stdin] + [--keypath KEYPATH] [--overwrite] [--pwstore PWSTORE] + [-q] [--stdin] [-v] [pwname] positional arguments: @@ -151,14 +176,14 @@ This is mostly just to allow testing to be a little faster Override identity of user running the program --keypath KEYPATH Path to directory containing private keys. Keys must end in '.key' - --nopassphrase, --nopin - Do not prompt for a pin/passphrase --overwrite Overwrite a password that already exists --pwstore PWSTORE, --srcpwstore PWSTORE Path to the source password store. Defaults to "./passwords" + -q, --quiet quiet output (show errors only) --stdin Take all password input from stdin instead of from a user input prompt + -v, --verbose verbose output (repeat for increased verbosity) Distribute ---------- @@ -173,8 +198,8 @@ This function will confirm password list is valid even if only one password matc [--certpath CERTPATH] [-e ESCROW_USERS] [-g GROUPS] [-i IDENTITY] [--keypath KEYPATH] [-m MIN_ESCROW] [--noescrow] [--nopassphrase] - [--nosign] [--pwstore PWSTORE] [--stdin] - [-u USERS] + [--nosign] [--pwstore PWSTORE] [-q] [--stdin] + [-u USERS] [-v] [pwname] positional arguments: @@ -209,10 +234,12 @@ This function will confirm password list is valid even if only one password matc --pwstore PWSTORE, --srcpwstore PWSTORE Path to the source password store. Defaults to "./passwords" + -q, --quiet quiet output (show errors only) --stdin Take all password input from stdin instead of from a user input prompt -u USERS, --users USERS Comma seperated list of recipients + -v, --verbose verbose output (repeat for increased verbosity) Export ------ @@ -222,7 +249,8 @@ Export allows the current user to migrate all his passwords to one file, this te usage: pkpass.py export [-h] [--cabundle CABUNDLE] [-c CARD_SLOT] [--certpath CERTPATH] [--dstpwstore DSTPWSTORE] - [-i IDENTITY] [--nocrypto] [--nopassphrase] [--stdin] + [-i IDENTITY] [--nocrypto] [--nopassphrase] [-q] + [--stdin] [-v] [pwfile] positional arguments: @@ -242,8 +270,10 @@ Export allows the current user to migrate all his passwords to one file, this te --nocrypto Do not use a password for import/export files --nopassphrase, --nopin Do not prompt for a pin/passphrase + -q, --quiet quiet output (show errors only) --stdin Take all password input from stdin instead of from a user input prompt + -v, --verbose verbose output (repeat for increased verbosity) Generate -------- @@ -257,8 +287,8 @@ rules_map: '{"default": "[^\\s]{20}", "sec": "([a-z]|[A-Z]|[0-9]){15}"}' [--certpath CERTPATH] [-e ESCROW_USERS] [-i IDENTITY] [--keypath KEYPATH] [-m MIN_ESCROW] [--noescrow] [--nopassphrase] [--nosign] - [--overwrite] [--pwstore PWSTORE] [-R RULES] - [--rules-map RULES_MAP] [--stdin] + [--overwrite] [--pwstore PWSTORE] [-q] [-R RULES] + [--rules-map RULES_MAP] [--stdin] [-v] [pwname] positional arguments: @@ -292,6 +322,7 @@ rules_map: '{"default": "[^\\s]{20}", "sec": "([a-z]|[A-Z]|[0-9]){15}"}' --pwstore PWSTORE, --srcpwstore PWSTORE Path to the source password store. Defaults to "./passwords" + -q, --quiet quiet output (show errors only) -R RULES, --rules RULES Key of rules to use from provided rules map --rules-map RULES_MAP @@ -299,7 +330,7 @@ rules_map: '{"default": "[^\\s]{20}", "sec": "([a-z]|[A-Z]|[0-9]){15}"}' passwords --stdin Take all password input from stdin instead of from a user input prompt - + -v, --verbose verbose output (repeat for increased verbosity) Import ------ @@ -309,7 +340,8 @@ Import allows a user to take an exported password file and import them into a ne usage: pkpass.py import [-h] [--cabundle CABUNDLE] [-c CARD_SLOT] [--certpath CERTPATH] [--dstpwstore DSTPWSTORE] - [-i IDENTITY] [--nocrypto] [--nopassphrase] [--stdin] + [-i IDENTITY] [--nocrypto] [--nopassphrase] [-q] + [--stdin] [-v] [pwfile] positional arguments: @@ -329,9 +361,48 @@ Import allows a user to take an exported password file and import them into a ne --nocrypto Do not use a password for import/export files --nopassphrase, --nopin Do not prompt for a pin/passphrase + -q, --quiet quiet output (show errors only) --stdin Take all password input from stdin instead of from a user input prompt + -v, --verbose verbose output (repeat for increased verbosity) + +Interpreter +----------- +Creates an interactive session, the default behavior of pkpass if no arguments are passed +.. code-block:: bash + + usage: pkpass.py interpreter [-h] [--cabundle CABUNDLE] [-c CARD_SLOT] + [--certpath CERTPATH] [--connect CONNECT] + [-e ESCROW_USERS] [-g GROUPS] [-i IDENTITY] + [--keypath KEYPATH] [-m MIN_ESCROW] + [--pwstore PWSTORE] [-q] [-v] + + optional arguments: + -h, --help show this help message and exit + --cabundle CABUNDLE Path to CA certificate bundle file + -c CARD_SLOT, --card_slot CARD_SLOT + The slot number of the card that should be used + --certpath CERTPATH Path to directory containing public keys. Certificates + must end in '.cert' + --connect CONNECT Connection string for the api to retrieve certs + -e ESCROW_USERS, --escrow_users ESCROW_USERS + Escrow users list is a comma sepearated list of + recovery users that each get part of a key + -g GROUPS, --groups GROUPS + Comma seperated list of recipient groups + -i IDENTITY, --identity IDENTITY + Override identity of user running the program + --keypath KEYPATH Path to directory containing private keys. Keys must + end in '.key' + -m MIN_ESCROW, --min_escrow MIN_ESCROW + Minimum number of users required to unlock escrowed + password + --pwstore PWSTORE, --srcpwstore PWSTORE + Path to the source password store. Defaults to + "./passwords" + -q, --quiet quiet output (show errors only) + -v, --verbose verbose output (repeat for increased verbosity) List ---- @@ -340,23 +411,27 @@ List shows all passwords available to a given user .. code-block:: bash usage: pkpass.py list [-h] [--cabundle CABUNDLE] [--certpath CERTPATH] - [-i IDENTITY] [--pwstore PWSTORE] [-r] [--stdin] + [-f FILTER] [-i IDENTITY] [--pwstore PWSTORE] [-q] [-r] + [--stdin] [-v] optional arguments: -h, --help show this help message and exit --cabundle CABUNDLE Path to CA certificate bundle file --certpath CERTPATH Path to directory containing public keys. Certificates must end in '.cert' + -f FILTER, --filter FILTER + Reduce output of commands to matching items -i IDENTITY, --identity IDENTITY Override identity of user running the program --pwstore PWSTORE, --srcpwstore PWSTORE Path to the source password store. Defaults to "./passwords" + -q, --quiet quiet output (show errors only) -r, --recovery Work with passwords distributed through escrow functionality --stdin Take all password input from stdin instead of from a user input prompt - + -v, --verbose verbose output (repeat for increased verbosity) Listrecipients -------------- @@ -365,18 +440,22 @@ List the recipients that pkpass knows about .. code-block:: bash usage: pkpass.py listrecipients [-h] [--cabundle CABUNDLE] - [--certpath CERTPATH] [-i IDENTITY] [--stdin] + [--certpath CERTPATH] [-f FILTER] + [-i IDENTITY] [-q] [--stdin] [-v] optional arguments: -h, --help show this help message and exit --cabundle CABUNDLE Path to CA certificate bundle file --certpath CERTPATH Path to directory containing public keys. Certificates must end in '.cert' + -f FILTER, --filter FILTER + Reduce output of commands to matching items -i IDENTITY, --identity IDENTITY Override identity of user running the program + -q, --quiet quiet output (show errors only) --stdin Take all password input from stdin instead of from a user input prompt - + -v, --verbose verbose output (repeat for increased verbosity) Recover ------- @@ -387,7 +466,8 @@ This requires password owners to have created escrow users. Each necessary escro usage: pkpass.py recover [-h] [--cabundle CABUNDLE] [--certpath CERTPATH] [-e ESCROW_USERS] [-i IDENTITY] [--keypath KEYPATH] - [-m MIN_ESCROW] [--nosign] [--pwstore PWSTORE] + [-m MIN_ESCROW] [--nosign] [--pwstore PWSTORE] [-q] + [-v] optional arguments: -h, --help show this help message and exit @@ -409,7 +489,8 @@ This requires password owners to have created escrow users. Each necessary escro --pwstore PWSTORE, --srcpwstore PWSTORE Path to the source password store. Defaults to "./passwords" - + -q, --quiet quiet output (show errors only) + -v, --verbose verbose output (repeat for increased verbosity) Rename ------ @@ -420,7 +501,7 @@ This renames a password in the given repository usage: pkpass.py rename [-h] [--cabundle CABUNDLE] [-c CARD_SLOT] [--certpath CERTPATH] [-i IDENTITY] [--keypath KEYPATH] [--nopassphrase] [--overwrite] - [--pwstore PWSTORE] [--stdin] + [--pwstore PWSTORE] [-q] [--stdin] [-v] [pwname] [rename] positional arguments: @@ -445,9 +526,10 @@ This renames a password in the given repository --pwstore PWSTORE, --srcpwstore PWSTORE Path to the source password store. Defaults to "./passwords" + -q, --quiet quiet output (show errors only) --stdin Take all password input from stdin instead of from a user input prompt - + -v, --verbose verbose output (repeat for increased verbosity) Show ---- @@ -458,7 +540,7 @@ This unlocks a password and displays it on stdout usage: pkpass.py show [-h] [-a] [--cabundle CABUNDLE] [-c CARD_SLOT] [--certpath CERTPATH] [-i IDENTITY] [-I] [--keypath KEYPATH] [--nopassphrase] [--noverify] - [--pwstore PWSTORE] [-r] [--stdin] + [--pwstore PWSTORE] [-q] [-r] [--stdin] [-v] [pwname] positional arguments: @@ -486,10 +568,12 @@ This unlocks a password and displays it on stdout --pwstore PWSTORE, --srcpwstore PWSTORE Path to the source password store. Defaults to "./passwords" + -q, --quiet quiet output (show errors only) -r, --recovery Work with passwords distributed through escrow functionality --stdin Take all password input from stdin instead of from a user input prompt + -v, --verbose verbose output (repeat for increased verbosity) Update ------ @@ -501,7 +585,7 @@ This changes a password value and redistributes the password to the recipients [--certpath CERTPATH] [-e ESCROW_USERS] [-i IDENTITY] [--keypath KEYPATH] [-m MIN_ESCROW] [--noescrow] [--nopassphrase] [--nosign] [--overwrite] - [--pwstore PWSTORE] [--stdin] + [--pwstore PWSTORE] [-q] [--stdin] [-v] [pwname] positional arguments: @@ -535,5 +619,7 @@ This changes a password value and redistributes the password to the recipients --pwstore PWSTORE, --srcpwstore PWSTORE Path to the source password store. Defaults to "./passwords" + -q, --quiet quiet output (show errors only) --stdin Take all password input from stdin instead of from a user input prompt + -v, --verbose verbose output (repeat for increased verbosity) diff --git a/docs/source/Python2.rst b/docs/source/Python2.rst index cb33a6b..734f504 100644 --- a/docs/source/Python2.rst +++ b/docs/source/Python2.rst @@ -1,3 +1,3 @@ Python 2 support ================ -We will support python2 until the end of the year, this tool was originally written in python2; and should also work with python3. +We will support python2 until the end of the year 2019, this tool was originally written in python2; and should also work with python3. diff --git a/docs/source/Setup.rst b/docs/source/Setup.rst index 117371e..74dc511 100644 --- a/docs/source/Setup.rst +++ b/docs/source/Setup.rst @@ -1,5 +1,7 @@ Setup ===== +Brew install is available via: + | ``brew install olcf/tap/pkpass`` You may clone the pkpass.py tool like this: | ``git clone https://github.com/olcf/pkpass.git`` diff --git a/docs/source/conf.py b/docs/source/conf.py index 5925ea1..b3ee765 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,9 +23,9 @@ author = u'Noah Ginsburg, Ryan Adamson' # The short X.Y version -version = u'1.0.3' +version = u'2.1.5' # The full version, including alpha/beta/rc tags -release = u'1.0.3' +release = u'2.1.5' # -- General configuration ---------------------------------------------------