doc.go 5.9 KB

  1. /*
  2. Package kyber provides a toolbox of advanced cryptographic primitives,
  3. for applications that need more than straightforward signing and encryption.
  4. This top level package defines the interfaces to cryptographic primitives
  5. designed to be independent of specific cryptographic algorithms,
  6. to facilitate upgrading applications to new cryptographic algorithms
  7. or switching to alternative algorithms for experimentation purposes.
  8. Abstract Groups
  9. This toolkits public-key crypto API includes a kyber.Group interface
  10. supporting a broad class of group-based public-key primitives
  11. including DSA-style integer residue groups and elliptic curve groups. Users of
  12. this API can write higher-level crypto algorithms such as zero-knowledge
  13. proofs without knowing or caring exactly what kind of group, let alone which
  14. precise security parameters or elliptic curves, are being used. The kyber.Group
  15. interface supports the standard algebraic operations on group elements and
  16. scalars that nontrivial public-key algorithms tend to rely on. The interface
  17. uses additive group terminology typical for elliptic curves, such that point
  18. addition is homomorphically equivalent to adding their (potentially secret)
  19. scalar multipliers. But the API and its operations apply equally well to
  20. DSA-style integer groups.
  21. As a trivial example, generating a public/private keypair is as simple as:
  22. suite := suites.MustFind("Ed25519") // Use the edwards25519-curve
  23. a := suite.Scalar().Pick(suite.RandomStream()) // Alice's private key
  24. A := suite.Point().Mul(a, nil) // Alice's public key
  25. The first statement picks a private key (Scalar) from a the suites's source of
  26. cryptographic random or pseudo-random bits, while the second performs elliptic
  27. curve scalar multiplication of the curve's standard base point (indicated by the
  28. 'nil' argument to Mul) by the scalar private key 'a'. Similarly, computing a
  29. Diffie-Hellman shared secret using Alice's private key 'a' and Bob's public key
  30. 'B' can be done via:
  31. S := suite.Point().Mul(a, B) // Shared Diffie-Hellman secret
  32. Note that we use 'Mul' rather than 'Exp' here because the library uses
  33. the additive-group terminology common for elliptic curve crypto,
  34. rather than the multiplicative-group terminology of traditional
  35. integer groups - but the two are semantically equivalent and the
  36. interface itself works for both elliptic curve and integer groups.
  37. Higher-level Building Blocks
  38. Various sub-packages provide several specific
  39. implementations of these cryptographic interfaces.
  40. In particular, the 'group/mod' sub-package provides implementations
  41. of modular integer groups underlying conventional DSA-style algorithms.
  42. The `group/nist` package provides NIST-standardized elliptic curves built on
  43. the Go crypto library.
  44. The 'group/edwards25519' sub-package provides the kyber.Group interface
  45. using the popular Ed25519 curve.
  46. Other sub-packages build more interesting high-level cryptographic tools
  47. atop these primitive interfaces, including:
  48. - share: Polynomial commitment and verifiable Shamir secret splitting
  49. for implementing verifiable 't-of-n' threshold cryptographic schemes.
  50. This can be used to encrypt a message so that any 2 out of 3 receivers
  51. must work together to decrypt it, for example.
  52. - proof: An implementation of the general Camenisch/Stadler framework
  53. for discrete logarithm knowledge proofs.
  54. This system supports both interactive and non-interactive proofs
  55. of a wide variety of statements such as,
  56. "I know the secret x associated with public key X
  57. or I know the secret y associated with public key Y",
  58. without revealing anything about either secret
  59. or even which branch of the "or" clause is true.
  60. - sign: The sign directory contains different signature schemes.
  61. - sign/anon provides anonymous and pseudonymous public-key encryption and signing,
  62. where the sender of a signed message or the receiver of an encrypted message
  63. is defined as an explicit anonymity set containing several public keys
  64. rather than just one. For example, a member of an organization's board of trustees
  65. might prove to be a member of the board without revealing which member she is.
  66. - sign/cosi provides collective signature algorithm, where a bunch of signers create a
  67. unique, compact and efficiently verifiable signature using the Schnorr signature as a basis.
  68. - sign/eddsa provides a kyber-native implementation of the EdDSA signature scheme.
  69. - sign/schnorr provides a basic vanilla Schnorr signature scheme implementation.
  70. - shuffle: Verifiable cryptographic shuffles of ElGamal ciphertexts,
  71. which can be used to implement (for example) voting or auction schemes
  72. that keep the sources of individual votes or bids private
  73. without anyone having to trust more than one of the shuffler(s) to shuffle
  74. votes/bids honestly.
  75. Target Use-cases
  76. As should be obvious, this library is intended to be used by
  77. developers who are at least moderately knowledgeable about
  78. cryptography. If you want a crypto library that makes it easy to
  79. implement "basic crypto" functionality correctly - i.e., plain
  80. public-key encryption and signing - then
  81. [NaCl secretbox](
  82. may be a better choice. This toolkit's purpose is to make it possible
  83. - and preferably easy - to do slightly more interesting things that
  84. most current crypto libraries don't support effectively. The one
  85. existing crypto library that this toolkit is probably most comparable
  86. to is the Charm rapid prototyping library for Python
  87. (
  88. This library incorporates and/or builds on existing code from a variety of
  89. sources, as documented in the relevant sub-packages.
  90. Reporting Security Problems
  91. This library is offered as-is, and without a guarantee. It will need an
  92. independent security review before it should be considered ready for use in
  93. security-critical applications. If you integrate Kyber into your application it
  94. is YOUR RESPONSIBILITY to arrange for that audit.
  95. If you notice a possible security problem, please report it
  96. to
  97. */
  98. package kyber