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