Merge pull request #85 from DrDaveD/v1.20

Improve httokensh, add man pages, update to v1.20

Author: DrDaveD

Makefile

@@ -1,7 +1,9 @@
 VERSION := $(shell sed -n 's/^Version: //p' htgettoken.spec)
 
-htgettoken.html: htgettoken.1
-	groff -mandoc -Thtml htgettoken.1 >htgettoken.html
+man: htgettoken.html htdestroytoken.html htdecodetoken.html httokensh.html
+
+%.html : %.1
+	groff -mandoc -Thtml $< >$@
 
 # For koji builds
 sources:

README.md

@@ -29,10 +29,17 @@ submitted to
 for a description of htgettoken, htvault-config, and their HTCondor
 integration.
 
-## httokendecode
+## additional commands
 
-An additional small script called `httokendecode` is bundled with
-`htgettoken`.  It decodes JSON Web Tokens that it finds either according
-to a given filename (`-` for stdin) or based on the
-[WLCG Bearer Token Discovery](https://zenodo.org/record/3937438#.YUDw7aBOlTY)
-standard if no filename is given.
+A few additional helpful commands are bundled with htgettoken.
+Click on each one below to see their man pages.
+
+- [htdecodetoken/httokendecode](https://htmlpreview.github.io/?https://github.com/fermitools/htgettoken/blob/master/htdecodetoken.html) --
+  decodes JSON Web Tokens that it finds either according to a given
+  filename or based on the
+  [WLCG Bearer Token Discovery](https://zenodo.org/record/3937438#.YUDw7aBOlTY)
+  standard if no filename is given.
+- [htdestroytoken](https://htmlpreview.github.io/?https://github.com/fermitools/htgettoken/blob/master/htdestroytoken.html) --
+  removes bearer and vault tokens
+- [httokensh](https://htmlpreview.github.io/?https://github.com/fermitools/htgettoken/blob/master/httokensh.html) --
+  keeps the bearer token renewed as long as a command it starts runs

httokendecode renamed to htdecodetoken

@@ -6,7 +6,7 @@
 
 usage()
 {
-    echo 'Usage: httokendecode [-a] [-H] [file]'
+    echo 'Usage: htdecodetoken [-a] [-H] [file]'
     echo
     echo 'Decodes a JSON Web Token'
     echo '  -a: show algorithm portion of JWT'

htdecodetoken.1

@@ -0,0 +1,53 @@
+.TH htdecodetoken 1
+.SH NAME
+htdecodetoken \- decode JSON Web Token
+
+.SH SYNOPSIS
+.B htdecodetoken
+[-a] [-H] [file]
+.PP
+.B httokendecode
+[-a] [-H] [file]
+
+.SH DESCRIPTION
+.B htdecodetoken
+(also known as
+.BR httokendecode )
+decodes a JSON Web Token (JWT) and prints the JSON output to standard
+output.
+If a file name provided is "-" it reads the JWT from standard input.
+If no file name is given, it follows the WLCG Bearer Token Discovery
+protocol, which is to first try reading the token from $BEARER_TOKEN,
+next reading the token from the file defined in $BEARER_TOKEN_FILE,
+and finally reading from a file called "bt_u`id -u`" either in
+$XDG_RUNTIME_DIR if it is defined or else in /tmp.
+
+If the
+.B scitokens-verify
+command is found in $PATH, then after decode that command is also run
+and will print an error if the JWT is not found to be currently valid.
+
+.SH OPTIONS
+The following options are recognized:
+.PP
+.TP
+.B \-a
+Additionally shows the algorithm portion of the JWT in a separate JSON
+structure printed first to standard output.
+.TP
+.B \-H
+Prints scopes (specifically "nbf", "iat", and "exp")
+that are normally shown in Epoch time
+(seconds since the beginning of 1970) 
+instead in the human-readable form used by default by the
+.B date
+command.
+
+.SH AUTHOR
+Dave Dykstra
+
+.SH COPYRIGHT
+Copyright \(co 2023 Fermi National Accelerator Laboratory
+
+.SH "SEE ALSO"
+htgettoken(1)

htdecodetoken.html

@@ -0,0 +1,38 @@
+.TH htdestroytoken 1
+.SH NAME
+htdestroytoken \- remove bearer and vault tokens
+
+.SH SYNOPSIS
+.B htdestroytoken
+[-q]
+
+.SH DESCRIPTION
+.B htdestroytoken
+removes a bearer token found by WLCG Bearer Token Discovery and also
+removes a vault token found in the default location used by 
+.BR htgettoken.
+
+Note that the vault server additionally caches bearer tokens, so the
+next time that
+.B htgettoken
+is run the same bearer token might be returned unless a new one is 
+forced to be retrieved with either oidc authentication or with an
+htgettoken
+.I \-\-minsecs
+option.
+
+.SH OPTIONS
+The following options are recognized:
+.PP
+.TP
+.BR \-q
+Do removals silently
+
+.SH AUTHOR
+Dave Dykstra
+
+.SH COPYRIGHT
+Copyright \(co 2023 Fermi National Accelerator Laboratory
+
+.SH "SEE ALSO"
+htgettoken(1), htdecodetoken(1)