1.\" Copyright (c) 2004 - 2005 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: krb5_get_credentials.3 22071 2007-11-14 20:04:50Z lha $ 33.\" 34.Dd July 26, 2004 35.Dt KRB5_GET_CREDENTIALS 3 36.Os HEIMDAL 37.Sh NAME 38.Nm krb5_get_credentials , 39.Nm krb5_get_credentials_with_flags , 40.Nm krb5_get_cred_from_kdc , 41.Nm krb5_get_cred_from_kdc_opt , 42.Nm krb5_get_kdc_cred , 43.Nm krb5_get_renewed_creds 44.Nd get credentials from the KDC using krbtgt 45.Sh LIBRARY 46Kerberos 5 Library (libkrb5, -lkrb5) 47.Sh SYNOPSIS 48.In krb5.h 49.Ft krb5_error_code 50.Fo krb5_get_credentials 51.Fa "krb5_context context" 52.Fa "krb5_flags options" 53.Fa "krb5_ccache ccache" 54.Fa "krb5_creds *in_creds" 55.Fa "krb5_creds **out_creds" 56.Fc 57.Ft krb5_error_code 58.Fo krb5_get_credentials_with_flags 59.Fa "krb5_context context" 60.Fa "krb5_flags options" 61.Fa "krb5_kdc_flags flags" 62.Fa "krb5_ccache ccache" 63.Fa "krb5_creds *in_creds" 64.Fa "krb5_creds **out_creds" 65.Fc 66.Ft krb5_error_code 67.Fo krb5_get_cred_from_kdc 68.Fa "krb5_context context" 69.Fa "krb5_ccache ccache" 70.Fa "krb5_creds *in_creds" 71.Fa "krb5_creds **out_creds" 72.Fa "krb5_creds ***ret_tgts" 73.Fc 74.Ft krb5_error_code 75.Fo krb5_get_cred_from_kdc_opt 76.Fa "krb5_context context" 77.Fa "krb5_ccache ccache" 78.Fa "krb5_creds *in_creds" 79.Fa "krb5_creds **out_creds" 80.Fa "krb5_creds ***ret_tgts" 81.Fa "krb5_flags flags" 82.Fc 83.Ft krb5_error_code 84.Fo krb5_get_kdc_cred 85.Fa "krb5_context context" 86.Fa "krb5_ccache id" 87.Fa "krb5_kdc_flags flags" 88.Fa "krb5_addresses *addresses" 89.Fa "Ticket *second_ticket" 90.Fa "krb5_creds *in_creds" 91.Fa "krb5_creds **out_creds" 92.Fc 93.Ft krb5_error_code 94.Fo krb5_get_renewed_creds 95.Fa "krb5_context context" 96.Fa "krb5_creds *creds" 97.Fa "krb5_const_principal client" 98.Fa "krb5_ccache ccache" 99.Fa "const char *in_tkt_service" 100.Fc 101.Sh DESCRIPTION 102.Fn krb5_get_credentials_with_flags 103get credentials specified by 104.Fa in_creds->server 105and 106.Fa in_creds->client 107(the rest of the 108.Fa in_creds 109structure is ignored) 110by first looking in the 111.Fa ccache 112and if doesn't exists or is expired, fetch the credential from the KDC 113using the krbtgt in 114.Fa ccache . 115The credential is returned in 116.Fa out_creds 117and should be freed using the function 118.Fn krb5_free_creds . 119.Pp 120Valid flags to pass into 121.Fa options 122argument are: 123.Pp 124.Bl -tag -width "KRB5_GC_USER_USER" -compact 125.It KRB5_GC_CACHED 126Only check the 127.Fa ccache , 128don't got out on network to fetch credential. 129.It KRB5_GC_USER_USER 130Request a user to user ticket. 131This option doesn't store the resulting user to user credential in 132the 133.Fa ccache . 134.It KRB5_GC_EXPIRED_OK 135returns the credential even if it is expired, default behavior is trying 136to refetch the credential from the KDC. 137.El 138.Pp 139.Fa Flags 140are KDCOptions, note the caller must fill in the bit-field and not 141use the integer associated structure. 142.Pp 143.Fn krb5_get_credentials 144works the same way as 145.Fn krb5_get_credentials_with_flags 146except that the 147.Fa flags 148field is missing. 149.Pp 150.Fn krb5_get_cred_from_kdc 151and 152.Fn krb5_get_cred_from_kdc_opt 153fetches the credential from the KDC very much like 154.Fn krb5_get_credentials, but doesn't look in the 155.Fa ccache 156if the credential exists there first. 157.Pp 158.Fn krb5_get_kdc_cred 159does the same as the functions above, but the caller must fill in all 160the information andits closer to the wire protocol. 161.Pp 162.Fn krb5_get_renewed_creds 163renews a credential given by 164.Fa in_tkt_service 165(if 166.Dv NULL 167the default 168.Li krbtgt ) 169using the credential cache 170.Fa ccache . 171The result is stored in 172.Fa creds 173and should be freed using 174.Fa krb5_free_creds . 175.Sh EXAMPLES 176Here is a example function that get a credential from a credential cache 177.Fa id 178or the KDC and returns it to the caller. 179.Bd -literal 180#include <krb5.h> 181 182int 183getcred(krb5_context context, krb5_ccache id, krb5_creds **creds) 184{ 185 krb5_error_code ret; 186 krb5_creds in; 187 188 ret = krb5_parse_name(context, "client@EXAMPLE.COM", 189 &in.client); 190 if (ret) 191 krb5_err(context, 1, ret, "krb5_parse_name"); 192 193 ret = krb5_parse_name(context, "host/server.example.com@EXAMPLE.COM", 194 &in.server); 195 if (ret) 196 krb5_err(context, 1, ret, "krb5_parse_name"); 197 198 ret = krb5_get_credentials(context, 0, id, &in, creds); 199 if (ret) 200 krb5_err(context, 1, ret, "krb5_get_credentials"); 201 202 return 0; 203} 204.Ed 205.Sh SEE ALSO 206.Xr krb5 3 , 207.Xr krb5_get_forwarded_creds 3 , 208.Xr krb5.conf 5 209