crypto/heimdal/lib/krb5/krb5_get_creds.3

   1 .\" Copyright (c) 2006 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" 3. Neither the name of the Institute nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Id$
  33 .\"
  34 .Dd June 15, 2006
  35 .Dt KRB5_GET_CREDS 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_get_creds ,
  39 .Nm krb5_get_creds_opt_add_options ,
  40 .Nm krb5_get_creds_opt_alloc ,
  41 .Nm krb5_get_creds_opt_free ,
  42 .Nm krb5_get_creds_opt_set_enctype ,
  43 .Nm krb5_get_creds_opt_set_impersonate ,
  44 .Nm krb5_get_creds_opt_set_options ,
  45 .Nm krb5_get_creds_opt_set_ticket
  46 .Nd get credentials from the KDC
  47 .Sh LIBRARY
  48 Kerberos 5 Library (libkrb5, -lkrb5)
  49 .Sh SYNOPSIS
  50 .In krb5.h
  51 .Ft krb5_error_code
  52 .Fo krb5_get_creds
  53 .Fa "krb5_context context"
  54 .Fa "krb5_get_creds_opt opt"
  55 .Fa "krb5_ccache ccache"
  56 .Fa "krb5_const_principal inprinc"
  57 .Fa "krb5_creds **out_creds"
  58 .Fc
  59 .Ft void
  60 .Fo krb5_get_creds_opt_add_options
  61 .Fa "krb5_context context"
  62 .Fa "krb5_get_creds_opt opt"
  63 .Fa "krb5_flags options"
  64 .Fc
  65 .Ft krb5_error_code
  66 .Fo krb5_get_creds_opt_alloc
  67 .Fa "krb5_context context"
  68 .Fa "krb5_get_creds_opt *opt"
  69 .Fc
  70 .Ft void
  71 .Fo krb5_get_creds_opt_free
  72 .Fa "krb5_context context"
  73 .Fa "krb5_get_creds_opt opt"
  74 .Fc
  75 .Ft void
  76 .Fo krb5_get_creds_opt_set_enctype
  77 .Fa "krb5_context context"
  78 .Fa "krb5_get_creds_opt opt"
  79 .Fa "krb5_enctype enctype"
  80 .Fc
  81 .Ft krb5_error_code
  82 .Fo krb5_get_creds_opt_set_impersonate
  83 .Fa "krb5_context context"
  84 .Fa "krb5_get_creds_opt opt"
  85 .Fa "krb5_const_principal self"
  86 .Fc
  87 .Ft void
  88 .Fo krb5_get_creds_opt_set_options
  89 .Fa "krb5_context context"
  90 .Fa "krb5_get_creds_opt opt"
  91 .Fa "krb5_flags options"
  92 .Fc
  93 .Ft krb5_error_code
  94 .Fo krb5_get_creds_opt_set_ticket
  95 .Fa "krb5_context context"
  96 .Fa "krb5_get_creds_opt opt"
  97 .Fa "const Ticket *ticket"
  98 .Fc
  99 .Sh DESCRIPTION
 100 .Fn krb5_get_creds
 101 fetches credentials specified by
 102 .Fa opt
 103 by first looking in the
 104 .Fa ccache ,
 105 and then it doesn't exists, fetch the credential from the KDC
 106 using the krbtgts in
 107 .Fa ccache .
 108 The credential is returned in
 109 .Fa out_creds
 110 and should be freed using the function
 111 .Fn krb5_free_creds .
 112 .Pp
 113 The structure
 114 .Li krb5_get_creds_opt
 115 controls the behavior of
 116 .Fn krb5_get_creds .
 117 The structure is opaque to consumers that can set the content of the
 118 structure with accessors functions. All accessor functions make copies
 119 of the data that is passed into accessor functions, so external
 120 consumers free the memory before calling
 121 .Fn krb5_get_creds .
 122 .Pp
 123 The structure
 124 .Li krb5_get_creds_opt
 125 is allocated with
 126 .Fn krb5_get_creds_opt_alloc
 127 and freed with
 128 .Fn krb5_get_creds_opt_free .
 129 The free function also frees the content of the structure set by the
 130 accessor functions.
 131 .Pp
 132 .Fn krb5_get_creds_opt_add_options
 133 and
 134 .Fn krb5_get_creds_opt_set_options
 135 adds and sets options to the
 136 .Fi krb5_get_creds_opt
 137 structure .
 138 The possible options to set are
 139 .Bl -tag -width "KRB5_GC_USER_USER" -compact
 140 .It KRB5_GC_CACHED
 141 Only check the
 142 .Fa ccache ,
 143 don't got out on network to fetch credential.
 144 .It KRB5_GC_USER_USER
 145 request a user to user ticket.
 146 This options doesn't store the resulting user to user credential in
 147 the
 148 .Fa ccache .
 149 .It KRB5_GC_EXPIRED_OK
 150 returns the credential even if it is expired, default behavior is trying
 151 to refetch the credential from the KDC.
 152 .It KRB5_GC_NO_STORE
 153 Do not store the resulting credentials in the
 154 .Fa ccache .
 155 .El
 156 .Pp
 157 .Fn krb5_get_creds_opt_set_enctype
 158 sets the preferred encryption type of the application. Don't set this
 159 unless you have to since if there is no match in the KDC, the function
 160 call will fail.
 161 .Pp
 162 .Fn krb5_get_creds_opt_set_impersonate
 163 sets the principal to impersonate., Returns a ticket that have the
 164 impersonation principal as a client and the requestor as the
 165 service. Note that the requested principal have to be the same as the
 166 client principal in the krbtgt.
 167 .Pp
 168 .Fn krb5_get_creds_opt_set_ticket
 169 sets the extra ticket used in user-to-user or contrained delegation use case.
 170 .Sh SEE ALSO
 171 .Xr krb5 3 ,
 172 .Xr krb5_get_credentials 3 ,
 173 .Xr krb5.conf 5