From 2d85aad0494ae9dbfec3cfa7bac0883b5983cc92 Mon Sep 17 00:00:00 2001 From: Christoph Egger Date: Sun, 12 Jan 2020 23:51:05 +0100 Subject: [PATCH] Update documentation --- doc/source/api.rst | 129 +++++++++++++++++++++++++++++++++++-------- doc/source/notes.rst | 20 ++++++- 2 files changed, 125 insertions(+), 24 deletions(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 3bb3d6e..8fbdb35 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -6,52 +6,135 @@ Types .. 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) diff --git a/doc/source/notes.rst b/doc/source/notes.rst index 7397dcb..bf83ecb 100644 --- a/doc/source/notes.rst +++ b/doc/source/notes.rst @@ -1,7 +1,25 @@ +Implementation Notes +==================== + Selection of Curves -=================== +------------------- Note that the ciphertext contains elements in $G_1$ as well as $G_t$ and therefore we need to be able to serialize them in a way that is (computationally) indistinguishable from random. As per Shermans comment and reference to https://ia.cr/2015/247 + +Key derivation +-------------- + +We're using `HKDF `_ to extract the AES key +and iv from the $G_t$ element. + +Encryption Mode +--------------- + +Ciphertext is `AES128` in `GCM` mode with 12 bit IV and 16 bit +tag. The ciphertext-format is as follows:: + + compress(s) | compress(cx) | c + enc(4 byte len(ptxt) | ptxt | 0 padding) | tag -- 2.39.5