krb5_mk_req.3
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 51 Kerberos 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 105 The functions documented in this manual page document the functions 106 that facilitates the exchange between a Kerberos client and server. 107 They are the core functions used in the authentication exchange 108 between the client and the server. 109 .Pp 110 The 111 .Nm krb5_mk_req 112 and 113 .Nm krb5_mk_req_extended 114 creates the Kerberos message 115 .Dv KRB_AP_REQ 116 that 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 120 should be allocated with 121 .Fn krb5_auth_con_init 122 or 123 .Dv NULL 124 passed in, in that case, it will be allocated and freed internally. 125 .Pp 126 The input data 127 .Fa in_data 128 will have a checksum calculated over it and checksum will be 129 transported in the message to the server. 130 .Pp 131 .Fa ap_req_options 132 can 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 136 Use the session key when creating the request, used for user to user 137 authentication. 138 .It Dv AP_OPTS_MUTUAL_REQUIRED 139 Mark the request as mutual authenticate required so that the receiver 140 returns a mutual authentication packet. 141 .El 142 .Pp 143 The 144 .Nm krb5_rd_req 145 read the AP_REQ in 146 .Fa inbuf 147 and verify and extract the content. 148 If 149 .Fa server 150 is specified, that server will be fetched from the 151 .Fa keytab 152 and used unconditionally. 153 If 154 .Fa server 155 is 156 .Dv NULL , 157 the 158 .Fa keytab 159 will be search for a matching principal. 160 .Pp 161 The 162 .Fa keytab 163 argument specifies what keytab to search for receiving principals. 164 The arguments 165 .Fa ap_req_options 166 and 167 .Fa ticket 168 returns the content. 169 .Pp 170 When the AS-REQ is a user to user request, neither of 171 .Fa keytab 172 or 173 .Fa principal 174 are used, instead 175 .Fn krb5_rd_req 176 expects the session key to be set in 177 .Fa auth_context . 178 .Pp 179 The 180 .Nm krb5_verify_ap_req 181 and 182 .Nm krb5_build_ap_req 183 both constructs and verify the AP_REQ message, should not be used by 184 external code. 185 .Sh SEE ALSO 186 .Xr krb5 3 , 187 .Xr krb5.conf 5