diff options
Diffstat (limited to 'crypto/heimdal/lib/krb5/krb5_ccache.3')
| -rw-r--r-- | crypto/heimdal/lib/krb5/krb5_ccache.3 | 307 |
1 files changed, 234 insertions, 73 deletions
diff --git a/crypto/heimdal/lib/krb5/krb5_ccache.3 b/crypto/heimdal/lib/krb5/krb5_ccache.3 index ec48c5f..3fca595 100644 --- a/crypto/heimdal/lib/krb5/krb5_ccache.3 +++ b/crypto/heimdal/lib/krb5/krb5_ccache.3 @@ -1,37 +1,37 @@ -.\" Copyright (c) 2003 Kungliga Tekniska Högskolan -.\" (Royal Institute of Technology, Stockholm, Sweden). -.\" All rights reserved. +.\" Copyright (c) 2003 - 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: +.\" 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. +.\" 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. +.\" 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. +.\" 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_ccache.3,v 1.7 2003/04/16 13:58:12 lha Exp $ -.\" -.Dd March 16, 2003 +.\" 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_ccache.3 22071 2007-11-14 20:04:50Z lha $ +.\" +.Dd October 19, 2005 .Dt KRB5_CCACHE 3 .Os HEIMDAL .Sh NAME @@ -40,6 +40,7 @@ .Nm krb5_cc_ops , .Nm krb5_fcc_ops , .Nm krb5_mcc_ops , +.Nm krb5_cc_clear_mcred , .Nm krb5_cc_close , .Nm krb5_cc_copy_cache , .Nm krb5_cc_default , @@ -47,21 +48,26 @@ .Nm krb5_cc_destroy , .Nm krb5_cc_end_seq_get , .Nm krb5_cc_gen_new , +.Nm krb5_cc_get_full_name , .Nm krb5_cc_get_name , +.Nm krb5_cc_get_ops , +.Nm krb5_cc_get_prefix_ops , .Nm krb5_cc_get_principal , .Nm krb5_cc_get_type , -.Nm krb5_cc_get_ops , .Nm krb5_cc_get_version , .Nm krb5_cc_initialize , +.Nm krb5_cc_next_cred , +.Nm krb5_cc_next_cred_match , +.Nm krb5_cc_new_unique , .Nm krb5_cc_register , +.Nm krb5_cc_remove_cred , .Nm krb5_cc_resolve , .Nm krb5_cc_retrieve_cred , -.Nm krb5_cc_remove_cred , .Nm krb5_cc_set_default_name , -.Nm krb5_cc_store_cred , .Nm krb5_cc_set_flags , -.Nm krb5_cc_next_cred -.Nd mange credential cache. +.Nm krb5_cc_start_seq_get , +.Nm krb5_cc_store_cred +.Nd mange credential cache .Sh LIBRARY Kerberos 5 Library (libkrb5, -lkrb5) .Sh SYNOPSIS @@ -77,90 +83,105 @@ Kerberos 5 Library (libkrb5, -lkrb5) .Pp .Li "struct krb5_cc_ops *krb5_mcc_ops;" .Pp +.Ft void +.Fo krb5_cc_clear_mcred +.Fa "krb5_creds *mcred" +.Fc .Ft krb5_error_code .Fo krb5_cc_close -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_ccache id" .Fc .Ft krb5_error_code .Fo krb5_cc_copy_cache -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "const krb5_ccache from" .Fa "krb5_ccache to" .Fc .Ft krb5_error_code .Fo krb5_cc_default -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_ccache *id" .Fc .Ft "const char *" .Fo krb5_cc_default_name -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fc .Ft krb5_error_code .Fo krb5_cc_destroy -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_ccache id" .Fc .Ft krb5_error_code .Fo krb5_cc_end_seq_get -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "const krb5_ccache id" .Fa "krb5_cc_cursor *cursor" .Fc .Ft krb5_error_code .Fo krb5_cc_gen_new -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "const krb5_cc_ops *ops" .Fa "krb5_ccache *id" .Fc +.Ft krb5_error_code +.Fo krb5_cc_get_full_name +.Fa "krb5_context context" +.Fa "krb5_ccache id" +.Fa "char **str" +.Fc .Ft "const char *" .Fo krb5_cc_get_name -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_ccache id" .Fc .Ft krb5_error_code .Fo krb5_cc_get_principal -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_ccache id" .Fa "krb5_principal *principal" .Fc .Ft "const char *" .Fo krb5_cc_get_type -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_ccache id" .Fc .Ft "const krb5_cc_ops *" .Fo krb5_cc_get_ops -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_ccache id" .Fc +.Ft "const krb5_cc_ops *" +.Fo krb5_cc_get_prefix_ops +.Fa "krb5_context context" +.Fa "const char *prefix" +.Fc .Ft krb5_error_code .Fo krb5_cc_get_version -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "const krb5_ccache id" .Fc .Ft krb5_error_code .Fo krb5_cc_initialize -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_ccache id" .Fa "krb5_principal primary_principal" .Fc .Ft krb5_error_code .Fo krb5_cc_register -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "const krb5_cc_ops *ops" .Fa "krb5_boolean override" .Fc .Ft krb5_error_code .Fo krb5_cc_resolve -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "const char *name" .Fa "krb5_ccache *id" .Fc .Ft krb5_error_code .Fo krb5_cc_retrieve_cred -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_ccache id" .Fa "krb5_flags whichfields" .Fa "const krb5_creds *mcreds" @@ -168,34 +189,56 @@ Kerberos 5 Library (libkrb5, -lkrb5) .Fc .Ft krb5_error_code .Fo krb5_cc_remove_cred -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_ccache id" .Fa "krb5_flags which" .Fa "krb5_creds *cred" .Fc .Ft krb5_error_code .Fo krb5_cc_set_default_name -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "const char *name" .Fc .Ft krb5_error_code +.Fo krb5_cc_start_seq_get +.Fa "krb5_context context" +.Fa "const krb5_ccache id" +.Fa "krb5_cc_cursor *cursor" +.Fc +.Ft krb5_error_code .Fo krb5_cc_store_cred -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_ccache id" .Fa "krb5_creds *creds" .Fc .Ft krb5_error_code .Fo krb5_cc_set_flags -.Fa "krb5_context *context" +.Fa "krb5_context context" .Fa "krb5_cc_set_flags id" .Fa "krb5_flags flags" .Fc .Ft krb5_error_code .Fo krb5_cc_next_cred -.Fa "krb5_context *context" +.Fa "krb5_context context" +.Fa "const krb5_ccache id" +.Fa "krb5_cc_cursor *cursor" +.Fa "krb5_creds *creds" +.Fc +.Ft krb5_error_code +.Fo krb5_cc_next_cred_match +.Fa "krb5_context context" .Fa "const krb5_ccache id" .Fa "krb5_cc_cursor *cursor" .Fa "krb5_creds *creds" +.Fa "krb5_flags whichfields" +.Fa "const krb5_creds *mcreds" +.Fc +.Ft krb5_error_code +.Fo krb5_cc_new_unique +.Fa "krb5_context context" +.Fa "const char *type" +.Fa "const char *hint" +.Fa "krb5_ccache *id" .Fc .Sh DESCRIPTION The @@ -231,68 +274,108 @@ gets and sets the default name for the .Fa context . .Pp .Fn krb5_cc_default -opens the default ccache in +opens the default credential cache in .Fa id . Return 0 or an error code. .Pp .Fn krb5_cc_gen_new -generates a new ccache of type +generates a new credential cache of type .Fa ops in .Fa id . Return 0 or an error code. +The Heimdal version of this function also runs +.Fn krb5_cc_initialize +on the credential cache, but since the MIT version doesn't, portable +code must call krb5_cc_initialize. +.Pp +.Fn krb5_cc_new_unique +generates a new unique credential cache of +.Fa type +in +.Fa id . +If type is +.Dv NULL , +the library chooses the default credential cache type. +The supplied +.Fa hint +(that can be +.Dv NULL ) +is a string that the credential cache type can use to base the name of +the credential on, this is to make it easier for the user to +differentiate the credentials. +The returned credential cache +.Fa id +should be freed using +.Fn krb5_cc_close +or +.Fn krb5_cc_destroy . +Returns 0 or an error code. .Pp .Fn krb5_cc_resolve -finds and allocates a ccache in +finds and allocates a credential cache in .Fa id -from the specification in +from the specification in .Fa residual . -If the ccache name doesn't contain any colon (:), interpret it as a +If the credential cache name doesn't contain any colon (:), interpret it as a file name. Return 0 or an error code. .Pp .Fn krb5_cc_initialize -creates a new ccache in +creates a new credential cache in .Fa id for .Fa primary_principal . Return 0 or an error code. .Pp .Fn krb5_cc_close -stops using the ccache +stops using the credential cache .Fa id and frees the related resources. Return 0 or an error code. .Fn krb5_cc_destroy -removes the ccache +removes the credential cache and closes (by calling .Fn krb5_cc_close ) .Fa id . Return 0 or an error code. .Pp .Fn krb5_cc_copy_cache -copys the contents of +copys the contents of .Fa from -to +to .Fa to . .Pp +.Fn krb5_cc_get_full_name +returns the complete resolvable name of the credential cache +.Fa id +in +.Fa str . +.Fa str +should be freed with +.Xr free 3 . +Returns 0 or an error, on error +.Fa *str +is set to +.Dv NULL . +.Pp .Fn krb5_cc_get_name -returns the name of the ccache +returns the name of the credential cache .Fa id . .Pp .Fn krb5_cc_get_principal -returns the principal of +returns the principal of .Fa id in .Fa principal . Return 0 or an error code. .Pp .Fn krb5_cc_get_type -returns the type of the ccache +returns the type of the credential cache .Fa id . .Pp .Fn krb5_cc_get_ops -returns the ops of the ccache +returns the ops of the credential cache .Fa id . .Pp .Fn krb5_cc_get_version @@ -300,23 +383,32 @@ returns the version of .Fa id . .Pp .Fn krb5_cc_register -Adds a new ccache type with operations +Adds a new credential cache type with operations .Fa ops , overwriting any existing one if .Fa override . Return an error code or 0. .Pp +.Fn krb5_cc_get_prefix_ops +Get the cc ops that is registered in +.Fa context +to handle the +.Fa prefix . +Returns +.Dv NULL +if ops not found. +.Pp .Fn krb5_cc_remove_cred removes the credential identified by .Fa ( cred , .Fa which ) -from +from .Fa id . .Pp .Fn krb5_cc_store_cred stores .Fa creds -in the ccache +in the credential cache .Fa id . Return 0 or an error code. .Pp @@ -326,8 +418,14 @@ sets the flags of to .Fa flags . .Pp +.Fn krb5_cc_clear_mcred +clears the +.Fa mcreds +argument so it is reset and can be used with +.Fa krb5_cc_retrieve_cred . +.Pp .Fn krb5_cc_retrieve_cred , -retrieves the credential identified by +retrieves the credential identified by .Fa mcreds (and .Fa whichfields ) @@ -335,8 +433,16 @@ from .Fa id in .Fa creds . +.Fa creds +should be freed using +.Fn krb5_free_cred_contents . Return 0 or an error code. .Pp +.Fn krb5_cc_start_seq_get +initiates the +.Li krb5_cc_cursor +structure to be used for iteration over the credential cache. +.Pp .Fn krb5_cc_next_cred retrieves the next cred pointed to by .Fa ( id , @@ -347,9 +453,64 @@ and advance .Fa cursor . Return 0 or an error code. .Pp +.Fn krb5_cc_next_cred_match +is similar to +.Fn krb5_cc_next_cred +except that it will only return creds matching +.Fa whichfields +and +.Fa mcreds +(as interpreted by +.Xr krb5_compare_creds 3 . ) +.Pp .Fn krb5_cc_end_seq_get Destroys the cursor .Fa cursor . +.Sh EXAMPLE +This is a minimalistic version of +.Nm klist . +.Pp +.Bd -literal +#include <krb5.h> + +int +main (int argc, char **argv) +{ + krb5_context context; + krb5_cc_cursor cursor; + krb5_error_code ret; + krb5_ccache id; + krb5_creds creds; + + if (krb5_init_context (&context) != 0) + errx(1, "krb5_context"); + + ret = krb5_cc_default (context, &id); + if (ret) + krb5_err(context, 1, ret, "krb5_cc_default"); + + ret = krb5_cc_start_seq_get(context, id, &cursor); + if (ret) + krb5_err(context, 1, ret, "krb5_cc_start_seq_get"); + + while((ret = krb5_cc_next_cred(context, id, &cursor, &creds)) == 0){ + char *principal; + + krb5_unparse_name_short(context, creds.server, &principal); + printf("principal: %s\\n", principal); + free(principal); + krb5_free_cred_contents (context, &creds); + } + ret = krb5_cc_end_seq_get(context, id, &cursor); + if (ret) + krb5_err(context, 1, ret, "krb5_cc_end_seq_get"); + + krb5_cc_close(context, id); + + krb5_free_context(context); + return 0; +} +.Ed .Sh SEE ALSO .Xr krb5 3 , .Xr krb5.conf 5 , |
