1.\" $NetBSD: krb5_get_credentials.3,v 1.1.1.2 2011/04/14 14:09:23 elric Exp $ 2.\" 3.\" Copyright (c) 2004 - 2005 Kungliga Tekniska Högskolan 4.\" (Royal Institute of Technology, Stockholm, Sweden). 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" 3. Neither the name of the Institute nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" Id 35.\" 36.Dd July 26, 2004 37.Dt KRB5_GET_CREDENTIALS 3 38.Os 39.Sh NAME 40.Nm krb5_get_credentials , 41.Nm krb5_get_credentials_with_flags , 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/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_kdc_cred 68.Fa "krb5_context context" 69.Fa "krb5_ccache id" 70.Fa "krb5_kdc_flags flags" 71.Fa "krb5_addresses *addresses" 72.Fa "Ticket *second_ticket" 73.Fa "krb5_creds *in_creds" 74.Fa "krb5_creds **out_creds" 75.Fc 76.Ft krb5_error_code 77.Fo krb5_get_renewed_creds 78.Fa "krb5_context context" 79.Fa "krb5_creds *creds" 80.Fa "krb5_const_principal client" 81.Fa "krb5_ccache ccache" 82.Fa "const char *in_tkt_service" 83.Fc 84.Sh DESCRIPTION 85.Fn krb5_get_credentials_with_flags 86get credentials specified by 87.Fa in_creds->server 88and 89.Fa in_creds->client 90(the rest of the 91.Fa in_creds 92structure is ignored) 93by first looking in the 94.Fa ccache 95and if doesn't exists or is expired, fetch the credential from the KDC 96using the krbtgt in 97.Fa ccache . 98The credential is returned in 99.Fa out_creds 100and should be freed using the function 101.Fn krb5_free_creds . 102.Pp 103Valid flags to pass into 104.Fa options 105argument are: 106.Pp 107.Bl -tag -width "KRB5_GC_EXPIRED_OK" -compact 108.It KRB5_GC_CACHED 109Only check the 110.Fa ccache , 111don't got out on network to fetch credential. 112.It KRB5_GC_USER_USER 113Request a user to user ticket. 114This option doesn't store the resulting user to user credential in 115the 116.Fa ccache . 117.It KRB5_GC_EXPIRED_OK 118returns the credential even if it is expired, default behavior is trying 119to refetch the credential from the KDC. 120.El 121.Pp 122.Fa Flags 123are KDCOptions, note the caller must fill in the bit-field and not 124use the integer associated structure. 125.Pp 126.Fn krb5_get_credentials 127works the same way as 128.Fn krb5_get_credentials_with_flags 129except that the 130.Fa flags 131field is missing. 132.Pp 133.Fn krb5_get_kdc_cred 134does the same as the functions above, but the caller must fill in all 135the information andits closer to the wire protocol. 136.Pp 137.Fn krb5_get_renewed_creds 138renews a credential given by 139.Fa in_tkt_service 140(if 141.Dv NULL 142the default 143.Li krbtgt ) 144using the credential cache 145.Fa ccache . 146The result is stored in 147.Fa creds 148and should be freed using 149.Fa krb5_free_creds . 150.Sh EXAMPLES 151Here is a example function that get a credential from a credential cache 152.Fa id 153or the KDC and returns it to the caller. 154.Bd -literal 155#include <krb5/krb5.h> 156 157int 158getcred(krb5_context context, krb5_ccache id, krb5_creds **creds) 159{ 160 krb5_error_code ret; 161 krb5_creds in; 162 163 ret = krb5_parse_name(context, "client@EXAMPLE.COM", 164 &in.client); 165 if (ret) 166 krb5_err(context, 1, ret, "krb5_parse_name"); 167 168 ret = krb5_parse_name(context, "host/server.example.com@EXAMPLE.COM", 169 &in.server); 170 if (ret) 171 krb5_err(context, 1, ret, "krb5_parse_name"); 172 173 ret = krb5_get_credentials(context, 0, id, &in, creds); 174 if (ret) 175 krb5_err(context, 1, ret, "krb5_get_credentials"); 176 177 return 0; 178} 179.Ed 180.Sh SEE ALSO 181.Xr krb5 3 , 182.Xr krb5_get_forwarded_creds 3 , 183.Xr krb5.conf 5 184