1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
.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\&.
|
