1.\" Copyright (c) 1999-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 12, 2005 35.Dt NAME 3 36.Os HEIMDAL 37.Sh NAME 38.Nm krb5_checksum , 39.Nm krb5_checksum_disable , 40.Nm krb5_checksum_is_collision_proof , 41.Nm krb5_checksum_is_keyed , 42.Nm krb5_checksumsize , 43.Nm krb5_cksumtype_valid , 44.Nm krb5_copy_checksum , 45.Nm krb5_create_checksum , 46.Nm krb5_crypto_get_checksum_type 47.Nm krb5_free_checksum , 48.Nm krb5_free_checksum_contents , 49.Nm krb5_hmac , 50.Nm krb5_verify_checksum 51.Nd creates, handles and verifies checksums 52.Sh LIBRARY 53Kerberos 5 Library (libkrb5, -lkrb5) 54.Sh SYNOPSIS 55.In krb5.h 56.Pp 57.Li "typedef Checksum krb5_checksum;" 58.Ft void 59.Fo krb5_checksum_disable 60.Fa "krb5_context context" 61.Fa "krb5_cksumtype type" 62.Fc 63.Ft krb5_boolean 64.Fo krb5_checksum_is_collision_proof 65.Fa "krb5_context context" 66.Fa "krb5_cksumtype type" 67.Fc 68.Ft krb5_boolean 69.Fo krb5_checksum_is_keyed 70.Fa "krb5_context context" 71.Fa "krb5_cksumtype type" 72.Fc 73.Ft krb5_error_code 74.Fo krb5_cksumtype_valid 75.Fa "krb5_context context" 76.Fa "krb5_cksumtype ctype" 77.Fc 78.Ft krb5_error_code 79.Fo krb5_checksumsize 80.Fa "krb5_context context" 81.Fa "krb5_cksumtype type" 82.Fa "size_t *size" 83.Fc 84.Ft krb5_error_code 85.Fo krb5_create_checksum 86.Fa "krb5_context context" 87.Fa "krb5_crypto crypto" 88.Fa "krb5_key_usage usage" 89.Fa "int type" 90.Fa "void *data" 91.Fa "size_t len" 92.Fa "Checksum *result" 93.Fc 94.Ft krb5_error_code 95.Fo krb5_verify_checksum 96.Fa "krb5_context context" 97.Fa "krb5_crypto crypto" 98.Fa "krb5_key_usage usage" 99.Fa "void *data" 100.Fa "size_t len" 101.Fa "Checksum *cksum" 102.Fc 103.Ft krb5_error_code 104.Fo krb5_crypto_get_checksum_type 105.Fa "krb5_context context" 106.Fa "krb5_crypto crypto" 107.Fa "krb5_cksumtype *type" 108.Fc 109.Ft void 110.Fo krb5_free_checksum 111.Fa "krb5_context context" 112.Fa "krb5_checksum *cksum" 113.Fc 114.Ft void 115.Fo krb5_free_checksum_contents 116.Fa "krb5_context context" 117.Fa "krb5_checksum *cksum" 118.Fc 119.Ft krb5_error_code 120.Fo krb5_hmac 121.Fa "krb5_context context" 122.Fa "krb5_cksumtype cktype" 123.Fa "const void *data" 124.Fa "size_t len" 125.Fa "unsigned usage" 126.Fa "krb5_keyblock *key" 127.Fa "Checksum *result" 128.Fc 129.Ft krb5_error_code 130.Fo krb5_copy_checksum 131.Fa "krb5_context context" 132.Fa "const krb5_checksum *old" 133.Fa "krb5_checksum **new" 134.Fc 135.Sh DESCRIPTION 136The 137.Li krb5_checksum 138structure holds a Kerberos checksum. 139There is no component inside 140.Li krb5_checksum 141that is directly referable. 142.Pp 143The functions are used to create and verify checksums. 144.Fn krb5_create_checksum 145creates a checksum of the specified data, and puts it in 146.Fa result . 147If 148.Fa crypto 149is 150.Dv NULL , 151.Fa usage_or_type 152specifies the checksum type to use; it must not be keyed. Otherwise 153.Fa crypto 154is an encryption context created by 155.Fn krb5_crypto_init , 156and 157.Fa usage_or_type 158specifies a key-usage. 159.Pp 160.Fn krb5_verify_checksum 161verifies the 162.Fa checksum 163against the provided data. 164.Pp 165.Fn krb5_checksum_is_collision_proof 166returns true is the specified checksum is collision proof (that it's 167very unlikely that two strings has the same hash value, and that it's 168hard to find two strings that has the same hash). Examples of 169collision proof checksums are MD5, and SHA1, while CRC32 is not. 170.Pp 171.Fn krb5_checksum_is_keyed 172returns true if the specified checksum type is keyed (that the hash 173value is a function of both the data, and a separate key). Examples of 174keyed hash algorithms are HMAC-SHA1-DES3, and RSA-MD5-DES. The 175.Dq plain 176hash functions MD5, and SHA1 are not keyed. 177.Pp 178.Fn krb5_crypto_get_checksum_type 179returns the checksum type that will be used when creating a checksum for the given 180.Fa crypto 181context. 182This function is useful in combination with 183.Fn krb5_checksumsize 184when you want to know the size a checksum will 185use when you create it. 186.Pp 187.Fn krb5_cksumtype_valid 188returns 0 or an error if the checksumtype is implemented and not 189currently disabled in this kerberos library. 190.Pp 191.Fn krb5_checksumsize 192returns the size of the outdata of checksum function. 193.Pp 194.Fn krb5_copy_checksum 195returns a copy of the checksum 196.Fn krb5_free_checksum 197should use used to free the 198.Fa new 199checksum. 200.Pp 201.Fn krb5_free_checksum 202free the checksum and the content of the checksum. 203.Pp 204.Fn krb5_free_checksum_contents 205frees the content of checksum in 206.Fa cksum . 207.Pp 208.Fn krb5_hmac 209calculates the HMAC over 210.Fa data 211(with length 212.Fa len ) 213using the keyusage 214.Fa usage 215and keyblock 216.Fa key . 217Note that keyusage is not always used in checksums. 218.Pp 219.Nm krb5_checksum_disable 220globally disables the checksum type. 221.\" .Sh EXAMPLE 222.\" .Sh BUGS 223.Sh SEE ALSO 224.Xr krb5_crypto_init 3 , 225.Xr krb5_c_encrypt 3 , 226.Xr krb5_encrypt 3 227