[Top][All Lists]
[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
- typos in gsasl.texi,
Marco Maggi <=