1*d3273b5bSchristos.\" $NetBSD: krb5_encrypt.3,v 1.2 2017/01/28 21:31:49 christos Exp $ 2ca1c9b0cSelric.\" 3ca1c9b0cSelric.\" Copyright (c) 1999 - 2004 Kungliga Tekniska Högskolan 4ca1c9b0cSelric.\" (Royal Institute of Technology, Stockholm, Sweden). 5ca1c9b0cSelric.\" All rights reserved. 6ca1c9b0cSelric.\" 7ca1c9b0cSelric.\" Redistribution and use in source and binary forms, with or without 8ca1c9b0cSelric.\" modification, are permitted provided that the following conditions 9ca1c9b0cSelric.\" are met: 10ca1c9b0cSelric.\" 11ca1c9b0cSelric.\" 1. Redistributions of source code must retain the above copyright 12ca1c9b0cSelric.\" notice, this list of conditions and the following disclaimer. 13ca1c9b0cSelric.\" 14ca1c9b0cSelric.\" 2. Redistributions in binary form must reproduce the above copyright 15ca1c9b0cSelric.\" notice, this list of conditions and the following disclaimer in the 16ca1c9b0cSelric.\" documentation and/or other materials provided with the distribution. 17ca1c9b0cSelric.\" 18ca1c9b0cSelric.\" 3. Neither the name of the Institute nor the names of its contributors 19ca1c9b0cSelric.\" may be used to endorse or promote products derived from this software 20ca1c9b0cSelric.\" without specific prior written permission. 21ca1c9b0cSelric.\" 22ca1c9b0cSelric.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 23ca1c9b0cSelric.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24ca1c9b0cSelric.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25ca1c9b0cSelric.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 26ca1c9b0cSelric.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27ca1c9b0cSelric.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28ca1c9b0cSelric.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29ca1c9b0cSelric.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30ca1c9b0cSelric.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31ca1c9b0cSelric.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32ca1c9b0cSelric.\" SUCH DAMAGE. 33ca1c9b0cSelric.\" 34b40995a4Selric.\" Id 35ca1c9b0cSelric.\" 36ca1c9b0cSelric.Dd March 20, 2004 37ca1c9b0cSelric.Dt KRB5_ENCRYPT 3 38ca1c9b0cSelric.Os 39ca1c9b0cSelric.Sh NAME 40ca1c9b0cSelric.Nm krb5_crypto_getblocksize , 41ca1c9b0cSelric.Nm krb5_crypto_getconfoundersize 42ca1c9b0cSelric.Nm krb5_crypto_getenctype , 43ca1c9b0cSelric.Nm krb5_crypto_getpadsize , 44ca1c9b0cSelric.Nm krb5_crypto_overhead , 45ca1c9b0cSelric.Nm krb5_decrypt , 46ca1c9b0cSelric.Nm krb5_decrypt_EncryptedData , 47ca1c9b0cSelric.Nm krb5_decrypt_ivec , 48ca1c9b0cSelric.Nm krb5_decrypt_ticket , 49ca1c9b0cSelric.Nm krb5_encrypt , 50ca1c9b0cSelric.Nm krb5_encrypt_EncryptedData , 51ca1c9b0cSelric.Nm krb5_encrypt_ivec , 52ca1c9b0cSelric.Nm krb5_enctype_disable , 53ca1c9b0cSelric.Nm krb5_enctype_keysize , 54ca1c9b0cSelric.Nm krb5_enctype_to_string , 55ca1c9b0cSelric.Nm krb5_enctype_valid , 56ca1c9b0cSelric.Nm krb5_get_wrapped_length , 57ca1c9b0cSelric.Nm krb5_string_to_enctype 58ca1c9b0cSelric.Nd "encrypt and decrypt data, set and get encryption type parameters" 59ca1c9b0cSelric.Sh LIBRARY 60ca1c9b0cSelricKerberos 5 Library (libkrb5, -lkrb5) 61ca1c9b0cSelric.Sh SYNOPSIS 62ca1c9b0cSelric.In krb5/krb5.h 63ca1c9b0cSelric.Ft krb5_error_code 64ca1c9b0cSelric.Fo krb5_encrypt 65ca1c9b0cSelric.Fa "krb5_context context" 66ca1c9b0cSelric.Fa "krb5_crypto crypto" 67ca1c9b0cSelric.Fa "unsigned usage" 68ca1c9b0cSelric.Fa "void *data" 69ca1c9b0cSelric.Fa "size_t len" 70ca1c9b0cSelric.Fa "krb5_data *result" 71ca1c9b0cSelric.Fc 72ca1c9b0cSelric.Ft krb5_error_code 73ca1c9b0cSelric.Fo krb5_encrypt_EncryptedData 74ca1c9b0cSelric.Fa "krb5_context context" 75ca1c9b0cSelric.Fa "krb5_crypto crypto" 76ca1c9b0cSelric.Fa "unsigned usage" 77ca1c9b0cSelric.Fa "void *data" 78ca1c9b0cSelric.Fa "size_t len" 79ca1c9b0cSelric.Fa "int kvno" 80ca1c9b0cSelric.Fa "EncryptedData *result" 81ca1c9b0cSelric.Fc 82ca1c9b0cSelric.Ft krb5_error_code 83ca1c9b0cSelric.Fo krb5_encrypt_ivec 84ca1c9b0cSelric.Fa "krb5_context context" 85ca1c9b0cSelric.Fa "krb5_crypto crypto" 86ca1c9b0cSelric.Fa "unsigned usage" 87ca1c9b0cSelric.Fa "void *data" 88ca1c9b0cSelric.Fa "size_t len" 89ca1c9b0cSelric.Fa "krb5_data *result" 90ca1c9b0cSelric.Fa "void *ivec" 91ca1c9b0cSelric.Fc 92ca1c9b0cSelric.Ft krb5_error_code 93ca1c9b0cSelric.Fo krb5_decrypt 94ca1c9b0cSelric.Fa "krb5_context context" 95ca1c9b0cSelric.Fa "krb5_crypto crypto" 96ca1c9b0cSelric.Fa "unsigned usage" 97ca1c9b0cSelric.Fa "void *data" 98ca1c9b0cSelric.Fa "size_t len" 99ca1c9b0cSelric.Fa "krb5_data *result" 100ca1c9b0cSelric.Fc 101ca1c9b0cSelric.Ft krb5_error_code 102ca1c9b0cSelric.Fo krb5_decrypt_EncryptedData 103ca1c9b0cSelric.Fa "krb5_context context" 104ca1c9b0cSelric.Fa "krb5_crypto crypto" 105ca1c9b0cSelric.Fa "unsigned usage" 106ca1c9b0cSelric.Fa "EncryptedData *e" 107ca1c9b0cSelric.Fa "krb5_data *result" 108ca1c9b0cSelric.Fc 109ca1c9b0cSelric.Ft krb5_error_code 110ca1c9b0cSelric.Fo krb5_decrypt_ivec 111ca1c9b0cSelric.Fa "krb5_context context" 112ca1c9b0cSelric.Fa "krb5_crypto crypto" 113ca1c9b0cSelric.Fa "unsigned usage" 114ca1c9b0cSelric.Fa "void *data" 115ca1c9b0cSelric.Fa "size_t len" 116ca1c9b0cSelric.Fa "krb5_data *result" 117ca1c9b0cSelric.Fa "void *ivec" 118ca1c9b0cSelric.Fc 119ca1c9b0cSelric.Ft krb5_error_code 120ca1c9b0cSelric.Fo krb5_decrypt_ticket 121ca1c9b0cSelric.Fa "krb5_context context" 122ca1c9b0cSelric.Fa "Ticket *ticket" 123ca1c9b0cSelric.Fa "krb5_keyblock *key" 124ca1c9b0cSelric.Fa "EncTicketPart *out" 125ca1c9b0cSelric.Fa "krb5_flags flags" 126ca1c9b0cSelric.Fc 127ca1c9b0cSelric.Ft krb5_error_code 128ca1c9b0cSelric.Fo krb5_crypto_getblocksize 129ca1c9b0cSelric.Fa "krb5_context context" 130ca1c9b0cSelric.Fa "size_t *blocksize" 131ca1c9b0cSelric.Fc 132ca1c9b0cSelric.Ft krb5_error_code 133ca1c9b0cSelric.Fo krb5_crypto_getenctype 134ca1c9b0cSelric.Fa "krb5_context context" 135ca1c9b0cSelric.Fa "krb5_crypto crypto" 136ca1c9b0cSelric.Fa "krb5_enctype *enctype" 137ca1c9b0cSelric.Fc 138ca1c9b0cSelric.Ft krb5_error_code 139ca1c9b0cSelric.Fo krb5_crypto_getpadsize 140ca1c9b0cSelric.Fa "krb5_context context" 141ca1c9b0cSelric.Fa size_t *padsize" 142ca1c9b0cSelric.Fc 143ca1c9b0cSelric.Ft krb5_error_code 144ca1c9b0cSelric.Fo krb5_crypto_getconfoundersize 145ca1c9b0cSelric.Fa "krb5_context context" 146ca1c9b0cSelric.Fa "krb5_crypto crypto" 147ca1c9b0cSelric.Fa size_t *confoundersize" 148ca1c9b0cSelric.Fc 149ca1c9b0cSelric.Ft krb5_error_code 150ca1c9b0cSelric.Fo krb5_enctype_keysize 151ca1c9b0cSelric.Fa "krb5_context context" 152ca1c9b0cSelric.Fa "krb5_enctype type" 153ca1c9b0cSelric.Fa "size_t *keysize" 154ca1c9b0cSelric.Fc 155ca1c9b0cSelric.Ft krb5_error_code 156ca1c9b0cSelric.Fo krb5_crypto_overhead 157ca1c9b0cSelric.Fa "krb5_context context" 158ca1c9b0cSelric.Fa size_t *padsize" 159ca1c9b0cSelric.Fc 160ca1c9b0cSelric.Ft krb5_error_code 161ca1c9b0cSelric.Fo krb5_string_to_enctype 162ca1c9b0cSelric.Fa "krb5_context context" 163ca1c9b0cSelric.Fa "const char *string" 164ca1c9b0cSelric.Fa "krb5_enctype *etype" 165ca1c9b0cSelric.Fc 166ca1c9b0cSelric.Ft krb5_error_code 167ca1c9b0cSelric.Fo krb5_enctype_to_string 168ca1c9b0cSelric.Fa "krb5_context context" 169ca1c9b0cSelric.Fa "krb5_enctype etype" 170ca1c9b0cSelric.Fa "char **string" 171ca1c9b0cSelric.Fc 172ca1c9b0cSelric.Ft krb5_error_code 173ca1c9b0cSelric.Fo krb5_enctype_valid 174ca1c9b0cSelric.Fa "krb5_context context" 175ca1c9b0cSelric.Fa "krb5_enctype etype" 176ca1c9b0cSelric.Fc 177ca1c9b0cSelric.Ft void 178ca1c9b0cSelric.Fo krb5_enctype_disable 179ca1c9b0cSelric.Fa "krb5_context context" 180ca1c9b0cSelric.Fa "krb5_enctype etype" 181ca1c9b0cSelric.Fc 182ca1c9b0cSelric.Ft size_t 183ca1c9b0cSelric.Fo krb5_get_wrapped_length 184ca1c9b0cSelric.Fa "krb5_context context" 185ca1c9b0cSelric.Fa "krb5_crypto crypto" 186ca1c9b0cSelric.Fa "size_t data_len" 187ca1c9b0cSelric.Fc 188ca1c9b0cSelric.Sh DESCRIPTION 189ca1c9b0cSelricThese functions are used to encrypt and decrypt data. 190ca1c9b0cSelric.Pp 191ca1c9b0cSelric.Fn krb5_encrypt_ivec 192ca1c9b0cSelricputs the encrypted version of 193ca1c9b0cSelric.Fa data 194ca1c9b0cSelric(of size 195ca1c9b0cSelric.Fa len ) 196ca1c9b0cSelricin 197ca1c9b0cSelric.Fa result . 198ca1c9b0cSelricIf the encryption type supports using derived keys, 199ca1c9b0cSelric.Fa usage 200ca1c9b0cSelricshould be the appropriate key-usage. 201ca1c9b0cSelric.Fa ivec 202ca1c9b0cSelricis a pointer to a initial IV, it is modified to the end IV at the end of 203ca1c9b0cSelricthe round. 204ca1c9b0cSelricIvec should be the size of 205ca1c9b0cSelricIf 206ca1c9b0cSelric.Dv NULL 207ca1c9b0cSelricis passed in, the default IV is used. 208ca1c9b0cSelric.Fn krb5_encrypt 209ca1c9b0cSelricdoes the same as 210ca1c9b0cSelric.Fn krb5_encrypt_ivec 211ca1c9b0cSelricbut with 212ca1c9b0cSelric.Fa ivec 213ca1c9b0cSelricbeing 214ca1c9b0cSelric.Dv NULL . 215ca1c9b0cSelric.Fn krb5_encrypt_EncryptedData 216ca1c9b0cSelricdoes the same as 217ca1c9b0cSelric.Fn krb5_encrypt , 218ca1c9b0cSelricbut it puts the encrypted data in a 219ca1c9b0cSelric.Fa EncryptedData 220ca1c9b0cSelricstructure instead. If 221ca1c9b0cSelric.Fa kvno 222ca1c9b0cSelricis not zero, it will be put in the (optional) 223ca1c9b0cSelric.Fa kvno 224ca1c9b0cSelricfield in the 225ca1c9b0cSelric.Fa EncryptedData . 226ca1c9b0cSelric.Pp 227ca1c9b0cSelric.Fn krb5_decrypt_ivec , 228ca1c9b0cSelric.Fn krb5_decrypt , 229ca1c9b0cSelricand 230ca1c9b0cSelric.Fn krb5_decrypt_EncryptedData 231ca1c9b0cSelricworks similarly. 232ca1c9b0cSelric.Pp 233ca1c9b0cSelric.Fn krb5_decrypt_ticket 234ca1c9b0cSelricdecrypts the encrypted part of 235ca1c9b0cSelric.Fa ticket 236ca1c9b0cSelricwith 237ca1c9b0cSelric.Fa key . 238ca1c9b0cSelric.Fn krb5_decrypt_ticket 239ca1c9b0cSelricalso verifies the timestamp in the ticket, invalid flag and if the KDC 240ca1c9b0cSelrichaven't verified the transited path, the transit path. 241ca1c9b0cSelric.Pp 242ca1c9b0cSelric.Fn krb5_enctype_keysize , 243ca1c9b0cSelric.Fn krb5_crypto_getconfoundersize , 244ca1c9b0cSelric.Fn krb5_crypto_getblocksize , 245ca1c9b0cSelric.Fn krb5_crypto_getenctype , 246ca1c9b0cSelric.Fn krb5_crypto_getpadsize , 247ca1c9b0cSelric.Fn krb5_crypto_overhead 248ca1c9b0cSelricall returns various (sometimes) useful information from a crypto context. 249ca1c9b0cSelric.Fn krb5_crypto_overhead 250ca1c9b0cSelricis the combination of krb5_crypto_getconfoundersize, 251ca1c9b0cSelrickrb5_crypto_getblocksize and krb5_crypto_getpadsize and return the 252ca1c9b0cSelricmaximum overhead size. 253ca1c9b0cSelric.Pp 254ca1c9b0cSelric.Fn krb5_enctype_to_string 255ca1c9b0cSelricconverts a encryption type number to a string that can be printable 256ca1c9b0cSelricand stored. The strings returned should be freed with 257ca1c9b0cSelric.Xr free 3 . 258ca1c9b0cSelric.Pp 259ca1c9b0cSelric.Fn krb5_string_to_enctype 260ca1c9b0cSelricconverts a encryption type strings to a encryption type number that 261ca1c9b0cSelriccan use used for other Kerberos crypto functions. 262ca1c9b0cSelric.Pp 263ca1c9b0cSelric.Fn krb5_enctype_valid 264ca1c9b0cSelricreturns 0 if the encrypt is supported and not disabled, otherwise and 265ca1c9b0cSelricerror code is returned. 266ca1c9b0cSelric.Pp 267ca1c9b0cSelric.Fn krb5_enctype_disable 268ca1c9b0cSelric(globally, for all contextes) disables the 269ca1c9b0cSelric.Fa enctype . 270ca1c9b0cSelric.Pp 271ca1c9b0cSelric.Fn krb5_get_wrapped_length 272ca1c9b0cSelricreturns the size of an encrypted packet by 273ca1c9b0cSelric.Fa crypto 274ca1c9b0cSelricof length 275ca1c9b0cSelric.Fa data_len . 276ca1c9b0cSelric.\" .Sh EXAMPLE 277ca1c9b0cSelric.\" .Sh BUGS 278ca1c9b0cSelric.Sh SEE ALSO 279ca1c9b0cSelric.Xr krb5_create_checksum 3 , 280ca1c9b0cSelric.Xr krb5_crypto_init 3 281