Longfellow ZK 0290cb32

Loading...
Searching...
No Matches
mdoc_zk.h
1// Copyright 2025 Google LLC.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15#ifndef PRIVACY_PROOFS_ZK_LIB_CIRCUITS_MDOC_MDOC_ZK_H_
16#define PRIVACY_PROOFS_ZK_LIB_CIRCUITS_MDOC_MDOC_ZK_H_
17
18#include <stddef.h>
19#include <stdint.h>
20
21#ifdef __cplusplus
22 extern "C" {
23#endif
24
25// This package implements C interfaces that allow external programs to call
26// the zk mdoc-based prover and verifier.
27//
28// It also contains a helper method that produces a byte representation
29// of a circuit which verifies the mdoc with regards to specific properties,
30// for example age_over_18. The circuit generation can be run once, and the
31// result cached for subsequent use in the prover and verifier.
32
33 const size_t kLigeroRate = 4;
34 const size_t kLigeroNreq = 128; // 86+ bits statistical security
35
36/* This struct allows a verifier to express which attribute and value the prover
37 * must claim. The value should be passed as the raw bytes of the CBOR value.
38 */
39 typedef struct {
40 uint8_t namespace_id[64];
41 uint8_t id[32];
42 uint8_t cbor_value[64];
43 size_t namespace_len, id_len, cbor_value_len;
44} RequestedAttribute;
45
46// Return codes for the run_mdoc2_prover method.
47 typedef enum {
48 MDOC_PROVER_SUCCESS = 0,
49 MDOC_PROVER_NULL_INPUT,
50 MDOC_PROVER_INVALID_INPUT,
51 MDOC_PROVER_CIRCUIT_PARSING_FAILURE,
52 MDOC_PROVER_HASH_PARSING_FAILURE,
53 MDOC_PROVER_WITNESS_CREATION_FAILURE,
54 MDOC_PROVER_GENERAL_FAILURE,
55 MDOC_PROVER_MEMORY_ALLOCATION_FAILURE,
56 MDOC_PROVER_INVALID_ZK_SPEC_VERSION,
57} MdocProverErrorCode;
58
59// Return codes for the run_mdoc2_verifier method.
60 typedef enum {
61 MDOC_VERIFIER_SUCCESS = 0,
62 MDOC_VERIFIER_CIRCUIT_PARSING_FAILURE,
63 MDOC_VERIFIER_PROOF_TOO_SMALL,
64 MDOC_VERIFIER_HASH_PARSING_FAILURE,
65 MDOC_VERIFIER_SIGNATURE_PARSING_FAILURE,
66 MDOC_VERIFIER_GENERAL_FAILURE,
67 MDOC_VERIFIER_NULL_INPUT,
68 MDOC_VERIFIER_INVALID_INPUT,
69 MDOC_VERIFIER_ARGUMENTS_TOO_SMALL,
70 MDOC_VERIFIER_ATTRIBUTE_NUMBER_MISMATCH,
71 MDOC_VERIFIER_INVALID_ZK_SPEC_VERSION,
72} MdocVerifierErrorCode;
73
74// Return codes for the generate_circuit method.
75 typedef enum {
76 CIRCUIT_GENERATION_SUCCESS = 0,
77 CIRCUIT_GENERATION_NULL_INPUT,
78 CIRCUIT_GENERATION_ZLIB_FAILURE,
79 CIRCUIT_GENERATION_GENERAL_FAILURE,
80 CIRCUIT_GENERATION_INVALID_ZK_SPEC_VERSION,
81} CircuitGenerationErrorCode;
82
83// This structure represents a version of ZK specification supported by this
84// library. It is passed into all the methods for circuit generation, running
85// the prover and verifier.
86// It allows us to version the specification of the ZK system. The prover and
87// the verifier are supposed to negotiate the version of the specification they
88// both support before executing digital credential presentment.
89 typedef struct {
90 // The ZK system name and version- "longfellow-libzk-v*" for Google library.
91 const char* system;
92 // The hash of the compressed circuit (the way it's generated and passed to
93 // prover/verifier)
94 const char circuit_hash[65];
95 // The number of attributes that the circuit supports.
96 size_t num_attributes;
97 // The version of the ZK specification.
98 size_t version;
99 // The block_enc parameter for the ZK proof.
100 size_t block_enc_hash, block_enc_sig;
101} ZkSpecStruct;
102
103 static const char kDefaultDocType[] = "org.iso.18013.5.1.mDL";
104
105// An upper-bound on the decompressed circuit size. It is better to make this
106// bound tight to avoid memory failure in the resource restricted Android
107// gmscore environment.
108 static const size_t kCircuitSizeMax = 150000000;
109
110// The run_mdoc2_prover method takes byte-oriented inputs that describe a
111// circuit, mdoc, the public key of the issuer for the mdoc, a transcript
112// for the mdoc request operation, an array of RequestedAttribute that
113// represents claims that you want to prove, and a 20-char representation of the
114// current time. It writes the proof and its length into the input parameter prf
115// and proof_len. It is the responsibility of the caller to later free the proof
116// memory. If the prover fails to produce a proof, e.g., because the mdoc is
117// invalid, or the now time does not satisfy the validFrom and validUntil
118// constraints, then the prover returns an error code.
119// The following lines document how attributes can be opened in ZK.
120// {(uint8_t *)"family_name", 11, (uint8_t *)"Mustermann", 10},
121// {(uint8_t *)"height", 6, (uint8_t *)"\x18\xaf", 2},
122// {(uint8_t *)"birth_date", 10, (uint8_t *)"\xD9\x03\xEC\x6A" "1971-09-01",
123// 14},
124// {(uint8_t *)"issue_date", 10, (uint8_t *)"\xD9\x03\xEC\x6A" "2024-03-15",
125// 14},
126MdocProverErrorCode run_mdoc_prover(
127 const uint8_t* bcp, size_t bcsz, /* circuit data */
128 const uint8_t* mdoc, size_t mdoc_len, /* full mdoc */
129 const char* pkx, const char* pky, /* string rep of public key */
130 const uint8_t* transcript, size_t tr_len, /* session transcript */
131 const RequestedAttribute* attrs, size_t attrs_len,
132 const char* now, /* time formatted as "2023-11-02T09:00:00Z" */
133 uint8_t** prf, size_t* proof_len, const ZkSpecStruct* zk_spec_version);
134
135// The run_mdoc2_verifier method accepts a byte representation of the circuit,
136// the public key of the issuer, the transcript, an array of RequestedAttribute
137// that represents claims that you want to verify, and a 20-char representation
138// of the time, as well as the proof and its length.
139MdocVerifierErrorCode run_mdoc_verifier(
140 const uint8_t* bcp, size_t bcsz, /* circuit data */
141 const char* pkx, const char* pky, /* string rep of public key */
142 const uint8_t* transcript, size_t tr_len, /* session transcript */
143 const RequestedAttribute* attrs, size_t attrs_len,
144 const char* now, /* time formatted as "2023-11-02T09:00:00Z" */
145 const uint8_t* zkproof, size_t proof_len, const char* docType,
146 const ZkSpecStruct* zk_spec_version);
147
148// Produces a compressed version of the circuit bytes for the specified number
149// of attributes. The generator only supports the latest version of the ZKSpec
150// for a number of attributes. Attempt to generate older circuits will result in
151// an error.
152CircuitGenerationErrorCode generate_circuit(const ZkSpecStruct* zk_spec_version,
153 uint8_t** cb, size_t* clen);
154
155// Produces an identifier for a pair of circuits (c_1, c_2) over (Fp256, f_128)
156// respectively. This method parses the input bytes into two circuits, computes
157// the circuit's ids of each, and then computes the SHA256 hash of the two ids.
158// This method is used to identify "circuit bundles" consisting of multiple
159// circuits.
160 int circuit_id(uint8_t id[/*kSHA256DigestSize*/], const uint8_t* bcp,
161 size_t bcsz, const ZkSpecStruct* zk_spec);
162
163 enum { kNumZkSpecs = 12 };
164// This is a hardcoded list of all the ZK specifications supported by this
165// library. Every time a new breaking change is introduced in either the circuit
166// format or its interpretation, a new version must be added here.
167// It is possible to remove old versions, if we're sure that they are not used
168// by either provers of verifiers in the wild.
169 extern const ZkSpecStruct kZkSpecs[kNumZkSpecs];
170
171// Returns a static pointer to the ZkSpecStruct that matches the given system
172// name and circuit hash. Returns nullptr if no matching ZkSpecStruct is found.
173 const ZkSpecStruct* find_zk_spec(const char* system_name,
174 const char* circuit_hash);
175
176#ifdef __cplusplus
177}
178#endif
179
180#endif // PRIVACY_PROOFS_ZK_LIB_CIRCUITS_MDOC_MDOC_ZK_H_
RequestedAttribute
Definition mdoc_zk.h:39
ZkSpecStruct
Definition mdoc_zk.h:89