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