diff --git a/README b/README index ce029ca..d686883 100644 --- a/README +++ b/README @@ -1,20 +1,280 @@ -General Information -=================== +Cryptic 1.1.0 -Cryptographic tools and protocols +Copyright (c) 2009-2011 Entr'ouvert +Copyright (c) 2009 Ates Mikael +All rights reserved. -Installation -============ +INTRODUCTION +------------ -Please check the Makefile before trying to compile. -Then, +Cryptic - Cryptographic tools and protocols +Cryptic is a free software library released under the GNU GPL v2 and above +license. + +Cryptic allows the implementation of digital certificates with advanced +properties. The goal is to ensure privacy for cross-organization exchanges of +certified data. + +Cryptic is written in C language and depends on glib and openssl. Bindings for +the Python and Java languages are provided. + +REPOSITORY +---------- + + * git@repos.entrouvert.org:cryptic.git + +LISTS +----- + + * Development: cryptic-devel (archive) + * Git commits: cryptic-commits (archive) + +DESCRIPTION +----------- + +Advanced certificates helps in reducing the certified information disclosed to +verifiers. The certificates have the following properties: + * Selective disclosure of content. + * Proofs on attributes contained in certificates. + * Unlinkability between certificate issuing and showing transactions. + +The Cryptic library can be used to create at a low-level certificates with the +properties previously enumerated. The certificate formatting, in XML or ASN1 +for instance, is not handled in Cryptic. + +The goal is a fine-grained information disclosure for off-line certificates. +Such certificates may be used multiple times without re-issuing. When a +certificate is issued on demand, it is trivial to make it includes only the +needed information. However, when the certificate is already issued, it is +useful to have means to select which signed information is revealed. For +instance, the selective disclosure allows to reveal a date of birth and not a +place of birth both contained in the same certificate. A range proof allows to +only reveal that the certificate prover is of age and not reveal the date of +birth contained in the certificate. + +A certificate is said 'proved' because a secret is included in the +certificate. To only show a certificate require to prove to verifier that the +secret is known without revealing it. (It is similar to prove the knowledge of +a private key making a signature. In a way, the public key is proved as a +certificate is proved.) + +Certificate holder is a term usually avoided because it may refer to bearer +tokens. Holder may be used if it is taken as a synomous to know the secret of +the certificate hold. + +Furthermore, the CL-Signature implementation allows the unlinkability of a +certificate issued with this certificate shown to verifiers. In other words, +the certificate signature can not be used as a factor of linkability between +to transactions involving a same certificate. (But many other factors may be +used (time correlation, attribute contents, etc.), unlinkability is a huge +paradigm.) + +The unlinkability may be expected when a user shows multiple times a same +certificate or between the issuing and showing transactions of this +certificate. The unlinkability of the user transactions is a strong property +of anonymity and ion some cases a privacy-preserving principle. + +For instance, Cryptic can be used to implement e-cash and e-voting +architectures. + +The library does not deal with storage and protocols, only computation. + +OVERVIEW +-------- + +The library includes: + +libcryptic.a: + Group generation + Prime order group + Quadratic residues group + + Signature schemas + Camenisch-Lysyanskaya Signature (CL-Signature) + + Proof of Knowledge + Schnorr zero-knowledge proof of knowledge protocol. + Range proofs on integers + +INSTALLATION +------------ + +Please check the Makefile before compiling. +Then, autogen.sh make + make check make install -Author -====== +QUICK START +----------- -Mikaël Ates +See tests/tests.c, bindings/python/examples/sample.py, +bindings/java/Myclass.java +BITS OF DOCUMENTATION +--------------------- + +*** Error Codes *** + + Error codes are listed in error.h. + - Functions return a negative error code on failure and 0 either + - Except verification functions that return 1 on success and <= 0 on + failure + - Getters return NULL if no member + Take care that functions cryptic_clsig_load_certificate* verify the + signatures but return 0 on success including the checking of a valid + signature. + +*** Generic helper functions *** + + Many helper functions are defined in utils.h + +*** Maths directory *** + +Class: CrypticPrimeOrderGroup + + Allows to create a prime order group. + This kind of group can be used for zero knowledge proofs of knowledge. + + The group has prime modulus p. p is a safe prime. + p = 2pp + 1 with pp also prime. + The generator of the group is g. + + To create a prime order group with a modulus of size 512 bits: + CrypticPrimeOrderGroup *g = NULL; + g = cryptic_prime_order_group_new(512); + + The classe has a member that is a table of generators that may be used as + bases for proofs. This table is filled with the function + cryptic_prime_order_group_more_bases(). + For instance, cryptic_prime_order_group_more_bases(g,10); + +Class: CrypticQRG + + Allows to create a quadratic residues group. + Such a group is used by the Camenisch-Lysyanskaya signature. + + Two safe primes p and q. p = 2pp +1 and q = 2qq +1 + n = pq + The QRG is the multiplicative group Z_n^* + The order is pp*qq + A base (a quadratic residue) is picked from the group: + From a random r of size n: + qr = r^2 mod n and qr != 1 and coprime(qr-1,n) + + Other quadratic residues are generated from the first picked. + With a random of size the group order: + New_qr = qr^rand mod n + + Functions to pick qrs: + int cryptic_qrg_pick_base(CrypticQRG *qrg, BIGNUM *out_base); + int cryptic_qrg_pick_k_bases(CrypticQRG *qrg, BIGNUM **out_bases, + int nb_bases); + +Class: CrypticDecomposeInteger + + Decompose an integer in four squares. + Used in range proofs. + + CrypticDecomposeInteger* decomposition = NULL; + decomposition = cryptic_decompose_integer_new(numToDecompose); + cryptic_print_bn("first square: ", decomposition->a); + cryptic_print_bn("second square: ", decomposition->b); + cryptic_print_bn("thrid square: ", decomposition->c); + cryptic_print_bn("forth square: ", decomposition->d); + +utils files + + Basic functions. + Up to now, only random numbers are necessary. + - The random value is returned in parameter and an error code is returned: + int cryptic_find_random(BIGNUM *ret, int size); + int cryptic_find_random_with_range_value(BIGNUM *ret, BIGNUM *value); + - Without error code: + BIGNUM* cryptic_ret_random(int size); + BIGNUM* cryptic_ret_random_with_range_value(BIGNUM *value); + +*** Protocols directory *** + +** Schnorr proof of knowledge (pok_schnorr directory) ** + +Class: CrypticZkpkSchnorr + + Used to lead Zero knowledge proof of knowledge with the Schnorr protocol. + Let g be the generator of a group of prime order q. + + Assume that you know y=g^x and as a prover you want to prove that you know + x to the verifier who knows y without revealing x and the verifier learns + with a negligeable probability nothing about x. + You pick a random and send the commitment: t = g^r + The verifier challenges you with c + you prove that you know x responding: s = r - cx + The verifier check that t ?= y^c . g^s + Explanation: s = r -cx <=> r = s + cx + <=> g^r = g^s + g^cx <=> g^r = g^s + (g^x)^c + + You can prove like this any discrete logarithm representation (DLREP). + A dlrep looks like dlrep = g1^q1 . ... . gi^qi + Then you want to prove that you know {q1,...,qi} to a verifier who knows + dlrep. + {g1,...,gi} are prime ordre group bases shared between the prover and the + verifier. + + Both the prover and the verifier init their proof the same way + CrypticZkpkSchnorr* shn_prover = NULL; + shn_prover = cryptic_zkpk_schnorr_new(bases, nb_quantities, modulus); + + The prover computes the commitment with + cryptic_zkpk_schnorr_round1(shn_prover); + and sends the commitment to the verifier shn_prover->commitment + The prover receives the challenge and compute the responses, one per + quantity to prove. + cryptic_zkpk_schnorr_round2(shn_prover, order, challenge, quantities); + and sends the responses to the verifier shn_prover->responses + The verifier verifies the proof with + cryptic_zkpk_schnorr_verify_interactive_proof(shn_verifier, dlrep, + commitment, challenge, responses); + + The order to compute the responses in not mandatory. however if not used + the random must be >> cx to keep the zero knowledge. This is useful + because in some cases the verifier is not assumed to know the group order + with cryptic_zkpk_schnorr_round2_without_order() + + You have noticed that the randoms used in the commitment are generated + into the function. However, in some cases you need to combine proofs to + prove statements on the same quantity in two different proofs. We you lead + this kind of proofs you must use the same random number in the two proofs + when you to prove that the quantity is the same. You deduce that the + answer will be the same for the two proofs. + The first round function can then be used with randoms given in parameters. + You generate them by yourself and then give them in parameters arranged as + you want. + cryptic_zkpk_schnorr_round1_one_random_chosen(shn, random, position); + cryptic_zkpk_schnorr_round1_randoms_chosen(shn, randoms); + + The proof previously presented is an interactive proof relying on a + challenge freshly generated by the verifier after the commitment. + Using the random oracle model played by a hash function, it is feasible + to realise a non-interactive proof. + The details on how to compute the hash are given later because the class + CrypticHashForNiProofs is dedicated for this purpose. + However th hash is tipically of the form of a concatenation + modulus || bases || dlrep || Commitment and then hashed. + Only the verifier function differs + cryptic_zkpk_schnorr_verify_noninteractive_proof(shn, dlrep, hash, + responses); + From the prover point of view, the prover needs to generate the hash and + give it as a parameter instead of the challenge to compute the responses. + +*** Utils directory *** + +print files + + Function used to print bignums and display CLSIG structure parameters + +AUTHOR +------ + +Mikaël Ates