1/* Copyright (c) 2020, Google Inc.
2 *
3 * Permission to use, copy, modify, and/or distribute this software for any
4 * purpose with or without fee is hereby granted, provided that the above
5 * copyright notice and this permission notice appear in all copies.
6 *
7 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
10 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
12 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
13 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
14
15#ifndef OPENSSL_HEADER_TRUST_TOKEN_H
16#define OPENSSL_HEADER_TRUST_TOKEN_H
17
18#include <openssl/base.h>
19#include <openssl/stack.h>
20
21#if defined(__cplusplus)
22extern "C" {
23#endif
24
25
26// Trust Token implementation.
27//
28// Trust Token is an implementation of an experimental mechanism similar to
29// Privacy Pass which allows issuance and redemption of anonymized tokens with
30// limited private metadata.
31//
32// References:
33// https://eprint.iacr.org/2020/072.pdf
34// https://github.com/alxdavids/privacy-pass-ietf/tree/master/drafts
35// https://github.com/WICG/trust-token-api/blob/master/README.md
36//
37// WARNING: This API is unstable and subject to change.
38
39// TRUST_TOKEN_experiment_v1 is an experimental Trust Tokens protocol using
40// PMBTokens and P-384.
41OPENSSL_EXPORT const TRUST_TOKEN_METHOD *TRUST_TOKEN_experiment_v1(void);
42
43// TRUST_TOKEN_experiment_v2_voprf is an experimental Trust Tokens protocol
44// using VOPRFs and P-384 with up to 6 keys, without RR verification.
45OPENSSL_EXPORT const TRUST_TOKEN_METHOD *TRUST_TOKEN_experiment_v2_voprf(void);
46
47// TRUST_TOKEN_experiment_v2_pmb is an experimental Trust Tokens protocol using
48// PMBTokens and P-384 with up to 3 keys, without RR verification.
49OPENSSL_EXPORT const TRUST_TOKEN_METHOD *TRUST_TOKEN_experiment_v2_pmb(void);
50
51// trust_token_st represents a single-use token for the Trust Token protocol.
52// For the client, this is the token and its corresponding signature. For the
53// issuer, this is the token itself.
54struct trust_token_st {
55 uint8_t *data;
56 size_t len;
57};
58
59DEFINE_STACK_OF(TRUST_TOKEN)
60
61// TRUST_TOKEN_new creates a newly-allocated |TRUST_TOKEN| with value |data| or
62// NULL on allocation failure.
63OPENSSL_EXPORT TRUST_TOKEN *TRUST_TOKEN_new(const uint8_t *data, size_t len);
64
65// TRUST_TOKEN_free releases memory associated with |token|.
66OPENSSL_EXPORT void TRUST_TOKEN_free(TRUST_TOKEN *token);
67
68#define TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE 512
69#define TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE 512
70
71// TRUST_TOKEN_generate_key creates a new Trust Token keypair labeled with |id|
72// and serializes the private and public keys, writing the private key to
73// |out_priv_key| and setting |*out_priv_key_len| to the number of bytes
74// written, and writing the public key to |out_pub_key| and setting
75// |*out_pub_key_len| to the number of bytes written.
76//
77// At most |max_priv_key_len| and |max_pub_key_len| bytes are written. In order
78// to ensure success, these should be at least
79// |TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE| and |TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE|.
80//
81// This function returns one on success or zero on error.
82OPENSSL_EXPORT int TRUST_TOKEN_generate_key(
83 const TRUST_TOKEN_METHOD *method, uint8_t *out_priv_key,
84 size_t *out_priv_key_len, size_t max_priv_key_len, uint8_t *out_pub_key,
85 size_t *out_pub_key_len, size_t max_pub_key_len, uint32_t id);
86
87// TRUST_TOKEN_derive_key_from_secret deterministically derives a new Trust
88// Token keypair labeled with |id| from an input |secret| and serializes the
89// private and public keys, writing the private key to |out_priv_key| and
90// setting |*out_priv_key_len| to the number of bytes written, and writing the
91// public key to |out_pub_key| and setting |*out_pub_key_len| to the number of
92// bytes written.
93//
94// At most |max_priv_key_len| and |max_pub_key_len| bytes are written. In order
95// to ensure success, these should be at least
96// |TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE| and |TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE|.
97//
98// This function returns one on success or zero on error.
99OPENSSL_EXPORT int TRUST_TOKEN_derive_key_from_secret(
100 const TRUST_TOKEN_METHOD *method, uint8_t *out_priv_key,
101 size_t *out_priv_key_len, size_t max_priv_key_len, uint8_t *out_pub_key,
102 size_t *out_pub_key_len, size_t max_pub_key_len, uint32_t id,
103 const uint8_t *secret, size_t secret_len);
104
105
106// Trust Token client implementation.
107//
108// These functions implements the client half of the Trust Token protocol. A
109// single |TRUST_TOKEN_CLIENT| can perform a single protocol operation.
110
111// TRUST_TOKEN_CLIENT_new returns a newly-allocated |TRUST_TOKEN_CLIENT|
112// configured to use a max batchsize of |max_batchsize| or NULL on error.
113// Issuance requests must be made in batches smaller than |max_batchsize|. This
114// function will return an error if |max_batchsize| is too large for Trust
115// Tokens.
116OPENSSL_EXPORT TRUST_TOKEN_CLIENT *TRUST_TOKEN_CLIENT_new(
117 const TRUST_TOKEN_METHOD *method, size_t max_batchsize);
118
119// TRUST_TOKEN_CLIENT_free releases memory associated with |ctx|.
120OPENSSL_EXPORT void TRUST_TOKEN_CLIENT_free(TRUST_TOKEN_CLIENT *ctx);
121
122// TRUST_TOKEN_CLIENT_add_key configures the |ctx| to support the public key
123// |key|. It sets |*out_key_index| to the index this key has been configured to.
124// It returns one on success or zero on error if the |key| can't be parsed or
125// too many keys have been configured.
126OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_add_key(TRUST_TOKEN_CLIENT *ctx,
127 size_t *out_key_index,
128 const uint8_t *key,
129 size_t key_len);
130
131// TRUST_TOKEN_CLIENT_set_srr_key sets the public key used to verify the SRR. It
132// returns one on success and zero on error.
133OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_set_srr_key(TRUST_TOKEN_CLIENT *ctx,
134 EVP_PKEY *key);
135
136// TRUST_TOKEN_CLIENT_begin_issuance produces a request for |count| trust tokens
137// and serializes the request into a newly-allocated buffer, setting |*out| to
138// that buffer and |*out_len| to its length. The caller takes ownership of the
139// buffer and must call |OPENSSL_free| when done. It returns one on success and
140// zero on error.
141OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_issuance(TRUST_TOKEN_CLIENT *ctx,
142 uint8_t **out,
143 size_t *out_len,
144 size_t count);
145
146// TRUST_TOKEN_CLIENT_begin_issuance_over_message produces a request for a trust
147// token derived from |msg| and serializes the request into a newly-allocated
148// buffer, setting |*out| to that buffer and |*out_len| to its length. The
149// caller takes ownership of the buffer and must call |OPENSSL_free| when done.
150// It returns one on success and zero on error.
151OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_issuance_over_message(
152 TRUST_TOKEN_CLIENT *ctx, uint8_t **out, size_t *out_len, size_t count,
153 const uint8_t *msg, size_t msg_len);
154
155// TRUST_TOKEN_CLIENT_finish_issuance consumes |response| from the issuer and
156// extracts the tokens, returning a list of tokens and the index of the key used
157// to sign the tokens in |*out_key_index|. The caller can use this to determine
158// what key was used in an issuance and to drop tokens if a new key commitment
159// arrives without the specified key present. The caller takes ownership of the
160// list and must call |sk_TRUST_TOKEN_pop_free| when done. The list is empty if
161// issuance fails.
162OPENSSL_EXPORT STACK_OF(TRUST_TOKEN) *
163 TRUST_TOKEN_CLIENT_finish_issuance(TRUST_TOKEN_CLIENT *ctx,
164 size_t *out_key_index,
165 const uint8_t *response,
166 size_t response_len);
167
168
169// TRUST_TOKEN_CLIENT_begin_redemption produces a request to redeem a token
170// |token| and receive a signature over |data| and serializes the request into
171// a newly-allocated buffer, setting |*out| to that buffer and |*out_len| to
172// its length. |time| is the number of seconds since the UNIX epoch and used to
173// verify the validity of the issuer's response in TrustTokenV1 and ignored in
174// other versions. The caller takes ownership of the buffer and must call
175// |OPENSSL_free| when done. It returns one on success or zero on error.
176OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_redemption(
177 TRUST_TOKEN_CLIENT *ctx, uint8_t **out, size_t *out_len,
178 const TRUST_TOKEN *token, const uint8_t *data, size_t data_len,
179 uint64_t time);
180
181// TRUST_TOKEN_CLIENT_finish_redemption consumes |response| from the issuer. In
182// |TRUST_TOKEN_experiment_v1|, it then verifies the SRR and if valid sets
183// |*out_rr| and |*out_rr_len| (respectively, |*out_sig| and |*out_sig_len|)
184// to a newly-allocated buffer containing the SRR (respectively, the SRR
185// signature). In other versions, it sets |*out_rr| and |*out_rr_len|
186// to a newly-allocated buffer containing |response| and leaves all validation
187// to the caller. It returns one on success or zero on failure.
188OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_finish_redemption(
189 TRUST_TOKEN_CLIENT *ctx, uint8_t **out_rr, size_t *out_rr_len,
190 uint8_t **out_sig, size_t *out_sig_len, const uint8_t *response,
191 size_t response_len);
192
193
194// Trust Token issuer implementation.
195//
196// These functions implement the issuer half of the Trust Token protocol. A
197// |TRUST_TOKEN_ISSUER| can be reused across multiple protocol operations. It
198// may be used concurrently on multiple threads by non-mutating functions,
199// provided no other thread is concurrently calling a mutating function.
200// Functions which take a |const| pointer are non-mutating and functions which
201// take a non-|const| pointer are mutating.
202
203// TRUST_TOKEN_ISSUER_new returns a newly-allocated |TRUST_TOKEN_ISSUER|
204// configured to use a max batchsize of |max_batchsize| or NULL on error.
205// Issuance requests must be made in batches smaller than |max_batchsize|. This
206// function will return an error if |max_batchsize| is too large for Trust
207// Tokens.
208OPENSSL_EXPORT TRUST_TOKEN_ISSUER *TRUST_TOKEN_ISSUER_new(
209 const TRUST_TOKEN_METHOD *method, size_t max_batchsize);
210
211// TRUST_TOKEN_ISSUER_free releases memory associated with |ctx|.
212OPENSSL_EXPORT void TRUST_TOKEN_ISSUER_free(TRUST_TOKEN_ISSUER *ctx);
213
214// TRUST_TOKEN_ISSUER_add_key configures the |ctx| to support the private key
215// |key|. It must be a private key returned by |TRUST_TOKEN_generate_key|. It
216// returns one on success or zero on error. This function may fail if the |key|
217// can't be parsed or too many keys have been configured.
218OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_add_key(TRUST_TOKEN_ISSUER *ctx,
219 const uint8_t *key,
220 size_t key_len);
221
222// TRUST_TOKEN_ISSUER_set_srr_key sets the private key used to sign the SRR. It
223// returns one on success and zero on error.
224OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_set_srr_key(TRUST_TOKEN_ISSUER *ctx,
225 EVP_PKEY *key);
226
227// TRUST_TOKEN_ISSUER_set_metadata_key sets the key used to encrypt the private
228// metadata. The key is a randomly generated bytestring of at least 32 bytes
229// used to encode the private metadata bit in the SRR. It returns one on success
230// and zero on error.
231OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_set_metadata_key(TRUST_TOKEN_ISSUER *ctx,
232 const uint8_t *key,
233 size_t len);
234
235// TRUST_TOKEN_ISSUER_issue ingests |request| for token issuance
236// and generates up to |max_issuance| valid tokens, producing a list of blinded
237// tokens and storing the response into a newly-allocated buffer and setting
238// |*out| to that buffer, |*out_len| to its length, and |*out_tokens_issued| to
239// the number of tokens issued. The tokens are issued with public metadata of
240// |public_metadata| and a private metadata value of |private_metadata|.
241// |public_metadata| must be one of the previously configured key IDs.
242// |private_metadata| must be 0 or 1. The caller takes ownership of the buffer
243// and must call |OPENSSL_free| when done. It returns one on success or zero on
244// error.
245OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_issue(
246 const TRUST_TOKEN_ISSUER *ctx, uint8_t **out, size_t *out_len,
247 size_t *out_tokens_issued, const uint8_t *request, size_t request_len,
248 uint32_t public_metadata, uint8_t private_metadata, size_t max_issuance);
249
250// TRUST_TOKEN_ISSUER_redeem ingests a |request| for token redemption and
251// verifies the token. The public metadata is stored in |*out_public|. The
252// private metadata (if any) is stored in |*out_private|. The extracted
253// |TRUST_TOKEN| is stored into a newly-allocated buffer and stored in
254// |*out_token|. The extracted client data is stored into a newly-allocated
255// buffer and stored in |*out_client_data|. The caller takes ownership of each
256// output buffer and must call |OPENSSL_free| when done. It returns one on
257// success or zero on error.
258//
259// The caller must keep track of all values of |*out_token| seen globally before
260// returning a response to the client. If the value has been reused, the caller
261// must report an error to the client. Returning a response with replayed values
262// allows an attacker to double-spend tokens.
263OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_redeem(
264 const TRUST_TOKEN_ISSUER *ctx, uint32_t *out_public, uint8_t *out_private,
265 TRUST_TOKEN **out_token, uint8_t **out_client_data,
266 size_t *out_client_data_len, const uint8_t *request, size_t request_len);
267
268// TRUST_TOKEN_ISSUER_redeem_raw is a legacy alias for
269// |TRUST_TOKEN_ISSUER_redeem|.
270#define TRUST_TOKEN_ISSUER_redeem_raw TRUST_TOKEN_ISSUER_redeem
271
272// TRUST_TOKEN_ISSUER_redeem_over_message ingests a |request| for token
273// redemption and a message and verifies the token and that it is derived from
274// the provided |msg|. The public metadata is stored in
275// |*out_public|. The private metadata (if any) is stored in |*out_private|. The
276// extracted |TRUST_TOKEN| is stored into a newly-allocated buffer and stored in
277// |*out_token|. The extracted client data is stored into a newly-allocated
278// buffer and stored in |*out_client_data|. The caller takes ownership of each
279// output buffer and must call |OPENSSL_free| when done. It returns one on
280// success or zero on error.
281//
282// The caller must keep track of all values of |*out_token| seen globally before
283// returning a response to the client. If the value has been reused, the caller
284// must report an error to the client. Returning a response with replayed values
285// allows an attacker to double-spend tokens.
286OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_redeem_over_message(
287 const TRUST_TOKEN_ISSUER *ctx, uint32_t *out_public, uint8_t *out_private,
288 TRUST_TOKEN **out_token, uint8_t **out_client_data,
289 size_t *out_client_data_len, const uint8_t *request, size_t request_len,
290 const uint8_t *msg, size_t msg_len);
291
292// TRUST_TOKEN_decode_private_metadata decodes |encrypted_bit| using the
293// private metadata key specified by a |key| buffer of length |key_len| and the
294// nonce by a |nonce| buffer of length |nonce_len|. The nonce in
295// |TRUST_TOKEN_experiment_v1| is the token-hash field of the SRR. |*out_value|
296// is set to the decrypted value, either zero or one. It returns one on success
297// and zero on error.
298OPENSSL_EXPORT int TRUST_TOKEN_decode_private_metadata(
299 const TRUST_TOKEN_METHOD *method, uint8_t *out_value, const uint8_t *key,
300 size_t key_len, const uint8_t *nonce, size_t nonce_len,
301 uint8_t encrypted_bit);
302
303
304#if defined(__cplusplus)
305} // extern C
306
307extern "C++" {
308
309BSSL_NAMESPACE_BEGIN
310
311BORINGSSL_MAKE_DELETER(TRUST_TOKEN, TRUST_TOKEN_free)
312BORINGSSL_MAKE_DELETER(TRUST_TOKEN_CLIENT, TRUST_TOKEN_CLIENT_free)
313BORINGSSL_MAKE_DELETER(TRUST_TOKEN_ISSUER, TRUST_TOKEN_ISSUER_free)
314
315BSSL_NAMESPACE_END
316
317} // extern C++
318#endif
319
320#define TRUST_TOKEN_R_KEYGEN_FAILURE 100
321#define TRUST_TOKEN_R_BUFFER_TOO_SMALL 101
322#define TRUST_TOKEN_R_OVER_BATCHSIZE 102
323#define TRUST_TOKEN_R_DECODE_ERROR 103
324#define TRUST_TOKEN_R_SRR_SIGNATURE_ERROR 104
325#define TRUST_TOKEN_R_DECODE_FAILURE 105
326#define TRUST_TOKEN_R_INVALID_METADATA 106
327#define TRUST_TOKEN_R_TOO_MANY_KEYS 107
328#define TRUST_TOKEN_R_NO_KEYS_CONFIGURED 108
329#define TRUST_TOKEN_R_INVALID_KEY_ID 109
330#define TRUST_TOKEN_R_INVALID_TOKEN 110
331#define TRUST_TOKEN_R_BAD_VALIDITY_CHECK 111
332#define TRUST_TOKEN_R_NO_SRR_KEY_CONFIGURED 112
333#define TRUST_TOKEN_R_INVALID_METADATA_KEY 113
334#define TRUST_TOKEN_R_INVALID_PROOF 114
335
336#endif // OPENSSL_HEADER_TRUST_TOKEN_H
337

source code of dart_sdk/third_party/boringssl/src/include/openssl/trust_token.h