| For accelerating the computation of aG:
|
| To harden against timing attacks, use the
| following mechanism:
|
| - Break up the multiplicand into groups of
| PREC_B bits, called n_0, n_1, n_2, …,
| n_(PREC_N-1).
|
| - Compute sum(n_i * (PREC_G)^i * G + U_i,
| i=0 … PREC_N-1), where:
|
| - U_i = U * 2^i, for i=0 … PREC_N-2
|
| - U_i = U * (1-2^(PREC_N-1)), for i=PREC_N-1
| where U is a point with no known
| corresponding scalar. Note that sum(U_i,
| i=0 … PREC_N-1) = 0.
|
| For each i, and each of the PREC_G possible
| values of n_i, (n_i * (PREC_G)^i * G + U_i)
| is precomputed (call it prec(i, n_i)). The
| formula now becomes sum(prec(i, n_i), i=0
| … PREC_N-1).
|
| None of the resulting prec group elements
| have a known scalar, and neither do any of
| the intermediate sums while computing aG.
| Opaque data structure that holds context
| information (precomputed tables etc.).
|
| The purpose of context structures is
| to cache large precomputed data tables
| that are expensive to construct, and
| also to maintain the randomization
| data for blinding.
|
| Do not create a new context object for
| each operation, as construction is
| far slower than all other API calls (~100
| times slower than an ECDSA verification).
|
| A constructed context can safely be
| used from multiple threads simultaneously,
| but API calls that take a non-const pointer
| to a context need exclusive access to
| it. In particular this is the case for
| context_destroy, context_preallocated_destroy,
| and context_randomize.
|
| Regarding randomization, either do
| it once at creation time (in which case
| you do not need any locking for the other
| calls), or use a read-write lock.
|
| Opaque data structured that holds a
| parsed ECDSA signature.
|
| The exact representation of data inside
| is implementation defined and not guaranteed
| to be portable between different platforms
| or versions. It is however guaranteed
| to be 64 bytes in size, and can be safely
| copied/moved.
|
| If you need to convert to a format suitable
| for storage, transmission, or comparison,
| use the ecdsa_signature_serialize_*
| and ecdsa_signature_parse_* functions.
|
| Larger values for ECMULT_WINDOW_SIZE result in
| possibly better performance at the cost of an
| exponentially larger precomputed table. The
| exact table size is
|
| (1 << (WINDOW_G - 2))
| * sizeof(ge_storage) bytes,
|
| where sizeof(ge_storage) is
| typically 64 bytes but can be larger due to
| platform-specific padding and alignment.
|
| Two tables of this size are used (due to the
| endomorphism optimization).
| Create a secp256k1 context object (in
| dynamically allocated memory).
|
| This function uses malloc to allocate
| memory. It is guaranteed that malloc
| is called at most once for every call
| of this function. If you need to avoid
| dynamic memory allocation entirely,
| see the functions in preallocated.h.
|
| Returns: a newly created context object.
|
| In: flags: which parts of the context
| to initialize.
|
| See also context_randomize.
|
| Destroy a secp256k1 context object
| (created in dynamically allocated
| memory).
|
| The context pointer may not be used afterwards.
|
| The context to destroy must have been
| created using context_create or context_clone.
| If the context has instead been created
| using context_preallocated_create
| or context_preallocated_clone, the
| behaviour is undefined. In that case,
| context_preallocated_destroy must
| be used instead.
|
| Args: ctx: an existing context to destroy,
| constructed using context_create
| or context_clone
|
| This serializes to a DER encoding of
| the ECPrivateKey type from section
| C.4 of SEC 1 https://www.secg.org/sec1-v2.pdf.
| The optional parameters and publicKey
| fields are included.
|
| seckey must point to an output buffer
| of length at least CKey::SIZE bytes.
| seckeylen must initially be set to the
| size of the seckey buffer. Upon return
| it will be set to the number of bytes used
| in the buffer. key32 must point to a 32-byte
| raw private key.
|
| This parses a format loosely based on
| a DER encoding of the ECPrivateKey type
| from section C.4 of SEC 1 https://www.secg.org/sec1-v2.pdf,
| with the following caveats:
|
| - The octet-length of the SEQUENCE must
| be encoded as 1 or 2 octets. It is not required
| to be encoded as one octet if it is less
| than 256, as DER would require.
|
| - The octet-length of the SEQUENCE must
| not be greater than the remaining length
| of the key encoding, but need not match
| it (i.e. the encoding may contain junk
| after the encoded SEQUENCE).
|
| - The privateKey OCTET STRING is zero-filled
| on the left to 32 octets.
|
| - Anything after the encoding of the
| privateKey OCTET STRING is ignored,
| whether or not it is validly encoded
| DER. out32 must point to an output buffer
| of length at least 32 bytes.
|
| This function is taken from the libsecp256k1
| distribution and implements
|
| DER parsing for ECDSA signatures, while
| supporting an arbitrary subset of format
| violations.
|
| Supported violations include negative
| integers, excessive padding, garbage
| at the end, and overly long length descriptors.
| This is safe to use in
|
| Bitcoin because since the activation
| of BIP66, signatures are verified to
| be strict DER before being passed to
| this module, and we know it supports
| all violations present in the blockchain
| before that point.
|
| Multiply: R = q*A (in constant-time)
|
| Here bits should be set to the maximum
| bitlength of the absolute value of
| q, plus one because we internally
| sometimes add 2 to the number during
| the WNAF conversion.
|
| Multi-multiply:
| R = inp_g_sc * G + sum_i ni * Ai.
|
| Chooses the right algorithm for a given number
| of points and scratch space size.
|
| Resets and overwrites the given scratch
| space. If the points do not fit in the scratch
| space the algorithm is repeatedly run with
| batches of points.
|
| If no scratch space is given then a simple
| algorithm is used that simply multiplies the
| points with the corresponding scalars and adds
| them up.
|
| Returns:
|
| 1 on success (including when inp_g_sc is NULL
| and n is 0)
|
| 0 if there is not enough scratch space for
| a single point or callback returns 0
| Fill a table ‘prej’ with precomputed
| odd multiples of a. Prej will contain
| the values [1a,3a,…,(2*n-1)*a],
| so it space for n values. zr[0] will contain
| prej[0].z / a.z. The other zr[i] values
| = prej[i].z / prej[i-1].z.
|
| Prej’s Z values are undefined, except
| for the last value.
|
| Fill a table ‘pre’ with precomputed
| odd multiples of a.
|
| There are two versions of this function:
|
| - ecmult_odd_multiples_table_globalz_windowa
| which brings its resulting point set
| to a single constant Z denominator,
| stores the X and Y coordinates as ge_storage
| points in pre, and stores the global
| Z in rz.
|
| It only operates on tables sized for
| WINDOW_A wnaf multiples.
|
| - ecmult_odd_multiples_table_storage_var,
| which converts its resulting point
| set to actually affine points, and stores
| those in pre.
|
| It operates on tables of any size.
|
| To compute aP + bG, we compute a table
| for P using the first function, and for
| G using the second (which requires an
| inverse, but it only needs to happen
| once).
|
| pippenger_wnaf computes the result of
| a multi-point multiplication as follows:
|
| The scalars are brought into wnaf with n_wnaf
| elements each.
|
| Then for every i < n_wnaf, first each point is
| added to a “bucket” corresponding to the
| point’s wnaf[i].
|
| Second, the buckets are added together such
| that r += 1bucket[0] + 3bucket[1]
| + 5*bucket[2] + …
| Convert a number to WNAF notation. The
| number becomes represented by sum(2^i
| * wnaf[i], i=0..bits), with the following
| guarantees:
|
| - each wnaf[i] is either 0, or an odd integer
| between -(1<<(w-1) - 1) and (1<<(w-1)
| - 1)
|
| - two non-zero entries in wnaf are separated
| by at least w-1 zeroes.
|
| - the number of set values in wnaf is returned.
| This number is at most 256, and at most
| one more than the number of bits in the
| (absolute value) of the input.
|
| Returns the maximum number of points
| in addition to G that can be used with
| a given scratch space. The function
| ensures that fewer points may also be
| used.
|
| Convert a number to WNAF notation.
|
| The number becomes represented by
| sum(2^{wi} * wnaf[i], i=0..WNAF_SIZE(w)+1) - return_val.
|
| It has the following guarantees:
|
| - each wnaf[i] an odd integer
| between -(1 << w) and (1 << w)
|
| - each wnaf[i] is nonzero
|
| - the number of words set is always
| WNAF_SIZE(w) + 1
|
| Adapted from The Width-w NAF Method Provides | Small Memory and Fast Elliptic Scalar | Multiplications Secure against Side Channel | Attacks, Okeya and Tagaki. M. Joye (Ed.)
| CT-RSA 2003, LNCS 2612, pp. 328-443,
| 2003. Springer-Verlag Berlin Heidelberg 2003
|
| Numbers reference steps of Algorithm | SPA-resistant Width-w NAF with Odd Scalar on
| pp. 335
| Convert a number to WNAF notation.
|
| The number becomes represented by sum(2^{wi}
| * wnaf[i], i=0..WNAF_SIZE(w)+1) -
| return_val.
|
| It has the following guarantees:
|
| - each wnaf[i] is either 0 or an odd integer
| between -(1 << w) and (1 << w)
|
| - the number of words set is always WNAF_SIZE(w)
|
| - the returned skew is 0 or 1
|
| A pointer to a function that hashes an EC point
| to obtain an ECDH secret
|
| Returns: 1 if the point was successfully
| hashed.
|
| 0 will cause ecdh to fail and return 0.
|
| Other return values are not allowed,
| and the behaviour of ecdh is
| undefined for other return values.
|
| Out: output: pointer to an array to be
| filled by the function
|
| In: x32: pointer to a 32-byte
| x coordinate
|
| y32: pointer to a 32-byte
| y coordinate
|
| data: arbitrary data pointer
| that is passed through
| A pointer to a function to deterministically
| generate a nonce.
|
| Returns: 1 if a nonce was successfully
| generated. 0 will cause signing to fail.
|
| Out: nonce32: pointer to a 32-byte array
| to be filled by the
| function.
|
| In: msg32: the 32-byte message hash
| being verified (will not be
| NULL)
|
| key32: pointer to a 32-byte secret
| key (will not be NULL)
|
| algo16: pointer to a 16-byte array
| describing the signature
| algorithm (will be NULL for
| ECDSA for compatibility).
|
| data: Arbitrary data pointer that
| is passed through.
|
| attempt: how many iterations we have
| tried to find a nonce.
| This will almost always be
| 0, but different attempt
| values are required to
| result in a different
| nonce.
|
| Except for test cases, this function should
| compute some cryptographic hash of the message,
| the algorithm, the key and the attempt.