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