[Pkg-gnupg-commit] [gnupg2] 27/205: gpg: Improve API documentation.
Daniel Kahn Gillmor
dkg at fifthhorseman.net
Wed May 11 08:38:11 UTC 2016
This is an automated email from the git hooks/post-receive script.
dkg pushed a commit to branch experimental
in repository gnupg2.
commit 9663b088480cef6734a3c5892d5ddbbd60ecc1a4
Author: Neal H. Walfield <neal at g10code.com>
Date: Wed Feb 3 14:23:51 2016 +0100
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 at 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 31ebbb6..1a879e3 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 abd8002..46b0be0 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 e79faf8..507eea1 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);
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/gnupg2.git
More information about the Pkg-gnupg-commit
mailing list