Improve some comments.
authorNeal H. Walfield <neal@g10code.com>
Tue, 29 Nov 2016 13:41:22 +0000 (14:41 +0100)
committerNeal H. Walfield <neal@g10code.com>
Tue, 29 Nov 2016 13:56:00 +0000 (14:56 +0100)
g10/armor.c
g10/cpr.c
g10/packet.h
g10/parse-packet.c
g10/sign.c
g10/tofu.c

index c80e902..58d8e01 100644 (file)
@@ -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;
     }
index c20c3f4..0133cad 100644 (file)
--- 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 )
 {
index 65f60a9..9780d93 100644 (file)
@@ -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;
index 38cfdd9..31e2a92 100644 (file)
@@ -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.
index a391128..19ca484 100644 (file)
@@ -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,
index bf2a048..14e4f1d 100644 (file)
 #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 <key: %s, user id: %s> had a conflict, but it's been resolved (probably via  cross sig).\n",