From 3e9f168069a6443cbd4eba28bead26580050ec36 Mon Sep 17 00:00:00 2001 From: Richard Russon Date: Mon, 11 Jun 2018 23:35:05 +0100 Subject: [PATCH] doxygen: document api implementors --- ncrypt/crypt_gpgme.c | 105 +++++++++++++++------------------ ncrypt/crypt_mod_pgp_gpgme.c | 15 ++++- ncrypt/crypt_mod_smime_gpgme.c | 12 +++- ncrypt/pgp.c | 47 ++++++++++----- ncrypt/pgpinvoke.c | 6 ++ ncrypt/pgpkey.c | 2 +- ncrypt/smime.c | 40 ++++++++++--- 7 files changed, 143 insertions(+), 84 deletions(-) diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c index 0cca2ae31..168084e6f 100644 --- a/ncrypt/crypt_gpgme.c +++ b/ncrypt/crypt_gpgme.c @@ -967,10 +967,6 @@ static void print_time(time_t t, struct State *s) state_puts(p, s); } -/* - * Implementation of `sign_message'. - */ - /** * sign_message - Sign a message * @param a Message to sign @@ -1097,25 +1093,24 @@ static struct Body *sign_message(struct Body *a, int use_smime) return a; } +/** + * pgp_gpgme_sign_message - Implements CryptModuleSpecs::sign_message() + */ struct Body *pgp_gpgme_sign_message(struct Body *a) { return sign_message(a, 0); } +/** + * smime_gpgme_sign_message - Implements CryptModuleSpecs::sign_message() + */ struct Body *smime_gpgme_sign_message(struct Body *a) { return sign_message(a, 1); } -/* - * Implementation of `encrypt_message'. - */ - /** - * pgp_gpgme_encrypt_message - Encrypt a message - * - * Encrypt the mail body A to all keys given as space separated keyids - * or fingerprints in KEYLIST and return the encrypted body. + * pgp_gpgme_encrypt_message - Implements CryptModuleSpecs::pgp_encrypt_message() */ struct Body *pgp_gpgme_encrypt_message(struct Body *a, char *keylist, int sign) { @@ -1167,15 +1162,8 @@ struct Body *pgp_gpgme_encrypt_message(struct Body *a, char *keylist, int sign) return t; } -/* - * Implementation of `smime_build_smime_entity'. - */ - /** - * smime_gpgme_build_smime_entity - Encrypt the email body to all recipients - * - * Encrypt the mail body A to all keys given as space separated fingerprints in - * KEYLIST and return the S/MIME encrypted body. + * smime_gpgme_build_smime_entity - Implements CryptModuleSpecs::smime_build_smime_entity() */ struct Body *smime_gpgme_build_smime_entity(struct Body *a, char *keylist) { @@ -1740,20 +1728,22 @@ static int verify_one(struct Body *sigbdy, struct State *s, const char *tempfile return badsig ? 1 : anywarn ? 2 : 0; } +/** + * pgp_gpgme_verify_one - Implements CryptModuleSpecs::verify_one() + */ int pgp_gpgme_verify_one(struct Body *sigbdy, struct State *s, const char *tempfile) { return verify_one(sigbdy, s, tempfile, 0); } +/** + * smime_gpgme_verify_one - Implements CryptModuleSpecs::verify_one() + */ int smime_gpgme_verify_one(struct Body *sigbdy, struct State *s, const char *tempfile) { return verify_one(sigbdy, s, tempfile, 1); } -/* - * Implementation of `decrypt_part'. - */ - /** * decrypt_part - Decrypt a PGP or SMIME message * @@ -1916,11 +1906,7 @@ restart: } /** - * pgp_gpgme_decrypt_mime - Decrypt a PGP/MIME message - * @retval 0 Success - * - * The message in FPIN and B and return a new body and the stream in CUR and - * FPOUT. + * pgp_gpgme_decrypt_mime - Implements CryptModuleSpecs::decrypt_mime() */ int pgp_gpgme_decrypt_mime(FILE *fpin, FILE **fpout, struct Body *b, struct Body **cur) { @@ -2009,11 +1995,7 @@ bail: } /** - * smime_gpgme_decrypt_mime - Decrypt a S/MIME message - * @retval 0 Success - * - * The message in FPIN and B and return a new body and - * the stream in CUR and FPOUT. + * smime_gpgme_decrypt_mime - Implements CryptModuleSpecs::decrypt_mime() */ int smime_gpgme_decrypt_mime(FILE *fpin, FILE **fpout, struct Body *b, struct Body **cur) { @@ -2291,9 +2273,6 @@ static int line_compare(const char *a, size_t n, const char *b) #define BEGIN_PGP_SIGNATURE(_y) \ _LINE_COMPARE("-----BEGIN PGP SIGNATURE-----", _y) -/* - * Implementation of `pgp_check_traditional'. - */ static int pgp_check_traditional_one_body(FILE *fp, struct Body *b) { char tempfile[PATH_MAX]; @@ -2350,6 +2329,9 @@ static int pgp_check_traditional_one_body(FILE *fp, struct Body *b) return 1; } +/** + * pgp_gpgme_check_traditional - Implements CryptModuleSpecs::pgp_check_traditional() + */ int pgp_gpgme_check_traditional(FILE *fp, struct Body *b, int just_one) { int rc = 0; @@ -2373,6 +2355,9 @@ int pgp_gpgme_check_traditional(FILE *fp, struct Body *b, int just_one) return rc; } +/** + * pgp_gpgme_invoke_import - Implements CryptModuleSpecs::pgp_invoke_import() + */ void pgp_gpgme_invoke_import(const char *fname) { gpgme_data_t keydata; @@ -2401,10 +2386,6 @@ void pgp_gpgme_invoke_import(const char *fname) mutt_file_fclose(&out); } -/* - * Implementation of `application_handler'. - */ - /** * copy_clearsigned - Copy a clearsigned message * @@ -2472,7 +2453,7 @@ static void copy_clearsigned(gpgme_data_t data, struct State *s, char *charset) } /** - * pgp_gpgme_application_handler - Support for classic_application/pgp + * pgp_gpgme_application_handler - Implements CryptModuleSpecs::application_handler() */ int pgp_gpgme_application_handler(struct Body *m, struct State *s) { @@ -2709,12 +2690,8 @@ int pgp_gpgme_application_handler(struct Body *m, struct State *s) return err; } -/* - * Implementation of `encrypted_handler'. - */ - /** - * pgp_gpgme_encrypted_handler - MIME handler for pgp/mime encrypted messages + * pgp_gpgme_encrypted_handler - Implements CryptModuleSpecs::encrypted_handler() * * This handler is passed the application/octet-stream directly. * The caller must propagate a->goodsig to its parent. @@ -2794,7 +2771,7 @@ int pgp_gpgme_encrypted_handler(struct Body *a, struct State *s) } /** - * smime_gpgme_application_handler - Support for application/smime + * smime_gpgme_application_handler - Implements CryptModuleSpecs::application_handler() */ int smime_gpgme_application_handler(struct Body *a, struct State *s) { @@ -3916,10 +3893,6 @@ leave: mutt_do_pager(cmd, tempfile, 0, NULL); } -/* - * Implementation of `findkeys'. - */ - /** * list_to_pattern - Convert STailQ to GPGME-compatible pattern * @param list List of strings to convert @@ -4755,11 +4728,17 @@ static char *find_keys(struct Address *addrlist, unsigned int app, bool oppenc_m return keylist; } +/** + * pgp_gpgme_findkeys - Implements CryptModuleSpecs::findkeys() + */ char *pgp_gpgme_findkeys(struct Address *addrlist, bool oppenc_mode) { return find_keys(addrlist, APPLICATION_PGP, oppenc_mode); } +/** + * smime_gpgme_findkeys - Implements CryptModuleSpecs::findkeys() + */ char *smime_gpgme_findkeys(struct Address *addrlist, bool oppenc_mode) { return find_keys(addrlist, APPLICATION_SMIME, oppenc_mode); @@ -4826,10 +4805,6 @@ bail: } #endif -/* - * Implementation of `init'. - */ - /** * init_common - Initialise code common to PGP and SMIME parts of GPGME */ @@ -4865,12 +4840,18 @@ static void init_smime(void) } } +/** + * pgp_gpgme_init - Implements CryptModuleSpecs::init() + */ void pgp_gpgme_init(void) { init_common(); init_pgp(); } +/** + * smime_gpgme_init - Implements CryptModuleSpecs::init() + */ void smime_gpgme_init(void) { init_common(); @@ -5039,11 +5020,17 @@ static int gpgme_send_menu(struct Header *msg, int is_smime) return msg->security; } +/** + * pgp_gpgme_send_menu - Implements CryptModuleSpecs::send_menu() + */ int pgp_gpgme_send_menu(struct Header *msg) { return gpgme_send_menu(msg, 0); } +/** + * smime_gpgme_send_menu - Implements CryptModuleSpecs::send_menu() + */ int smime_gpgme_send_menu(struct Header *msg) { return gpgme_send_menu(msg, 1); @@ -5124,11 +5111,17 @@ static int verify_sender(struct Header *h) return rc; } +/** + * smime_gpgme_verify_sender - Implements CryptModuleSpecs::smime_verify_sender() + */ int smime_gpgme_verify_sender(struct Header *h) { return verify_sender(h); } +/** + * mutt_gpgme_set_sender - Implements CryptModuleSpecs::set_sender() + */ void mutt_gpgme_set_sender(const char *sender) { mutt_debug(2, "setting to: %s\n", sender); diff --git a/ncrypt/crypt_mod_pgp_gpgme.c b/ncrypt/crypt_mod_pgp_gpgme.c index 16dba5d29..fc8f706e0 100644 --- a/ncrypt/crypt_mod_pgp_gpgme.c +++ b/ncrypt/crypt_mod_pgp_gpgme.c @@ -32,17 +32,28 @@ #include "crypt_mod.h" #include "ncrypt.h" +/** + * crypt_mod_pgp_void_passphrase - Implements CryptModuleSpecs::void_passphrase() + * + * This is handled by gpg-agent. + */ static void crypt_mod_pgp_void_passphrase(void) { - /* Handled by gpg-agent. */ } +/** + * crypt_mod_pgp_valid_passphrase - Implements CryptModuleSpecs::valid_passphrase() + * + * This is handled by gpg-agent. + */ static int crypt_mod_pgp_valid_passphrase(void) { - /* Handled by gpg-agent. */ return 1; } +/** + * crypt_mod_pgp_make_key_attachment - Implements CryptModuleSpecs::pgp_make_key_attachment() + */ static struct Body *crypt_mod_pgp_make_key_attachment(char *tempf) { #ifdef HAVE_GPGME_OP_EXPORT_KEYS diff --git a/ncrypt/crypt_mod_smime_gpgme.c b/ncrypt/crypt_mod_smime_gpgme.c index 85011431c..8c7d268d6 100644 --- a/ncrypt/crypt_mod_smime_gpgme.c +++ b/ncrypt/crypt_mod_smime_gpgme.c @@ -32,14 +32,22 @@ #include "crypt_mod.h" #include "ncrypt.h" +/** + * crypt_mod_smime_void_passphrase - Implements CryptModuleSpecs::void_passphrase() + * + * This is handled by gpg-agent. + */ static void crypt_mod_smime_void_passphrase(void) { - /* Handled by gpg-agent. */ } +/** + * crypt_mod_smime_valid_passphrase - Implements CryptModuleSpecs::valid_passphrase() + * + * This is handled by gpg-agent. + */ static int crypt_mod_smime_valid_passphrase(void) { - /* Handled by gpg-agent. */ return 1; } diff --git a/ncrypt/pgp.c b/ncrypt/pgp.c index 1e690b727..314932b9b 100644 --- a/ncrypt/pgp.c +++ b/ncrypt/pgp.c @@ -63,12 +63,18 @@ char PgpPass[LONG_STRING]; time_t PgpExptime = 0; /* when does the cached passphrase expire? */ +/** + * pgp_void_passphrase - Implements CryptModuleSpecs::void_passphrase() + */ void pgp_void_passphrase(void) { memset(PgpPass, 0, sizeof(PgpPass)); PgpExptime = 0; } +/** + * pgp_valid_passphrase - Implements CryptModuleSpecs::valid_passphrase() + */ int pgp_valid_passphrase(void) { time_t now = time(NULL); @@ -315,7 +321,7 @@ static void pgp_copy_clearsigned(FILE *fpin, struct State *s, char *charset) } /** - * pgp_application_pgp_handler - Support for the Application/PGP Content Type + * pgp_application_pgp_handler - Implements CryptModuleSpecs::application_handler() */ int pgp_application_pgp_handler(struct Body *m, struct State *s) { @@ -673,6 +679,9 @@ static int pgp_check_traditional_one_body(FILE *fp, struct Body *b) return 1; } +/** + * pgp_check_traditional - Implements CryptModuleSpecs::pgp_check_traditional() + */ int pgp_check_traditional(FILE *fp, struct Body *b, int just_one) { int rc = 0; @@ -697,6 +706,9 @@ int pgp_check_traditional(FILE *fp, struct Body *b, int just_one) return rc; } +/** + * pgp_verify_one - Implements CryptModuleSpecs::verify_one() + */ int pgp_verify_one(struct Body *sigbdy, struct State *s, const char *tempfile) { char sigfile[PATH_MAX], pgperrfile[PATH_MAX]; @@ -791,6 +803,9 @@ static void pgp_extract_keys_from_attachment(FILE *fp, struct Body *top) mutt_file_unlink(tempfname); } +/** + * pgp_extract_keys_from_attachment_list - Implements CryptModuleSpecs::pgp_extract_keys_from_attachment_list() + */ void pgp_extract_keys_from_attachment_list(FILE *fp, int tag, struct Body *top) { if (!fp) @@ -944,6 +959,9 @@ static struct Body *pgp_decrypt_part(struct Body *a, struct State *s, return tattach; } +/** + * pgp_decrypt_mime - Implements CryptModuleSpecs::decrypt_mime() + */ int pgp_decrypt_mime(FILE *fpin, FILE **fpout, struct Body *b, struct Body **cur) { char tempfile[PATH_MAX]; @@ -1025,10 +1043,7 @@ bail: } /** - * pgp_encrypted_handler - Handler of PGP encrypted data - * - * This handler is passed the application/octet-stream directly. - * The caller must propagate a->goodsig to its parent. + * pgp_encrypted_handler - Implements CryptModuleSpecs::encrypted_handler() */ int pgp_encrypted_handler(struct Body *a, struct State *s) { @@ -1101,6 +1116,9 @@ int pgp_encrypted_handler(struct Body *a, struct State *s) * Routines for sending PGP/MIME messages. */ +/** + * pgp_sign_message - Implements CryptModuleSpecs::sign_message() + */ struct Body *pgp_sign_message(struct Body *a) { struct Body *t = NULL; @@ -1226,14 +1244,7 @@ struct Body *pgp_sign_message(struct Body *a) } /** - * pgp_find_keys - Find the keyids of the recipients of a message - * @param addrlist Address List - * @param oppenc_mode If true, use opportunistic encryption - * @retval ptr Space-separated string of keys - * @retval NULL At least one of the keys can't be found - * - * If oppenc_mode is true, only keys that can be determined without prompting - * will be used. + * pgp_find_keys - Implements CryptModuleSpecs::findkeys() */ char *pgp_find_keys(struct Address *addrlist, bool oppenc_mode) { @@ -1352,9 +1363,9 @@ char *pgp_find_keys(struct Address *addrlist, bool oppenc_mode) } /** - * pgp_encrypt_message - Encrypt a message + * pgp_encrypt_message - Implements CryptModuleSpecs::pgp_encrypt_message() * - * Warning: "a" is no longer freed in this routine, you need to free it later. + * @warning "a" is no longer freed in this routine, you need to free it later. * This is necessary for $fcc_attach. */ struct Body *pgp_encrypt_message(struct Body *a, char *keylist, int sign) @@ -1485,6 +1496,9 @@ struct Body *pgp_encrypt_message(struct Body *a, char *keylist, int sign) return t; } +/** + * pgp_traditional_encryptsign - Implements CryptModuleSpecs::pgp_traditional_encryptsign() + */ struct Body *pgp_traditional_encryptsign(struct Body *a, int flags, char *keylist) { struct Body *b = NULL; @@ -1660,6 +1674,9 @@ struct Body *pgp_traditional_encryptsign(struct Body *a, int flags, char *keylis return b; } +/** + * pgp_send_menu - Implements CryptModuleSpecs::send_menu() + */ int pgp_send_menu(struct Header *msg) { struct PgpKeyInfo *p = NULL; diff --git a/ncrypt/pgpinvoke.c b/ncrypt/pgpinvoke.c index be82fdf74..251ae3ed0 100644 --- a/ncrypt/pgpinvoke.c +++ b/ncrypt/pgpinvoke.c @@ -245,6 +245,9 @@ pid_t pgp_invoke_traditional(FILE **pgpin, FILE **pgpout, FILE **pgperr, } } +/** + * pgp_invoke_import - Implements CryptModuleSpecs::pgp_invoke_import() + */ void pgp_invoke_import(const char *fname) { char tmp_fname[PATH_MAX + SHORT_STRING]; @@ -265,6 +268,9 @@ void pgp_invoke_import(const char *fname) mutt_debug(1, "Error running \"%s\"!", cmd); } +/** + * pgp_invoke_getkeys - Implements CryptModuleSpecs::pgp_invoke_getkeys() + */ void pgp_invoke_getkeys(struct Address *addr) { char buf[PATH_MAX]; diff --git a/ncrypt/pgpkey.c b/ncrypt/pgpkey.c index 792a9779b..c07566de7 100644 --- a/ncrypt/pgpkey.c +++ b/ncrypt/pgpkey.c @@ -740,7 +740,7 @@ struct PgpKeyInfo *pgp_ask_for_key(char *tag, char *whatfor, short abilities, en } /** - * pgp_make_key_attachment - generate a public key attachment + * pgp_make_key_attachment - Implements CryptModuleSpecs::pgp_make_key_attachment() */ struct Body *pgp_make_key_attachment(char *tempf) { diff --git a/ncrypt/smime.c b/ncrypt/smime.c index a93428f5e..8ae312824 100644 --- a/ncrypt/smime.c +++ b/ncrypt/smime.c @@ -122,14 +122,18 @@ static struct SmimeKey *smime_copy_key(struct SmimeKey *key) * Queries and passphrase handling. */ -/* these are copies from pgp.c */ - +/** + * smime_void_passphrase - Implements CryptModuleSpecs::void_passphrase() + */ void smime_void_passphrase(void) { memset(SmimePass, 0, sizeof(SmimePass)); SmimeExptime = 0; } +/** + * smime_valid_passphrase - Implements CryptModuleSpecs::valid_passphrase() + */ int smime_valid_passphrase(void) { time_t now = time(NULL); @@ -875,6 +879,9 @@ static void getkeys(char *mailbox) NONULL(SmimeCertificates), NONULL(SmimeDefaultKey)); } +/** + * smime_getkeys - Implements CryptModuleSpecs::smime_getkeys() + */ void smime_getkeys(struct Envelope *env) { struct Address *t = NULL; @@ -914,11 +921,7 @@ void smime_getkeys(struct Envelope *env) } /** - * smime_find_keys - Find the keys of the recipients of a message - * @retval NULL if any of the keys can not be found - * - * If oppenc_mode is true, only keys that can be determined without - * prompting will be used. + * smime_find_keys - Implements CryptModuleSpecs::findkeys() */ char *smime_find_keys(struct Address *addrlist, bool oppenc_mode) { @@ -1221,7 +1224,7 @@ static char *smime_extract_signer_certificate(char *infile) } /** - * smime_invoke_import - Add a certificate and update index file (externally) + * smime_invoke_import - Implements CryptModuleSpecs::smime_invoke_import() */ void smime_invoke_import(char *infile, char *mailbox) { @@ -1295,6 +1298,9 @@ void smime_invoke_import(char *infile, char *mailbox) mutt_file_fclose(&fperr); } +/** + * smime_verify_sender - Implements CryptModuleSpecs::smime_verify_sender() + */ int smime_verify_sender(struct Header *h) { char *mbox = NULL, *certfile = NULL, tempfname[PATH_MAX]; @@ -1377,6 +1383,9 @@ static pid_t smime_invoke_sign(FILE **smimein, FILE **smimeout, FILE **smimeerr, SmimeCertToUse, SmimeIntermediateToUse, SmimeSignCommand); } +/** + * smime_build_smime_entity - Implements CryptModuleSpecs::smime_build_smime_entity() + */ struct Body *smime_build_smime_entity(struct Body *a, char *certlist) { char buf[LONG_STRING], certfile[PATH_MAX]; @@ -1527,6 +1536,9 @@ static char *openssl_md_to_smime_micalg(char *md) return micalg; } +/** + * smime_sign_message - Implements CryptModuleSpecs::sign_message() + */ struct Body *smime_sign_message(struct Body *a) { char buffer[LONG_STRING]; @@ -1682,6 +1694,9 @@ static pid_t smime_invoke_decrypt(FILE **smimein, FILE **smimeout, SmimeCertToUse, NULL, SmimeDecryptCommand); } +/** + * smime_verify_one - Implements CryptModuleSpecs::verify_one() + */ int smime_verify_one(struct Body *sigbdy, struct State *s, const char *tempfile) { char signedfile[PATH_MAX], smimeerrfile[PATH_MAX]; @@ -2002,6 +2017,9 @@ static struct Body *smime_handle_entity(struct Body *m, struct State *s, FILE *o return p; } +/** + * smime_decrypt_mime - Implements CryptModuleSpecs::decrypt_mime() + */ int smime_decrypt_mime(FILE *fpin, FILE **fpout, struct Body *b, struct Body **cur) { char tempfile[PATH_MAX]; @@ -2071,11 +2089,17 @@ bail: return rc; } +/** + * smime_application_smime_handler - Implements CryptModuleSpecs::application_handler() + */ int smime_application_smime_handler(struct Body *m, struct State *s) { return smime_handle_entity(m, s, NULL) ? 0 : -1; } +/** + * smime_send_menu - Implements CryptModuleSpecs::send_menu() + */ int smime_send_menu(struct Header *msg) { struct SmimeKey *key = NULL; -- 2.40.0