libfrost.rst (6222B)
1 .. 2 This file is part of Frosix. 3 Copyright (C) 2022, 2023 Joel Urech 4 5 Frosix is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 2.1, or (at your option) any later version. 8 9 Frosix is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 Frosix; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Joel Urech 17 18 ============================ 19 How to use Frosix's Libfrost 20 ============================ 21 22 The library libfrost is an implementation of the FROST protocol and does not reflect the latest design decisions of Frosix at the moment. 23 Additionally, the distributed key generation is generating correct key material, but needs a revision and a stricter typification. 24 25 26 Key Generation 27 ============== 28 29 Libfrost provides two possibilities to generate key pairs. 30 31 32 Trusted Dealer 33 ^^^^^^^^^^^^^^ 34 35 Trusted dealer should only be used for testing purposes! 36 With trusted dealer everything can be generated by itself and the need for several participants to generate keys is eliminated. 37 But also the main security property of the whole system is eliminated and can not be guaranteed. 38 The reason for this is the fact, that with trusted dealer the secret key exists for a short time. But that could be enough for a strong attacker to learn and therefore misuse the secret key. 39 40 To let Libfrost create key pairs with trusted dealer, just call the function below and provide the number of key shares (num_of_participants) and the threshold value. 41 42 ``FROST_trusted_dealer_keygen (key_pairs[], num_of_participants, threshold)`` 43 44 45 Distributed Key Generation 46 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 47 48 Round 1 49 ------- 50 51 First every participant initializes an object of the struct FROST_DkgCommitment. 52 This will allocate some memory on the heap. The threshold value must be already known. 53 54 ``FROST_initialize_dkg_commitment (dkg_commitment, my_index, threshold)`` 55 56 Every participant does now makes a kind of a trusted dealer on his own and commits to each of the t-1 values of the created polynomial. 57 Additionally, every participant has to compute a zero knowledge proof of the underlying secret (y-value of the point x=0 on the polynomial). 58 59 This function below does all of this and returns a commitment and a share for each participant. 60 The commitment should now be send to all other participants. But do not send the dkg shares! 61 62 ``FROST_keygen_begin (*dkg_commitment, dkg_shares[], my_index, num_of_participants, threshold)`` 63 64 65 Round 2 66 ------- 67 68 Before receiving the commitments, one should initialize further objects of type FROST_DkgCommitment. 69 70 After receiving all commitments from all other participants, they have to be validated. 71 This means, that every value will be checked if it is a point on the curve25519 and correctly encoded. 72 Additionally the included zero knowledge proof will be validated as well. 73 74 If any of the participants commitment or zero knowledge proof fails the validation, exclude this participant. 75 76 ``FROST_keygen_receive_commitments_and_validate_peers (dkg_commitments[], num_of_participants)`` 77 78 79 Round 3 80 ------- 81 82 Finally send to each participant his share and also receive from each participant a share. 83 This shares will be verified against the previously received commitments. 84 If this check failes, the distributed key generation process must be restarted without the failing participant. 85 But if all received shares are correct, this function computes the individual key pair and also derives the group public key from all commitments. 86 87 ``FROST_keygen_finalize (*key_pair, my_index, shares[], commitments[], num_of_participants)`` 88 89 In the end, every initialized struct should be properly freed. 90 91 ``FROST_free_dkg_commitment (*dkg_commitment)`` 92 93 Every participant now has a key share and can participate in a signing process. 94 95 96 Sign a message 97 ============== 98 99 Round 1 100 ^^^^^^^ 101 102 The Signature Aggregator 'SA' chooses 't' (t = threshold) random participants out of all available participants and asks them to send him a commitment. 103 104 Each chosen participant generates a nonce and a commitment and sends the commitment back to the 'SA'. 105 The nonce should be stored securely, we will use it in round 2. 106 107 ``FROST_generate_nonce_and_commitment (nonce, commitment, my_key_pair)`` 108 109 110 Round 2 111 ^^^^^^^ 112 113 To issue a signature over an arbitrary long message (msg with length msg_len), the message must first be converted to a point on the curve by the 'SA'. 114 115 ``FROST_message_to_hash (message_hash, msg, msg_len)`` 116 117 The 'SA' constructs then a sorted list out of all received commitments and send this list of commitments together with the message hash to each chosen participant. 118 Each chosen participant validates the data from the 'SA' and aborts if the validation failes. 119 120 ``FROST_validate_message_hash_and_commitments (message_hash, commitments[], commitments_len))`` 121 122 123 If all data from the 'SA' are valid, every chosen participant computes a signature share and sends this signature share back to the 'SA'. 124 125 ``FROST_sign_message_hash (signature_share, mesage_hash, commitments[], commitments_len, my_key_pair, my_nonce)`` 126 127 The 'SA' receives and verifies each partial signature and aborts if the verification fails. 128 129 ``FROST_verify_signature_share (commitment_i, signature_share_i, commitments[], commitments_len, public_key, message_hash)`` 130 131 If all partial signatures are succesfully verified, the 'SA' finally creates the signature. 132 133 ``FROST_compose_signature (signature, commitments[], signature_shares[], commitments_and_sig_shares_len, message_hash)`` 134 135 136 Verify 137 ====== 138 139 The verification of a given signature over a specific message is simple. Just call the function below with the public key, the signature and the hash of the message. 140 If the return value is 1, the signature is correct. 141 142 ``FROST_verify_signature (public_key, signature, message_hash)``