oysteikt/heimdal
0
0
Fork 0
Code Issues 5 Pull Requests Releases Activity

spelling

Browse Source 
git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@16770 ec53bebd-3082-4978-b11e-865c3cabbd6b
This commit is contained in:
Johan Danielsson
2006-02-27 12:38:28 +00:00
parent 6c13e96c9c
commit 5fcb994762
2 changed files with 41 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
doc/programming.texi
View File

@@ -8,28 +8,28 @@ introduction text (@pxref{What is Kerberos?}).
@menu
* Kerberos 5 API Overview::
* Walkthru a sample Kerberos 5 client::
* Walkthrough of a sample Kerberos 5 client::
* Validating a password in a server application::
* API diffrences to MIT Kerberos::
* API differences to MIT Kerberos::
@end menu
@node Kerberos 5 API Overview, Walkthru a sample Kerberos 5 client, Programming with Kerberos, Programming with Kerberos
@node Kerberos 5 API Overview, Walkthrough of a sample Kerberos 5 client, Programming with Kerberos, Programming with Kerberos
@section Kerberos 5 API Overview
All functions are documenteded in manual pages. This section tries to
All functions are documented in manual pages. This section tries to
give an overview of the major components used in Kerberos library, and
point to where to look for a specific function.
@subsection Kerberos context
A kerberos context (@code{krb5_context}) holds all per thread state. All global variables that
are context specific are stored in this struture, including default
are context specific are stored in this structure, including default
encryption types, credential cache (for example, a ticket file), and default realms.
See the manual pages for @manpage{krb5_context,3} and
@manpage{krb5_init_context,3}.
@subsection Kerberos authenication context
@subsection Kerberos authentication context
Kerberos authentication context (@code{krb5_auth_context}) holds all
context related to an authenticated connection, in a similar way to the
@@ -47,12 +47,12 @@ See the manual page for @manpage{krb5_auth_context,3}.
The Kerberos principal is the structure that identifies a user or
service in Kerberos. The structure that holds the principal is the
@code{krb5_principal}. There are function os extract the realm and
elements of the principal, but Most applications have no reason to
@code{krb5_principal}. There are function to extract the realm and
elements of the principal, but most applications have no reason to
inspect the content of the structure.
The are several ways to create a principal (with diffrent degree of
portibility), and one way to free it.
The are several ways to create a principal (with different degree of
portability), and one way to free it.
See manual page for @manpage{krb5_principal,3} for more information
about the functions.
@@ -63,8 +63,8 @@ A credential cache holds the tickets for a user. A given user can have
several credential caches, one for each realm where the user have the
initial tickets (the first krbtgt).
The credential cache data can be stored internally in diffrent way, each of them for
diffrent proposes. File credential (FILE) caches and processes based
The credential cache data can be stored internally in different way, each of them for
different proposes. File credential (FILE) caches and processes based
(KCM) caches are for permanent storage. While memory caches (MEMORY)
are local caches to the local process.
@@ -83,20 +83,20 @@ See also manual page for @manpage{krb5_ccache,3}
Kerberos errors are based on the com_err library. All error codes are
32-bit signed numbers, the first 24 bits define what subsystem the
error originates from, and last 8 bits are 255 error codes withing the
error originates from, and last 8 bits are 255 error codes within the
library. Each error code have fixed string associated with it. For
example, the error-code -1765328383 have the symbolic name
KRB5KDC_ERR_NAME_EXP, and associated error string ``Client's entry in
database has expired''.
This is a great improvment compared to just getting one of the unix
This is a great improvement compared to just getting one of the unix
error-codes back. However, Heimdal have an extention to pass back
customized errors messages. Instead of getting ``Key table entry not
customised errors messages. Instead of getting ``Key table entry not
found'', the user might back ``failed to find
host/host.example.com@@EXAMLE.COM(kvno 3) in keytab /etc/krb5.keytab
(des-cbc-crc)''. This improves the chance that the user find the
cause of the error so you should use the customized error message
whenever its avaible.
cause of the error so you should use the customised error message
whenever its available.
See also manual page for @manpage{krb5_get_error_string,3} and
@manpage{krb5_get_err_text,3}.
@@ -117,8 +117,8 @@ See also manual page for @manpage{krb5_crypto_init,3},
@manpage{krb5_keyblock,3}, @manpage{krb5_create_checksum,3},
and @manpage{krb5_encrypt,3}.
@node Walkthru a sample Kerberos 5 client, Validating a password in a server application, Kerberos 5 API Overview, Programming with Kerberos
@section Walkthru a sample Kerberos 5 client
@node Walkthrough of a sample Kerberos 5 client, Validating a password in a server application, Kerberos 5 API Overview, Programming with Kerberos
@section Walkthrough of a sample Kerberos 5 client
This example contains parts of a sample TCP Kerberos 5 clients, if you
want a real working client, please look in @file{appl/test} directory in
@@ -127,17 +127,17 @@ the Heimdal distribution.
All Kerberos error-codes that are returned from kerberos functions in
this program are passed to @code{krb5_err}, that will print a
descriptive text of the error code and exit. Graphical programs can
convert error-code to a humal readable error-string with the
convert error-code to a human readable error-string with the
@manpage{krb5_get_err_text,3} function.
Note that you should not use any Kerberos function before
@code{krb5_init_context()} have completed successfully. That is the
reson @code{err()} is used when @code{krb5_init_context()} fails.
reason @code{err()} is used when @code{krb5_init_context()} fails.
First the client needs to call @code{krb5_init_context} to initialise
the Kerberos 5 library. This is only needed once per thread
in the program. If the function returns a non-zero value it indicates
that either the Kerberos implemtation is failing or its disabled on
that either the Kerberos implementation is failing or its disabled on
this host.
@example
@@ -201,7 +201,7 @@ connection (see @manpage{krb5_auth_context,3}).
@end example
For setting the address in the authentication there is a help function
@code{krb5_auth_con_setaddrs_from_fd} that does everthing that is needed
@code{krb5_auth_con_setaddrs_from_fd} that does everything that is needed
when given a connected file descriptor to the socket.
@example
@@ -233,8 +233,8 @@ out itself.
The server program is using the function @manpage{krb5_recvauth,3} to
receive the Kerberos 5 authenticator.
In this case, mutual authenication will be tried. That means that the server
will authenticate to the client. Using mutual authenication
In this case, mutual authentication will be tried. That means that the server
will authenticate to the client. Using mutual authentication
is good since it enables the user to verify that they are talking to the
right server (a server that knows the key).
@@ -332,13 +332,13 @@ And send it over the network.
The server is using @manpage{krb5_rd_safe,3} and
@manpage{krb5_rd_priv,3} to verify the signature and decrypt the packet.
@node Validating a password in a server application, API diffrences to MIT Kerberos, Walkthru a sample Kerberos 5 client, Programming with Kerberos
@node Validating a password in a server application, API differences to MIT Kerberos, Walkthrough of a sample Kerberos 5 client, Programming with Kerberos
@section Validating a password in an application
See the manual page for @manpage{krb5_verify_user,3}.
@node API diffrences to MIT Kerberos, , Validating a password in a server application, Programming with Kerberos
@section API diffrences to MIT Kerberos
@node API differences to MIT Kerberos, , Validating a password in a server application, Programming with Kerberos
@section API differences to MIT Kerberos
This section is somewhat disorganised, but so far there is no overall
structure to the differences, though some of the have their root in
@@ -373,7 +373,7 @@ global @code{com_err} table isn't initialised. Then
the error code itself).
@c @node Why you should use GSS-API for new applications, Walkthru a sample GSS-API client, Validating a password in a server application, Programming with Kerberos
@c @node Why you should use GSS-API for new applications, Walkthrough of a sample GSS-API client, Validating a password in a server application, Programming with Kerberos
@c @section Why you should use GSS-API for new applications
@c
@c SSPI, bah, bah, microsoft, bah, bah, almost GSS-API.
@@ -381,7 +381,7 @@ the error code itself).
@c It would also be possible for other mechanisms then Kerberos, but that
@c doesn't exist any other GSS-API implementations today.
@c
@c @node Walkthru a sample GSS-API client, , Why you should use GSS-API for new applications, Programming with Kerberos
@c @section Walkthru a sample GSS-API client
@c @node Walkthrough of a sample GSS-API client, , Why you should use GSS-API for new applications, Programming with Kerberos
@c @section Walkthrough of a sample GSS-API client
@c
@c Write about how gssapi_clent.c works.