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