crypto/heimdal/lib/krb5/krb5_c_make_checksum.3

   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 collision 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