| blob | 511e9b9c1d096dc3fc8ce086fa076b9214ba6b30 |
1 .\" Copyright (c) 2003 - 2006 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 Nov 17, 2006
35 .Dt KRB5_C_MAKE_CHECKSUM 3
36 .Os HEIMDAL
37 .Sh NAME
38 .Nm krb5_c_block_size ,
39 .Nm krb5_c_decrypt ,
40 .Nm krb5_c_encrypt ,
41 .Nm krb5_c_encrypt_length ,
42 .Nm krb5_c_enctype_compare ,
43 .Nm krb5_c_get_checksum ,
44 .Nm krb5_c_is_coll_proof_cksum ,
45 .Nm krb5_c_is_keyed_cksum ,
46 .Nm krb5_c_keylength ,
47 .Nm krb5_c_make_checksum ,
48 .Nm krb5_c_make_random_key ,
49 .Nm krb5_c_set_checksum ,
50 .Nm krb5_c_valid_cksumtype ,
51 .Nm krb5_c_valid_enctype ,
52 .Nm krb5_c_verify_checksum ,
53 .Nm krb5_c_checksum_length
54 .Nd Kerberos 5 crypto API
55 .Sh LIBRARY
56 Kerberos 5 Library (libkrb5, -lkrb5)
57 .Sh SYNOPSIS
58 .In krb5.h
59 .Pp
60 .Ft krb5_error_code
61 .Fo krb5_c_block_size
62 .Fa "krb5_context context"
63 .Fa "krb5_enctype enctype"
64 .Fa "size_t *blocksize"
65 .Fc
66 .Ft krb5_error_code
67 .Fo krb5_c_decrypt
68 .Fa "krb5_context context"
69 .Fa "const krb5_keyblock key"
70 .Fa "krb5_keyusage usage"
71 .Fa "const krb5_data *ivec"
72 .Fa "krb5_enc_data *input"
73 .Fa "krb5_data *output"
74 .Fc
75 .Ft krb5_error_code
76 .Fo krb5_c_encrypt
77 .Fa "krb5_context context"
78 .Fa "const krb5_keyblock *key"
79 .Fa "krb5_keyusage usage"
80 .Fa "const krb5_data *ivec"
81 .Fa "const krb5_data *input"
82 .Fa "krb5_enc_data *output"
83 .Fc
84 .Ft krb5_error_code
85 .Fo krb5_c_encrypt_length
86 .Fa "krb5_context context"
87 .Fa "krb5_enctype enctype"
88 .Fa "size_t inputlen"
89 .Fa "size_t *length"
90 .Fc
91 .Ft krb5_error_code
92 .Fo krb5_c_enctype_compare
93 .Fa "krb5_context context"
94 .Fa "krb5_enctype e1"
95 .Fa "krb5_enctype e2"
96 .Fa "krb5_boolean *similar"
97 .Fc
98 .Ft krb5_error_code
99 .Fo krb5_c_make_random_key
100 .Fa "krb5_context context"
101 .Fa "krb5_enctype enctype"
102 .Fa "krb5_keyblock *random_key"
103 .Fc
104 .Ft krb5_error_code
105 .Fo krb5_c_make_checksum
106 .Fa "krb5_context context"
107 .Fa "krb5_cksumtype cksumtype"
108 .Fa "const krb5_keyblock *key"
109 .Fa "krb5_keyusage usage"
110 .Fa "const krb5_data *input"
111 .Fa "krb5_checksum *cksum"
112 .Fc
113 .Ft krb5_error_code
114 .Fo krb5_c_verify_checksum
115 .Fa "krb5_context context
116 .Fa "const krb5_keyblock *key"
117 .Fa "krb5_keyusage usage"
118 .Fa "const krb5_data *data"
119 .Fa "const krb5_checksum *cksum"
120 .Fa "krb5_boolean *valid"
121 .Fc
122 .Ft krb5_error_code
123 .Fo krb5_c_checksum_length
124 .Fa "krb5_context context"
125 .Fa "krb5_cksumtype cksumtype"
126 .Fa "size_t *length"
127 .Fc
128 .Ft krb5_error_code
129 .Fo krb5_c_get_checksum
130 .Fa "krb5_context context"
131 .Fa "const krb5_checksum *cksum"
132 .Fa "krb5_cksumtype *type"
133 .Fa "krb5_data **data"
134 .Fc
135 .Ft krb5_error_code
136 .Fo krb5_c_set_checksum
137 .Fa "krb5_context context"
138 .Fa "krb5_checksum *cksum"
139 .Fa "krb5_cksumtype type"
140 .Fa "const krb5_data *data"
141 .Fc
142 .Ft krb5_boolean
143 .Fo krb5_c_valid_enctype
144 .Fa krb5_enctype etype"
145 .Fc
146 .Ft krb5_boolean
147 .Fo krb5_c_valid_cksumtype
148 .Fa "krb5_cksumtype ctype"
149 .Fc
150 .Ft krb5_boolean
151 .Fo krb5_c_is_coll_proof_cksum
152 .Fa "krb5_cksumtype ctype"
153 .Fc
154 .Ft krb5_boolean
155 .Fo krb5_c_is_keyed_cksum
156 .Fa "krb5_cksumtype ctype"
157 .Fc
158 .Ft krb5_error_code
159 .Fo krb5_c_keylengths
160 .Fa "krb5_context context"
161 .Fa "krb5_enctype enctype"
162 .Fa "size_t *inlength"
163 .Fa "size_t *keylength"
164 .Fc
165 .Sh DESCRIPTION
166 The functions starting with krb5_c are compat functions with MIT kerberos.
167 .Pp
168 The
169 .Li krb5_enc_data
170 structure holds and encrypted data.
171 There are two public accessable members of
172 .Li krb5_enc_data .
173 .Li enctype
174 that holds the encryption type of the data encrypted and
175 .Li ciphertext
176 that is a
177 .Ft krb5_data
178 that might contain the encrypted data.
179 .Pp
180 .Fn krb5_c_block_size
181 returns the blocksize of the encryption type.
182 .Pp
183 .Fn krb5_c_decrypt
184 decrypts
185 .Fa input
186 and store the data in
187 .Fa output.
188 If
189 .Fa ivec
190 is
191 .Dv NULL
192 the default initialization vector for that encryption type will be used.
193 .Pp
194 .Fn krb5_c_encrypt
195 encrypts the plaintext in
196 .Fa input
197 and store the ciphertext in
198 .Fa output .
199 .Pp
200 .Fn krb5_c_encrypt_length
201 returns the length the encrypted data given the plaintext length.
202 .Pp
203 .Fn krb5_c_enctype_compare
204 compares to encryption types and returns if they use compatible
205 encryption key types.
206 .Pp
207 .Fn krb5_c_make_checksum
208 creates a checksum
209 .Fa cksum
210 with the checksum type
211 .Fa cksumtype
212 of the data in
213 .Fa data .
214 .Fa key
215 and
216 .Fa usage
217 are used if the checksum is a keyed checksum type.
218 Returns 0 or an error code.
219 .Pp
220 .Fn krb5_c_verify_checksum
221 verifies the checksum
222 of
223 .Fa data
224 in
225 .Fa cksum
226 that was created with
227 .Fa key
228 using the key usage
229 .Fa usage .
230 .Fa verify
231 is set to non-zero if the checksum verifies correctly and zero if not.
232 Returns 0 or an error code.
233 .Pp
234 .Fn krb5_c_checksum_length
235 returns the length of the checksum.
236 .Pp
237 .Fn krb5_c_set_checksum
238 sets the
239 .Li krb5_checksum
240 structure given
241 .Fa type
242 and
243 .Fa data .
244 The content of
245 .Fa cksum
246 should be freeed with
247 .Fn krb5_c_free_checksum_contents .
248 .Pp
249 .Fn krb5_c_get_checksum
250 retrieves the components of the
251 .Li krb5_checksum .
252 structure.
253 .Fa data
254 should be free with
255 .Fn krb5_free_data .
256 If some either of
257 .Fa data
258 or
259 .Fa checksum
260 is not needed for the application,
261 .Dv NULL
262 can be passed in.
263 .Pp
264 .Fn krb5_c_valid_enctype
265 returns true if
266 .Fa etype
267 is a valid encryption type.
268 .Pp
269 .Fn krb5_c_valid_cksumtype
270 returns true if
271 .Fa ctype
272 is a valid checksum type.
273 .Pp
274 .Fn krb5_c_is_keyed_cksum
275 return true if
276 .Fa ctype
277 is a keyed checksum type.
278 .Pp
279 .Fn krb5_c_is_coll_proof_cksum
280 returns true if
281 .Fa ctype
282 is a collition proof checksum type.
283 .Pp
284 .Fn krb5_c_keylengths
285 return the minimum length (
286 .Fa inlength )
287 bytes needed to create a key and the
288 length (
289 .Fa keylength )
290 of the resulting key
291 for the
292 .Fa enctype .
293 .Sh SEE ALSO
294 .Xr krb5 3 ,
295 .Xr krb5_create_checksum 3 ,
296 .Xr krb5_free_data 3 ,
297 .Xr kerberos 8