1.\" $NetBSD: krb5_get_in_cred.3,v 1.5 2023/06/19 21:41:44 christos Exp $ 2.\" 3.\" Copyright (c) 2003 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 May 31, 2003 37.Dt KRB5_GET_IN_TKT 3 38.Os 39.Sh NAME 40.Nm krb5_get_in_tkt , 41.Nm krb5_get_in_cred , 42.Nm krb5_get_in_tkt_with_password , 43.Nm krb5_get_in_tkt_with_keytab , 44.Nm krb5_get_in_tkt_with_skey , 45.Nm krb5_free_kdc_rep , 46.Nm krb5_password_key_proc 47.Nd deprecated initial authentication functions 48.Sh LIBRARY 49Kerberos 5 Library (libkrb5, -lkrb5) 50.Sh SYNOPSIS 51.In krb5/krb5.h 52.Pp 53.Ft krb5_error_code 54.Fo krb5_get_in_tkt 55.Fa "krb5_context context" 56.Fa "krb5_flags options" 57.Fa "const krb5_addresses *addrs" 58.Fa "const krb5_enctype *etypes" 59.Fa "const krb5_preauthtype *ptypes" 60.Fa "krb5_key_proc key_proc" 61.Fa "krb5_const_pointer keyseed" 62.Fa "krb5_decrypt_proc decrypt_proc" 63.Fa "krb5_const_pointer decryptarg" 64.Fa "krb5_creds *creds" 65.Fa "krb5_ccache ccache" 66.Fa "krb5_kdc_rep *ret_as_reply" 67.Fc 68.Ft krb5_error_code 69.Fo krb5_get_in_cred 70.Fa "krb5_context context" 71.Fa "krb5_flags options" 72.Fa "const krb5_addresses *addrs" 73.Fa "const krb5_enctype *etypes" 74.Fa "const krb5_preauthtype *ptypes" 75.Fa "const krb5_preauthdata *preauth" 76.Fa "krb5_key_proc key_proc" 77.Fa "krb5_const_pointer keyseed" 78.Fa "krb5_decrypt_proc decrypt_proc" 79.Fa "krb5_const_pointer decryptarg" 80.Fa "krb5_creds *creds" 81.Fa "krb5_kdc_rep *ret_as_reply" 82.Fc 83.Ft krb5_error_code 84.Fo krb5_get_in_tkt_with_password 85.Fa "krb5_context context" 86.Fa "krb5_flags options" 87.Fa "krb5_addresses *addrs" 88.Fa "const krb5_enctype *etypes" 89.Fa "const krb5_preauthtype *pre_auth_types" 90.Fa "const char *password" 91.Fa "krb5_ccache ccache" 92.Fa "krb5_creds *creds" 93.Fa "krb5_kdc_rep *ret_as_reply" 94.Fc 95.Ft krb5_error_code 96.Fo krb5_get_in_tkt_with_keytab 97.Fa "krb5_context context" 98.Fa "krb5_flags options" 99.Fa "krb5_addresses *addrs" 100.Fa "const krb5_enctype *etypes" 101.Fa "const krb5_preauthtype *pre_auth_types" 102.Fa "krb5_keytab keytab" 103.Fa "krb5_ccache ccache" 104.Fa "krb5_creds *creds" 105.Fa "krb5_kdc_rep *ret_as_reply" 106.Fc 107.Ft krb5_error_code 108.Fo krb5_get_in_tkt_with_skey 109.Fa "krb5_context context" 110.Fa "krb5_flags options" 111.Fa "krb5_addresses *addrs" 112.Fa "const krb5_enctype *etypes" 113.Fa "const krb5_preauthtype *pre_auth_types" 114.Fa "const krb5_keyblock *key" 115.Fa "krb5_ccache ccache" 116.Fa "krb5_creds *creds" 117.Fa "krb5_kdc_rep *ret_as_reply" 118.Fc 119.Ft krb5_error_code 120.Fo krb5_free_kdc_rep 121.Fa "krb5_context context" 122.Fa "krb5_kdc_rep *rep" 123.Fc 124.Ft krb5_error_code 125.Fo krb5_password_key_proc 126.Fa "krb5_context context" 127.Fa "krb5_enctype type" 128.Fa "krb5_salt salt" 129.Fa "krb5_const_pointer keyseed" 130.Fa "krb5_keyblock **key" 131.Fc 132.Sh DESCRIPTION 133.Bf Em 134All the functions in this manual page are deprecated in the MIT 135implementation, and will soon be deprecated in Heimdal too, don't use them. 136.Ef 137.Pp 138Getting initial credential ticket for a principal. 139.Nm krb5_get_in_cred 140is the function all other krb5_get_in function uses to fetch tickets. 141The other krb5_get_in function are more specialized and therefor 142somewhat easier to use. 143.Pp 144If your need is only to verify a user and password, consider using 145.Xr krb5_verify_user 3 146instead, it have a much simpler interface. 147.Pp 148.Nm krb5_get_in_tkt 149and 150.Nm krb5_get_in_cred 151fetches initial credential, queries after key using the 152.Fa key_proc 153argument. 154The differences between the two function is that 155.Nm krb5_get_in_tkt 156stores the credential in a 157.Li krb5_creds 158while 159.Nm krb5_get_in_cred 160stores the credential in a 161.Li krb5_ccache . 162.Pp 163.Nm krb5_get_in_tkt_with_password , 164.Nm krb5_get_in_tkt_with_keytab , 165and 166.Nm krb5_get_in_tkt_with_skey 167does the same work as 168.Nm krb5_get_in_cred 169but are more specialized. 170.Pp 171.Nm krb5_get_in_tkt_with_password 172uses the clients password to authenticate. 173If the password argument is 174.Dv NULL 175the user user queried with the default password query function. 176.Pp 177.Nm krb5_get_in_tkt_with_keytab 178searches the given keytab for a service entry for the client principal. 179If the keytab is 180.Dv NULL 181the default keytab is used. 182.Pp 183.Nm krb5_get_in_tkt_with_skey 184uses a key to get the initial credential. 185.Pp 186There are some common arguments to the krb5_get_in functions, these are: 187.Pp 188.Fa options 189are the 190.Dv KDC_OPT 191flags. 192.Pp 193.Fa etypes 194is a 195.Dv NULL 196terminated array of encryption types that the client approves. 197.Pp 198.Fa addrs 199a list of the addresses that the initial ticket. 200If it is 201.Dv NULL 202the list will be generated by the library. 203.Pp 204.Fa pre_auth_types 205a 206.Dv NULL 207terminated array of pre-authentication types. 208If 209.Fa pre_auth_types 210is 211.Dv NULL 212the function will try without pre-authentication and return those 213pre-authentication that the KDC returned. 214.Pp 215.Fa ret_as_reply 216will (if not 217.Dv NULL ) 218be filled in with the response of the KDC and should be free with 219.Fn krb5_free_kdc_rep . 220.Pp 221.Fa key_proc 222is a pointer to a function that should return a key salted appropriately. 223Using 224.Dv NULL 225will use the default password query function. 226.Pp 227.Fa decrypt_proc 228Using 229.Dv NULL 230will use the default decryption function. 231.Pp 232.Fa decryptarg 233will be passed to the decryption function 234.Fa decrypt_proc . 235.Pp 236.Fa creds 237creds should be filled in with the template for a credential that 238should be requested. 239The client and server elements of the creds structure must be filled in. 240Upon return of the function it will be contain the content of the 241requested credential 242.Fa ( krb5_get_in_cred ) , 243or it will be freed with 244.Xr krb5_free_creds 3 245(all the other krb5_get_in functions). 246.Pp 247.Fa ccache 248will store the credential in the credential cache 249.Fa ccache . 250The credential cache will not be initialized, thats up the the caller. 251.Pp 252.Nm krb5_password_key_proc 253is a library function that is suitable using as the 254.Fa krb5_key_proc 255argument to 256.Nm krb5_get_in_cred 257or 258.Nm krb5_get_in_tkt . 259.Fa keyseed 260should be a pointer to a 261.Dv NUL 262terminated string or 263.Dv NULL . 264.Nm krb5_password_key_proc 265will query the user for the pass on the console if the password isn't 266given as the argument 267.Fa keyseed . 268.Pp 269.Fn krb5_free_kdc_rep 270frees the content of 271.Fa rep . 272.Sh SEE ALSO 273.Xr krb5 3 , 274.Xr krb5_verify_user 3 , 275.Xr krb5.conf 5 , 276.Xr kerberos 8 277