tools: Rewrite jwt-verify (was jwtauth) and create man page

- Using pandoc for md to man
- Lots of pretty output for jwt-verify
- Cleaned up jwt-verify code
- jwt-verify now can take tokens on stdin

Signed-off-by: Ben Collins <[email protected]>

CMakeLists.txt

@@ -33,7 +33,6 @@ if (NOT DEFINED WITH_GNUTLS)
 endif()
 
 option(WITH_GNUTLS "Whether to use GnuTLS (default is auto detect)" ON)
-option(WITH_EXAMPLES "Whether to build the example programs (default is OFF)" OFF)
 option(WITH_TESTS "Whether to build and run the testsuite (default is ON)" ON)
 
 # Need at least one of these
@@ -111,17 +110,6 @@ list(APPEND JWT_SOURCES
      libjwt/openssl/jwk-parse.c
      libjwt/openssl/sign-verify.c)
 
-function(jwt_add_extra)
-	set(oneValueArgs NAME SRC DIR)
-	cmake_parse_arguments(Extra "" "${oneValueArgs}" "" ${ARGN})
-
-	add_executable(${Extra_NAME} ${Extra_SRC})
-	target_link_libraries(${Extra_NAME} PRIVATE jwt)
-	set_target_properties(${Extra_NAME} PROPERTIES
-		RUNTIME_OUTPUT_DIRECTORY
-		"${CMAKE_BINARY_DIR}/${Extra_DIR}")
-endfunction()
-
 function(jwt_add_tool)
 	set(oneValueArgs NAME SRC DIR)
 	cmake_parse_arguments(Tool "" "${oneValueArgs}" "" ${ARGN})
@@ -136,19 +124,14 @@ function(jwt_add_tool)
 		RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
 endfunction()
 
-if (WITH_EXAMPLES)
-	jwt_add_extra(NAME jwtauth
-		      SRC examples/main-auth.c
-		      DIR examples)
-	jwt_add_extra(NAME jwtgen
-                      SRC examples/main-gen.c
-                      DIR examples)
-endif()
-
+jwt_add_tool(NAME jwt-verify
+	     SRC tools/jwt-verify.c)
+jwt_add_tool(NAME jwt-generate
+	     SRC tools/jwt-generate.c)
 jwt_add_tool(NAME jwk2key
-	      SRC tests/keys/jwks/jwk2key.c)
+	     SRC tools/jwk2key.c)
 jwt_add_tool(NAME key2jwk
-              SRC tests/keys/jwks/key2jwk.c)
+	     SRC tools/key2jwk.c)
 
 # We need one of the things above to even work
 if (NOT HAVE_CRYPTO)
@@ -218,9 +201,13 @@ if (DOXYGEN_FOUND)
 
 	install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen-doc/man/man3/
 		DESTINATION ${CMAKE_INSTALL_MANDIR}/man3
-		FILES_MATCHING PATTERN "man3/J*.3"
+		FILES_MATCHING PATTERN "man3/JW*.3"
 		PATTERN "man3/jw*.3")
 
+	install(DIRECTORY ${CMAKE_SOURCE_DIR}/tools/
+		DESTINATION ${CMAKE_INSTALL_MANDIR}/man1
+		FILES_MATCHING PATTERN "*.1")
+
 	install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen-doc/html/
 		DESTINATION  ${CMAKE_INSTALL_DOCDIR}/html/)
 endif()
@@ -243,9 +230,11 @@ function(jwt_add_test)
 	set(oneValueArgs NAME)
 	cmake_parse_arguments(LibTest "" "${oneValueArgs}" "" ${ARGN})
 
-	jwt_add_extra(NAME ${LibTest_NAME}
-                      SRC tests/${LibTest_NAME}.c
-                      DIR tests)
+	add_executable(${LibTest_NAME} tests/${LibTest_NAME}.c)
+	target_link_libraries(${LibTest_NAME} PRIVATE jwt)
+	set_target_properties(${LibTest_NAME} PROPERTIES
+			RUNTIME_OUTPUT_DIRECTORY
+			${CMAKE_BINARY_DIR}/tests)
 
 	target_link_libraries(${LibTest_NAME} PRIVATE PkgConfig::CHECK)
 	add_test(NAME ${LibTest_NAME} COMMAND /bin/bash -c

tools/Makefile

@@ -0,0 +1,15 @@
+PANDOC ?= pandoc
+
+MANSECTION ?= 1
+
+MANPAGE.md = $(PANDOC) --standalone $(PANDOCFLAGS) --to man
+
+MAN_PAGES = jwt-verify.1
+
+all: $(MAN_PAGES)
+
+%.$(MANSECTION): %.$(MANSECTION).md
+	$(MANPAGE.md) $< -o $@
+
+clean:
+	rm -f $(MAN_PAGES)

tools/jwt-verify.1

@@ -0,0 +1,61 @@
+.\" Automatically generated by Pandoc 3.6.1
+.\"
+.TH "JWT\-VERIFY" "1" "" "jwt\-verify User Manual" "LibJWT C Library"
+.SH NAME
+\f[B]jwt\-verify\f[R] \- Verify a JSON Web Token
+.SH SYNOPSIS
+.PP
+\f[B]jwt\-verify\f[R] \f[B][options]\f[R] \f[I]token\f[R] \&...
+.PD 0
+.P
+.PD
+\f[B]jwt\-verify\f[R] \f[B][options]\f[R] \- < \f[I]token\f[R]
+.SH DESCRIPTION
+\f[B]jwt\-verify\f[R] Decodes and (optionally) verifies the signature of
+a JSON Web Token.
+.PP
+By default, the token(s) will be decoded and verified.
+If there is a signature block on the JWT, then you must give a JWK key
+with the \f[B]\-k\f[R] option.
+Verifying a signature requires specifying the algorithm, so it must
+either be in the key file (as the \f[B]alg\f[R] attribute), or passed on
+the command line with the \f[B]\-a\f[R] argument.
+.PP
+\f[B]jwt\-verify\f[R] will not assume the alogirthm from the JWT itself
+(for security reasons), however, the algorithm in the JWT must match
+what you provide to \f[B]jwt\-verify\f[R].
+.PP
+Tokens may be passed on the command line, after any options, separated
+by spaces, or passed via \f[B]stdin\f[R], one per line.
+To use \f[B]stdin\f[R], you must pass \f[B]\-\f[R] as the last and only
+argument after any options.
+.SS Options
+.TP
+\f[B]\-h\f[R], \f[B]\-\-help\f[R]
+Show common options and quit.
+.TP
+\f[B]\-l\f[R], \f[B]\-\-list\f[R]
+List all supported algorithms that can be passed to the \f[B]\-a\f[R]
+option and quit.
+.TP
+\f[B]\-v\f[R], \f[B]\-\-verbose\f[R]
+Show the contents of the \f[I]HEADER\f[R] and \f[I]PAYLOAD\f[R] of the
+JWT in addition to verifying the token.
+.TP
+\f[B]\-a\f[R] \f[I]ALG\f[R], \f[B]\-\-algorithm\f[R]=\f[I]ALG\f[R]
+Specify the algorithm to be used when verifying the signature block of
+any tokens passed to the program.
+See \f[B]\-l\f[R] for values of \f[I]ALG\f[R].
+.TP
+\f[B]\-k\f[R] \f[I]FILE\f[R], \f[B]\-\-key\f[R]=\f[I]FILE\f[R]
+Path to a file containing a key in JSON Web Key format.
+If your keys are in PEM or DER (or some other common format that
+\f[I]OpenSSL\f[R] understands), then you can convert it to a JWK with
+the \f[B]key2jwk(1)\f[R] tool.
+.SH BUGS
+See GitHub Issues: \c
+.UR https://github.com/benmcollins/libjwt/issues
+.UE \c
+.SH AUTHOR
+\f[B]jwt\-verify\f[R] was originally written by Jeremy Thien.
+Major rewriting and man page by Ben Collins.

tools/jwt-verify.1.md

@@ -0,0 +1,60 @@
+% JWT-VERIFY(1) jwt-verify User Manual | LibJWT C Library
+
+# NAME
+
+**jwt-verify** - Verify a JSON Web Token
+
+# SYNOPSIS
+
+| **jwt-verify**  **\[options]** _token_ ...
+| **jwt-verify**  **\[options]** - < _token_
+
+# DESCRIPTION
+
+**jwt-verify** Decodes and (optionally) verifies the signature
+of a JSON Web Token.
+
+By default, the token(s) will be decoded and verified. If there is a
+signature block on the JWT, then you must give a JWK key with the
+**-k** option. Verifying a signature requires specifying the algorithm,
+so it must either be in the key file (as the **alg** attribute), or
+passed on the command line with the **-a** argument.
+
+**jwt-verify** will not assume the alogirthm from the JWT itself (for
+security reasons), however, the algorithm in the JWT must match what
+you provide to **jwt-verify**.
+
+Tokens may be passed on the command line, after any options, separated
+by spaces, or passed via **stdin**, one per line. To use **stdin**, you
+must pass **-** as the last and only argument after any options.
+
+## Options
+
+**\-h**, **\-\-help**
+  ~ Show common options and quit.
+
+**\-l**, **\-\-list**
+  ~ List all supported algorithms that can be passed to the **-a** option
+  and quit.
+
+**\-v**, **\-\-verbose**
+  ~ Show the contents of the _HEADER_ and _PAYLOAD_ of the JWT in addition
+  to verifying the token.
+
+**\-a** _ALG_, **\-\-algorithm**=_ALG_
+  ~ Specify the algorithm to be used when verifying the signature block of
+  any tokens passed to the program. See **-l** for values of _ALG_.
+
+**\-k** _FILE_, **\-\-key**=_FILE_
+  ~ Path to a file containing a key in JSON Web Key format. If your keys are
+  in PEM or DER (or some other common format that _OpenSSL_ understands), then
+  you can convert it to a JWK with the **key2jwk(1)** tool.
+
+# BUGS
+
+See GitHub Issues: <https://github.com/benmcollins/libjwt/issues>
+
+# AUTHOR
+
+**jwt-verify** was originally written by Jeremy Thien. Major rewriting and man
+page by Ben Collins.