crypto/heimdal/lib/krb5/krb5_keyblock.3

   1 .\" Copyright (c) 2003 - 2004 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: krb5_keyblock.3 17385 2006-05-01 08:48:55Z lha $
  33 .\"
  34 .Dd May  1, 2006
  35 .Dt KRB5_KEYBLOCK 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_keyblock ,
  39 .Nm krb5_keyblock_get_enctype ,
  40 .Nm krb5_copy_keyblock ,
  41 .Nm krb5_copy_keyblock_contents ,
  42 .Nm krb5_free_keyblock ,
  43 .Nm krb5_free_keyblock_contents ,
  44 .Nm krb5_generate_random_keyblock ,
  45 .Nm krb5_generate_subkey ,
  46 .Nm krb5_generate_subkey_extended ,
  47 .Nm krb5_keyblock_init ,
  48 .Nm krb5_keyblock_zero ,
  49 .Nm krb5_random_to_key
  50 .Nd Kerberos 5 key handling functions
  51 .Sh LIBRARY
  52 Kerberos 5 Library (libkrb5, -lkrb5)
  53 .Sh SYNOPSIS
  54 .In krb5.h
  55 .Pp
  56 .Li krb5_keyblock ;
  57 .Ft krb5_enctype
  58 .Fo krb5_keyblock_get_enctype
  59 .Fa "const krb5_keyblock *block"
  60 .Fc
  61 .Ft krb5_error_code
  62 .Fo krb5_copy_keyblock
  63 .Fa "krb5_context context"
  64 .Fa "krb5_keyblock **to"
  65 .Fc
  66 .Ft krb5_error_code
  67 .Fo krb5_copy_keyblock_contents
  68 .Fa "krb5_context context"
  69 .Fa "const krb5_keyblock *inblock"
  70 .Fa "krb5_keyblock *to"
  71 .Fc
  72 .Ft void
  73 .Fo krb5_free_keyblock
  74 .Fa "krb5_context context"
  75 .Fa "krb5_keyblock *keyblock"
  76 .Fc
  77 .Ft void
  78 .Fo krb5_free_keyblock_contents
  79 .Fa "krb5_context context"
  80 .Fa "krb5_keyblock *keyblock"
  81 .Fc
  82 .Ft krb5_error_code
  83 .Fo krb5_generate_random_keyblock
  84 .Fa "krb5_context context"
  85 .Fa "krb5_enctype type"
  86 .Fa "krb5_keyblock *key"
  87 .Fc
  88 .Ft krb5_error_code
  89 .Fo krb5_generate_subkey
  90 .Fa "krb5_context context"
  91 .Fa "const krb5_keyblock *key"
  92 .Fa "krb5_keyblock **subkey"
  93 .Fc
  94 .Ft krb5_error_code
  95 .Fo krb5_generate_subkey_extended
  96 .Fa "krb5_context context"
  97 .Fa "const krb5_keyblock *key"
  98 .Fa "krb5_enctype enctype"
  99 .Fa "krb5_keyblock **subkey"
 100 .Fc
 101 .Ft krb5_error_code
 102 .Fo krb5_keyblock_init
 103 .Fa "krb5_context context"
 104 .Fa "krb5_enctype type"
 105 .Fa "const void *data"
 106 .Fa "size_t size"
 107 .Fa "krb5_keyblock *key"
 108 .Fc
 109 .Ft void
 110 .Fo krb5_keyblock_zero
 111 .Fa "krb5_keyblock *keyblock"
 112 .Fc
 113 .Ft krb5_error_code
 114 .Fo krb5_random_to_key
 115 .Fa "krb5_context context"
 116 .Fa "krb5_enctype type"
 117 .Fa "const void *data"
 118 .Fa "size_t size"
 119 .Fa "krb5_keyblock *key"
 120 .Fc
 121 .Sh DESCRIPTION
 122 .Li krb5_keyblock
 123 holds the encryption key for a specific encryption type.
 124 There is no component inside
 125 .Li krb5_keyblock
 126 that is directly referable.
 127 .Pp
 128 .Fn krb5_keyblock_get_enctype
 129 returns the encryption type of the keyblock.
 130 .Pp
 131 .Fn krb5_copy_keyblock
 132 makes a copy the keyblock
 133 .Fa inblock
 134 to the
 135 output
 136 .Fa out .
 137 .Fa out
 138 should be freed by the caller with
 139 .Fa krb5_free_keyblock .
 140 .Pp
 141 .Fn krb5_copy_keyblock_contents
 142 copies the contents of
 143 .Fa inblock
 144 to the
 145 .Fa to
 146 keyblock.
 147 The destination keyblock is overritten.
 148 .Pp
 149 .Fn krb5_free_keyblock
 150 zeros out and frees the content and the keyblock itself.
 151 .Pp
 152 .Fn krb5_free_keyblock_contents
 153 zeros out and frees the content of the keyblock.
 154 .Pp
 155 .Fn krb5_generate_random_keyblock
 156 creates a new content of the keyblock
 157 .Fa key
 158 of type encrytion type
 159 .Fa type .
 160 The content of
 161 .Fa key
 162 is overwritten and not freed, so the caller should be sure it is
 163 freed before calling the function.
 164 .Pp
 165 .Fn krb5_generate_subkey
 166 generates a
 167 .Fa subkey
 168 of the same type as
 169 .Fa key .
 170 The caller must free the subkey with
 171 .Fa krb5_free_keyblock .
 172 .Pp
 173 .Fn krb5_generate_subkey_extended
 174 generates a
 175 .Fa subkey
 176 of the specified encryption type
 177 .Fa type .
 178 If
 179 .Fa type
 180 is
 181 .Dv ETYPE_NULL ,
 182 of the same type as
 183 .Fa key .
 184 The caller must free the subkey with
 185 .Fa krb5_free_keyblock .
 186 .Pp
 187 .Fn krb5_keyblock_init
 188 Fill in
 189 .Fa key
 190 with key data of type
 191 .Fa enctype
 192 from
 193 .Fa data
 194 of length
 195 .Fa size .
 196 Key should be freed using
 197 .Fn krb5_free_keyblock_contents .
 198 .Pp
 199 .Fn krb5_keyblock_zero
 200 zeros out the keyblock to to make sure no keymaterial is in
 201 memory.
 202 Note that
 203 .Fn krb5_free_keyblock_contents
 204 also zeros out the memory.
 205 .Pp
 206 .Fn krb5_random_to_key
 207 converts the random bytestring to a protocol key according to Kerberos
 208 crypto frame work.
 209 It the resulting key will be of type
 210 .Fa enctype .
 211 It may be assumed that all the bits of the input string are equally
 212 random, even though the entropy present in the random source may be
 213 limited
 214 .\" .Sh EXAMPLES
 215 .Sh SEE ALSO
 216 .Xr krb5_crypto_init 3 ,
 217 .Xr krb5 3 ,
 218 .Xr krb5.conf 5