diff options
Diffstat (limited to 'third_party/heimdal/lib/krb5/krb5_auth_context.3')
| -rw-r--r-- | third_party/heimdal/lib/krb5/krb5_auth_context.3 | 395 |
1 files changed, 395 insertions, 0 deletions
diff --git a/third_party/heimdal/lib/krb5/krb5_auth_context.3 b/third_party/heimdal/lib/krb5/krb5_auth_context.3 new file mode 100644 index 0000000..b627e48 --- /dev/null +++ b/third_party/heimdal/lib/krb5/krb5_auth_context.3 @@ -0,0 +1,395 @@ +.\" Copyright (c) 2001 - 2005 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id$ +.\" +.Dd May 17, 2005 +.Dt KRB5_AUTH_CONTEXT 3 +.Os HEIMDAL +.Sh NAME +.Nm krb5_auth_con_addflags , +.Nm krb5_auth_con_free , +.Nm krb5_auth_con_genaddrs , +.Nm krb5_auth_con_generatelocalsubkey , +.Nm krb5_auth_con_getaddrs , +.Nm krb5_auth_con_getauthenticator , +.Nm krb5_auth_con_getflags , +.Nm krb5_auth_con_getkey , +.Nm krb5_auth_con_getlocalsubkey , +.Nm krb5_auth_con_getrcache , +.Nm krb5_auth_con_getremotesubkey , +.Nm krb5_auth_con_getuserkey , +.Nm krb5_auth_con_init , +.Nm krb5_auth_con_initivector , +.Nm krb5_auth_con_removeflags , +.Nm krb5_auth_con_setaddrs , +.Nm krb5_auth_con_setaddrs_from_fd , +.Nm krb5_auth_con_setflags , +.Nm krb5_auth_con_setivector , +.Nm krb5_auth_con_setkey , +.Nm krb5_auth_con_setlocalsubkey , +.Nm krb5_auth_con_setrcache , +.Nm krb5_auth_con_setremotesubkey , +.Nm krb5_auth_con_setuserkey , +.Nm krb5_auth_context , +.Nm krb5_auth_getcksumtype , +.Nm krb5_auth_getkeytype , +.Nm krb5_auth_getlocalseqnumber , +.Nm krb5_auth_getremoteseqnumber , +.Nm krb5_auth_setcksumtype , +.Nm krb5_auth_setkeytype , +.Nm krb5_auth_setlocalseqnumber , +.Nm krb5_auth_setremoteseqnumber , +.Nm krb5_free_authenticator +.Nd manage authentication on connection level +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5.h +.Ft krb5_error_code +.Fo krb5_auth_con_init +.Fa "krb5_context context" +.Fa "krb5_auth_context *auth_context" +.Fc +.Ft void +.Fo krb5_auth_con_free +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_setflags +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "int32_t flags" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_getflags +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "int32_t *flags" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_addflags +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "int32_t addflags" +.Fa "int32_t *flags" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_removeflags +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "int32_t removelags" +.Fa "int32_t *flags" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_setaddrs +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "krb5_address *local_addr" +.Fa "krb5_address *remote_addr" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_getaddrs +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "krb5_address **local_addr" +.Fa "krb5_address **remote_addr" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_genaddrs +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "int fd" +.Fa "int flags" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_setaddrs_from_fd +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "void *p_fd" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_getkey +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "krb5_keyblock **keyblock" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_getlocalsubkey +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "krb5_keyblock **keyblock" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_getremotesubkey +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa "krb5_keyblock **keyblock" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_generatelocalsubkey +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fa krb5_keyblock *key" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_initivector +.Fa "krb5_context context" +.Fa "krb5_auth_context auth_context" +.Fc +.Ft krb5_error_code +.Fo krb5_auth_con_setivector +.Fa "krb5_context context" +.Fa "krb5_auth_context *auth_context" +.Fa "krb5_pointer ivector" +.Fc +.Ft void +.Fo krb5_free_authenticator +.Fa "krb5_context context" +.Fa "krb5_authenticator *authenticator" +.Fc +.Sh DESCRIPTION +The +.Nm krb5_auth_context +structure holds all context related to an authenticated connection, in +a similar way to +.Nm krb5_context +that holds the context for the thread or process. +.Nm krb5_auth_context +is used by various functions that are directly related to +authentication between the server/client. Example of data that this +structure contains are various flags, addresses of client and server, +port numbers, keyblocks (and subkeys), sequence numbers, replay cache, +and checksum-type. +.Pp +.Fn krb5_auth_con_init +allocates and initializes the +.Nm krb5_auth_context +structure. Default values can be changed with +.Fn krb5_auth_con_setcksumtype +and +.Fn krb5_auth_con_setflags . +The +.Nm auth_context +structure must be freed by +.Fn krb5_auth_con_free . +.Pp +.Fn krb5_auth_con_getflags , +.Fn krb5_auth_con_setflags , +.Fn krb5_auth_con_addflags +and +.Fn krb5_auth_con_removeflags +gets and modifies the flags for a +.Nm krb5_auth_context +structure. Possible flags to set are: +.Bl -tag -width Ds +.It Dv KRB5_AUTH_CONTEXT_DO_SEQUENCE +Generate and check sequence-number on each packet. +.It Dv KRB5_AUTH_CONTEXT_DO_TIME +Check timestamp on incoming packets. +.It Dv KRB5_AUTH_CONTEXT_RET_SEQUENCE , Dv KRB5_AUTH_CONTEXT_RET_TIME +Return sequence numbers and time stamps in the outdata parameters. +.It Dv KRB5_AUTH_CONTEXT_CLEAR_FORWARDED_CRED +will force +.Fn krb5_get_forwarded_creds +and +.Fn krb5_fwd_tgt_creds +to create unencrypted ) +.Dv KRB5_ENCTYPE_NULL ) +credentials. +This is for use with old MIT server and JAVA based servers as +they can't handle encrypted +.Dv KRB-CRED . +Note that sending such +.Dv KRB-CRED +is clear exposes crypto keys and tickets and is insecure, +make sure the packet is encrypted in the protocol. +.Xr krb5_rd_cred 3 , +.Xr krb5_rd_priv 3 , +.Xr krb5_rd_safe 3 , +.Xr krb5_mk_priv 3 +and +.Xr krb5_mk_safe 3 . +Setting this flag requires that parameter to be passed to these +functions. +.Pp +The flags +.Dv KRB5_AUTH_CONTEXT_DO_TIME +also modifies the behavior the function +.Fn krb5_get_forwarded_creds +by removing the timestamp in the forward credential message, this have +backward compatibility problems since not all versions of the heimdal +supports timeless credentional messages. +Is very useful since it always the sender of the message to cache +forward message and thus avoiding a round trip to the KDC for each +time a credential is forwarded. +The same functionality can be obtained by using address-less tickets. +.\".It Dv KRB5_AUTH_CONTEXT_PERMIT_ALL +.El +.Pp +.Fn krb5_auth_con_setaddrs , +.Fn krb5_auth_con_setaddrs_from_fd +and +.Fn krb5_auth_con_getaddrs +gets and sets the addresses that are checked when a packet is received. +It is mandatory to set an address for the remote +host. If the local address is not set, it iss deduced from the underlaying +operating system. +.Fn krb5_auth_con_getaddrs +will call +.Fn krb5_free_address +on any address that is passed in +.Fa local_addr +or +.Fa remote_addr . +.Fn krb5_auth_con_setaddr +allows passing in a +.Dv NULL +pointer as +.Fa local_addr +and +.Fa remote_addr , +in that case it will just not set that address. +.Pp +.Fn krb5_auth_con_setaddrs_from_fd +fetches the addresses from a file descriptor. +.Pp +.Fn krb5_auth_con_genaddrs +fetches the address information from the given file descriptor +.Fa fd +depending on the bitmap argument +.Fa flags . +.Pp +Possible values on +.Fa flags +are: +.Bl -tag -width Ds +.It Va KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR +fetches the local address from +.Fa fd . +.It Va KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR +fetches the remote address from +.Fa fd . +.El +.Pp +.Fn krb5_auth_con_setkey , +.Fn krb5_auth_con_setuserkey +and +.Fn krb5_auth_con_getkey +gets and sets the key used for this auth context. The keyblock returned by +.Fn krb5_auth_con_getkey +should be freed with +.Fn krb5_free_keyblock . +The keyblock send into +.Fn krb5_auth_con_setkey +is copied into the +.Nm krb5_auth_context , +and thus no special handling is needed. +.Dv NULL +is not a valid keyblock to +.Fn krb5_auth_con_setkey . +.Pp +.Fn krb5_auth_con_setuserkey +is only useful when doing user to user authentication. +.Fn krb5_auth_con_setkey +is equivalent to +.Fn krb5_auth_con_setuserkey . +.Pp +.Fn krb5_auth_con_getlocalsubkey , +.Fn krb5_auth_con_setlocalsubkey , +.Fn krb5_auth_con_getremotesubkey +and +.Fn krb5_auth_con_setremotesubkey +gets and sets the keyblock for the local and remote subkey. +The keyblock returned by +.Fn krb5_auth_con_getlocalsubkey +and +.Fn krb5_auth_con_getremotesubkey +must be freed with +.Fn krb5_free_keyblock . +.Pp +.Fn krb5_auth_setcksumtype +and +.Fn krb5_auth_getcksumtype +sets and gets the checksum type that should be used for this +connection. +.Pp +.Fn krb5_auth_con_generatelocalsubkey +generates a local subkey that have the same encryption type as +.Fa key . +.Pp +.Fn krb5_auth_getremoteseqnumber +.Fn krb5_auth_setremoteseqnumber , +.Fn krb5_auth_getlocalseqnumber +and +.Fn krb5_auth_setlocalseqnumber +gets and sets the sequence-number for the local and remote +sequence-number counter. +.Pp +.Fn krb5_auth_setkeytype +and +.Fn krb5_auth_getkeytype +gets and gets the keytype of the keyblock in +.Nm krb5_auth_context . +.Pp +.Fn krb5_auth_con_getauthenticator +Retrieves the authenticator that was used during mutual +authentication. The +.Dv authenticator +returned should be freed by calling +.Fn krb5_free_authenticator . +.Pp +.Fn krb5_auth_con_getrcache +and +.Fn krb5_auth_con_setrcache +gets and sets the replay-cache. +.Pp +.Fn krb5_auth_con_initivector +allocates memory for and zeros the initial vector in the +.Fa auth_context +keyblock. +.Pp +.Fn krb5_auth_con_setivector +sets the i_vector portion of +.Fa auth_context +to +.Fa ivector . +.Pp +.Fn krb5_free_authenticator +free the content of +.Fa authenticator +and +.Fa authenticator +itself. +.Sh SEE ALSO +.Xr krb5_context 3 , +.Xr kerberos 8 |