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