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