diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/mint/key_io.c | 104 | ||||
| -rw-r--r-- | src/mint/key_io.h | 69 |
2 files changed, 109 insertions, 64 deletions
diff --git a/src/mint/key_io.c b/src/mint/key_io.c index 928d51db..ad06da62 100644 --- a/src/mint/key_io.c +++ b/src/mint/key_io.c @@ -13,7 +13,6 @@ You should have received a copy of the GNU General Public License along with TALER; see the file COPYING. If not, If not, see <http://www.gnu.org/licenses/> */ - /** * @file mint/key_io.c * @brief I/O operations for the Mint's private keys @@ -23,36 +22,40 @@ * @author Christian Grothoff * * TODO: - * - document better * - revisit IO with respect to variable-size RSA keys! */ #include "platform.h" #include "key_io.h" + /** - * + * Closure for the #signkeys_iterate_dir_iter(). */ struct SignkeysIterateContext { /** - * + * Function to call on each signing key. */ TALER_MINT_SignkeyIterator it; /** - * + * Closure for @e it. */ void *it_cls; }; /** + * Function called on each file in the directory with + * our signing keys. Parses the file and calls the + * iterator from @a cls. * - * - * @param cls - * @param filename - * @return + * @param cls the `struct SignkeysIterateContext *` + * @param filename name of the file to parse + * @return #GNUNET_OK to continue, + * #GNUNET_NO to stop iteration without error, + * #GNUNET_SYSERR to stop iteration with error */ static int signkeys_iterate_dir_iter (void *cls, @@ -78,6 +81,18 @@ signkeys_iterate_dir_iter (void *cls, } +/** + * Call @a it for each signing key found in the @a mint_base_dir. + * + * @param mint_base_dir base directory for the mint, + * the signing keys must be in the #DIR_SIGNKEYS + * subdirectory + * @param it function to call on each signing key + * @param it_cls closure for @a it + * @return number of files found (may not match + * number of keys given to @a it as malformed + * files are simply skipped), -1 on error + */ int TALER_MINT_signkeys_iterate (const char *mint_base_dir, TALER_MINT_SignkeyIterator it, @@ -101,10 +116,10 @@ TALER_MINT_signkeys_iterate (const char *mint_base_dir, /** - * Import a denomination key from the given file + * Import a denomination key from the given file. * * @param filename the file to import the key from - * @param dki pointer to return the imported denomination key + * @param[OUT] dki set to the imported denomination key * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure */ int @@ -203,34 +218,40 @@ TALER_MINT_write_denom_key (const char *filename, /** - * + * Closure for #denomkeys_iterate_keydir_iter() and + * #denomkeys_iterate_topdir_iter(). */ struct DenomkeysIterateContext { /** - * + * Set to the name of the directory below the top-level directory + * during the call to #denomkeys_iterate_keydir_iter(). */ const char *alias; /** - * + * Function to call on each denomination key. */ TALER_MINT_DenomkeyIterator it; /** - * + * Closure for @e it. */ void *it_cls; }; /** + * Decode the denomination key in the given file @a filename and call + * the callback in @a cls with the information. * - * - * @param cls - * @param filename - * @return + * @param cls the `struct DenomkeysIterateContext *` + * @param filename name of a file that should contain + * a denomination key + * @return #GNUNET_OK to continue to iterate + * #GNUNET_NO to abort iteration with success + * #GNUNET_SYSERR to abort iteration with failure */ static int denomkeys_iterate_keydir_iter (void *cls, @@ -255,11 +276,14 @@ denomkeys_iterate_keydir_iter (void *cls, /** + * Function called on each subdirectory in the #DIR_DENOMKEYS. Will + * call the #denomkeys_iterate_keydir_iter() on each file in the + * subdirectory. * - * - * @param cls - * @param filename - * @return + * @param cls the `struct DenomkeysIterateContext *` + * @param filename name of the subdirectory to scan + * @return #GNUNET_OK on success, + * #GNUNET_SYSERR if we need to abort */ static int denomkeys_iterate_topdir_iter (void *cls, @@ -268,8 +292,6 @@ denomkeys_iterate_topdir_iter (void *cls, struct DenomkeysIterateContext *dic = cls; dic->alias = GNUNET_STRINGS_get_short_name (filename); - - // FIXME: differentiate between error case and normal iteration abortion if (0 > GNUNET_DISK_directory_scan (filename, &denomkeys_iterate_keydir_iter, dic)) @@ -278,6 +300,19 @@ denomkeys_iterate_topdir_iter (void *cls, } +/** + * Call @a it for each denomination key found in the @a mint_base_dir. + * + * @param mint_base_dir base directory for the mint, + * the signing keys must be in the #DIR_DENOMKEYS + * subdirectory + * @param it function to call on each denomination key found + * @param it_cls closure for @a it + * @return -1 on error, 0 if no files were found, otherwise + * a positive number (however, even with a positive + * number it is possible that @a it was never called + * as maybe none of the files were well-formed) + */ int TALER_MINT_denomkeys_iterate (const char *mint_base_dir, TALER_MINT_DenomkeyIterator it, @@ -286,19 +321,18 @@ TALER_MINT_denomkeys_iterate (const char *mint_base_dir, char *dir; size_t len; struct DenomkeysIterateContext dic; + int ret; - len = GNUNET_asprintf (&dir, - "%s" DIR_SEPARATOR_STR DIR_DENOMKEYS, - mint_base_dir); - GNUNET_assert (len > 0); - + GNUNET_asprintf (&dir, + "%s" DIR_SEPARATOR_STR DIR_DENOMKEYS, + mint_base_dir); dic.it = it; dic.it_cls = it_cls; - - // scan over alias dirs - return GNUNET_DISK_directory_scan (dir, - &denomkeys_iterate_topdir_iter, - &dic); + ret = GNUNET_DISK_directory_scan (dir, + &denomkeys_iterate_topdir_iter, + &dic); + GNUNET_free (dir); + return ret; } diff --git a/src/mint/key_io.h b/src/mint/key_io.h index ae7f183e..aa59213c 100644 --- a/src/mint/key_io.h +++ b/src/mint/key_io.h @@ -19,9 +19,6 @@ * @author Florian Dold * @author Benedikt Mueller * @author Christian Grothoff - * - * TODO: - * - document better */ #ifndef KEY_IO_H #define KEY_IO_H @@ -30,59 +27,64 @@ #include "taler_signatures.h" /** - * + * Subdirectroy under the mint's base directory which contains + * the mint's signing keys. */ #define DIR_SIGNKEYS "signkeys" /** - * + * Subdirectory under the mint's base directory which contains + * the mint's denomination keys. */ #define DIR_DENOMKEYS "denomkeys" /** - * On disk format used for a mint signing key. - * Includes the private key followed by the signed - * issue message. + * On disk format used for a mint signing key. Signing keys are used + * by the mint to affirm its messages, but not to create coins. + * Includes the private key followed by the public information about + * the signing key. */ struct TALER_MINT_SignKeyIssuePriv { /** - * FIXME. + * Private key part of the mint's signing key. */ struct GNUNET_CRYPTO_EddsaPrivateKey signkey_priv; /** - * FIXME. + * Public information about a mint signing key. */ struct TALER_MINT_SignKeyIssue issue; }; /** - * FIXME. + * All information about a denomination key (which is used to + * sign coins into existence). */ struct TALER_MINT_DenomKeyIssuePriv { /** - * The private key of the denomination. Will be NULL if the private key is - * not available. + * The private key of the denomination. Will be NULL if the private + * key is not available (this is the case after the key has expired + * for signing coins, but is still valid for depositing coins). */ struct GNUNET_CRYPTO_rsa_PrivateKey *denom_priv; /** - * FIXME. + * Public information about a denomination key. */ struct TALER_MINT_DenomKeyIssue issue; }; /** - * Iterator for sign keys. + * Iterator over signing keys. * * @param cls closure * @param filename name of the file the key came from - * @param ski the sign key issue + * @param ski the sign key * @return #GNUNET_OK to continue to iterate, * #GNUNET_NO to stop iteration with no error, * #GNUNET_SYSERR to abort iteration with error! @@ -94,10 +96,10 @@ typedef int /** - * Iterator for denomination keys. + * Iterator over denomination keys. * * @param cls closure - * @param dki the denomination key issue + * @param dki the denomination key * @param alias coin alias * @return #GNUNET_OK to continue to iterate, * #GNUNET_NO to stop iteration with no error, @@ -111,12 +113,16 @@ typedef int /** - * FIXME + * Call @a it for each signing key found in the @a mint_base_dir. * - * @param mint_base_dir - * @param it + * @param mint_base_dir base directory for the mint, + * the signing keys must be in the #DIR_SIGNKEYS + * subdirectory + * @param it function to call on each signing key * @param it_cls closure for @a it - * @return + * @return number of files found (may not match + * number of keys given to @a it as malformed + * files are simply skipped), -1 on error */ int TALER_MINT_signkeys_iterate (const char *mint_base_dir, @@ -125,12 +131,17 @@ TALER_MINT_signkeys_iterate (const char *mint_base_dir, /** - * FIXME + * Call @a it for each denomination key found in the @a mint_base_dir. * - * @param mint_base_dir - * @param it + * @param mint_base_dir base directory for the mint, + * the signing keys must be in the #DIR_DENOMKEYS + * subdirectory + * @param it function to call on each denomination key found * @param it_cls closure for @a it - * @return + * @return -1 on error, 0 if no files were found, otherwise + * a positive number (however, even with a positive + * number it is possible that @a it was never called + * as maybe none of the files were well-formed) */ int TALER_MINT_denomkeys_iterate (const char *mint_base_dir, @@ -139,7 +150,7 @@ TALER_MINT_denomkeys_iterate (const char *mint_base_dir, /** - * Exports a denomination key to the given file + * Exports a denomination key to the given file. * * @param filename the file where to write the denomination key * @param dki the denomination key @@ -151,10 +162,10 @@ TALER_MINT_write_denom_key (const char *filename, /** - * Import a denomination key from the given file + * Import a denomination key from the given file. * * @param filename the file to import the key from - * @param dki pointer to return the imported denomination key + * @param[OUT] dki set to the imported denomination key * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure */ int |