From 0ef7129a4a7776db9d0c4dd52519e2ca21b428d5 Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Thu, 22 Sep 2011 11:02:58 -0500 Subject: signing: document most undocumented functions Signed-off-by: Dan McGee --- lib/libalpm/signing.c | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/lib/libalpm/signing.c b/lib/libalpm/signing.c index b090b6a9..45488104 100644 --- a/lib/libalpm/signing.c +++ b/lib/libalpm/signing.c @@ -42,6 +42,12 @@ if(gpg_err_code(err) != GPG_ERR_NO_ERROR) { goto error; } \ } while(0) +/** + * Return a statically allocated validity string based on the GPGME validity + * code. This is mainly for debug purposes and is not translated. + * @param validity a validity code returned by GPGME + * @return a string such as "marginal" + */ static const char *string_validity(gpgme_validity_t validity) { switch(validity) { @@ -69,6 +75,12 @@ static void sigsum_test_bit(gpgme_sigsum_t sigsum, alpm_list_t **summary, } } +/** + * Calculate a set of strings to represent the given GPGME signature summary + * value. This is a bitmask so you may get any number of strings back. + * @param sigsum a GPGME signature summary bitmask + * @return the list of signature summary strings + */ static alpm_list_t *list_sigsum(gpgme_sigsum_t sigsum) { alpm_list_t *summary = NULL; @@ -104,6 +116,12 @@ static alpm_list_t *list_sigsum(gpgme_sigsum_t sigsum) return summary; } +/** + * Initialize the GPGME library. + * This can be safely called multiple times; however it is not thread-safe. + * @param handle the context handle + * @return 0 on success, 1 on error + */ static int init_gpgme(alpm_handle_t *handle) { static int init = 0; @@ -434,6 +452,20 @@ char *_alpm_sigpath(alpm_handle_t *handle, const char *path) return sigpath; } +/** + * Helper for checking the PGP signature for the given file path. + * This wraps #_alpm_gpgme_checksig in a slightly friendlier manner to simplify + * handling of optional signatures and marginal/unknown trust levels and + * handling the correct error code return values. + * @param handle the context handle + * @param path the full path to a file + * @param base64_sig optional PGP signature data in base64 encoding + * @param optional whether signatures are optional (e.g., missing OK) + * @param marginal whether signatures with marginal trust are acceptable + * @param unknown whether signatures with unknown trust are acceptable + * @param sigdata a pointer to storage for signature results + * @return 0 on success, -1 on error (consult pm_errno or sigdata) + */ int _alpm_check_pgp_helper(alpm_handle_t *handle, const char *path, const char *base64_sig, int optional, int marginal, int unknown, alpm_siglist_t **sigdata) @@ -507,6 +539,20 @@ int _alpm_check_pgp_helper(alpm_handle_t *handle, const char *path, return ret; } +/** + * Examine a signature result list and take any appropriate or necessary + * actions. This may include asking the user to import a key or simply printing + * helpful failure messages so the user can take action out of band. + * @param handle the context handle + * @param identifier a friendly name for the signed resource; usually a + * database or package name + * @param siglist a pointer to storage for signature results + * @param optional whether signatures are optional (e.g., missing OK) + * @param marginal whether signatures with marginal trust are acceptable + * @param unknown whether signatures with unknown trust are acceptable + * @return 0 if all signatures are OK, -1 on errors, 1 if we should retry the + * validation process + */ int _alpm_process_siglist(alpm_handle_t *handle, const char *identifier, alpm_siglist_t *siglist, int optional, int marginal, int unknown) { @@ -573,6 +619,7 @@ int _alpm_process_siglist(alpm_handle_t *handle, const char *identifier, /** * Check the PGP signature for the given package file. * @param pkg the package to check + * @param siglist a pointer to storage for signature results * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) */ int SYMEXPORT alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, @@ -589,6 +636,7 @@ int SYMEXPORT alpm_pkg_check_pgp_signature(alpm_pkg_t *pkg, /** * Check the PGP signature for the given database. * @param db the database to check + * @param siglist a pointer to storage for signature results * @return a int value : 0 (valid), 1 (invalid), -1 (an error occurred) */ int SYMEXPORT alpm_db_check_pgp_signature(alpm_db_t *db, @@ -601,6 +649,13 @@ int SYMEXPORT alpm_db_check_pgp_signature(alpm_db_t *db, return _alpm_gpgme_checksig(db->handle, _alpm_db_path(db), NULL, siglist); } +/** + * Clean up and free a signature result list. + * Note that this does not free the #alpm_siglist_t object itself in case that + * was allocated on the stack; this is the responsibility of the caller. + * @param siglist a pointer to storage for signature results + * @return 0 on success, -1 on error + */ int SYMEXPORT alpm_siglist_cleanup(alpm_siglist_t *siglist) { ASSERT(siglist != NULL, return -1); -- cgit v1.2.3-24-g4f1b