diff options
Diffstat (limited to 'crypto/heimdal/lib/krb5/krb5_get_credentials.3')
| -rw-r--r-- | crypto/heimdal/lib/krb5/krb5_get_credentials.3 | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/crypto/heimdal/lib/krb5/krb5_get_credentials.3 b/crypto/heimdal/lib/krb5/krb5_get_credentials.3 new file mode 100644 index 0000000..32e0ffe --- /dev/null +++ b/crypto/heimdal/lib/krb5/krb5_get_credentials.3 @@ -0,0 +1,208 @@ +.\" Copyright (c) 2004 - 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: krb5_get_credentials.3 22071 2007-11-14 20:04:50Z lha $ +.\" +.Dd July 26, 2004 +.Dt KRB5_GET_CREDENTIALS 3 +.Os HEIMDAL +.Sh NAME +.Nm krb5_get_credentials , +.Nm krb5_get_credentials_with_flags , +.Nm krb5_get_cred_from_kdc , +.Nm krb5_get_cred_from_kdc_opt , +.Nm krb5_get_kdc_cred , +.Nm krb5_get_renewed_creds +.Nd get credentials from the KDC using krbtgt +.Sh LIBRARY +Kerberos 5 Library (libkrb5, -lkrb5) +.Sh SYNOPSIS +.In krb5.h +.Ft krb5_error_code +.Fo krb5_get_credentials +.Fa "krb5_context context" +.Fa "krb5_flags options" +.Fa "krb5_ccache ccache" +.Fa "krb5_creds *in_creds" +.Fa "krb5_creds **out_creds" +.Fc +.Ft krb5_error_code +.Fo krb5_get_credentials_with_flags +.Fa "krb5_context context" +.Fa "krb5_flags options" +.Fa "krb5_kdc_flags flags" +.Fa "krb5_ccache ccache" +.Fa "krb5_creds *in_creds" +.Fa "krb5_creds **out_creds" +.Fc +.Ft krb5_error_code +.Fo krb5_get_cred_from_kdc +.Fa "krb5_context context" +.Fa "krb5_ccache ccache" +.Fa "krb5_creds *in_creds" +.Fa "krb5_creds **out_creds" +.Fa "krb5_creds ***ret_tgts" +.Fc +.Ft krb5_error_code +.Fo krb5_get_cred_from_kdc_opt +.Fa "krb5_context context" +.Fa "krb5_ccache ccache" +.Fa "krb5_creds *in_creds" +.Fa "krb5_creds **out_creds" +.Fa "krb5_creds ***ret_tgts" +.Fa "krb5_flags flags" +.Fc +.Ft krb5_error_code +.Fo krb5_get_kdc_cred +.Fa "krb5_context context" +.Fa "krb5_ccache id" +.Fa "krb5_kdc_flags flags" +.Fa "krb5_addresses *addresses" +.Fa "Ticket *second_ticket" +.Fa "krb5_creds *in_creds" +.Fa "krb5_creds **out_creds" +.Fc +.Ft krb5_error_code +.Fo krb5_get_renewed_creds +.Fa "krb5_context context" +.Fa "krb5_creds *creds" +.Fa "krb5_const_principal client" +.Fa "krb5_ccache ccache" +.Fa "const char *in_tkt_service" +.Fc +.Sh DESCRIPTION +.Fn krb5_get_credentials_with_flags +get credentials specified by +.Fa in_creds->server +and +.Fa in_creds->client +(the rest of the +.Fa in_creds +structure is ignored) +by first looking in the +.Fa ccache +and if doesn't exists or is expired, fetch the credential from the KDC +using the krbtgt in +.Fa ccache . +The credential is returned in +.Fa out_creds +and should be freed using the function +.Fn krb5_free_creds . +.Pp +Valid flags to pass into +.Fa options +argument are: +.Pp +.Bl -tag -width "KRB5_GC_USER_USER" -compact +.It KRB5_GC_CACHED +Only check the +.Fa ccache , +don't got out on network to fetch credential. +.It KRB5_GC_USER_USER +Request a user to user ticket. +This option doesn't store the resulting user to user credential in +the +.Fa ccache . +.It KRB5_GC_EXPIRED_OK +returns the credential even if it is expired, default behavior is trying +to refetch the credential from the KDC. +.El +.Pp +.Fa Flags +are KDCOptions, note the caller must fill in the bit-field and not +use the integer associated structure. +.Pp +.Fn krb5_get_credentials +works the same way as +.Fn krb5_get_credentials_with_flags +except that the +.Fa flags +field is missing. +.Pp +.Fn krb5_get_cred_from_kdc +and +.Fn krb5_get_cred_from_kdc_opt +fetches the credential from the KDC very much like +.Fn krb5_get_credentials, but doesn't look in the +.Fa ccache +if the credential exists there first. +.Pp +.Fn krb5_get_kdc_cred +does the same as the functions above, but the caller must fill in all +the information andits closer to the wire protocol. +.Pp +.Fn krb5_get_renewed_creds +renews a credential given by +.Fa in_tkt_service +(if +.Dv NULL +the default +.Li krbtgt ) +using the credential cache +.Fa ccache . +The result is stored in +.Fa creds +and should be freed using +.Fa krb5_free_creds . +.Sh EXAMPLES +Here is a example function that get a credential from a credential cache +.Fa id +or the KDC and returns it to the caller. +.Bd -literal +#include <krb5.h> + +int +getcred(krb5_context context, krb5_ccache id, krb5_creds **creds) +{ + krb5_error_code ret; + krb5_creds in; + + ret = krb5_parse_name(context, "client@EXAMPLE.COM", + &in.client); + if (ret) + krb5_err(context, 1, ret, "krb5_parse_name"); + + ret = krb5_parse_name(context, "host/server.example.com@EXAMPLE.COM", + &in.server); + if (ret) + krb5_err(context, 1, ret, "krb5_parse_name"); + + ret = krb5_get_credentials(context, 0, id, &in, creds); + if (ret) + krb5_err(context, 1, ret, "krb5_get_credentials"); + + return 0; +} +.Ed +.Sh SEE ALSO +.Xr krb5 3 , +.Xr krb5_get_forwarded_creds 3 , +.Xr krb5.conf 5 |
