doc/source/api.rst

   1 API Documentation
   2 =================
   3
   4 Types
   5 -----
   6
   7 .. c:type:: dipe_param_t
   8
   9    Public Parameters. Initialized by :c:func:`dipe_init`. Freed by
  10    :c:func:`dipe_free_param`
  11
  12 .. c:type:: dipe_master_secretkey_t
  13
  14    Master Secretkey held by an authority. Needed to create user
  15    secretkeys. Initialized by :c:func:`dipe_master_keygen`. Freed by
  16    :c:func:`dipe_free_master_secretkey`
  17
  18 .. c:type:: dipe_master_publickey_t
  19
  20    Public key corresponding to a mastersecretkey. Needed for
  21    encryption. Initialized by :c:func:`dipe_master_keygen`. Freed by
  22    :c:func:`dipe_free_master_publickey`
  23
  24 .. c:type:: dipe_secretkey_t
  25
  26    Secretkey held by a user. Needed for decryption. Initialized by
  27    :c:func:`dipe_keygen`. Freed by :c:func:`dipe_free_secretkey`
  28
  29 .. c:type:: dipe_ctxt_t
  30
  31    KEM ciphertext. Initialized by :c:func:`dipe_encap`. Freed by
  32    :c:func:`dipe_free_ctxt`
  33
  34 .. c:type:: element_t
  35
  36    PBC element type. Freed by :c:func:`element_clear`. For details see
  37    the PBC documentation.
  38
  39 Interface Functions
  40 -------------------
  41
  42 Initialization
  43 ~~~~~~~~~~~~~~
  44
  45 .. c:function:: void dipe_init(FILE* configfp, dipe_param_t* param)
  46
  47    Initializes public parameters as well as the PBC library. The
  48    function allocates data for the `param` structure that needs to be
  49    freed with :c:func:`dipe_free_param`.
  50
  51    :param configfp: File structure holding the pairing group definition as understood by PBC
  52    :param param: Pointer to the :c:type:`dipe_param_t` structure to be created
  53
  54 Key Generation
  55 ~~~~~~~~~~~~~~
  56
  57 .. c:function:: void dipe_master_keygen(dipe_param_t param, size_t dimension, dipe_master_publickey_t* pk, dipe_master_secretkey_t* sk)
  58
  59    Generate a keypair for an authority. The `dimension` is supposed to
  60    be a system parameter and needs to be consistently used for all
  61    operations. The function allocates data for the `pk` and `sk`
  62    structures that need to be freed with
  63    :c:func:`dipe_free_master_publickey` and
  64    :c:func:`dipe_free_master_secretkey` respectively.
  65
  66    :param dipe_param_t param: Public parameters
  67    :param size_t dimension: Size of the vector used for inner-product policy
  68    :param dipe_master_publickey_t* pk: Pointer to the public-key structure to be generated
  69    :param dipe_master_secretkey_t* sk: Pointer to the secret-key structure to be generated
  70
  71 .. c:function:: void dipe_keygen(dipe_param_t param, dipe_master_secretkey_t msk, char* cid, element_t* y, dipe_secretkey_t* sk)
  72
  73    Issues a secretkey for a used identified by the 16-bit string
  74    `cid`. The element vector `y` is expected to be an array of
  75    `dimension` many elements. The function allocates data for the `sk`
  76    structure that need to be freed with :c:func:`dipe_free_secretkey`.
  77
  78    :param char* cid: Client ID, expected to be 16 bytes
  79    :param y: Policy vector for the secret key that is to be generated. Must match with the dimensions when `msk` was generated
  80    :type y: Array of Zn elements
  81
  82 En-/Decryption
  83 ~~~~~~~~~~~~~~
  84
  85 .. c:function:: void dipe_encrypt(dipe_param_t param, dipe_master_publickey_t mpk, element_t* x, size_t ptxt_len, char* ptxt, size_t ctxt_len, char* ctxt)
  86
  87    Creates a DIPE ciphertext of exactly length `ctxt_len` for a policy
  88    vector `x` from some plaintext. `ctxt_len` needs to be large enough
  89    to store `ptxt_len` + :c:func:`dipe_ciphertext_overhead` many bytes
  90    but may be arbitrarily larger.
  91
  92    :param dipe_param_t param: Public Parameters
  93    :param dipe_master_publickey_t mpk: Master publickey for encryption
  94    :param element_t* x: Element vector for encryption policy
  95    :param size_t ptxt_len: Actual plaintext length
  96    :param char* ptxt: Buffer holding the plaintext
  97    :param size_t ctxt_len: Ciphertext length. ciphertext will be padded to match this size exactly
  98    :param char* ctxt: buffer to hold the ciphertext
  99
 100 .. c:function:: size_t dipe_decrypt(dipe_param_t param, dipe_secretkey_t sk, char* cid, element_t* y, size_t ctxt_len, char* ctxt, char* ptxt)
 101
 102    Decrypts a DIPE ciphertext. The buffer `ptxt` needs to be able to
 103    hold at least `ctxt_len` - :c:func:`dipe_ciphertext_overhead` many
 104    bytes. The function returns the length of the recovered plaintext
 105    but may modify the remaining bits of the `ptxt` buffer as well.
 106
 107    :param dipe_param_t param: Public Parameters
 108    :param dipe_secretkey_t sk: User Secretkey
 109    :param char* cid: 16-bytes user identification string
 110    :param element_t* y: user's predicate vector
 111    :param size_t ctxt_len: length of the ciphertext
 112    :param char* ctxt: buffer containing the ciphertext
 113    :param char* ptxt: buffer to hold the plaintext.
 114
 115 .. c:function:: size_t dipe_ciphertext_overhead(dipe_param_t param, size_t dimension);
 116
 117    Calculates the size overhead of a DIPE ciphertext in bytes.
 118
 119    :param dipe_param_t param: Public Parameters
 120    :param size_t dimension: Dimension of the policy vector
 121
 122 Memory Management
 123 ~~~~~~~~~~~~~~~~~
 124
 125 .. c:function:: void dipe_free_param(dipe_param_t param)
 126 .. c:function:: void dipe_free_master_secretkey(dipe_master_secretkey_t sk)
 127 .. c:function:: void dipe_free_master_publickey(dipe_master_publickey_t pk)
 128 .. c:function:: void dipe_free_secretkey(dipe_secretkey_t sk)
 129 .. c:function:: void dipe_free_ctxt(dipe_ctxt_t ctxt)
 130
 131    Freeing the dipe data structures
 132
 133 Plumbing Functions
 134 ------------------
 135
 136 .. c:function:: void dipe_encap(dipe_param_t param, dipe_master_publickey_t mpk, element_t* x, element_t ptxt, dipe_ctxt_t* ctxt)
 137 .. c:function:: void dipe_decap(dipe_param_t param, dipe_secretkey_t sk, char* cid, element_t* y, dipe_ctxt_t ctxt, element_t ptxt)
 138
 139 .. c:function:: size_t dipe_serialize_ctxt(dipe_param_t param, dipe_ctxt_t ctxt, uint8_t* buffer)
 140 .. c:function:: size_t dipe_deserialize_ctxt(dipe_param_t param, size_t dimension, dipe_ctxt_t* ctxt, uint8_t* buffer)