dh.h 3.0 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798
  1. /* SPDX-License-Identifier: GPL-2.0-or-later */
  2. /*
  3. * Diffie-Hellman secret to be used with kpp API along with helper functions
  4. *
  5. * Copyright (c) 2016, Intel Corporation
  6. * Authors: Salvatore Benedetto <[email protected]>
  7. */
  8. #ifndef _CRYPTO_DH_
  9. #define _CRYPTO_DH_
  10. /**
  11. * DOC: DH Helper Functions
  12. *
  13. * To use DH with the KPP cipher API, the following data structure and
  14. * functions should be used.
  15. *
  16. * To use DH with KPP, the following functions should be used to operate on
  17. * a DH private key. The packet private key that can be set with
  18. * the KPP API function call of crypto_kpp_set_secret.
  19. */
  20. /**
  21. * struct dh - define a DH private key
  22. *
  23. * @key: Private DH key
  24. * @p: Diffie-Hellman parameter P
  25. * @g: Diffie-Hellman generator G
  26. * @key_size: Size of the private DH key
  27. * @p_size: Size of DH parameter P
  28. * @g_size: Size of DH generator G
  29. */
  30. struct dh {
  31. const void *key;
  32. const void *p;
  33. const void *g;
  34. unsigned int key_size;
  35. unsigned int p_size;
  36. unsigned int g_size;
  37. };
  38. /**
  39. * crypto_dh_key_len() - Obtain the size of the private DH key
  40. * @params: private DH key
  41. *
  42. * This function returns the packet DH key size. A caller can use that
  43. * with the provided DH private key reference to obtain the required
  44. * memory size to hold a packet key.
  45. *
  46. * Return: size of the key in bytes
  47. */
  48. unsigned int crypto_dh_key_len(const struct dh *params);
  49. /**
  50. * crypto_dh_encode_key() - encode the private key
  51. * @buf: Buffer allocated by the caller to hold the packet DH
  52. * private key. The buffer should be at least crypto_dh_key_len
  53. * bytes in size.
  54. * @len: Length of the packet private key buffer
  55. * @params: Buffer with the caller-specified private key
  56. *
  57. * The DH implementations operate on a packet representation of the private
  58. * key.
  59. *
  60. * Return: -EINVAL if buffer has insufficient size, 0 on success
  61. */
  62. int crypto_dh_encode_key(char *buf, unsigned int len, const struct dh *params);
  63. /**
  64. * crypto_dh_decode_key() - decode a private key
  65. * @buf: Buffer holding a packet key that should be decoded
  66. * @len: Length of the packet private key buffer
  67. * @params: Buffer allocated by the caller that is filled with the
  68. * unpacked DH private key.
  69. *
  70. * The unpacking obtains the private key by pointing @p to the correct location
  71. * in @buf. Thus, both pointers refer to the same memory.
  72. *
  73. * Return: -EINVAL if buffer has insufficient size, 0 on success
  74. */
  75. int crypto_dh_decode_key(const char *buf, unsigned int len, struct dh *params);
  76. /**
  77. * __crypto_dh_decode_key() - decode a private key without parameter checks
  78. * @buf: Buffer holding a packet key that should be decoded
  79. * @len: Length of the packet private key buffer
  80. * @params: Buffer allocated by the caller that is filled with the
  81. * unpacked DH private key.
  82. *
  83. * Internal function providing the same services as the exported
  84. * crypto_dh_decode_key(), but without any of those basic parameter
  85. * checks conducted by the latter.
  86. *
  87. * Return: -EINVAL if buffer has insufficient size, 0 on success
  88. */
  89. int __crypto_dh_decode_key(const char *buf, unsigned int len,
  90. struct dh *params);
  91. #endif