1.\" Copyright (c) 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 August 27, 2005 35.Dt KRB5_MK_REQ 3 36.Os HEIMDAL 37.Sh NAME 38.Nm krb5_mk_req , 39.Nm krb5_mk_req_exact , 40.Nm krb5_mk_req_extended , 41.Nm krb5_rd_req , 42.Nm krb5_rd_req_with_keyblock , 43.Nm krb5_mk_rep , 44.Nm krb5_mk_rep_exact , 45.Nm krb5_mk_rep_extended , 46.Nm krb5_rd_rep , 47.Nm krb5_build_ap_req , 48.Nm krb5_verify_ap_req 49.Nd create and read application authentication request 50.Sh LIBRARY 51Kerberos 5 Library (libkrb5, -lkrb5) 52.Sh SYNOPSIS 53.In krb5.h 54.Ft krb5_error_code 55.Fo krb5_mk_req 56.Fa "krb5_context context" 57.Fa "krb5_auth_context *auth_context" 58.Fa "const krb5_flags ap_req_options" 59.Fa "const char *service" 60.Fa "const char *hostname" 61.Fa "krb5_data *in_data" 62.Fa "krb5_ccache ccache" 63.Fa "krb5_data *outbuf" 64.Fc 65.Ft krb5_error_code 66.Fo krb5_mk_req_extended 67.Fa "krb5_context context" 68.Fa "krb5_auth_context *auth_context" 69.Fa "const krb5_flags ap_req_options" 70.Fa "krb5_data *in_data" 71.Fa "krb5_creds *in_creds" 72.Fa "krb5_data *outbuf" 73.Fc 74.Ft krb5_error_code 75.Fo krb5_rd_req 76.Fa "krb5_context context" 77.Fa "krb5_auth_context *auth_context" 78.Fa "const krb5_data *inbuf" 79.Fa "krb5_const_principal server" 80.Fa "krb5_keytab keytab" 81.Fa "krb5_flags *ap_req_options" 82.Fa "krb5_ticket **ticket" 83.Fc 84.Ft krb5_error_code 85.Fo krb5_build_ap_req 86.Fa "krb5_context context" 87.Fa "krb5_enctype enctype" 88.Fa "krb5_creds *cred" 89.Fa "krb5_flags ap_options" 90.Fa "krb5_data authenticator" 91.Fa "krb5_data *retdata" 92.Fc 93.Ft krb5_error_code 94.Fo krb5_verify_ap_req 95.Fa "krb5_context context" 96.Fa "krb5_auth_context *auth_context" 97.Fa "krb5_ap_req *ap_req" 98.Fa "krb5_const_principal server" 99.Fa "krb5_keyblock *keyblock" 100.Fa "krb5_flags flags" 101.Fa "krb5_flags *ap_req_options" 102.Fa "krb5_ticket **ticket" 103.Fc 104.Sh DESCRIPTION 105The functions documented in this manual page document the functions 106that facilitates the exchange between a Kerberos client and server. 107They are the core functions used in the authentication exchange 108between the client and the server. 109.Pp 110The 111.Nm krb5_mk_req 112and 113.Nm krb5_mk_req_extended 114creates the Kerberos message 115.Dv KRB_AP_REQ 116that is sent from the client to the server as the first packet in a client/server exchange. The result that should be sent to server is stored in 117.Fa outbuf . 118.Pp 119.Fa auth_context 120should be allocated with 121.Fn krb5_auth_con_init 122or 123.Dv NULL 124passed in, in that case, it will be allocated and freed internally. 125.Pp 126The input data 127.Fa in_data 128will have a checksum calculated over it and checksum will be 129transported in the message to the server. 130.Pp 131.Fa ap_req_options 132can be set to one or more of the following flags: 133.Pp 134.Bl -tag -width indent 135.It Dv AP_OPTS_USE_SESSION_KEY 136Use the session key when creating the request, used for user to user 137authentication. 138.It Dv AP_OPTS_MUTUAL_REQUIRED 139Mark the request as mutual authenticate required so that the receiver 140returns a mutual authentication packet. 141.El 142.Pp 143The 144.Nm krb5_rd_req 145read the AP_REQ in 146.Fa inbuf 147and verify and extract the content. 148If 149.Fa server 150is specified, that server will be fetched from the 151.Fa keytab 152and used unconditionally. 153If 154.Fa server 155is 156.Dv NULL , 157the 158.Fa keytab 159will be search for a matching principal. 160.Pp 161The 162.Fa keytab 163argument specifies what keytab to search for receiving principals. 164The arguments 165.Fa ap_req_options 166and 167.Fa ticket 168returns the content. 169.Pp 170When the AS-REQ is a user to user request, neither of 171.Fa keytab 172or 173.Fa principal 174are used, instead 175.Fn krb5_rd_req 176expects the session key to be set in 177.Fa auth_context . 178.Pp 179The 180.Nm krb5_verify_ap_req 181and 182.Nm krb5_build_ap_req 183both constructs and verify the AP_REQ message, should not be used by 184external code. 185.Sh SEE ALSO 186.Xr krb5 3 , 187.Xr krb5.conf 5 188