'\" t
.\"     Title: jose-jwk-exc
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 11/01/2022
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "JOSE\-JWK\-EXC" "1" "11/01/2022" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
jose-jwk-exc \- Performs a key exchange using the two input keys
.SH "SYNOPSIS"
.sp
\fBjose jwk exc\fR [\-i JWK] \-l JWK \-r JWK [\-o JWK]
.SH "OVERVIEW"
.sp
The \fBjose jwk exc\fR command performs a key exchange using the two input keys and provides the result of the exchange as output\&. The user can specify a JWK template as input and the specified properties will appear in the output JWK unmodified\&.
.sp
A key exchange requires two keys:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
The local key, which usually contains private key material\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
The remote key, which usually contains public key material\&.
.RE
.sp
The algorithm for the exchange is inferred from the inputs\&.
.sp
The \fBECDH\fR algorithm performs a standard elliptic curve multiplication such that the public value of \ep rem is multiplied by the private value of \ep\&.
.sp
The \fBECMR\fR algorithm has three modes of operation\&. Where the local key has a private key (the "d" property), it performs exactly like \fBECDH\fR\&. If the local key does not have a private key and the remote key does have a private key, elliptic curve addition is performed on the two values\&. Otherwise, if neither the local key nor the remote key have a private key, the remote key is subtracted from the local key using elliptic curve subtraction\&. When using ECMR, be sure to validate the content of your inputs to avoid triggering the incorrect operation!
.SH "OPTIONS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-i\fR
\fIJSON\fR,
\fB\-\-input\fR=\fIJSON\fR
: Parse JWK template from JSON
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-i\fR
\fIFILE\fR,
\fB\-\-input\fR=\fIFILE\fR
: Read JWK template from FILE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-i\fR
\-,
\fB\-\-input\fR=\- : Read JWK template from standard input
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-o\fR
\fIFILE\fR,
\fB\-\-output\fR=\fIFILE\fR
: Write JWK(Set) to FILE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-o\fR
\-,
\fB\-\-output\fR=\- : Write JWK(Set) to standard input
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-l\fR
\fIFILE\fR,
\fB\-\-local\fR=\fIFILE\fR
: Read local JWK from FILE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-l\fR
\-,
\fB\-\-local\fR=\- : Read local JWK from standard input
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-r\fR
\fIFILE\fR,
\fB\-\-remote\fR=\fIFILE\fR
: Read remote JWK from FILE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-r\fR
\-,
\fB\-\-remote\fR=\- : Read remote JWK from standard input
.RE
.SH "EXAMPLES"
.sp
Perform a key exchange:
.sp
.if n \{\
.RS 4
.\}
.nf
$ jose jwk gen \-i \*(Aq{"alg":"ECDH"}\*(Aq \-o local\&.jwk
$ jose jwk gen \-i \*(Aq{"alg":"ECDH"}\*(Aq | jose jwk pub \-i\- \-o remote\&.jwk
$ jose jwk exc \-l local\&.jwk \-r remote\&.jwk \-o exchanged\&.jwk
.fi
.if n \{\
.RE
.\}
.SH "AUTHOR"
.sp
Nathaniel McCallum <npmccallum@redhat\&.com>
.SH "SEE ALSO"
.sp
\fBjose\-alg\fR(1), \fBjose\-jwk\-exc\fR(1), \fBjose\-jwk\-gen\fR(1), \fBjose\-jwk\-pub\fR(1)