lib/krb5/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