From 228b4f8c2255acb701fd669161f62c1f777a0a98 Mon Sep 17 00:00:00 2001 From: Christoph Egger Date: Sun, 12 Jan 2020 23:58:58 +0100 Subject: [PATCH] update documentation --- doc/source/api.rst | 24 ++++++++++++------------ doc/source/index.rst | 1 + doc/source/install.rst | 16 ++++++++++++++++ doc/source/notes.rst | 2 +- 4 files changed, 30 insertions(+), 13 deletions(-) create mode 100644 doc/source/install.rst diff --git a/doc/source/api.rst b/doc/source/api.rst index 8fbdb35..0da1209 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -45,7 +45,7 @@ Initialization .. c:function:: void dipe_init(FILE* configfp, dipe_param_t* param) Initializes public parameters as well as the PBC library. The - function allocates data for the `param` structure that needs to be + 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 @@ -56,9 +56,9 @@ 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) - Generate a keypair for an authority. The `dimension` is supposed to + 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` + 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. @@ -71,12 +71,12 @@ Key Generation .. 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` + ``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 + :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 @@ -84,9 +84,9 @@ 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 + 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 @@ -99,10 +99,10 @@ En-/Decryption .. 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) - Decrypts a DIPE ciphertext. The buffer `ptxt` needs to be able to - hold at least `ctxt_len` - :c:func:`dipe_ciphertext_overhead` many + 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. + 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 diff --git a/doc/source/index.rst b/doc/source/index.rst index a5ce351..60f4f92 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -10,6 +10,7 @@ Welcome to DIPE's documentation! :maxdepth: 2 :caption: Contents: + install notes api diff --git a/doc/source/install.rst b/doc/source/install.rst new file mode 100644 index 0000000..c7cc5f6 --- /dev/null +++ b/doc/source/install.rst @@ -0,0 +1,16 @@ +Installation +============ + +Get the code from `git.siccegge.de +`_. +Installing dependencies on debian requires a manual installation of +`PBC `_ and the packages ``googletest +cmake nettle-dev libgmp-dev``. Standard out-of-tree-build via:: + + mkdir build + cd build + cmake .. + make -j + +The googletest integration is expected to need manual fiddling on +non-Debian and probably also on Debian systems. diff --git a/doc/source/notes.rst b/doc/source/notes.rst index bf83ecb..b20d922 100644 --- a/doc/source/notes.rst +++ b/doc/source/notes.rst @@ -18,7 +18,7 @@ and iv from the $G_t$ element. Encryption Mode --------------- -Ciphertext is `AES128` in `GCM` mode with 12 bit IV and 16 bit +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 -- 2.39.5