jose/doc/doxygen/man/man3/jose_jwk.3

.TH "jose_jwk" 3 "Tue May 30 2017" "José" \" -*- nroff -*-
.ad l
.nh
.SH NAME
jose_jwk \- JSON Web Keys (RFC 7517)  

.SH SYNOPSIS
.br
.PP
.SS "Functions"

.in +1c
.ti -1c
.RI "bool \fBjose_jwk_gen\fP (jose_cfg_t *cfg, json_t *jwk)"
.br
.RI "Generates a new JWK\&. "
.ti -1c
.RI "bool \fBjose_jwk_pub\fP (jose_cfg_t *cfg, json_t *jwk)"
.br
.RI "Removes all private key material from a JWK\&. "
.ti -1c
.RI "bool \fBjose_jwk_prm\fP (jose_cfg_t *cfg, const json_t *jwk, bool req, const char *op)"
.br
.RI "Determines if an operation is permitted for a JWK\&. "
.ti -1c
.RI "json_t * \fBjose_jwk_thp\fP (jose_cfg_t *cfg, const json_t *jwk, const char *alg)"
.br
.RI "Calculates the thumbprint of a JWK as a URL-safe Base64 encoded JSON string\&. "
.ti -1c
.RI "size_t \fBjose_jwk_thp_buf\fP (jose_cfg_t *cfg, const json_t *jwk, const char *alg, uint8_t *thp, size_t len)"
.br
.RI "Calculates the thumbprint of a JWK\&. "
.ti -1c
.RI "json_t * \fBjose_jwk_exc\fP (jose_cfg_t *cfg, const json_t *prv, const json_t *pub)"
.br
.RI "Perform a key exchange\&. "
.in -1c
.SH "Detailed Description"
.PP 
JSON Web Keys (RFC 7517) 

A JSON Web Key (JWS) is a standard data format for expresing cryptographic keys in JSON\&.
.PP
\fBSee also:\fP
.RS 4
https://tools.ietf.org/html/rfc7517 
.PP
https://tools.ietf.org/html/rfc7638 
.RE
.PP

.SH "Function Documentation"
.PP 
.SS "bool jose_jwk_gen (jose_cfg_t * cfg, json_t * jwk)"

.PP
Generates a new JWK\&. The JWK is generated using hints from the input in exactly the same format as you would find in the output\&. For example, the most common way to generate a key is to specify the algorithm you'd like to use the key with\&. For example (error handling omitted): 
.PP
.nf
json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s}", "alg", "ES256");
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}

.fi
.PP
.PP
This method is preferred because other metadata can be inferred from the algorithm name, such as the key usage\&. Additionally, the algorithm metadata can be used to automatically generate correct headers when creating signatures (JWS) or encryptions (JWE)\&. Thus, you should always default to creating keys by their algorithm usage\&.
.PP
However, should your requirements differ, you can also generate a key using raw parameters (again, error handling omitted): 
.PP
.nf
json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s,s:s}", "kty", "EC", "crv", "P-256");
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}

json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s,s:i}", "kty", "RSA", "bits", 2048);
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}

json_t *gen(void) {
    json_auto_t *jwk = json_pack("{s:s,s:i}", "kty", "oct", "bytes", 32);
    jose_jwk_gen(NULL, jwk);
    return json_incref(jwk);
}

.fi
.PP
.PP
In this case, 'bits' and 'bytes' will be removed from the final output\&.
.PP
\fBSee also:\fP
.RS 4
https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIcfg\fP The configuration context (optional)\&. 
.br
\fIjwk\fP The JWK to generate\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
On success, true\&. Otherwise, false\&. 
.RE
.PP

.SS "bool jose_jwk_pub (jose_cfg_t * cfg, json_t * jwk)"

.PP
Removes all private key material from a JWK\&. In addition, this function will remove any key operations from the \fCkey_ops\fP JWK property (if present) that apply only to the private key\&.
.PP
This function should be used before exporting keys to third parties\&.
.PP
\fBParameters:\fP
.RS 4
\fIcfg\fP The configuration context (optional)\&. 
.br
\fIjwk\fP The JWK to remove private keys from\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
On success, true\&. Otherwise, false\&. 
.RE
.PP

.SS "bool jose_jwk_prm (jose_cfg_t * cfg, const json_t * jwk, bool req, const char * op)"

.PP
Determines if an operation is permitted for a JWK\&. The operation to be confirmed (\fCop\fP) is always specified according to the syntax of the 'key_ops' JWK property, even when the 'use' property is defined on the JWK\&.
.PP
This function has two modes of operation\&. If \fCreq\fP is false, then JWKs which do not have any key use metadata will be approved for this operation\&. However, if \fCreq\fP is true then this metadata will be required for approval\&.
.PP
\fBParameters:\fP
.RS 4
\fIcfg\fP The configuration context (optional)\&. 
.br
\fIjwk\fP The JWK from which to remove private keys\&. 
.br
\fIreq\fP Whether JWK key use metadata is required or not\&. 
.br
\fIop\fP The opperation to seek approval for\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
When the JWK is approved, true\&. Otherwise, false\&. 
.RE
.PP

.SS "json_t* jose_jwk_thp (jose_cfg_t * cfg, const json_t * jwk, const char * alg)"

.PP
Calculates the thumbprint of a JWK as a URL-safe Base64 encoded JSON string\&. This function is a thin wrapper around \fBjose_jwk_thp_buf()\fP\&.
.PP
\fBSee also:\fP
.RS 4
\fBjose_jwk_thp_buf()\fP 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIcfg\fP The configuration context (optional)\&. 
.br
\fIjwk\fP The JWK to calculate the thumbprint for\&. 
.br
\fIalg\fP The hash algorithm to use\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
On success, a newly-allocated JSON string\&. Otherwise, NULL\&. 
.RE
.PP

.SS "size_t jose_jwk_thp_buf (jose_cfg_t * cfg, const json_t * jwk, const char * alg, uint8_t * thp, size_t len)"

.PP
Calculates the thumbprint of a JWK\&. This function calculates the thumbprint of a JWK according to the method defined by RFC 7638\&.
.PP
If \fCthp\fP is NULL, this function returns the size of the buffer required for the thumbprint output\&.
.PP
\fBSee also:\fP
.RS 4
https://tools.ietf.org/html/rfc7638 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIcfg\fP The configuration context (optional)\&. 
.br
\fIjwk\fP The JWK to calculate the thumbprint for\&. 
.br
\fIalg\fP The hash algorithm to use\&. 
.br
\fIthp\fP The output hash buffer\&. 
.br
\fIlen\fP The size of the output hash buffer\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
On success, the number of bytes written\&. Otherwise, SIZE_MAX\&. 
.RE
.PP

.SS "json_t* jose_jwk_exc (jose_cfg_t * cfg, const json_t * prv, const json_t * pub)"

.PP
Perform a key exchange\&. The only currently implemented algorithm is ECDH\&.
.PP
\fBParameters:\fP
.RS 4
\fIcfg\fP The configuration context (optional)\&. 
.br
\fIprv\fP The private JWK\&. 
.br
\fIpub\fP The public JWK\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
On success, the JWK result of the key exchange\&. Otherwise, NULL\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for José from the source code\&.