LXR linux/include/crypto/dh.h

   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 <salvatore.benedetto@intel.com>
   7 */
   8#ifndef _CRYPTO_DH_
   9#define _CRYPTO_DH_
  10
  11/**
  12 * DOC: DH Helper Functions
  13 *
  14 * To use DH with the KPP cipher API, the following data structure and
  15 * functions should be used.
  16 *
  17 * To use DH with KPP, the following functions should be used to operate on
  18 * a DH private key. The packet private key that can be set with
  19 * the KPP API function call of crypto_kpp_set_secret.
  20 */
  21
  22/**
  23 * struct dh - define a DH private key
  24 *
  25 * @key:        Private DH key
  26 * @p:          Diffie-Hellman parameter P
  27 * @q:          Diffie-Hellman parameter Q
  28 * @g:          Diffie-Hellman generator G
  29 * @key_size:   Size of the private DH key
  30 * @p_size:     Size of DH parameter P
  31 * @q_size:     Size of DH parameter Q
  32 * @g_size:     Size of DH generator G
  33 */
  34struct dh {
  35        void *key;
  36        void *p;
  37        void *q;
  38        void *g;
  39        unsigned int key_size;
  40        unsigned int p_size;
  41        unsigned int q_size;
  42        unsigned int g_size;
  43};
  44
  45/**
  46 * crypto_dh_key_len() - Obtain the size of the private DH key
  47 * @params:     private DH key
  48 *
  49 * This function returns the packet DH key size. A caller can use that
  50 * with the provided DH private key reference to obtain the required
  51 * memory size to hold a packet key.
  52 *
  53 * Return: size of the key in bytes
  54 */
  55unsigned int crypto_dh_key_len(const struct dh *params);
  56
  57/**
  58 * crypto_dh_encode_key() - encode the private key
  59 * @buf:        Buffer allocated by the caller to hold the packet DH
  60 *              private key. The buffer should be at least crypto_dh_key_len
  61 *              bytes in size.
  62 * @len:        Length of the packet private key buffer
  63 * @params:     Buffer with the caller-specified private key
  64 *
  65 * The DH implementations operate on a packet representation of the private
  66 * key.
  67 *
  68 * Return:      -EINVAL if buffer has insufficient size, 0 on success
  69 */
  70int crypto_dh_encode_key(char *buf, unsigned int len, const struct dh *params);
  71
  72/**
  73 * crypto_dh_decode_key() - decode a private key
  74 * @buf:        Buffer holding a packet key that should be decoded
  75 * @len:        Length of the packet private key buffer
  76 * @params:     Buffer allocated by the caller that is filled with the
  77 *              unpacked DH private key.
  78 *
  79 * The unpacking obtains the private key by pointing @p to the correct location
  80 * in @buf. Thus, both pointers refer to the same memory.
  81 *
  82 * Return:      -EINVAL if buffer has insufficient size, 0 on success
  83 */
  84int crypto_dh_decode_key(const char *buf, unsigned int len, struct dh *params);
  85
  86#endif
  87