jwt-generate: Major rewrite to match jwt-verify

Includes manpage

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

tools/Makefile

@@ -4,7 +4,7 @@ MANSECTION ?= 1
 
 MANPAGE.md = $(PANDOC) --standalone $(PANDOCFLAGS) --to man
 
-MAN_PAGES = jwt-verify.1
+MAN_PAGES = jwt-verify.1 jwt-generate.1
 
 all: $(MAN_PAGES)
 

tools/jwt-generate.1

@@ -0,0 +1,80 @@
+.\" Automatically generated by Pandoc 3.6.1
+.\"
+.TH "JWT\-GENERATE" "1" "" "jwt\-generate User Manual" "LibJWT C Library"
+.SH NAME
+\f[B]jwt\-generate\f[R] \- Generate a JSON Web Token
+.SH SYNOPSIS
+.PP
+\f[B]jwt\-generate\f[R] \f[B][options]\f[R]
+.SH DESCRIPTION
+\f[B]jwt\-generate\f[R] Generates and (optionally) signs a JSON Web
+Token.
+.PP
+By default this will simply encode a JWT.
+If you want a signature, then you must give a JWK key with the
+\f[B]\-k\f[R] option.
+Generating 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
+If \f[B]\-a\f[R] is specified and the key has an \f[B]alg\f[R]
+attribute, they must match.
+.PP
+One token will be generated for each call.
+You can specify claims using the \f[B]\-c\f[R] option.
+By default, \f[B]jwt\-generate\f[R] will add the \f[B]iat\f[R] claim,
+which is \f[B]Issued At\f[R] and is the time in seconds since the
+\f[I]Unix Epcoch\f[R].
+.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 generating the token.
+\f[B]NOTE\f[R] the header will not show the \f[B]typ\f[R] or
+\f[B]alg\f[R] attributes since they do not get added until the final
+step.
+.TP
+\f[B]\-q\f[R], \f[B]\-\-quiet\f[R]
+Do not output anything except for hard errors.
+On success you will only see the token generared.
+.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 signing the token.
+.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.
+.TP
+\f[B]\-c\f[R] \f[I]CLAIM\f[R], \f[B]\-\-claim\f[R]=\f[I]CLAIM\f[R]
+Add a claim to the JWT.
+The format of \f[I]CLAIM\f[R] is
+\f[B]t\f[R]:\f[B]key\f[R]=\f[B]value\f[R] Where \f[B]t\f[R] is the type
+and is one of \f[B]i\f[R] for integer, \f[B]s\f[R] for string, or
+\f[B]b\f[R] for boolean.
+The value for integer must be parseable my \f[B]strtol(3)\f[R].
+For boolean, any value starting with \f[B]0\f[R], \f[B]f\f[R], or
+\f[B]F\f[R] will be interpreted as **false\f[I].
+Anything else will be considered \f[BI]true\f[I].
+They \f[BI]key\f[I] is any \f[R]ASCII* string.
+.TP
+\f[B]\-j\f[R] \f[I]JSON\f[R], \f[B]\-\-json\f[R]=\f[I]JSON\f[R]
+Use JSON string as the payload of the token.
+This will not replace, but be added to the payload.
+The string must be in valid JSON, meaning either a \f[B]{}\f[R] object
+or a \f[B][]\f[R] array.
+.SH BUGS
+See GitHub Issues: \c
+.UR https://github.com/benmcollins/libjwt/issues
+.UE \c
+.SH AUTHOR
+\f[B]jwt\-generate\f[R] was originally written by Jeremy Thien.
+Major rewriting and man page by Ben Collins.

tools/jwt-generate.1.md

@@ -0,0 +1,74 @@
+% JWT-GENERATE(1) jwt-generate User Manual | LibJWT C Library
+
+# NAME
+
+**jwt-generate** - Generate a JSON Web Token
+
+# SYNOPSIS
+
+| **jwt-generate**  **\[options]**
+
+# DESCRIPTION
+
+**jwt-generate** Generates and (optionally) signs a JSON Web Token.
+
+By default this will simply encode a JWT. If you want a signature, then
+you must give a JWK key with the **-k** option. Generating 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.
+
+If **-a** is specified and the key has an **alg** attribute, they must
+match.
+
+One token will be generated for each call. You can specify claims using the
+**-c** option. By default, **jwt-generate** will add the **iat** claim, which
+is **Issued At** and is the time in seconds since the *Unix Epcoch*.
+
+## 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 generating the token. **NOTE** the header will not show the **typ** or
+  **alg** attributes since they do not get added until the final step.
+
+**\-q**, **\-\-quiet**
+  ~ Do not output anything except for hard errors. On success you will only
+  see the token generared.
+
+**\-a** _ALG_, **\-\-algorithm**=_ALG_
+  ~ Specify the algorithm to be used when signing the token.
+
+**\-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.
+
+**\-c** _CLAIM_, **\-\-claim**=_CLAIM_
+  ~ Add a claim to the JWT. The format of _CLAIM_ is **t**:**key**=**value**
+  Where **t** is the type and is one of **i** for integer, **s** for string,
+  or **b** for boolean. The value for integer must be parseable my **strtol(3)**.
+  For boolean, any value starting with **0**, **f**, or **F** will be interpreted
+  as **false*. Anything else will be considered **true**. They **key** is any
+  *ASCII* string.
+
+**\-j** _JSON_, **\-\-json**=_JSON_
+  ~ Use JSON string as the payload of the token. This will not replace, but be added
+  to the payload. The string must be in valid JSON, meaning either a **{}** object
+  or a **[]** array.
+
+# BUGS
+
+See GitHub Issues: <https://github.com/benmcollins/libjwt/issues>
+
+# AUTHOR
+
+**jwt-generate** was originally written by Jeremy Thien. Major rewriting and man
+page by Ben Collins.