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