| /* Copyright (c) 2020, Google Inc. |
| * |
| * Permission to use, copy, modify, and/or distribute this software for any |
| * purpose with or without fee is hereby granted, provided that the above |
| * copyright notice and this permission notice appear in all copies. |
| * |
| * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
| * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
| * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY |
| * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
| * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION |
| * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN |
| * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ |
| |
| #ifndef OPENSSL_HEADER_TRUST_TOKEN_H |
| #define OPENSSL_HEADER_TRUST_TOKEN_H |
| |
| #include <openssl/base.h> |
| #include <openssl/stack.h> |
| |
| #if defined(__cplusplus) |
| extern "C" { |
| #endif |
| |
| |
| // Trust Token implementation. |
| // |
| // Trust Token is an implementation of an experimental mechanism similar to |
| // Privacy Pass which allows issuance and redemption of anonymized tokens with |
| // limited private metadata. |
| // |
| // References: |
| // https://eprint.iacr.org/2020/072.pdf |
| // https://github.com/alxdavids/privacy-pass-ietf/tree/master/drafts |
| // https://github.com/WICG/trust-token-api/blob/master/README.md |
| // |
| // WARNING: This API is unstable and subject to change. |
| |
| // TRUST_TOKEN_experiment_v0 is an experimental Trust Tokens protocol using |
| // PMBTokens and P-521. |
| OPENSSL_EXPORT const TRUST_TOKEN_METHOD *TRUST_TOKEN_experiment_v0(void); |
| |
| // TRUST_TOKEN_experiment_v1 is an experimental Trust Tokens protocol using |
| // PMBTokens and P-384. This version is still under developement and should not |
| // be used yet. |
| OPENSSL_EXPORT const TRUST_TOKEN_METHOD *TRUST_TOKEN_experiment_v1(void); |
| |
| // trust_token_st represents a single-use token for the Trust Token protocol. |
| // For the client, this is the token and its corresponding signature. For the |
| // issuer, this is the token itself. |
| struct trust_token_st { |
| uint8_t *data; |
| size_t len; |
| }; |
| |
| DEFINE_STACK_OF(TRUST_TOKEN) |
| |
| // TRUST_TOKEN_new creates a newly-allocated |TRUST_TOKEN| with value |data| or |
| // NULL on allocation failure. |
| OPENSSL_EXPORT TRUST_TOKEN *TRUST_TOKEN_new(const uint8_t *data, size_t len); |
| |
| // TRUST_TOKEN_free releases memory associated with |token|. |
| OPENSSL_EXPORT void TRUST_TOKEN_free(TRUST_TOKEN *token); |
| |
| #define TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE 512 |
| #define TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE 512 |
| |
| // TRUST_TOKEN_generate_key creates a new Trust Token keypair labeled with |id| |
| // and serializes the private and public keys, writing the private key to |
| // |out_priv_key| and setting |*out_priv_key_len| to the number of bytes |
| // written, and writing the public key to |out_pub_key| and setting |
| // |*out_pub_key_len| to the number of bytes written. |
| // |
| // At most |max_priv_key_len| and |max_pub_key_len| bytes are written. In order |
| // to ensure success, these should be at least |
| // |TRUST_TOKEN_MAX_PRIVATE_KEY_SIZE| and |TRUST_TOKEN_MAX_PUBLIC_KEY_SIZE|. |
| // |
| // WARNING: This API is unstable and the serializations of these keys are |
| // subject to change. Keys generated with this function may not be persisted. |
| // |
| // This function returns one on success or zero on error. |
| OPENSSL_EXPORT int TRUST_TOKEN_generate_key( |
| const TRUST_TOKEN_METHOD *method, uint8_t *out_priv_key, |
| size_t *out_priv_key_len, size_t max_priv_key_len, uint8_t *out_pub_key, |
| size_t *out_pub_key_len, size_t max_pub_key_len, uint32_t id); |
| |
| |
| // Trust Token client implementation. |
| // |
| // These functions implements the client half of the Trust Token protocol. A |
| // single |TRUST_TOKEN_CLIENT| can perform a single protocol operation. |
| |
| // TRUST_TOKEN_CLIENT_new returns a newly-allocated |TRUST_TOKEN_CLIENT| |
| // configured to use a max batchsize of |max_batchsize| or NULL on error. |
| // Issuance requests must be made in batches smaller than |max_batchsize|. This |
| // function will return an error if |max_batchsize| is too large for Trust |
| // Tokens. |
| OPENSSL_EXPORT TRUST_TOKEN_CLIENT *TRUST_TOKEN_CLIENT_new( |
| const TRUST_TOKEN_METHOD *method, size_t max_batchsize); |
| |
| // TRUST_TOKEN_CLIENT_free releases memory associated with |ctx|. |
| OPENSSL_EXPORT void TRUST_TOKEN_CLIENT_free(TRUST_TOKEN_CLIENT *ctx); |
| |
| // TRUST_TOKEN_CLIENT_add_key configures the |ctx| to support the public key |
| // |key|. It sets |*out_key_index| to the index this key has been configured to. |
| // It returns one on success or zero on error if the |key| can't be parsed or |
| // too many keys have been configured. |
| OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_add_key(TRUST_TOKEN_CLIENT *ctx, |
| size_t *out_key_index, |
| const uint8_t *key, |
| size_t key_len); |
| |
| // TRUST_TOKEN_CLIENT_set_srr_key sets the public key used to verify the SRR. It |
| // returns one on success and zero on error. |
| OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_set_srr_key(TRUST_TOKEN_CLIENT *ctx, |
| EVP_PKEY *key); |
| |
| // TRUST_TOKEN_CLIENT_begin_issuance produces a request for |count| trust tokens |
| // and serializes the request into a newly-allocated buffer, setting |*out| to |
| // that buffer and |*out_len| to its length. The caller takes ownership of the |
| // buffer and must call |OPENSSL_free| when done. It returns one on success and |
| // zero on error. |
| OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_issuance(TRUST_TOKEN_CLIENT *ctx, |
| uint8_t **out, |
| size_t *out_len, |
| size_t count); |
| |
| // TRUST_TOKEN_CLIENT_finish_issuance consumes |response| from the issuer and |
| // extracts the tokens, returning a list of tokens and the index of the key used |
| // to sign the tokens in |*out_key_index|. The caller can use this to determine |
| // what key was used in an issuance and to drop tokens if a new key commitment |
| // arrives without the specified key present. The caller takes ownership of the |
| // list and must call |sk_TRUST_TOKEN_pop_free| when done. The list is empty if |
| // issuance fails. |
| OPENSSL_EXPORT STACK_OF(TRUST_TOKEN) * |
| TRUST_TOKEN_CLIENT_finish_issuance(TRUST_TOKEN_CLIENT *ctx, |
| size_t *out_key_index, |
| const uint8_t *response, |
| size_t response_len); |
| |
| |
| // TRUST_TOKEN_CLIENT_begin_redemption produces a request to redeem a token |
| // |token| and receive a signature over |data| and serializes the request into |
| // a newly-allocated buffer, setting |*out| to that buffer and |*out_len| to |
| // its length. |time| is the number of seconds since the UNIX epoch and used to |
| // verify the validity of the issuer's response. The caller takes ownership of |
| // the buffer and must call |OPENSSL_free| when done. It returns one on success |
| // or zero on error. |
| OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_begin_redemption( |
| TRUST_TOKEN_CLIENT *ctx, uint8_t **out, size_t *out_len, |
| const TRUST_TOKEN *token, const uint8_t *data, size_t data_len, |
| uint64_t time); |
| |
| // TRUST_TOKEN_CLIENT_finish_redemption consumes |response| from the issuer and |
| // verifies the SRR. If valid, it returns one and sets |*out_srr| and |
| // |*out_srr_len| (respectively, |*out_sig| and |*out_sig_len|) to a |
| // newly-allocated buffer containing the SRR (respectively, the SRR signature). |
| // Otherwise, it returns zero. |
| OPENSSL_EXPORT int TRUST_TOKEN_CLIENT_finish_redemption( |
| TRUST_TOKEN_CLIENT *ctx, uint8_t **out_srr, size_t *out_srr_len, |
| uint8_t **out_sig, size_t *out_sig_len, const uint8_t *response, |
| size_t response_len); |
| |
| |
| // Trust Token issuer implementation. |
| // |
| // These functions implement the issuer half of the Trust Token protocol. A |
| // |TRUST_TOKEN_ISSUER| can be reused across multiple protocol operations. It |
| // may be used concurrently on multiple threads by non-mutating functions, |
| // provided no other thread is concurrently calling a mutating function. |
| // Functions which take a |const| pointer are non-mutating and functions which |
| // take a non-|const| pointer are mutating. |
| |
| // TRUST_TOKEN_ISSUER_new returns a newly-allocated |TRUST_TOKEN_ISSUER| |
| // configured to use a max batchsize of |max_batchsize| or NULL on error. |
| // Issuance requests must be made in batches smaller than |max_batchsize|. This |
| // function will return an error if |max_batchsize| is too large for Trust |
| // Tokens. |
| OPENSSL_EXPORT TRUST_TOKEN_ISSUER *TRUST_TOKEN_ISSUER_new( |
| const TRUST_TOKEN_METHOD *method, size_t max_batchsize); |
| |
| // TRUST_TOKEN_ISSUER_free releases memory associated with |ctx|. |
| OPENSSL_EXPORT void TRUST_TOKEN_ISSUER_free(TRUST_TOKEN_ISSUER *ctx); |
| |
| // TRUST_TOKEN_ISSUER_add_key configures the |ctx| to support the private key |
| // |key|. It must be a private key returned by |TRUST_TOKEN_generate_key|. It |
| // returns one on success or zero on error. This function may fail if the |key| |
| // can't be parsed or too many keys have been configured. |
| OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_add_key(TRUST_TOKEN_ISSUER *ctx, |
| const uint8_t *key, |
| size_t key_len); |
| |
| // TRUST_TOKEN_ISSUER_set_srr_key sets the private key used to sign the SRR. It |
| // returns one on success and zero on error. |
| OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_set_srr_key(TRUST_TOKEN_ISSUER *ctx, |
| EVP_PKEY *key); |
| |
| // TRUST_TOKEN_ISSUER_set_metadata_key sets the key used to encrypt the private |
| // metadata. The key is a randomly generated bytestring of at least 32 bytes |
| // used to encode the private metadata bit in the SRR. It returns one on success |
| // and zero on error. |
| OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_set_metadata_key(TRUST_TOKEN_ISSUER *ctx, |
| const uint8_t *key, |
| size_t len); |
| |
| // TRUST_TOKEN_ISSUER_issue ingests |request| for token issuance |
| // and generates up to |max_issuance| valid tokens, producing a list of blinded |
| // tokens and storing the response into a newly-allocated buffer and setting |
| // |*out| to that buffer, |*out_len| to its length, and |*out_tokens_issued| to |
| // the number of tokens issued. The tokens are issued with public metadata of |
| // |public_metadata| and a private metadata value of |private_metadata|. |
| // |public_metadata| must be one of the previously configured key IDs. |
| // |private_metadata| must be 0 or 1. The caller takes ownership of the buffer |
| // and must call |OPENSSL_free| when done. It returns one on success or zero on |
| // error. |
| OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_issue( |
| const TRUST_TOKEN_ISSUER *ctx, uint8_t **out, size_t *out_len, |
| size_t *out_tokens_issued, const uint8_t *request, size_t request_len, |
| uint32_t public_metadata, uint8_t private_metadata, size_t max_issuance); |
| |
| // TRUST_TOKEN_ISSUER_redeem ingests a |request| for token redemption and |
| // verifies the token. If the token is valid, a SRR is produced with a lifetime |
| // of |lifetime| (in seconds), signing over the requested data from the request |
| // and the value of the token, storing the result into a newly-allocated buffer |
| // and setting |*out| to that buffer and |*out_len| to its length. The extracted |
| // |TRUST_TOKEN| is stored into a newly-allocated buffer and stored in |
| // |*out_token|. The extracted client data is stored into a newly-allocated |
| // buffer and stored in |*out_client_data|. The extracted redemption time is |
| // stored in |*out_redemption_time|. The caller takes ownership of each output |
| // buffer and must call |OPENSSL_free| when done. It returns one on success or |
| // zero on error. |
| // |
| // The caller must keep track of all values of |*out_token| and |
| // |*out_client_data| and seen globally before returning the SRR to the client. |
| // If either value has been repeated, the caller must discard the SRR and report |
| // an error to the caller. Returning an SRR with replayed values allows an |
| // attacker to double-spend tokens and query private metadata bits in SRRs. |
| // |
| // TODO(svaldez): The private metadata bit should not be leaked on replay. This |
| // means callers cannot use eventual consistency to trade off double-spending |
| // and distributed system performance. See https://crbug.com/boringssl/328. |
| OPENSSL_EXPORT int TRUST_TOKEN_ISSUER_redeem( |
| const TRUST_TOKEN_ISSUER *ctx, uint8_t **out, size_t *out_len, |
| TRUST_TOKEN **out_token, uint8_t **out_client_data, |
| size_t *out_client_data_len, uint64_t *out_redemption_time, |
| const uint8_t *request, size_t request_len, uint64_t lifetime); |
| |
| // TRUST_TOKEN_decode_private_metadata decodes |encrypted_bit| using the |
| // private metadata key specified by a |key| buffer of length |key_len| and the |
| // client data specified by a |client_data| buffer of length |client_data_len|. |
| // |*out_value is set to the decrypted value, either zero or one. It returns one |
| // on success and zero on error. |
| OPENSSL_EXPORT int TRUST_TOKEN_decode_private_metadata( |
| const TRUST_TOKEN_METHOD *method, uint8_t *out_value, const uint8_t *key, |
| size_t key_len, const uint8_t *client_data, size_t client_data_len, |
| uint8_t encrypted_bit); |
| |
| |
| #if defined(__cplusplus) |
| } // extern C |
| |
| extern "C++" { |
| |
| BSSL_NAMESPACE_BEGIN |
| |
| BORINGSSL_MAKE_DELETER(TRUST_TOKEN, TRUST_TOKEN_free) |
| BORINGSSL_MAKE_DELETER(TRUST_TOKEN_CLIENT, TRUST_TOKEN_CLIENT_free) |
| BORINGSSL_MAKE_DELETER(TRUST_TOKEN_ISSUER, TRUST_TOKEN_ISSUER_free) |
| |
| BSSL_NAMESPACE_END |
| |
| } // extern C++ |
| #endif |
| |
| #define TRUST_TOKEN_R_KEYGEN_FAILURE 100 |
| #define TRUST_TOKEN_R_BUFFER_TOO_SMALL 101 |
| #define TRUST_TOKEN_R_OVER_BATCHSIZE 102 |
| #define TRUST_TOKEN_R_DECODE_ERROR 103 |
| #define TRUST_TOKEN_R_SRR_SIGNATURE_ERROR 104 |
| #define TRUST_TOKEN_R_DECODE_FAILURE 105 |
| #define TRUST_TOKEN_R_INVALID_METADATA 106 |
| #define TRUST_TOKEN_R_TOO_MANY_KEYS 107 |
| #define TRUST_TOKEN_R_NO_KEYS_CONFIGURED 108 |
| #define TRUST_TOKEN_R_INVALID_KEY_ID 109 |
| #define TRUST_TOKEN_R_INVALID_TOKEN 110 |
| #define TRUST_TOKEN_R_BAD_VALIDITY_CHECK 111 |
| #define TRUST_TOKEN_R_NO_SRR_KEY_CONFIGURED 112 |
| #define TRUST_TOKEN_R_INVALID_METADATA_KEY 113 |
| #define TRUST_TOKEN_R_INVALID_PROOF 114 |
| |
| #endif // OPENSSL_HEADER_TRUST_TOKEN_H |