include/crypto/ecdh.h

   1 /*
   2  * ECDH params to be used with kpp API
   3  *
   4  * Copyright (c) 2016, Intel Corporation
   5  * Authors: Salvatore Benedetto <salvatore.benedetto@intel.com>
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License as published by the Free
   9  * Software Foundation; either version 2 of the License, or (at your option)
  10  * any later version.
  11  *
  12  */
  13 #ifndef _CRYPTO_ECDH_
  14 #define _CRYPTO_ECDH_
  15
  16 /**
  17  * DOC: ECDH Helper Functions
  18  *
  19  * To use ECDH with the KPP cipher API, the following data structure and
  20  * functions should be used.
  21  *
  22  * The ECC curves known to the ECDH implementation are specified in this
  23  * header file.
  24  *
  25  * To use ECDH with KPP, the following functions should be used to operate on
  26  * an ECDH private key. The packet private key that can be set with
  27  * the KPP API function call of crypto_kpp_set_secret.
  28  */
  29
  30 /* Curves IDs */
  31 #define ECC_CURVE_NIST_P192     0x0001
  32 #define ECC_CURVE_NIST_P256     0x0002
  33
  34 /**
  35  * struct ecdh - define an ECDH private key
  36  *
  37  * @curve_id:   ECC curve the key is based on.
  38  * @key:        Private ECDH key
  39  * @key_size:   Size of the private ECDH key
  40  */
  41 struct ecdh {
  42         unsigned short curve_id;
  43         char *key;
  44         unsigned short key_size;
  45 };
  46
  47 /**
  48  * crypto_ecdh_key_len() - Obtain the size of the private ECDH key
  49  * @params:     private ECDH key
  50  *
  51  * This function returns the packet ECDH key size. A caller can use that
  52  * with the provided ECDH private key reference to obtain the required
  53  * memory size to hold a packet key.
  54  *
  55  * Return: size of the key in bytes
  56  */
  57 unsigned int crypto_ecdh_key_len(const struct ecdh *params);
  58
  59 /**
  60  * crypto_ecdh_encode_key() - encode the private key
  61  * @buf:        Buffer allocated by the caller to hold the packet ECDH
  62  *              private key. The buffer should be at least crypto_ecdh_key_len
  63  *              bytes in size.
  64  * @len:        Length of the packet private key buffer
  65  * @p:          Buffer with the caller-specified private key
  66  *
  67  * The ECDH implementations operate on a packet representation of the private
  68  * key.
  69  *
  70  * Return:      -EINVAL if buffer has insufficient size, 0 on success
  71  */
  72 int crypto_ecdh_encode_key(char *buf, unsigned int len, const struct ecdh *p);
  73
  74 /**
  75  * crypto_ecdh_decode_key() - decode a private key
  76  * @buf:        Buffer holding a packet key that should be decoded
  77  * @len:        Length of the packet private key buffer
  78  * @p:          Buffer allocated by the caller that is filled with the
  79  *              unpacked ECDH private key.
  80  *
  81  * The unpacking obtains the private key by pointing @p to the correct location
  82  * in @buf. Thus, both pointers refer to the same memory.
  83  *
  84  * Return:      -EINVAL if buffer has insufficient size, 0 on success
  85  */
  86 int crypto_ecdh_decode_key(const char *buf, unsigned int len, struct ecdh *p);
  87
  88 #endif