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