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