From 522f74f7e377135cf098b6b0b9b35284c1dfc963 Mon Sep 17 00:00:00 2001 From: "Neal H. Walfield" Date: Tue, 29 Nov 2016 14:41:22 +0100 Subject: [PATCH] Improve some comments. --- g10/armor.c | 3 +++ g10/cpr.c | 2 +- g10/packet.h | 6 ++++-- g10/parse-packet.c | 4 ++-- g10/sign.c | 32 ++++++++++++++++++++++++-------- g10/tofu.c | 34 +++++++++++++++++----------------- 6 files changed, 51 insertions(+), 30 deletions(-) diff --git a/g10/armor.c b/g10/armor.c index c80e902d2..58d8e01b1 100644 --- a/g10/armor.c +++ b/g10/armor.c @@ -1026,17 +1026,20 @@ armor_filter( void *opaque, int control, if( control == IOBUFCTRL_UNDERFLOW && afx->inp_bypass ) { n = 0; if( afx->buffer_len ) { + /* Copy the data from AFX->BUFFER to BUF. */ for(; n < size && afx->buffer_pos < afx->buffer_len; n++ ) buf[n++] = afx->buffer[afx->buffer_pos++]; if( afx->buffer_pos >= afx->buffer_len ) afx->buffer_len = 0; } + /* If there is still space in BUF, read directly into it. */ for(; n < size; n++ ) { if( (c=iobuf_get(a)) == -1 ) break; buf[n] = c & 0xff; } if( !n ) + /* We didn't get any data. EOF. */ rc = -1; *ret_len = n; } diff --git a/g10/cpr.c b/g10/cpr.c index c20c3f4ce..0133cad31 100644 --- a/g10/cpr.c +++ b/g10/cpr.c @@ -405,7 +405,7 @@ myread(int fd, void *buf, size_t count) /* Request a string from the client over the command-fd. If GETBOOL is set the function returns a static string (do not free) if the - netered value was true or NULL if the entered value was false. */ + entered value was true or NULL if the entered value was false. */ static char * do_get_from_fd ( const char *keyword, int hidden, int getbool ) { diff --git a/g10/packet.h b/g10/packet.h index 65f60a9e5..9780d939e 100644 --- a/g10/packet.h +++ b/g10/packet.h @@ -95,7 +95,9 @@ typedef struct typedef struct { /* RFC 4880: this must be 4. */ byte version; - /* The cipher algorithm used. */ + /* The cipher algorithm used to encrypt the session key. (This may + be different from the algorithm that is used to encrypt the SED + packet.) */ byte cipher_algo; /* The string-to-key specifier. */ STRING2KEY s2k; @@ -269,7 +271,7 @@ typedef struct struct user_attribute *attribs; int numattribs; /* If this is not NULL, the packet is a user attribute rather than a - user id. (Serialized.) */ + user id (See RFC 4880 5.12). (Serialized.) */ byte *attrib_data; /* The length of ATTRIB_DATA. */ unsigned long attrib_len; diff --git a/g10/parse-packet.c b/g10/parse-packet.c index 38cfdd985..31e2a92d8 100644 --- a/g10/parse-packet.c +++ b/g10/parse-packet.c @@ -809,8 +809,8 @@ dump_hex_line (int c, int *i) decoded values are given as PKGTYPE and PKTLEN. If the packet is a partial body length packet (RFC 4880, Section - 4.2.2.4), then iobuf_set_partial_block_mode should already have - been called on INP and PARTIAL should be set. + 4.2.2.4), then iobuf_set_partial_block_modeiobuf_set_partial_block_mode + should already have been called on INP and PARTIAL should be set. If PARTIAL is set or PKTLEN is 0 and PKTTYPE is PKT_COMPRESSED, copy until the first EOF is encountered on INP. diff --git a/g10/sign.c b/g10/sign.c index a39112824..19ca4840c 100644 --- a/g10/sign.c +++ b/g10/sign.c @@ -1386,14 +1386,30 @@ sign_symencrypt_file (ctrl_t ctrl, const char *fname, strlist_t locusr) /**************** - * Create a signature packet for the given public key certificate and - * the user id and return it in ret_sig. User signature class SIGCLASS - * user-id is not used (and may be NULL if sigclass is 0x20) If - * DIGEST_ALGO is 0 the function selects an appropriate one. - * SIGVERSION gives the minimal required signature packet version; - * this is needed so that special properties like local sign are not - * applied (actually: dropped) when a v3 key is used. TIMESTAMP is - * the timestamp to use for the signature. 0 means "now" */ + * Create a v4 signature in *RET_SIG. + * + * PK is the primary key to sign (required for all sigs) + * UID is the user id to sign (required for 0x10..0x13, 0x30) + * SUBPK is subkey to sign (required for 0x18, 0x19, 0x28) + * + * PKSK is the signing key + * + * SIGCLASS is the type of signature to create. + * + * DIGEST_ALGO is the digest algorithm. If it is 0 the function + * selects an appropriate one. + * + * TIMESTAMP is the timestamp to use for the signature. 0 means "now" + * + * DURATION is the amount of time (in seconds) until the signature + * expires. + * + * This function creates the following subpackets: issuer, created, + * and expire (if duration is not 0). Additional subpackets can be + * added using MKSUBPKT, which is called after these subpackets are + * added and before the signature is generated. OPAQUE is passed to + * MKSUBPKT. + */ int make_keysig_packet (PKT_signature **ret_sig, PKT_public_key *pk, PKT_user_id *uid, PKT_public_key *subpk, diff --git a/g10/tofu.c b/g10/tofu.c index bf2a0484d..14e4f1d29 100644 --- a/g10/tofu.c +++ b/g10/tofu.c @@ -57,12 +57,11 @@ #define FULL_TRUST_THRESHOLD 100 -/* An struct with data pertaining to the tofu DB. - - To initialize this data structure, call opendbs(). Cleanup is done - when the CTRL object is released. To get a handle to a database, - use the getdb() function. This will either return an existing - handle or open a new DB connection, as appropriate. */ +/* A struct with data pertaining to the tofu DB. There is one such + struct per session and it is cached in session's ctrl structure. + To initialize this or get the current singleton, call opendbs(). + There is no need to explicitly release it; cleanup is done when the + CTRL object is released. */ struct tofu_dbs_s { sqlite3 *db; @@ -179,8 +178,8 @@ begin_transaction (ctrl_t ctrl, int only_batch) * than 500 ms), to prevent starving other gpg processes, we drop * and retake the batch lock. * - * Note: if we wanted higher resolution, we could use - * npth_clock_gettime. */ + * Note: gnupg_get_time has a one second resolution, if we wanted a + * higher resolution, we could use npth_clock_gettime. */ if (/* No real transactions. */ dbs->in_transaction == 0 /* There is an open batch transaction. */ @@ -264,8 +263,8 @@ begin_transaction (ctrl_t ctrl, int only_batch) /* Commit a transaction. If ONLY_BATCH is 1, then this only ends the * batch transaction if we have left batch mode. If ONLY_BATCH is 2, - * this ends any open batch transaction even if we are still in batch - * mode. */ + * this commits any open batch transaction even if we are still in + * batch mode. */ static gpg_error_t end_transaction (ctrl_t ctrl, int only_batch) { @@ -341,7 +340,7 @@ rollback_transaction (ctrl_t ctrl) log_assert (dbs); log_assert (dbs->in_transaction > 0); - /* Be careful to not any progress made by closed transactions in + /* Be careful to not undo any progress made by closed transactions in batch mode. */ rc = gpgsql_exec_printf (dbs->db, NULL, NULL, &err, "rollback to inner%d;", @@ -1152,7 +1151,7 @@ record_binding (tofu_dbs_t dbs, const char *fingerprint, const char *email, } -/* Collect the strings returned by a query in a simply string list. +/* Collect the strings returned by a query in a simple string list. Any NULL values are converted to the empty string. If a result has 3 rows and each row contains two columns, then the @@ -2475,11 +2474,12 @@ get_policy (tofu_dbs_t dbs, PKT_public_key *pk, if (conflict_set_count == 1 && (conflict_set->flags & BINDING_CONFLICT)) { - /* No known conflicts now, but there was a conflict. That is, - * at somepoint there was a conflict, but it went away. A - * conflict can go away if there is now a cross sig between the - * two keys. In this case, we just silently clear the - * conflict. */ + /* No known conflicts now, but there was a conflict. This means + * at some point, there was a conflict and we changed this + * binding's policy to ask and set the conflicting key. The + * conflict can go away if there is not a cross sig between the + * two keys. In this case, just silently clear the conflict and + * reset the policy to auto. */ if (DBG_TRUST) log_debug ("TOFU: binding had a conflict, but it's been resolved (probably via cross sig).\n",