doc_test.go 4.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125
  1. // doc_test.go - Kyber godoc examples.
  2. //
  3. // To the extent possible under law, Yawning Angel has waived all copyright
  4. // and related or neighboring rights to the software, using the Creative
  5. // Commons "CC0" public domain dedication. See LICENSE or
  6. // <http://creativecommons.org/publicdomain/zero/1.0/> for full details.
  7. package kyber
  8. import (
  9. "bytes"
  10. "crypto/rand"
  11. )
  12. func Example_keyEncapsulationMechanism() {
  13. // Unauthenticated Key Encapsulation Mechanism (KEM)
  14. // Alice, step 1: Generate a key pair.
  15. alicePublicKey, alicePrivateKey, err := Kyber768.GenerateKeyPair(rand.Reader)
  16. if err != nil {
  17. panic(err)
  18. }
  19. // Alice, step 2: Send the public key to Bob (Not shown).
  20. // Bob, step 1: Deserialize Alice's public key from the binary encoding.
  21. peerPublicKey, err := Kyber768.PublicKeyFromBytes(alicePublicKey.Bytes())
  22. if err != nil {
  23. panic(err)
  24. }
  25. // Bob, step 2: Generate the KEM cipher text and shared secret.
  26. cipherText, bobSharedSecret, err := peerPublicKey.KEMEncrypt(rand.Reader)
  27. if err != nil {
  28. panic(err)
  29. }
  30. // Bob, step 3: Send the cipher text to Alice (Not shown).
  31. // Alice, step 3: Decrypt the KEM cipher text.
  32. aliceSharedSecret := alicePrivateKey.KEMDecrypt(cipherText)
  33. // Alice and Bob have identical values for the shared secrets.
  34. if bytes.Equal(aliceSharedSecret, bobSharedSecret) {
  35. panic("Shared secrets mismatch")
  36. }
  37. }
  38. func Example_keyExchangeUnilateralAuth() {
  39. // Unilaterally-Authenticated Key Exchange (UAKE)
  40. // Alice, step 0: Generate a long-term (static) key pair, the public
  41. // component of which is shared with Bob prior to the actual key exchange.
  42. aliceStaticPublicKey, aliceStaticPrivateKey, err := Kyber768.GenerateKeyPair(rand.Reader)
  43. if err != nil {
  44. panic(err)
  45. }
  46. // Bob, step 1: Initialize the key exchange.
  47. //
  48. // WARNING: The state MUST NOT be use for more than one key exchange,
  49. // successful or not.
  50. bobState, err := aliceStaticPublicKey.NewUAKEInitiatorState(rand.Reader)
  51. if err != nil {
  52. panic(err)
  53. }
  54. // Bob, step 2: Send the key exchange message to Alice (Not shown).
  55. // Alice, step 1: Generates a responder message and shared secret.
  56. aliceMessage, aliceSharedSecret := aliceStaticPrivateKey.UAKEResponderShared(rand.Reader, bobState.Message)
  57. // Alice, step 2: Send the responder message to Bob (Not shown).
  58. // Bob, step 3: Generate the shared secret.
  59. bobSharedSecret := bobState.Shared(aliceMessage)
  60. // Alice and Bob have identical values for the shared secrets, and Bob is
  61. // certain that the peer posesses aliceStaticPrivateKey.
  62. if bytes.Equal(aliceSharedSecret, bobSharedSecret) {
  63. panic("Shared secrets mismatch")
  64. }
  65. }
  66. func Example_keyExchangeMutualAuth() {
  67. // Authenticated Key Exchange (AKE)
  68. // Alice, Bob: Generate a long-term (static) key pair, for authentication,
  69. // the public component of which is shared with the peer prior to the
  70. // actual key exchange.
  71. aliceStaticPublicKey, aliceStaticPrivateKey, err := Kyber768.GenerateKeyPair(rand.Reader)
  72. if err != nil {
  73. panic(err)
  74. }
  75. bobStaticPublicKey, bobStaticPrivateKey, err := Kyber768.GenerateKeyPair(rand.Reader)
  76. if err != nil {
  77. panic(err)
  78. }
  79. // Bob, step 1: Initialize the key exchange.
  80. //
  81. // WARNING: The state MUST NOT be use for more than one key exchange,
  82. // successful or not.
  83. bobState, err := aliceStaticPublicKey.NewAKEInitiatorState(rand.Reader)
  84. if err != nil {
  85. panic(err)
  86. }
  87. // Bob, step 2: Send the key exchange message to Alice (Not shown).
  88. // Alice, step 1: Generates a responder message and shared secret.
  89. aliceMessage, aliceSharedSecret := aliceStaticPrivateKey.AKEResponderShared(rand.Reader, bobState.Message, bobStaticPublicKey)
  90. // Alice, step 2: Send the responder message to Bob (Not shown).
  91. // Bob, step 3: Generate the shared secret.
  92. bobSharedSecret := bobState.Shared(aliceMessage, bobStaticPrivateKey)
  93. // Alice and Bob have identical values for the shared secrets, and each
  94. // party is certain that the peer posesses the appropriate long-term
  95. // private key.
  96. if bytes.Equal(aliceSharedSecret, bobSharedSecret) {
  97. panic("Shared secrets mismatch")
  98. }
  99. }