From 9663b088480cef6734a3c5892d5ddbbd60ecc1a4 Mon Sep 17 00:00:00 2001
From: "Neal H. Walfield" <neal@g10code.com>
Date: Wed, 3 Feb 2016 14:23:51 +0100
Subject: [PATCH] gpg: Improve API documentation.

* g10/seskey.c (make_session_key): Improve documentation.
(encode_session_key): Improve documentation.
* g10/encrypt.c (encrypt_seskey): Remove gratuitous initialization.
* g10/dek.h (DEK): Improve documenation.

--
Signed-off-by: Neal H. Walfield <neal@g10code.com>
---
 g10/dek.h     |  6 ++++++
 g10/encrypt.c |  3 +--
 g10/seskey.c  | 28 +++++++++++++++++-----------
 3 files changed, 24 insertions(+), 13 deletions(-)

diff --git a/g10/dek.h b/g10/dek.h
index 31ebbb6d2..1a879e3af 100644
--- a/g10/dek.h
+++ b/g10/dek.h
@@ -22,10 +22,16 @@
 
 typedef struct
 {
+  /* The algorithm (e.g., CIPHER_ALGO_AES).  */
   int algo;
+  /* The length of the key (in bytes).  */
   int keylen;
+  /* Whether we've already printed information about this key.  This
+     is currently only used in decrypt_data() and only if we are in
+     verbose mode.  */
   int algo_info_printed;
   int use_mdc;
+  /* This key was read from a SK-ESK packet (see proc_symkey_enc).  */
   int symmetric;
   byte key[32]; /* This is the largest used keylen (256 bit). */
   char s2k_cacheid[1+16+1];
diff --git a/g10/encrypt.c b/g10/encrypt.c
index abd800258..46b0be0cc 100644
--- a/g10/encrypt.c
+++ b/g10/encrypt.c
@@ -75,7 +75,6 @@ encrypt_seskey (DEK *dek, DEK **seskey, byte *enckey)
   if (!*seskey)
     {
       *seskey=xmalloc_clear(sizeof(DEK));
-      (*seskey)->keylen=dek->keylen;
       (*seskey)->algo=dek->algo;
       make_session_key(*seskey);
       /*log_hexdump( "thekey", c->key, c->keylen );*/
@@ -326,7 +325,7 @@ encrypt_simple (const char *filename, int mode, int use_seskey)
 
   if (!opt.no_literal)
     {
-      /* Note that PT has been initialized above in no_literal mode.  */
+      /* Note that PT has been initialized above in !no_literal mode.  */
       pt->timestamp = make_timestamp();
       pt->mode = opt.textmode? 't' : 'b';
       pt->len = filesize;
diff --git a/g10/seskey.c b/g10/seskey.c
index e79faf8c9..507eea111 100644
--- a/g10/seskey.c
+++ b/g10/seskey.c
@@ -31,9 +31,11 @@
 #include "i18n.h"
 
 
-/****************
- * Make a session key and put it into DEK
- */
+/* Generate a new session key in *DEK that is appropriate for the
+   algorithm DEK->ALGO (i.e., ensure that the key is not weak).
+
+   This function overwrites DEK->KEYLEN, DEK->KEY.  The rest of the
+   fields are left as is.  */
 void
 make_session_key( DEK *dek )
 {
@@ -67,11 +69,12 @@ make_session_key( DEK *dek )
 }
 
 
-/****************
- * Encode the session key. NBITS is the number of bits which should be used
- * for packing the session key.
- * returns: A mpi with the session key (caller must free)
- */
+/* Encode the session key stored in DEK as an MPI in preparation to
+   encrypt it with the public key algorithm OPENPGP_PK_ALGO with a key
+   whose length (the size of the public key) is NBITS.
+
+   On success, returns an MPI, which the caller must free using
+   gcry_mpi_release().  */
 gcry_mpi_t
 encode_session_key (int openpgp_pk_algo, DEK *dek, unsigned int nbits)
 {
@@ -136,14 +139,15 @@ encode_session_key (int openpgp_pk_algo, DEK *dek, unsigned int nbits)
     log_bug ("can't encode a %d bit key in a %d bits frame\n",
              dek->keylen*8, nbits );
 
-  /* We encode the session key in this way:
+  /* We encode the session key according to PKCS#1 v1.5 (see section
+   * 13.1.1 of RFC 4880):
    *
-   *	   0  2  RND(n bytes)  0  A  DEK(k bytes)  CSUM(2 bytes)
+   *	   0  2  RND(i bytes)  0  A  DEK(k bytes)  CSUM(2 bytes)
    *
    * (But how can we store the leading 0 - the external representaion
    *  of MPIs doesn't allow leading zeroes =:-)
    *
-   * RND are non-zero random bytes.
+   * RND are (at least 1) non-zero random bytes.
    * A   is the cipher algorithm
    * DEK is the encryption key (session key) length k depends on the
    *	   cipher algorithm (20 is used with blowfish160).
@@ -154,6 +158,8 @@ encode_session_key (int openpgp_pk_algo, DEK *dek, unsigned int nbits)
   n = 0;
   frame[n++] = 0;
   frame[n++] = 2;
+  /* The number of random bytes are the number of otherwise unused
+     bytes.  See diagram above.  */
   i = nframe - 6 - dek->keylen;
   assert( i > 0 );
   p = gcry_random_bytes_secure (i, GCRY_STRONG_RANDOM);