source: heimdal/trunk/lib/krb5/krb5_mk_req.3

Last change on this file was 1, checked in by Paul Smedley, 10 years ago

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