suggested doc & comment improvements for gnutls
Patrick Pelletier
code at funwithsoftware.org
Wed Dec 28 11:00:05 CET 2011
Hi,
I've been reading through the gnutls manual and code, and I've found a
few typos and phrases that sounded awkward, as well as a few minor
factual errors. (Like the fact that entropy is refreshed every 20
minutes, not every minute.)
Here's a diff of the changes I made to the manual and the comments in
the code. Let me know if there's a better way to submit this, such as
by pushing it to Github so you could pull it down from there.
Thanks,
--Patrick
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 32c806e..12ef7e4 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -130,10 +130,10 @@ The random generator of the cryptographic back-
end, is not thread safe and requi
mutex locks which are setup by @acronym{GnuTLS}.
Applications can either call @funcref{gnutls_global_init} which will
initialize the default
operating system provided locks (i.e. @code{pthreads} on GNU/Linux and
- at code{CriticalSection} on Windows), or specify manually the locking
system using
+ at code{CriticalSection} on Windows), or manually specify the locking
system using
the function @funcref{gnutls_global_set_mutex} before calling
@funcref{gnutls_global_init}.
-Setting manually mutexes is recommended
-only to applications that have full control of the underlying
libraries. If this
+Setting mutexes manually is recommended
+only for applications that have full control of the underlying
libraries. If this
is not the case, the use of the operating system defaults is
recommended. An example of
non-native thread usage is shown below.
@@ -305,7 +305,7 @@ current session using
@funcref{gnutls_credentials_set}.
When using certificates the server is required to have at least one
certificate and private key pair. Clients may not hold such
-a pair, but a server could require it. On this section we discuss
+a pair, but a server could require it. In this section we discuss
general issues applying to both client and server certificates. The
next
section will elaborate on issues arising from client authentication
only.
@@ -617,7 +617,7 @@ fatal for the protocol or can be ignored.
@showfuncdesc{gnutls_error_is_fatal}
-In DTLS it is adviceable to use the extended receive
+In DTLS it is advisable to use the extended receive
function shown below, because it allows the extraction
of the sequence number. This is required in DTLS because
messages may arrive out of order.
@@ -861,7 +861,7 @@ even it was requested. That is to prevent
temporal session keys
from becoming long-term keys. Also note that as a client you must
enable, using the
priority functions, at least the algorithms used in the last session.
-It is highly recommended clients to enable the session ticket
extension using
+It is highly recommended for clients to enable the session ticket
extension using
@funcref{gnutls_session_ticket_enable_client} in order to allow
resumption with
servers that do not store any state.
diff --git a/doc/cha-gtls-examples.texi b/doc/cha-gtls-examples.texi
index 7ce4ee1..7fa92af 100644
--- a/doc/cha-gtls-examples.texi
+++ b/doc/cha-gtls-examples.texi
@@ -188,7 +188,7 @@ server. Here it is separate for simplicity.
@node Echo Server with anonymous authentication
@subsection Echo Server with anonymous authentication
-This example server support anonymous authentication, and could be
+This example server supports anonymous authentication, and could be
used to serve the example client for anonymous authentication.
@verbatiminclude examples/ex-serv-anon.c
diff --git a/doc/cha-internals.texi b/doc/cha-internals.texi
index 81eb8e6..d7ec167 100644
--- a/doc/cha-internals.texi
+++ b/doc/cha-internals.texi
@@ -250,7 +250,7 @@ parsing incoming extension data (both in the
client and server).
The @funcintref{_foobar_send_params} function is responsible for
sending extension data (both in the client and server).
-If you receive length fields that doesn't match, return
+If you receive length fields that don't match, return
@code{GNUTLS_E_ at -UNEXPECTED_@-PACKET_ at -LENGTH}. If you receive
invalid
data, return @code{GNUTLS_E_ at -RECEIVED_@-ILLEGAL_ at -PARAMETER}. You
can use
other error codes from the list in @ref{Error codes}. Return 0 on
success.
diff --git a/lib/algorithms/ciphers.c b/lib/algorithms/ciphers.c
index 198844f..f8e1469 100644
--- a/lib/algorithms/ciphers.c
+++ b/lib/algorithms/ciphers.c
@@ -43,7 +43,7 @@ typedef struct gnutls_cipher_entry
gnutls_cipher_entry;
* View first: "The order of encryption and authentication for
* protecting communications" by Hugo Krawczyk - CRYPTO 2001
*
- * Make sure to updated MAX_CIPHER_BLOCK_SIZE and MAX_CIPHER_KEY_SIZE
as well.
+ * Make sure to update MAX_CIPHER_BLOCK_SIZE and MAX_CIPHER_KEY_SIZE
as well.
*/
static const gnutls_cipher_entry algorithms[] = {
{"AES-256-CBC", GNUTLS_CIPHER_AES_256_CBC, 16, 32, CIPHER_BLOCK,
16, 0, 0},
@@ -203,7 +203,7 @@ gnutls_cipher_get_name (gnutls_cipher_algorithm_t
algorithm)
/**
* gnutls_cipher_get_id:
- * @name: is a MAC algorithm name
+ * @name: is a cipher algorithm name
*
* The names are compared in a case insensitive way.
*
diff --git a/lib/algorithms/protocols.c b/lib/algorithms/protocols.c
index 6d6b04c..e59c8fd 100644
--- a/lib/algorithms/protocols.c
+++ b/lib/algorithms/protocols.c
@@ -162,7 +162,7 @@ gnutls_protocol_get_id (const char *name)
*
* Get a list of supported protocols, e.g. SSL 3.0, TLS 1.0 etc.
*
- * This function is not threat safe.
+ * This function is not thread safe.
*
* Returns: a (0)-terminated list of #gnutls_protocol_t integers
* indicating the available protocols.
diff --git a/lib/algorithms/secparams.c b/lib/algorithms/secparams.c
index ba6c7d5..456e3a1 100644
--- a/lib/algorithms/secparams.c
+++ b/lib/algorithms/secparams.c
@@ -127,7 +127,7 @@ _gnutls_pk_bits_to_subgroup_bits (unsigned int
pk_bits)
* Convert a #gnutls_sec_param_t value to a string.
*
* Returns: a pointer to a string that contains the name of the
- * specified public key algorithm, or %NULL.
+ * specified security level, or %NULL.
*
* Since: 2.12.0
**/
diff --git a/lib/gnutls_cert.c b/lib/gnutls_cert.c
index 75638b9..66d0a9f 100644
--- a/lib/gnutls_cert.c
+++ b/lib/gnutls_cert.c
@@ -129,7 +129,7 @@ gnutls_certificate_get_issuer
(gnutls_certificate_credentials_t sc,
* sending the names of it would just consume bandwidth without
providing
* information to client.
*
- * CA names are used by servers to advertize the CAs they support to
+ * CA names are used by servers to advertise the CAs they support to
* clients.
**/
void
diff --git a/lib/gnutls_cipher.c b/lib/gnutls_cipher.c
index c157843..f041821 100644
--- a/lib/gnutls_cipher.c
+++ b/lib/gnutls_cipher.c
@@ -253,7 +253,7 @@ calc_enc_length (gnutls_session_t session, int
data_size,
#define MAX_PREAMBLE_SIZE 16
/* generates the authentication data (data to be hashed only
- * and are not to be send). Returns their size.
+ * and are not to be sent). Returns their size.
*/
static inline int
make_preamble (opaque * uint64_data, opaque type, int length,
diff --git a/lib/gnutls_db.c b/lib/gnutls_db.c
index 5e07b04..ed91fe7 100644
--- a/lib/gnutls_db.c
+++ b/lib/gnutls_db.c
@@ -76,8 +76,8 @@ gnutls_db_set_remove_function (gnutls_session_t
session,
* @session: is a #gnutls_session_t structure.
* @store_func: is the function
*
- * Sets the function that will be used to store data from the resumed
- * sessions database. This function must remove 0 on success.
+ * Sets the function that will be used to store data in the resumed
+ * sessions database. This function must return 0 on success.
*
* The first argument to @store_func will be null unless
* gnutls_db_set_ptr() has been called.
@@ -124,7 +124,7 @@ gnutls_db_get_ptr (gnutls_session_t session)
* @seconds: is the number of seconds.
*
* Set the expiration time for resumed sessions. The default is 3600
- * (one hour) at the time writing this.
+ * (one hour) at the time of this writing.
**/
void
gnutls_db_set_cache_expiration (gnutls_session_t session, int seconds)
@@ -138,7 +138,7 @@ gnutls_db_set_cache_expiration (gnutls_session_t
session, int seconds)
* @session_entry: is the session data (not key)
*
* Check if database entry has expired. This function is to be used
- * when you want to clear unnesessary session which occupy space in
+ * when you want to clear unnecessary sessions which occupy space in
* your backend.
*
* Returns: Returns %GNUTLS_E_EXPIRED, if the database entry has
diff --git a/lib/gnutls_global.c b/lib/gnutls_global.c
index 010e614..e874abb 100644
--- a/lib/gnutls_global.c
+++ b/lib/gnutls_global.c
@@ -130,7 +130,7 @@ gnutls_global_set_log_level (int level)
* @realloc_func: A realloc function
* @free_func: The function that frees allocated data. Must accept a
NULL pointer.
*
- * This is the function were you set the memory allocation functions
+ * This is the function where you set the memory allocation functions
* gnutls is going to use. By default the libc's allocation functions
* (malloc(), free()), are used by gnutls, to allocate both sensitive
* and not sensitive data. This function is provided to set the
@@ -184,7 +184,7 @@ static int _gnutls_init = 0;
* Note that this function will also initialize the underlying crypto
* backend, if it has not been initialized before.
*
- * This function increment a global counter, so that
+ * This function increments a global counter, so that
* gnutls_global_deinit() only releases resources when it has been
* called as many times as gnutls_global_init(). This is useful when
* GnuTLS is used by more than one library in an application. This
diff --git a/lib/gnutls_handshake.c b/lib/gnutls_handshake.c
index bf75919..805bed5 100644
--- a/lib/gnutls_handshake.c
+++ b/lib/gnutls_handshake.c
@@ -2324,7 +2324,7 @@ cleanup:
*
* The non-fatal errors such as %GNUTLS_E_AGAIN and
* %GNUTLS_E_INTERRUPTED interrupt the handshake procedure, which
- * should be later be resumed. Call this function again, until it
+ * should be resumed later. Call this function again, until it
* returns 0; cf. gnutls_record_get_direction() and
* gnutls_error_is_fatal().
*
diff --git a/lib/gnutls_priority.c b/lib/gnutls_priority.c
index 8ac89a5..0a79b67 100644
--- a/lib/gnutls_priority.c
+++ b/lib/gnutls_priority.c
@@ -285,7 +285,7 @@ static const int kx_priority_export[] = {
static const int kx_priority_secure[] = {
/* The ciphersuites that offer forward secrecy take
- * precendance
+ * precedence
*/
GNUTLS_KX_ECDHE_ECDSA,
GNUTLS_KX_ECDHE_RSA,
@@ -396,7 +396,7 @@ static const int cipher_priority_export[] = {
};
static const int comp_priority[] = {
- /* compression should be explicitely requested to be enabled */
+ /* compression should be explicitly requested to be enabled */
GNUTLS_COMP_NULL,
0
};
diff --git a/lib/gnutls_state.c b/lib/gnutls_state.c
index d1b9561..712ba1d 100644
--- a/lib/gnutls_state.c
+++ b/lib/gnutls_state.c
@@ -725,9 +725,9 @@ gnutls_openpgp_send_cert (gnutls_session_t session,
*
* If status is non zero, this function will order gnutls not to send
* the rdnSequence in the certificate request message. That is the
- * server will not advertize it's trusted CAs to the peer. If status
+ * server will not advertise its trusted CAs to the peer. If status
* is zero then the default behaviour will take effect, which is to
- * advertize the server's trusted CAs.
+ * advertise the server's trusted CAs.
*
* This function has no effect in clients, and in authentication
* methods other than certificate with X.509 certificates.
diff --git a/lib/gnutls_ui.c b/lib/gnutls_ui.c
index 248c8a0..edf80c0 100644
--- a/lib/gnutls_ui.c
+++ b/lib/gnutls_ui.c
@@ -22,7 +22,7 @@
*/
/* This file contains certificate authentication functions to be
exported in the
- * API and did not fit elsewhere.
+ * API which did not fit elsewhere.
*/
#include <gnutls_int.h>
@@ -42,7 +42,7 @@
* @session: is a #gnutls_session_t structure.
* @bits: is the number of bits
*
- * This function sets the number of bits, for use in an Diffie-Hellman
+ * This function sets the number of bits, for use in a Diffie-Hellman
* key exchange. This is used both in DH ephemeral and DH anonymous
* cipher suites. This will set the minimum size of the prime that
* will be used for the handshake.
@@ -313,7 +313,7 @@ mpi_buf2bits (gnutls_datum_t * mpi_buf)
* This function will return the bits of the prime used in the last
* Diffie-Hellman key exchange with the peer. Should be used for both
* anonymous and ephemeral Diffie-Hellman. Note that some ciphers,
- * like RSA and DSA without DHE, does not use a Diffie-Hellman key
+ * like RSA and DSA without DHE, do not use a Diffie-Hellman key
* exchange, and then this function will return 0.
*
* Returns: The Diffie-Hellman bit strength is returned, or 0 if no
diff --git a/lib/nettle/rnd.c b/lib/nettle/rnd.c
index 3f611f1..792d65c 100644
--- a/lib/nettle/rnd.c
+++ b/lib/nettle/rnd.c
@@ -116,7 +116,7 @@ do_device_source (int init)
&& (init || ((now - device_last_read) > DEVICE_READ_INTERVAL)))
{
- /* More than a minute since we last read the device */
+ /* More than 20 minutes since we last read the device */
uint8_t buf[DEVICE_READ_SIZE_MAX];
if (!CryptGenRandom (device_fd, (DWORD) read_size, buf))
@@ -250,7 +250,7 @@ do_device_source_urandom (int init)
if ((device_fd > 0)
&& (init || ((now - device_last_read) > DEVICE_READ_INTERVAL)))
{
- /* More than a minute since we last read the device */
+ /* More than 20 minutes since we last read the device */
uint8_t buf[DEVICE_READ_SIZE_MAX];
uint32_t done;
@@ -312,7 +312,7 @@ do_device_source_egd (int init)
&& (init || ((now - device_last_read) > DEVICE_READ_INTERVAL)))
{
- /* More than a minute since we last read the device */
+ /* More than 20 minutes since we last read the device */
uint8_t buf[DEVICE_READ_SIZE_MAX];
uint32_t done;
More information about the Gnutls-devel
mailing list