tools/jwe-encrypt.1

.\" Automatically generated by Pandoc 3.9.0.2
.\"
.TH "JWE\-ENCRYPT" "1" "" "jwe\-encrypt User Manual" "LibJWT C Library"
.SH NAME
\f[B]jwe\-encrypt\f[R] \- Encrypt content into a JSON Web Encryption
(JWE) token
.SH SYNOPSIS
.PP
\f[B]jwe\-encrypt\f[R] \f[B]\-k\f[R] \f[I]KEY\f[R] \f[B]\-a\f[R]
\f[I]ALG\f[R] \f[B]\-e\f[R] \f[I]ENC\f[R] \f[B][options]\f[R]
.SH DESCRIPTION
\f[B]jwe\-encrypt\f[R] encrypts content into a JWE token.
By default it produces the Compact Serialization; \f[B]\-f\f[R] selects
a JSON Serialization instead.
.PP
A JWE requires two algorithms: a key management algorithm (the
\f[B]alg\f[R] header, given with \f[B]\-a\f[R]) that determines how the
Content Encryption Key (CEK) is produced for the recipient, and a
content encryption algorithm (the \f[B]enc\f[R] header, given with
\f[B]\-e\f[R]) that performs the authenticated encryption of the
plaintext.
.PP
The recipient key is supplied as a JSON Web Key with \f[B]\-k\f[R].
See key2jwk(1) to convert a PEM or DER key to JWK format.
.PP
The plaintext is encrypted once with a single CEK.
Additional recipients may be added with \f[B]\-r\f[R]: each
independently wraps that same CEK with its own algorithm and key, and
any one recipient\(cqs key can later decrypt the token.
More than one recipient requires (and implies) the General JSON
Serialization.
.PP
The plaintext is taken from the \f[B]\-j\f[R] option or, if not given,
read from standard input.
The resulting token is written to standard output.
.SH OPTIONS
.TP
\-h, \-\-help
Show help and exit.
.TP
\-k, \-\-key=\f[I]FILE\f[R]
File containing the recipient JSON Web Key.
Required.
.TP
\-a, \-\-algorithm=\f[I]ALG\f[R]
The JWE key management algorithm.
Required.
One of: \f[B]dir\f[R], \f[B]A128KW\f[R], \f[B]A192KW\f[R],
\f[B]A256KW\f[R], \f[B]RSA\-OAEP\f[R], \f[B]RSA\-OAEP\-256\f[R],
\f[B]ECDH\-ES\f[R], \f[B]ECDH\-ES+A128KW\f[R],
\f[B]ECDH\-ES+A192KW\f[R], \f[B]ECDH\-ES+A256KW\f[R].
.TP
\-e, \-\-enc=\f[I]ENC\f[R]
The JWE content encryption algorithm.
Required.
One of: \f[B]A128GCM\f[R], \f[B]A192GCM\f[R], \f[B]A256GCM\f[R],
\f[B]A128CBC\-HS256\f[R], \f[B]A192CBC\-HS384\f[R],
\f[B]A256CBC\-HS512\f[R].
.TP
\-f, \-\-format=\f[I]FORMAT\f[R]
The serialization to produce: \f[B]compact\f[R] (the default five\-part
string), \f[B]json\-flat\f[R] (the Flattened JSON Serialization), or
\f[B]json\-general\f[R] (the General JSON Serialization).
The Compact and Flattened forms carry exactly one recipient.
.TP
\-r, \-\-recipient=\f[I]ALG\f[R]:\f[I]FILE\f[R]
Add another recipient: key management algorithm \f[I]ALG\f[R] with the
JWK in \f[I]FILE\f[R].
May be given more than once.
Each recipient wraps the shared CEK independently.
Using \f[B]\-r\f[R] implies \f[B]\-\-format=json\-general\f[R].
\f[B]dir\f[R] and \f[B]ECDH\-ES\f[R] (Direct) constrain the CEK and
cannot be combined with other recipients.
.TP
\-A, \-\-aad=\f[I]FILE\f[R]
File whose raw contents become the JWE Additional Authenticated Data
(the \f[B]aad\f[R] member).
It is authenticated but not encrypted, and is only available in the JSON
serializations.
.TP
\-j, \-\-json=\f[I]STRING\f[R]
The plaintext to encrypt.
If omitted, the plaintext is read from standard input.
.SH NOTES
For \f[B]dir\f[R], the JWK must be a symmetric (\f[B]oct\f[R]) key whose
length exactly matches the CEK length required by the \f[B]enc\f[R]
algorithm.
For \f[B]A*KW\f[R], the JWK must be an \f[B]oct\f[R] key of the matching
size.
For \f[B]RSA\-OAEP\f[R] and \f[B]RSA\-OAEP\-256\f[R], the JWK must be an
RSA public (or private) key.
For \f[B]ECDH\-ES\f[R] and its \f[B]+A*KW\f[R] variants, the JWK must be
an EC key (P\-256/384/521) or an OKP X\-curve key (X25519/X448).
.PP
The key must permit encryption use: a key marked
\f[B]\(lquse\(rq:\(lqsig\(rq\f[R] or whose \f[B]key_ops\f[R] forbid the
operation is rejected.
.PP
For the JSON serializations, the same header parameter name must not
appear in more than one of the protected, shared\-unprotected, or
per\-recipient headers; \f[B]jwe\-encrypt\f[R] rejects a configuration
that would violate this.
.SH SEE ALSO
jwe\-decrypt(1), key2jwk(1), jwt\-generate(1)