initial addition of essential crypto, encoders, workflows and LLM instructions

pkg/crypto/ec/schnorr/doc.go

@@ -0,0 +1,103 @@
+// Copyright (c) 2020-2022 The Decred developers
+// Use of this source code is governed by an ISC
+// license that can be found in the LICENSE file.
+
+// Package schnorr provides custom Schnorr signing and verification via
+// secp256k1.
+//
+// This package provides data structures and functions necessary to produce and
+// verify deterministic canonical Schnorr signatures using a custom scheme named
+// EC-Schnorr-DCRv0 that is described herein. The signatures and implementation
+// are optimized specifically for the secp256k1 curve. See
+// https://www.secg.org/sec2-v2.pdf for details on the secp256k1 standard.
+//
+// It also provides functions to parse and serialize the Schnorr signatures
+// according to the specification described herein.
+//
+// A comprehensive suite of tests is provided to ensure proper functionality.
+//
+// # Overview
+//
+// A Schnorr signature is a digital signature scheme that is known for its
+// simplicity, provable security and efficient generation of short signatures.
+//
+// It provides many advantages over ECDSA signatures that make them ideal for
+// use with the only real downside being that they are not well standardized at
+// the time of this writing.
+//
+// Some of the advantages over ECDSA include:
+//
+//   - They are linear which makes them easier to aggregate and use in
+//     protocols that  build on them such as multi-party signatures, threshold
+//     signatures, adaptor signatures, and blind signatures
+//   - They are provably secure with weaker assumptions than the best known
+//     security proofs for ECDSA
+//   - Specifically Schnorr signatures are provably secure under SUF-CMA (Strong
+//     Existential Unforgeability under Chosen Message Attack) in the ROM
+//     (Random Oracle Model) which guarantees that as long as the hash
+//     function behaves ideally, the only way to break Schnorr signatures is
+//     by solving the ECDLP (Elliptic Curve Discrete Logarithm Problem).
+//   - Their relatively straightforward and efficient aggregation properties
+//     make them excellent for scalability and allow them to provide some nice
+//     secrecy characteristics
+//   - They support faster batch verification unlike the standardized version of
+//     ECDSA signatures
+//
+// # Custom Schnorr-based Signature Scheme
+//
+// As mentioned in the overview, the primary downside of Schnorr signatures for
+// elliptic curves is that they are not standardized as well as ECDSA signatures,
+// which means there are a number of variations that are not compatible with
+// each other.
+//
+// In addition, many of the standardization attempts have had various
+// disadvantages that make them unsuitable for use in Decred. Some of these
+// details and some insight into the design decisions made are discussed further
+// in the README.md file.
+//
+// Consequently, this package implements a custom Schnorr-based signature scheme
+// named EC-Schnorr-DCRv0 suitable for use in Decred.
+//
+// The following provides a high-level overview of the key design features of
+// the scheme:
+//
+//   - Uses signatures of the form (R, s)
+//   - Produces 64-byte signatures by only encoding the x coordinate of R
+//   - Enforces even y coordinates for R to support efficient verification by
+//     disambiguating the two possible y coordinates
+//   - Canonically encodes by both components of the signature with 32-bytes
+//     each
+//   - Uses BLAKE-256 with 14 rounds for the hash function to calculate
+//     challenge e
+//   - Uses RFC6979 to obviate the need for an entropy source at signing time
+//   - Produces deterministic signatures for a given message and secret key pair
+//
+// # EC-Schnorr-DCRv0 Specification
+//
+// See the README.md file for the specific details of the signing and
+// verification algorithm as well as the signature serialization format.
+//
+// # Future Design Considerations
+//
+// It is worth noting that there are some additional optimizations and
+// modifications that have been identified since the introduction of
+// EC-Schnorr-DCRv0 that can be made to further harden security for multi-party
+// and threshold signature use cases as well provide the opportunity for faster
+// signature verification with a sufficiently optimized implementation.
+//
+// However, the v0 scheme is used in the existing consensus rules and any
+// changes to the signature scheme would invalidate existing uses. Therefore
+// changes in this regard will need to come in the form of a v1 signature scheme
+// and be accompanied by the necessary consensus updates.
+//
+// # Schnorr use in Decred
+//
+// At the time of this writing, Schnorr signatures are not yet in widespread use
+// on the Decred network, largely due to the current lack of support in wallets
+// and infrastructure for secure multi-party and threshold signatures.
+//
+// However, the consensus rules and scripting engine supports the necessary
+// primitives and given many of the beneficial properties of Schnorr signatures,
+// a good goal is to work towards providing the additional infrastructure to
+// increase their usage.
+package schnorr