help-gsasl
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

typos in gsasl.texi


From: Marco Maggi
Subject: typos in gsasl.texi
Date: Fri, 22 May 2009 10:29:01 +0200

Do no apply it blindly.

--- original-gsasl.texi 2009-03-24 22:45:59.000000000 +0100
+++ gsasl.texi  2009-05-22 10:16:08.000000000 +0200
@@ -98,7 +98,7 @@
 to authenticate against servers.
 
 GNU SASL consists of a library (`libgsasl'), a command line utility
-(`gsasl') to access the library from the shell, and a manual.  The
+(@command{gsasl}) to access the library from the shell, and a manual.  The
 library includes support for the framework (with authentication
 functions and application data privacy and integrity functions) and at
 least partial support for the CRAM-MD5, EXTERNAL, GSSAPI, ANONYMOUS,
@@ -107,7 +107,7 @@
 The library is easily ported because it does not do network
 communication by itself, but rather leaves it up to the calling
 application.  The library is flexible with regards to the
-authorization infrastructure used, as it utilize a callback into the
+authorization infrastructure used, as it utilizes a callback into the
 application to decide whether a user is authorized or not.
 
 GNU SASL is developed for the GNU/Linux system, but runs on over 20
@@ -117,15 +117,15 @@
 GNU SASL is written in pure ANSI C89 to be portable to embedded and
 otherwise limited platforms.  The entire library, with full support
 for ANONYMOUS, EXTERNAL, PLAIN, LOGIN and CRAM-MD5, and the front-end
-that support client and server mode, and the IMAP and SMTP protocols,
-fits in under 60kb on an Intel x86 platform, without any modifications
-to the code.  (This figure was accurate as of version 0.0.13.)
+that supports client and server mode, and the IMAP and SMTP protocols,
+fits in under 80kb on an Intel x86 platform, without any modifications
+to the code.  (This figure was accurate as of version 1.1.)
 
 The library is licensed under the GNU Lesser General Public License
-version 2.1 or later.  The command-line application (src/), examples
-(examples/), self-test suite (tests/) are licensed under the GNU
+version 2.1 or later.  The command-line application (@file{src/}), examples
+(@file{examples/}), self-test suite (@file{tests/}) are licensed under the GNU
 General Public License license version 3.0 or later.  The
-documentation (doc/) is licensed under the GNU Free Documentation
+documentation (@file{doc/}) is licensed under the GNU Free Documentation
 License version 1.3 or later.
 
 @float Illustration,fig:abstraction
@@ -184,7 +184,7 @@
 handles may be used in parallel.
 
 @item It's internationalized
-It handles non-ASCII username and passwords and user visible strings
+It handles non-ASCII usernames and passwords and user visible strings
 used in the library (error messages) can be translated into the users'
 language.
 
@@ -195,7 +195,7 @@
 
 @end table
 
-Note that the library do not implement any policy to decide whether a
+Note that the library does not implement any policy to decide whether a
 certain user is ``authenticated'' or ``authorized'' or not.  Rather,
 it uses a callback into the application to answer these questions.
 
@@ -220,7 +220,7 @@
 server challenges and client responses that are specific to the
 requested mechanism.  The challenges and responses are defined by the
 mechanisms as binary tokens of arbitrary length.  The protocol's
-profile then specifies how these binary tokens are then encoded for
+profile then specifies how these binary tokens are encoded for
 transfer over the connection.
 
 After receiving the authentication command or any client response, a
@@ -234,7 +234,7 @@
 
 During the authentication protocol exchange, the mechanism performs
 authentication, transmits an authorization identity (frequently known
-as a userid) from the client to server, and negotiates the use of a
+as a userid) from client to server, and negotiates the use of a
 mechanism-specific security layer.  If the use of a security layer is
 agreed upon, then the mechanism must also define or negotiate the
 maximum cipher-text buffer size that each side is able to receive.
@@ -242,7 +242,7 @@
 The transmitted authorization identity may be different than the
 identity in the client's authentication credentials.  This permits
 agents such as proxy servers to authenticate using their own
-credentials, yet request the access privileges of the identity for
+credentials, yet to request the access privileges of the identity for
 which they are proxying.  With any mechanism, transmitting an
 authorization identity of the empty string directs the server to
 derive an authorization identity from the client's authentication
@@ -255,7 +255,7 @@
 for data sent by the server.  Once the security layer is in effect,
 the protocol stream is processed by the security layer into buffers
 of cipher-text.  Each buffer is transferred over the connection as a
-stream of octets prepended with a four octet field in network byte
+stream of octets prepended with a four-octet field in network byte
 order that represents the length of the following buffer.  The length
 of the cipher-text buffer must be no larger than the maximum size
 that was defined or negotiated by the other side.
@@ -277,7 +277,7 @@
 (@url{http://www.gnu.org/software/gss/}), MIT Kerberos or Heimdal.
 
 @item LibIDN
-Processing of non-ASCII username and passwords requires the SASLprep
+Processing of non-ASCII usernames and passwords requires the SASLprep
 implementation in LibIDN (@url{http://www.gnu.org/software/libidn/}).
 This is needed for full conformance with the latest SASL protocol
 drafts, but is optional in the library for improved portability.
@@ -469,7 +469,7 @@
 E-mail: address@hidden
 @end verbatim
 
-If your company provide support related to GNU SASL and would like to
+If your company provides support related to GNU SASL and would like to
 be mentioned here, contact the author (@pxref{Bug Reports}).
 
 @node Downloading and Installing
@@ -490,8 +490,8 @@
 and building it, refer to the @file{INSTALL} file that is part of the
 distribution archive.
 
-Here is an example terminal session that download, configure, build
-and install the package.  You will need a few basic tools, such as
+Here is an example terminal session that downloads, configures, builds
+and installs the package.  You will need a few basic tools, such as
 @samp{sh}, @samp{make} and @samp{cc}.
 
 @example
@@ -516,13 +516,13 @@
 @item --disable-client
 @itemx --disable-server
 If your target system require a minimal implementation, you may wish
-to disable the client or the server part of the code.  This do not
+to disable the client or the server part of the code.  This does not
 remove symbols from the library, so if you attempt to call an
 application that uses server functions in a library built with
 @code{--disable-server}, the function will return an error code.
 
 @item --disable-obsolete
-This remove backwards compatibility (@pxref{Old Functions}).  Use if
+Remove backwards compatibility (@pxref{Old Functions}).  Use if
 you want to limit the size of the library.
 
 @item --disable-anonymous
@@ -561,7 +561,7 @@
 the generic installation instructions (@pxref{Downloading and
 Installing}).  The DLL is installed by default.
 
-For information on how to use the DLL in other applications, see:
+For informations on how to use the DLL in other applications, see:
 @url{http://www.mingw.org/mingwfaq.shtml#faq-msvcdll}.
 
 You can build GNU SASL as a native Visual Studio C++ project.  This
@@ -582,7 +582,7 @@
 uses the Windows function @code{CryptGenRandom} for generating
 cryptographic random data.  The function is known to have some
 security weaknesses.  See @url{http://eprint.iacr.org/2007/419} for
-more information.  The code will attempt to use the Intel RND crypto
+more informations.  The code will attempt to use the Intel RND crypto
 provider if it is installed, see @file{lib/gl/gc-gnulib.c}.
 
 @node Bug Reports
@@ -602,15 +602,15 @@
 reproduce the bug.
 
 @item You also have to explain what is wrong; if you get a crash, or
-if the results printed are not good and in that case, in what way.
-Make sure that the bug report includes all information you would need
+if the results printed are not good and in that case, in which way.
+Make sure that the bug report includes all the informations you would need
 to fix this kind of bug for someone else.
 
 @end itemize
 
 Please make an effort to produce a self-contained report, with
 something definite that can be tested or debugged.  Vague queries or
-piecemeal messages are difficult to act on and don't help the
+piecemeal messages are difficult to act upon and don't help the
 development effort.
 
 If your bug report is good, we will do our best to help you to get a
@@ -631,8 +631,8 @@
 @cindex Contributing
 @cindex Hacking
 
-If you want to submit a patch for inclusion -- from solve a typo you
-discovered, up to adding support for a new feature -- you should
+If you want to submit a patch for inclusion --- from solve a typo you
+discovered, up to adding support for a new feature --- you should
 submit it as a bug report (@pxref{Bug Reports}).  There are some
 things that you can do to increase the chances for it to be included
 in the official package.
@@ -662,7 +662,7 @@
 
 @item Return errors.
 No reason whatsoever should abort the execution of the library.  Even
-memory allocation errors, e.g. when malloc return NULL, should work
+memory allocation errors, e.g. when @code{malloc} returns @code{NULL}, should 
work
 although result in an error code.
 
 @item Design with thread safety in mind.
@@ -726,11 +726,11 @@
 @node Initialization
 @section Initialization
 
-The library must be initialized before it can be used.  The library is
-initialized by calling @code{gsasl_init} (@pxref{Global Functions}).
-The resources allocated by the initialization process can be released
-if the application no longer has a need to call `Libgsasl' functions,
-this is done by calling @code{gsasl_done}.  For example:
+The library must be initialized before it can be used, by calling
address@hidden (@pxref{Global Functions}).  The resources allocated
+by the initialization process can be released if the application no
+longer has a need to call `Libgsasl' functions, this is done by calling
address@hidden  For example:
 
 @example
 int
@@ -779,7 +779,7 @@
 that GNU SASL really use Libgcrypt, if this is what you want.}, you
 need to initialize secure memory in your application, and for some
 platforms even make your application setuid root.  See the Libgcrypt
-documentation for more information.  Example code to initialize secure
+documentation for more information.  Example to initialize secure
 memory in your code:
 
 @example
@@ -813,17 +813,17 @@
 @end example
 
 If you do not do this, keying material will not be allocated in secure
-memory (which for most application is not the biggest secure problem
+memory (which, for most applications, it is not the biggest security problem
 anyway).  Note that the GNU SASL Library has not been audited to make
-sure it only ever stores passwords or keys in secure memory.
+sure it stores passwords and keys in secure memory only.
 
 @node Version Check
 @section Version Check
 
 It is often desirable to check that the version of the library used is
 indeed one which fits all requirements.  Even with binary
-compatibility new features may have been introduced but due to problem
-with the dynamic linker an old version is actually used.  So you may
+compatibility, new features may have been introduced but, due to problems
+with the dynamic linker, an old version may actually be used.  So you may
 want to check that the version is okay right after program startup.
 
 @include texi/gsasl_check_version.texi
@@ -844,11 +844,11 @@
 @section Building the source
 @cindex Compiling your application
 
-If you want to compile a source file including the @file{gsasl.h}
-header file, you must make sure that the compiler can find it in the
-directory hierarchy.  This is accomplished by adding the path to the
-directory in which the header file is located to the compilers include
-file search path (via the @option{-I} option).
+If you want to compile a source file including the @file{gsasl.h} header
+file, you must make sure that the compiler can find it in the directory
+hierarchy.  This is accomplished by adding to the compiler include file
+search path (via the @option{-I} option), the path to the directory in
+which the header file is located.
 
 However, the path to the include file is determined at the time the
 source is configured.  To solve this problem, the library uses the
@@ -863,7 +863,7 @@
 @end example
 
 Adding the output of @samp{pkg-config libgsasl --cflags} to the
-compilers command line will ensure that the compiler can find the
+compiler command line will ensure that the compiler can find the
 @file{gsasl.h} header file.
 
 A similar problem occurs when linking the program with the library.
@@ -872,7 +872,7 @@
 path (via the @option{-L} option).  For this, the option
 @option{--libs} to @command{pkg-config libgsasl} can be used.  For
 convenience, this option also outputs all other options that are
-required to link the program with the libarary (for instance, the
+required to link the program with the library (for instance, the
 @samp{-lidn} option).  The example shows how to link @file{foo.o} with
 the library to a program @command{foo}.
 
@@ -905,7 +905,7 @@
 If your audience is a typical GNU/Linux desktop, you can often assume
 they have the @samp{pkg-config} tool installed, in which you can use
 its Autoconf M4 macro to find and set up your package for use with
-Libgsasl.  The following illustrate this scenario.
+Libgsasl.  The following example illustrates this scenario.
 
 @example
 AC_ARG_ENABLE(gsasl,
@@ -929,10 +929,10 @@
 
 @subsection Standalone Autoconf test using Libtool
 
-If your package uses Libtool(@pxref{top, GNU Libtool,, libtool}), you
+If your package uses Libtool (@pxref{top, GNU Libtool,, libtool}), you
 can use the normal Autoconf tests to find Libgsasl and rely on the
 Libtool dependency tracking to include the proper dependency libraries
-(e.g., Libidn).  The following illustrate this scenario.
+(e.g., Libidn).  The following example illustrates this scenario.
 
 @example
 AC_CHECK_HEADER(gsasl.h,
@@ -963,20 +963,20 @@
 Your application's use of the library can be roughly modeled into the
 following steps: initialize the library, optionally specify the
 callback, perform the authentication, and finally clean up.  The
-following image illustrate this.
+following image illustrates this.
 
 @image{controlflow,15cm,5cm}
 
-The third step may look the most complex, but for a simple client it
-will actually not involve any code.  If your application need to
-handle several concurrent clients, or if it is a server that need to
-serve many clients simultaneous, things do get a bit more complicated.
+The third step may look complex, but for a simple client it
+will actually not involve any code.  If your application needs to
+handle several concurrent clients, or if it is a server that needs to
+serve many clients simultaneously, things do get a bit more complicated.
 
 For illustration, we will write a simple client.  Writing a server
 would be similar, the only difference is that, later on, instead of
-supplying username or passwords, you need to decide whether someone
+supplying username or password, you need to decide whether someone
 should be allowed to log in or not.  The code for what we have
-discussed so far make up our @code{main} function in our client
+discussed so far make up the @code{main} function in our client
 (@pxref{Example 1}):
 
 @example
@@ -1003,13 +1003,13 @@
 Here, the call to the function @code{client} correspond to the third
 step in the image above.
 
-For a more complicated application, that have several clients running
-simultaneous, instead of simply calling @code{client}, it may have
+For a more complicated application, having several clients running
+simultaneously, instead of a simple call to @code{client}, it may have
 created new threads for each session, and call @code{client} within
 each thread.  The library is thread safe.
 
 An actual authentication session is more complicated than what we have
-seen so far.  The steps that make up it are: decide which mechanism to
+seen so far.  The steps that make it up are: decide which mechanism to
 use, start the session, optionally specify the callback, optionally
 set any properties, perform the authentication loop, and clean up.
 Naturally, your application will start to talk its own protocol (e.g.,
@@ -1017,19 +1017,19 @@
 
 The authentication loop is based on sending tokens (typically short
 messages encoded in base 64) back and forth between the client and
-server.  It continue until authentication succeeds or there is an
-error.  The format of the data to transfer, the number of iterations
+server.  It continues until authentication succeeds or an error occurs.
+The format of the data to be transferred, the number of iterations
 in the loop, and other details are specified by each mechanism.  The
 goal of the library is to isolate your application from the details of
 all different mechanisms.
 
-Note that the library do not send data to the server itself, but
-return it in an buffer.  You must send it to the server yourself,
+Note that the library does not send data to the server itself, but
+returns it in a buffer.  You must send it to the server yourself,
 according to an application protocol profile.  For example, the
 @acronym{SASL} application protocol profile for @acronym{SMTP} is
 described in @acronym{RFC} 2554.
 
-The following image illustrate the steps we have been talking about.
+The following image illustrates the steps we have been talking about.
 
 @image{controlflow2,16cm,12cm}
 
@@ -1066,10 +1066,10 @@
 
 This function is responsible for deciding which mechanism to use.  In
 this case, the @samp{PLAIN} mechanism is hard coded, but you will see
-later how this can be made more flexible.  The function create a new
-session, store the username and password in the session handle, then
-call another function @code{client_authenticate} to handle the
-authentication loop, and end by cleaning up.  Let's continue with the
+later how this can be made more flexible.  The function creates a new
+session, then it stores the username and password in the session handle, then
+it calls another function @code{client_authenticate} to handle the
+authentication loop, and finally it cleans up.  Let's continue with the
 implementation of @code{client_authenticate}.
 
 @example
@@ -1079,7 +1079,7 @@
   char *p;
   int rc;
 
-  /* This loop mimic a protocol where the server get to send data
+  /* This loop mimics a protocol where the server sends data
      first. */
 
   do
@@ -1115,14 +1115,14 @@
 @}
 @end example
 
-This last function need to be discussed in some detail.  First, you
+This last function needs to be discussed in some detail.  First, you
 should be aware that there are two versions of this function, that
 differ in a subtle way.  The version above (@pxref{Example 2}) is used
-for application profiles where the server send data first.  For some
-mechanisms, this may waste a roundtrip, because the server need input
-from the client to proceed.  Therefor, today the recommended approach
+for application profiles where the server sends data first.  For some
+mechanisms, this may waste a roundtrip, because the server needs input
+from the client to proceed.  Therefore, today the recommended approach
 is to permit client to send data first (@pxref{Example 1}).  Which
-version you should use depend on which application protocol you are
+version you should use depends on which application protocol you are
 implementing.
 
 Further, you should realize that it is bad programming style to use a
@@ -1134,14 +1134,14 @@
 now.  But don't say I didn't warn you, when a future mechanism doesn't
 work in your application, because of a fixed size buffer.
 
-The @code{gsasl_step64} (and of course also @code{gasl_step}) return
+The function @code{gsasl_step64} (and of course also @code{gasl_step}) returns
 two non-error return codes.  @code{GSASL_OK} is used for success,
-indicating that the library consider the authentication finished.
+indicating that the library considers the authentication finished.
 That may include a successful server authentication, depending on the
 mechanism.  You must not let the client continue to the application
 protocol part unless you receive @code{GSASL_OK} from these functions.
 In particular, don't be fooled into believing authentication were
-successful if the server reply ``OK'' but these function has failed
+successful if the server replies ``OK'' but these functions have failed
 with an error.  The server may have been hacked, and could be tricking
 you into sending confidential data, without having successfully
 authenticated the server.
@@ -1149,7 +1149,7 @@
 The non-error return code @code{GSASL_NEEDS_MORE} is used to signal to
 your application that you should send the output token to the peer,
 and wait for a new token, and do another iteration.  If the server
-conclude the authentication process, with no data, you should call
+concludes the authentication process, with no data, you should call
 @code{gsasl_step64} (or @code{gsasl_step}) specifying a zero-length
 token.
 
@@ -1164,17 +1164,17 @@
 
 Our earlier code was hard coded to use a specific mechanism.  This is
 rarely a good idea.  Instead, it is recommended to select the best
-mechanism available from the list of mechanism supported by the
+mechanism available from the list of mechanisms supported by the
 server.  Note that without TLS or similar, the list may have been
 maliciously altered, by an attacker.  This means that you should abort
 if you cannot find any mechanism that exceeds your minimum security
 level.  There is a function @code{gsasl_client_suggest_mechanism}
 (@pxref{Global Functions}) that will try to pick the ``best''
 available mechanism from a list of mechanisms.  Our simple interactive
-example client (@pxref{Example 3}) include the following function to
+example client (@pxref{Example 3}) includes the following function to
 decide which mechanism to use.  Note that the code doesn't blindly use
-what is returned from @code{gsasl_client_suggest_mechanism}, but
-rather let some logic (in this case the user, through an interactive
+what is returned from @code{gsasl_client_suggest_mechanism},
+rather it lets some logic (in this case the user, through an interactive
 query) decide which mechanism is acceptable.
 
 @example
@@ -1184,12 +1184,12 @@
   char mechlist[BUFSIZ] = "";
   const char *suggestion;
 
-  printf ("Enter list of mechanism that server support, separate by SPC:\n");
+  printf ("Enter list of server supported mechanisms, separated by SPC:\n");
   fgets (mechlist, sizeof (mechlist) - 1, stdin);
 
   suggestion = gsasl_client_suggest_mechanism (ctx, mechlist);
   if (suggestion)
-    printf ("Library suggest use of `%s'.\n", suggestion);
+    printf ("Library suggests use of `%s'.\n", suggestion);
 
   printf ("Enter mechanism to use:\n");
   fgets (mech, sizeof (mech) - 1, stdin);
@@ -1203,9 +1203,9 @@
 output.
 
 @example
-Enter list of mechanism that server support, separate by SPC:
+Enter list of server supported mechanisms, separated by SPC:
 CRAM-MD5 DIGEST-MD5 GSSAPI FOO BAR
-Library suggest use of `GSSAPI'.
+Library suggests use of `GSSAPI'.
 Enter mechanism to use:
 CRAM-MD5
 Input base64 encoded data from server:
@@ -1222,38 +1222,38 @@
 authentication loop, as in:
 
 @example
-  gsasl_property_set (ctx, GSASL_AUTHID, "jas");
-  gsasl_property_set (ctx, GSASL_PASSWORD, "secret");
+gsasl_property_set (ctx, GSASL_AUTHID, "jas");
+gsasl_property_set (ctx, GSASL_PASSWORD, "secret");
 @end example
 
-This may work for simple mechanisms, that only ever need an username
-and a password.  But some mechanism require more information, such as
+This may work for simple mechanisms, that need only a username
+and a password.  But some mechanism requires more information, such as
 an authorization identity, a special PIN or passcode, a realm, a
 hostname, a service name, or an anonymous identifier.  Querying the
 user for all that information, without knowing exactly which of it is
 really needed will result in a poor user interface.  The user should
-not have to input private information, if it isn't required.
+not have to input private informations, if it isn't required.
 
 The approach is a bad idea for another reason.  What if the server
-abort the authentication process?  Then your application have already
+aborts the authentication process?  Then your application has already
 queried the user for a username and password.  It would be better if
 you only asked the user for this information, annoying to input, when
 it is known to be needed.
 
 A better approach to this problem is to use a callback.  Then the
-mechanism may query your application whenever it need some
+mechanism may query your application whenever it needs some
 information, like the username and password.  It will only do this at
 the precise step in the authentication when the information is
-actually needed.  Further, if the user abort, e.g., a password prompt,
+actually needed.  Further, if the user aborts, e.g., a password prompt,
 the mechanism is directly informed of this (because it invoked the
 callback), and could recover somehow.
 
-Our final example (@pxref{Example 4}) specify a callback function,
+Our final example (@pxref{Example 4}) specifies a callback function,
 inside @code{main} as below.
 
 @example
-  /* Set the callback handler for the library. */
-  gsasl_callback_set (ctx, callback);
+/* Set the callback handler for the library. */
+gsasl_callback_set (ctx, callback);
 @end example
 
 The function itself is implemented as follows.
@@ -1320,110 +1320,89 @@
 
 Properties with associated data:
 
address@hidden
-
address@hidden @code{GSASL_AUTHID}
-
address@hidden @code
address@hidden GSASL_AUTHID
 The authentication identity.
 
address@hidden @code{GSASL_AUTHZID}
-
address@hidden GSASL_AUTHZID
 The authorization identity.
 
address@hidden @code{GSASL_PASSWORD}
-
address@hidden GSASL_PASSWORD
 The password of the authentication identity.
 
address@hidden @code{GSASL_ANONYMOUS_TOKEN}
-
address@hidden GSASL_ANONYMOUS_TOKEN
 The anonymous token.  This is typically the email address of the user.
 
address@hidden @code{GSASL_SERVICE}
-
address@hidden GSASL_SERVICE
 The registered GSSAPI service name of the application service,
 e.g. ``imap''.  While the names are registered for GSSAPI, other
 mechanisms such as DIGEST-MD5 may also use this.
 
address@hidden @code{GSASL_HOSTNAME}
-
address@hidden GSASL_HOSTNAME
 Should be the local host name of the machine.
 
address@hidden @code{GSASL_GSSAPI_DISPLAY_NAME}
-
address@hidden GSASL_GSSAPI_DISPLAY_NAME
 Contain the GSSAPI ``display name'', set by the server GSSAPI
 mechanism.  Typically you retrieve this property in your callback,
 when invoked for @code{GSASL_VALIDATE_GSSAPI}.
 
address@hidden @code{GSASL_REALM}
-
address@hidden GSASL_REALM
 The name of the authentication domain.  This is used by several
 mechanisms, including DIGEST-MD5, GSS-API, KERBEROS_V5 and NTLM.
 
address@hidden @code{GSASL_PASSCODE}
-
address@hidden GSASL_PASSCODE
 The SecurID passcode.
 
address@hidden @code{GSASL_PIN}
-
address@hidden GSASL_PIN
 The SecurID personal identification number (PIN).
 
address@hidden @code{GSASL_SUGGESTED_PIN}
-
address@hidden GSASL_SUGGESTED_PIN
 A SecurID personal identification number (PIN) suggested by the server.
 
address@hidden @code{GSASL_DIGEST_MD5_HASHED_PASSWORD}
-
address@hidden GSASL_DIGEST_MD5_HASHED_PASSWORD
 For the DIGEST-MD5 mechanism, this is a hashed password.  It is used
 in servers to avoid storing clear-text credentials.
 
address@hidden @code{GSASL_QOPS}
-
-The DIGEST-MD5 server query for this property to get the set of
address@hidden GSASL_QOPS
+The DIGEST-MD5 server queries for this property to get the set of
 quality of protection (QOP) values to advertise.  The property holds
 strings with comma separated keywords denoting the set of qops to use,
 for example @code{qop-auth, qop-int}.  Valid keywords are
 @code{qop-auth}, @code{qop-int}, and @code{qop-conf}.
 
address@hidden @code{GSASL_QOP}
-
-The DIGEST-MD5 client query for this property to get the quality of
address@hidden GSASL_QOP
+The DIGEST-MD5 client queries for this property to get the quality of
 protection (QOP) values to request.  The property value is one of the
-keywords for @code{GSASL_QOPS}.  The client must chose one of the QOP
+keywords for @code{GSASL_QOPS}.  The client must choose one of the QOP
 values offered by the server (which may be inspected through the
 @code{GSASL_QOPS} property).
 
address@hidden itemize
address@hidden table
 
 Abstract properties, used to trigger the callback, typically used in
 servers to validate client credentials:
 
address@hidden
-
address@hidden @code{GSASL_VALIDATE_SIMPLE}
-
address@hidden @code
address@hidden GSASL_VALIDATE_SIMPLE
 You may retrieve GSASL_AUTHID, GSASL_AUTHZID and GSASL_PASSWORD and
 use them to make an authentication and authorization decision.
 
address@hidden @code{GSASL_VALIDATE_EXTERNAL}
-
-Used by EXTERNAL mechanism on the server side to validate the client.
address@hidden GSASL_VALIDATE_EXTERNAL
+Used by the EXTERNAL mechanism on the server side to validate the client.
 The GSASL_AUTHID will contain the authorization identity of the
 client.
 
address@hidden @code{GSASL_VALIDATE_ANONYMOUS}
-
-Used by ANONYMOUS mechanism on the server side to validate the client.
address@hidden GSASL_VALIDATE_ANONYMOUS
+Used by the ANONYMOUS mechanism on the server side to validate the client.
 The GSASL_ANONYMOUS_TOKEN will contain token that identity the client.
 
address@hidden @code{GSASL_VALIDATE_GSSAPI}
-
address@hidden GSASL_VALIDATE_GSSAPI
 Used by the GSSAPI mechanism on the server side, to validate the
 client.  You may retrieve the authorization identity from
 GSASL_AUTHZID and the GSS-API display name from
 GSASL_GSSAPI_DISPLAY_NAME.
 
address@hidden @code{GSASL_VALIDATE_SECURID}
-
address@hidden GSASL_VALIDATE_SECURID
 Used by SECURID mechanism on the server side to validate client.  The
 GSASL_AUTHID, GSASL_AUTHZID, GSASL_PASSCODE, and GSASL_PIN will be
 set.  It can return GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE to
@@ -1431,7 +1410,7 @@
 GSASL_SECURID_SERVER_NEED_NEW_PIN to require the client to supply a
 new PIN code.
 
address@hidden itemize
address@hidden table
 
 
 @c **********************************************************
@@ -1444,13 +1423,13 @@
 application using it.  To handle these differences the library can use
 a callback function into your application in several different ways.
 Some mechanisms, such as @samp{PLAIN}, are simple to explain and use.
-The client callback query the user for a username and password.  The
-server callback hand the username and password into any local policy
+The client callback queries the user for a username and password.  The
+server callback hands the username and password into any local policy
 deciding authentication system (such as @file{/etc/passwd} via PAM).
 
 Mechanism such as @samp{CRAM-MD5} and @samp{DIGEST-MD5} uses hashed
 passwords.  The client callback behaviour is the same as for PLAIN.
-However, the server do not receive the plain text password over the
+However, the server does not receive the plain text password over the
 network but rather a hash of it.  Existing policy deciding systems
 like PAM cannot handle this, so the server callback for these
 mechanisms are more complicated.
@@ -1486,10 +1465,10 @@
 based on out-of-band authentication.  EXTERNAL is typically used over
 TLS authenticated channels.  Note that in the server, you need to make
 sure that TLS actually authenticated the client successfully.  It is
-normally not sufficient that TLS is used, since they also support
+normally not sufficient to use TLS, since it also supports
 anonymous modes.
 
-In the client, this mechanism is always enabled, and will send the
+In the client, this mechanism is always enabled, and it will send the
 @code{GSASL_AUTHZID} property as the authorization name to the server,
 if the property is set.  If the property is not set, the empty
 authorization name is sent.  You need not implement a callback.
@@ -1513,8 +1492,8 @@
 @code{GSASL_ANONYMOUS_TOKEN} property as the trace information to the
 server.
 
-In the server, this mechanism will invoke the
address@hidden callback to decide whether the client
+In the server, this mechanism will request the
address@hidden callback property to decide whether the client
 should be permitted to log in.  Your callback can retrieve the
 @code{GSASL_ANONYMOUS_TOKEN} property to, for example, save it in a
 log file.  The token is normally not used to decide whether the client
@@ -1525,7 +1504,7 @@
 
 The PLAIN mechanism uses username and password to authenticate users.
 Two user names are relevant.  The first, the authentication identity,
-indicate the credential holder, i.e., whom the provided password
+indicates the credential holder, i.e., whom the provided password
 belongs to.  The second, the authorization identity, is typically
 empty, to indicate that the user requests to log on to the server as
 herself.  However, if the authorization identity is not empty, the
@@ -1538,15 +1517,15 @@
 @code{GSASL_AUTHZID} will also be used.
 
 In the server, the mechanism is always enabled.  Two approaches to
-authenticate and authorize the client is provided.
+authenticate and authorize the client are provided.
 
-In the first approach, the server side of the mechanism will invoke
+In the first approach, the server side of the mechanism will request
 the @code{GSASL_VALIDATE_SIMPLE} callback property to decide whether
 the client should be accepted or not.  The callback may inspect the
 @code{GSASL_AUTHID}, @code{GSASL_AUTHID}, and @code{GSASL_PASSWORD}
-properties.  These properties values will be normalized.
+properties.  These property values will be normalized.
 
-If the first approach fails (because, e.g., your callback return
+If the first approach fails (because, e.g., your callback returns
 @samp{GSASL_NO_CALLBACK} to signal that it does not implement
 @code{GSASL_VALIDATE_SIMPLE}) the mechanism will continue to query the
 application for a password, via the @code{GSASL_PASSWORD} property.
@@ -1554,7 +1533,7 @@
 properties to select the proper password.  The password is then
 normalized and compared to the client credential.
 
-Which approach to use?  If your database store hashed passwords, you
+Which approach to use?  If your database stores hashed passwords, you
 have no option, but must use the first approach.  If passwords in your
 user database are stored in prepared (@acronym{SASLprep}) form, the
 first approach will be faster.  If you do not have prepared passwords
@@ -1565,11 +1544,11 @@
 @section The LOGIN mechanism
 
 The LOGIN mechanism is a non-standard mechanism, and is similar to the
-PLAIN mechanism except that LOGIN lack the support for authorization
+PLAIN mechanism except that LOGIN lacks support for authorization
 identities.  Always use PLAIN instead of LOGIN in new applications.
 
 The callback behaviour is the same as for PLAIN, except that
address@hidden is not used nor required, and that the server do
address@hidden is neither used nor required, and that the server does
 not normalize the password using @acronym{SASLprep}.
 
 @xref{Use of SASLprep in LOGIN}, for a proposed clarification of the
@@ -1580,10 +1559,10 @@
 @cindex CRAM-MD5
 
 The CRAM-MD5 is a widely used, but officially deprecated (apparently
-in favor of DIGEST-MD5), challenge-response mechanism that transfer
+in favor of DIGEST-MD5), challenge-response mechanism that transfers
 hashed passwords instead of clear text passwords.  For insecure
 channels (e.g., when @acronym{TLS} is not used), it is safer than
-PLAIN.  The CRAM-MD5 mechanism do not support authorization
+PLAIN.  The CRAM-MD5 mechanism does not support authorization
 identities; making the relationship between CRAM-MD5 and DIGEST-MD5
 similar to the relationship between LOGIN and PLAIN.
 
@@ -1592,11 +1571,11 @@
 must have access to the correct password in order to validate an
 authentication attempt.
 
-In the client, this mechanism is always enabled, and require the
+In the client, this mechanism is always enabled, and it requires the
 @code{GSASL_AUTHID} and @code{GSASL_PASSWORD} properties.
 
-In the server, the mechanism will invoke the @code{GSASL_PASSWORD}
-callback, which may use the @code{GSASL_AUTHID} property to determine
+In the server, the mechanism will require the @code{GSASL_PASSWORD}
+callback property, which may use the @code{GSASL_AUTHID} property to determine
 which users' password should be used.  The @code{GSASL_AUTHID} will be
 in normalized form.  The server will then normalize the returned
 password, and compare the client response with the computed correct
@@ -1614,34 +1593,34 @@
 after the MD5 break may be argued to be weaker than HMAC-MD5, but
 supports more features.  For example, authorization identities and
 data integrity and privacy protection are supported.  Like CRAM-MD5,
-only a hashed password is transfered.  Consequently, DIGEST-MD5 need
+only a hashed password is transferred.  Consequently, DIGEST-MD5 needs
 access to the correct password (although it may be hashed, another
 improvement compared to CRAM-MD5) to verify the client response.
-Alas, this make it impossible to use, e.g., @acronym{PAM} on the
+Alas, this makes it impossible to use, e.g., @acronym{PAM} on the
 server side.
 
-In the client, this mechanism is always enabled, and require the
+In the client, this mechanism is always enabled, and it requires the
 @code{GSASL_AUTHID}, @code{GSASL_PASSWORD}, @code{GSASL_SERVICE}, and
 @code{GSASL_HOSTNAME} properties.  If set, @code{GSASL_AUTHZID} and
 @code{GSASL_REALM} will also be used.
 
-In the server, the mechanism will first invoke the
address@hidden callback to get the user's
+In the server, the mechanism will first request the
address@hidden callback property to get the user's
 hashed password.  If the callback doesn't supply a hashed password,
-the @code{GSASL_PASSWORD} callback will be invoked.  Both callbacks
+the @code{GSASL_PASSWORD} callback property will be requested.  Both callbacks
 may use the @code{GSASL_AUTHID}, @code{GSASL_AUTHZID} and
 @code{GSASL_REALM} properties to determine which users' password
 should be used.  The server will then compare the client response with
 a computed correct response, and accept the user accordingly.
 
 The server uses the @code{GSASL_QOPS} callback to get the set of
-quality of protection values to use.  By default, it advertise support
-for authentication (@code{qop-auth}) only.  You can use the callback
-to, for example, make the server advertise support for authentication
+quality of protection values to use.  By default, it advertises support
+for authentication (@code{qop-auth}) only.  You can use the callback,
+for example, to make the server advertise support for authentication
 with integrity layers.
 
 The client uses the @code{GSASL_QOP} callback to get the quality of
-protection value to request.  The client must chose be one of the QOP
+protection value to request.  The client must choose one of the QOP
 values offered by the server (which may be inspected through the
 @code{GSASL_QOPS} property).  If the client does not return a value,
 @code{qop-auth} is used by default.
@@ -1654,7 +1633,7 @@
 applications, and do not expect it to be secure.  Currently only the
 client side is supported.
 
-In the client, this mechanism is always enabled, and require the
+In the client, this mechanism is always enabled, and it requires the
 @code{GSASL_AUTHID} and @code{GSASL_PASSWORD} properties.  It will set
 the @samp{domain} field in the NTLM request to the value of
 @code{GSASL_REALM}.  Some servers reportedly need non-empty but
@@ -1667,7 +1646,7 @@
 The SECURID mechanism uses authentication and authorization identity
 together with a passcode from a hardware token to authenticate users.
 
-In the client, this mechanism is always enabled, and require the
+In the client, this mechanism is always enabled, and it requires the
 @code{GSASL_AUTHID} and @code{GSASL_PASSCODE} properties.  If set,
 @code{GSASL_AUTHZID} will also be used.  If the server requests it,
 the @code{GSASL_PIN} property is also required, and its callback may
@@ -1683,7 +1662,7 @@
 @code{GSASL_SECURID_SERVER_NEED_NEW_PIN} to ask for a new PIN code
 from the client, in which case it may also set the
 @code{GSASL_SUGGESTED_PIN} property to indicate a recommended new PIN.
-If the callbacks has invoked again, after having returned
+If the callbacks is invoked again, after having returned
 @code{GSASL_SECURID_SERVER_NEED_NEW_PIN}, it may also inspect the
 @code{GSASL_PIN} property, in addition to the other properties, to
 find out the client selected PIN code.
@@ -1693,18 +1672,18 @@
 @cindex GSSAPI
 
 GSS-API is a framework, similar to SASL, for authentication.  The
-GSSAPI mechanism only support the Kerberos 5 GSS-API mechanism,
+GSSAPI mechanism only supports the Kerberos 5 GSS-API mechanism,
 though.  (A new SASL mechanism to support non-Kerberos 5 GSS-API
 mechanisms may be supported in the future.)
 
 In the client, the mechanism is enabled only if the user has acquired
-credentials (i.e., a ticket granting ticket), and require the
+credentials (i.e., a ticket granting ticket), and it requires the
 @code{GSASL_AUTHID}, @code{GSASL_SERVICE}, and @code{GSASL_HOSTNAME}
 properties.
 
-In the server, the mechanism require the @code{GSASL_SERVICE}, and
address@hidden properties, and will invoke the
address@hidden callback in order to validate the user.
+In the server, the mechanism requires the @code{GSASL_SERVICE} and
address@hidden properties, and it will invoke the
address@hidden callback property in order to validate the user.
 The callback may inspect the @code{GSASL_AUTHZID} and
 @code{GSASL_GSSAPI_DISPLAY_NAME} properties to decide whether to
 authorize the user.  Note that authentication is performed by the
@@ -1733,13 +1712,13 @@
 In the infrastructure mode (proxied or otherwise), it allows clients
 and servers to authenticate via SASL in an RFC 1510 environment, using
 a trusted third party, a ``Key Distribution Central''.  In the normal
-mode, clients aquire tickets out of band and then invokes a one
+mode, clients acquire tickets out of band and then invokes a one
 roundtrip AP-REQ and AP-REP exchange.  In the proxied mode, which can
 be used by clients without IP addresses or without connectivity to the
 KDC (e.g., when the KDC is IPv4 and the client is IPV6-only), the
 client uses the server to proxy ticket requests and finishes with the
 AP-REQ/AP-REP exchange.  In infrastructure mode (proxied or
-otherwise), the client nor server need to implement any callbacks
+otherwise), neither the client nor server need to implement any callbacks
 (this will likely change later, to allow a server to authorize users,
 similar to the GSSAPI callback).
 
@@ -1766,16 +1745,16 @@
 @chapter Callback Functions
 @cindex Callbacks
 
-The callback is used by mechanisms to retrieve information, such as
+The callback is used by mechanisms to retrieve informations, such as
 username and password, from the application.  In a server, the
 callback is used to decide whether a user is permitted to log in or
 not.  You tell the library of your callback function by calling
 @code{gsasl_callback_set}.
 
-Since your callback may need to access to data from other parts of
+Since your callback may need access to data from other parts of
 your application, there are hooks to store and retrieve application
-specific pointers.  This avoid the use of global variables in your
-application, which wouldn't be thread safe.  You store a pointer to
+specific pointers.  This avoids the use of global variables,
+which wouldn't be thread safe.  You store a pointer to
 some information (opaque from the point of view of the library) by
 calling @code{gsasl_callback_hook_set} and can later retrieve this
 data in your callback by calling @code{gsasl_callback_hook_get}.
@@ -1834,7 +1813,7 @@
 @chapter Error Handling
 @cindex Error Handling
 
-Most functions in the GNU SASL Library are returning an error if they
+Most functions in the GNU SASL Library return an error if they
 fail.  For this reason, the application should always catch the error
 condition and take appropriate measures, for example by releasing the
 resources and passing the error up to the caller, or by displaying a
@@ -1879,7 +1858,7 @@
 @chapter Examples
 @cindex Examples
 
-This chapter contains example code which illustrate how the GNU SASL
+This chapter contains example code which illustrates how the GNU SASL
 Library can be used when writing your own application.
 
 @menu
@@ -1953,6 +1932,7 @@
 GNU SASL (gsasl) -- Command line interface to libgsasl.
 
 @majorheading Description
+
 @code{gsasl} is the main program of GNU SASL.
 
 This section only lists the commands and options available.
@@ -1961,6 +1941,7 @@
 optional for any corresponding short options.
 
 @majorheading Commands
+
 @code{gsasl} recognizes these commands:
 
 @verbatim
@@ -2005,7 +1986,7 @@
 @majorheading SASL Mechanism Options
 
 These options modify the behaviour of the callbacks (@pxref{Callback
-Functions}) in the library.  The default is the query the user on the
+Functions}) in the library.  The default is to query the user on the
 terminal.
 
 @verbatim
@@ -2080,9 +2061,9 @@
 @node Protocol Clarifications
 @appendix Protocol Clarifications
 
-This appendix contain clarification to various SASL specification that
+This appendix contains clarifications of various SASL specifications that
 we felt were necessary to include, if for nothing else it may serve as
-a guide for other implementors that worry about the same issues.
+a guide for other implementers that worry about the same issues.
 
 @menu
 * Use of SASLprep in CRAM-MD5::
@@ -2093,12 +2074,12 @@
 @section Use of SASLprep in CRAM-MD5
 
 The specification, as of @file{draft-ietf-sasl-crammd5-04.txt}, is
-silent on whether a SASL server implementation applying
+silent on whether a SASL server implementations applying
 @acronym{SASLprep} on a password received from an external, non-SASL
 specific database (i.e., the passwords are not stored in
 @acronym{SASLprep} form in the database), should set or clear the
 AllowUnassigned bit.  The motivation for the AU-bit in
address@hidden/@acronym{SASLprep} is for stored vs query
address@hidden/@acronym{SASLprep} is for stored vs queried
 strings.  It could be argued that in this situation the server can
 treat the external password either as a stored string (from a
 database) or as a query (the server uses the string as a query into
@@ -2107,7 +2088,7 @@
 The specification is also unclear on whether clients should set or
 clear the AllowUnassigned flag.
 
-In the server, GNU SASL apply @acronym{SASLprep} to the password with
+In the server, GNU SASL applies @acronym{SASLprep} to the password with
 the AllowUnassigned bit cleared.
 
 @node Use of SASLprep in LOGIN
-- 
Marco Maggi

reply via email to

[Prev in Thread] Current Thread [Next in Thread]