jose/doc/ronn/jose-jws-sig.1

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "JOSE\-JWS\-SIG" "1" "June 2017" "" ""
.
.SH "NAME"
\fBjose\-jws\-sig\fR \- Signs a payload using one or more JWKs
.
.SH "SYNOPSIS"
\fBjose jws sig\fR [\-i JWS] [\-I PAY] [\-s SIG] \-k JWK [\-o JWS] [\-O PAY] [\-c]
.
.SH "OVERVIEW"
The \fBjose jws sig\fR command signs a payload using one or more JWKs\. The payload can be provided either in its decoded form (\fB\-I\fR) or embedded in an existing JWS (\fB\-i\fR)\.
.
.P
A detached JWS can be created by specifying the \fB\-O\fR option\. In this case, the decoded payload will be written to the output specified and will not be included in the JWS\.
.
.P
If only one key is used (\fB\-k\fR), the resulting JWS may be output in JWS Compact Serialization by using the \fB\-c\fR option\.
.
.P
This command uses a template based approach for constructing a JWS\. You can specify templates of the JWS itself (\fB\-i\fR) or for the JWS Signature Object (\fB\-r\fR)\. Attributes specified in either of these templates will appear unmodified in the output\. One exception to this rule is that the JWS Protected Header should be specified in its decoded form in the JWS Signature Object template\. This command will automatically encode it as part of the encryption process\.
.
.P
If you specify a JOSE Header Parameter (via either the \fB\-i\fR or \fB\-r\fR options) that affects the construction of the JWE, this command will attempt to behave according to this parameter as if it were configuration\. Currently, \fBjose\fR will modify its behavior for the "alg" JOSE Header Parameter (see RFC 7515 Section 4\.1\.1)\.
.
.P
However, it is not necessary to provide any templates: \fBjose jwe enc\fR will automatically fill in the "alg" parameter by inferring the correct algorithm from the provided input JWKs\. Therefore, the \fB\-i\fR and \fB\-r\fR options should generally be used for providing extended JWE metadata\.
.
.P
It is possible to specify an existing JWS as the JWS template input (\fB\-i\fR)\. This allows the addition of new signatures to an existing JWS\.
.
.SH "OPTIONS"
.
.TP
\fB\-i\fR \fIJSON\fR, \fB\-\-input\fR=\fIJSON\fR
Parse JWS template from JSON
.
.TP
\fB\-i\fR \fIFILE\fR, \fB\-\-input\fR=\fIFILE\fR
Read JWS template from FILE
.
.TP
\fB\-i\fR \-, \fB\-\-input\fR=\-
Read JWS template from standard input
.
.TP
\fB\-I\fR \fIFILE\fR, \fB\-\-detached\fR=\fIFILE\fR
Read decoded payload from FILE
.
.TP
\fB\-I\fR \-, \fB\-\-detached\fR=\-
Read decoded payload from standard input
.
.TP
\fB\-s\fR \fIJSON\fR, \fB\-\-signature\fR=\fIJSON\fR
Parse JWS signature template from JSON
.
.TP
\fB\-s\fR \fIFILE\fR, \fB\-\-signature\fR=\fIFILE\fR
Read JWS signature template from FILE
.
.TP
\fB\-s\fR \-, \fB\-\-signature\fR=\-
Read JWS signature template standard input
.
.TP
\fB\-k\fR \fIFILE\fR, \fB\-\-key\fR=\fIFILE\fR
Read JWK(Set) from FILE
.
.TP
\fB\-k\fR \-, \fB\-\-key\fR=\-
Read JWK(Set) from standard input
.
.TP
\fB\-o\fR \fIFILE\fR, \fB\-\-output\fR=\fIFILE\fR
Write JWS to FILE
.
.TP
\fB\-o\fR \-, \fB\-\-output\fR=\-
Write JWS to stdout (default)
.
.TP
\fB\-O\fR \fIFILE\fR, \fB\-\-detach\fR=\fIFILE\fR
Detach payload and decode to FILE
.
.TP
\fB\-O\fR \-, \fB\-\-detach\fR=\-
Detach payload and decode to standard output
.
.TP
\fB\-c\fR, \fB\-\-compact\fR
Output JWS using compact serialization
.
.SH "EXAMPLES"
Sign data with a symmetric key using JWE JSON Serialization:
.
.IP "" 4
.
.nf

$ jose jwk gen \-i \'{"alg":"HS256"}\' \-o key\.jwk
$ jose jws sig \-I msg\.txt \-k key\.jwk \-o msg\.jws
.
.fi
.
.IP "" 0
.
.P
Sign data using detached JWE Compact Serialization:
.
.IP "" 4
.
.nf

$ jose jws sig \-I msg\.txt \-k key\.jwk \-O /dev/null \-c \-o msg\.jws
.
.fi
.
.IP "" 0
.
.P
Sign with two keys:
.
.IP "" 4
.
.nf

$ jose jwk gen \-i \'{"alg":"ES256"}\' \-o ec\.jwk
$ jose jwk gen \-i \'{"alg":"RS256"}\' \-o rsa\.jwk
$ jose jws sig \-I msg\.txt \-k ec\.jwk \-k rsa\.jwk \-o msg\.jws
.
.fi
.
.IP "" 0
.
.SH "AUTHOR"
Nathaniel McCallum <npmccallum@redhat\.com>
.
.SH "SEE ALSO"
\fBjose\-jws\-sig\fR(1), \fBjose\-jws\-ver\fR(1)