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 48Kerberos 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 101fetches credentials specified by 102.Fa opt 103by first looking in the 104.Fa ccache , 105and then it doesn't exists, fetch the credential from the KDC 106using the krbtgts in 107.Fa ccache . 108The credential is returned in 109.Fa out_creds 110and should be freed using the function 111.Fn krb5_free_creds . 112.Pp 113The structure 114.Li krb5_get_creds_opt 115controls the behavior of 116.Fn krb5_get_creds . 117The structure is opaque to consumers that can set the content of the 118structure with accessors functions. All accessor functions make copies 119of the data that is passed into accessor functions, so external 120consumers free the memory before calling 121.Fn krb5_get_creds . 122.Pp 123The structure 124.Li krb5_get_creds_opt 125is allocated with 126.Fn krb5_get_creds_opt_alloc 127and freed with 128.Fn krb5_get_creds_opt_free . 129The free function also frees the content of the structure set by the 130accessor functions. 131.Pp 132.Fn krb5_get_creds_opt_add_options 133and 134.Fn krb5_get_creds_opt_set_options 135adds and sets options to the 136.Fi krb5_get_creds_opt 137structure . 138The possible options to set are 139.Bl -tag -width "KRB5_GC_USER_USER" -compact 140.It KRB5_GC_CACHED 141Only check the 142.Fa ccache , 143don't got out on network to fetch credential. 144.It KRB5_GC_USER_USER 145request a user to user ticket. 146This options doesn't store the resulting user to user credential in 147the 148.Fa ccache . 149.It KRB5_GC_EXPIRED_OK 150returns the credential even if it is expired, default behavior is trying 151to refetch the credential from the KDC. 152.It KRB5_GC_NO_STORE 153Do not store the resulting credentials in the 154.Fa ccache . 155.El 156.Pp 157.Fn krb5_get_creds_opt_set_enctype 158sets the preferred encryption type of the application. Don't set this 159unless you have to since if there is no match in the KDC, the function 160call will fail. 161.Pp 162.Fn krb5_get_creds_opt_set_impersonate 163sets the principal to impersonate., Returns a ticket that have the 164impersonation principal as a client and the requestor as the 165service. Note that the requested principal have to be the same as the 166client principal in the krbtgt. 167.Pp 168.Fn krb5_get_creds_opt_set_ticket 169sets 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 174