.. c:type:: dipe_param_t
- Stores public parameters used in DIPE. Initialized by :c:func:`dipe_init()` and freed by :c:func:`dipe_free_param`
-
+ Public Parameters. Initialized by :c:func:`dipe_init`. Freed by
+ :c:func:`dipe_free_param`
+
.. c:type:: dipe_master_secretkey_t
+
+ Master Secretkey held by an authority. Needed to create user
+ secretkeys. Initialized by :c:func:`dipe_master_keygen`. Freed by
+ :c:func:`dipe_free_master_secretkey`
+
.. c:type:: dipe_master_publickey_t
+
+ Public key corresponding to a mastersecretkey. Needed for
+ encryption. Initialized by :c:func:`dipe_master_keygen`. Freed by
+ :c:func:`dipe_free_master_publickey`
+
.. c:type:: dipe_secretkey_t
+
+ Secretkey held by a user. Needed for decryption. Initialized by
+ :c:func:`dipe_keygen`. Freed by :c:func:`dipe_free_secretkey`
+
.. c:type:: dipe_ctxt_t
-
-Functions
----------
+
+ KEM ciphertext. Initialized by :c:func:`dipe_encap`. Freed by
+ :c:func:`dipe_free_ctxt`
+
+.. c:type:: element_t
+
+ PBC element type. Freed by :c:func:`element_clear`. For details see
+ the PBC documentation.
+
+Interface Functions
+-------------------
Initialization
~~~~~~~~~~~~~~
.. c:function:: void dipe_init(FILE* configfp, dipe_param_t* param)
- initializes public parameters as well as the PBC library
+ Initializes public parameters as well as the PBC library. The
+ function allocates data for the `param` structure that needs to be
+ freed with :c:func:`dipe_free_param`.
:param configfp: File structure holding the pairing group definition as understood by PBC
+ :param param: Pointer to the :c:type:`dipe_param_t` structure to be created
Key Generation
~~~~~~~~~~~~~~
-
-.. c:function:: void dipe_master_keygen(dipe_param_t param, size_t dimension, dipe_master_publickey_t* pk, dipe_master_secretkey_t* sk);
-
-.. c:function:: void dipe_keygen(dipe_param_t param, dipe_master_secretkey_t msk, char* cid, element_t* y, dipe_secretkey_t* sk);
- :param cid: Client ID, expected to be 16 bytes
+.. c:function:: void dipe_master_keygen(dipe_param_t param, size_t dimension, dipe_master_publickey_t* pk, dipe_master_secretkey_t* sk)
+
+ Generate a keypair for an authority. The `dimension` is supposed to
+ be a system parameter and needs to be consistently used for all
+ operations. The function allocates data for the `pk` and `sk`
+ structures that need to be freed with
+ :c:func:`dipe_free_master_publickey` and
+ :c:func:`dipe_free_master_secretkey` respectively.
+
+ :param dipe_param_t param: Public parameters
+ :param size_t dimension: Size of the vector used for inner-product policy
+ :param dipe_master_publickey_t* pk: Pointer to the public-key structure to be generated
+ :param dipe_master_secretkey_t* sk: Pointer to the secret-key structure to be generated
+
+.. c:function:: void dipe_keygen(dipe_param_t param, dipe_master_secretkey_t msk, char* cid, element_t* y, dipe_secretkey_t* sk)
+
+ Issues a secretkey for a used identified by the 16-bit string
+ `cid`. The element vector `y` is expected to be an array of
+ `dimension` many elements. The function allocates data for the `sk`
+ structure that need to be freed with :c:func:`dipe_free_secretkey`.
+
+ :param char* cid: Client ID, expected to be 16 bytes
:param y: Policy vector for the secret key that is to be generated. Must match with the dimensions when `msk` was generated
:type y: Array of Zn elements
-En/Decryption
-~~~~~~~~~~~~~
-
-.. c:function:: void dipe_encrypt(dipe_param_t param, dipe_master_publickey mpk, element_t* x, element_t ptxt, dipe_ctxt_t* ctxt)
-.. c:function:: void dipe_decrypt(dipe_param_t param, dipe_secretkey_t sk, char* cid, element_t* y, dipe_ctxt_t ctxt, element_t* ptxt)
+En-/Decryption
+~~~~~~~~~~~~~~
+
+.. 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)
+
+ Creates a DIPE ciphertext of exactly length `ctxt_len` for a policy
+ vector `x` from some plaintext. `ctxt_len` needs to be large enough
+ to store `ptxt_len` + :c:func:`dipe_ciphertext_overhead` many bytes
+ but may be arbitrarily larger.
+
+ :param dipe_param_t param: Public Parameters
+ :param dipe_master_publickey_t mpk: Master publickey for encryption
+ :param element_t* x: Element vector for encryption policy
+ :param size_t ptxt_len: Actual plaintext length
+ :param char* ptxt: Buffer holding the plaintext
+ :param size_t ctxt_len: Ciphertext length. ciphertext will be padded to match this size exactly
+ :param char* ctxt: buffer to hold the ciphertext
+
+.. 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)
- :param result: It is the responsibility of the caller to initialize the element to GT and to free it after usage
- :type result: :c:type:`element_t`
+ Decrypts a DIPE ciphertext. The buffer `ptxt` needs to be able to
+ hold at least `ctxt_len` - :c:func:`dipe_ciphertext_overhead` many
+ bytes. The function returns the length of the recovered plaintext
+ but may modify the remaining bits of the `ptxt` buffer as well.
+
+ :param dipe_param_t param: Public Parameters
+ :param dipe_secretkey_t sk: User Secretkey
+ :param char* cid: 16-bytes user identification string
+ :param element_t* y: user's predicate vector
+ :param size_t ctxt_len: length of the ciphertext
+ :param char* ctxt: buffer containing the ciphertext
+ :param char* ptxt: buffer to hold the plaintext.
+
+.. c:function:: size_t dipe_ciphertext_overhead(dipe_param_t param, size_t dimension);
+
+ Calculates the size overhead of a DIPE ciphertext in bytes.
+
+ :param dipe_param_t param: Public Parameters
+ :param size_t dimension: Dimension of the policy vector
Memory Management
~~~~~~~~~~~~~~~~~
-
-.. c:function:: void dipe_free_param(dipe_param_t param);
-.. c:function:: void dipe_free_master_secretkey(dipe_master_secretkey_t sk);
-.. c:function:: void dipe_free_master_publickey(dipe_master_publickey_t pk);
-.. c:function:: void dipe_free_secretkey(dipe_secretkey_t sk);
+.. c:function:: void dipe_free_param(dipe_param_t param)
+.. c:function:: void dipe_free_master_secretkey(dipe_master_secretkey_t sk)
+.. c:function:: void dipe_free_master_publickey(dipe_master_publickey_t pk)
+.. c:function:: void dipe_free_secretkey(dipe_secretkey_t sk)
+.. c:function:: void dipe_free_ctxt(dipe_ctxt_t ctxt)
+
+ Freeing the dipe data structures
+
+Plumbing Functions
+------------------
+.. c:function:: void dipe_encap(dipe_param_t param, dipe_master_publickey_t mpk, element_t* x, element_t ptxt, dipe_ctxt_t* ctxt)
+.. 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)
+.. c:function:: size_t dipe_serialize_ctxt(dipe_param_t param, dipe_ctxt_t ctxt, uint8_t* buffer)
+.. c:function:: size_t dipe_deserialize_ctxt(dipe_param_t param, size_t dimension, dipe_ctxt_t* ctxt, uint8_t* buffer)
projects / software / DIPE.git / commitdiff