crypto/heimdal/lib/krb5/krb5_string_to_key.3

   1 .\" Copyright (c) 2004 - 2006 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_string_to_key.3 17820 2006-07-10 14:28:01Z lha $
  33 .\"
  34 .Dd July 10, 2006
  35 .Dt KRB5_STRING_TO_KEY 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_string_to_key ,
  39 .Nm krb5_string_to_key_data ,
  40 .Nm krb5_string_to_key_data_salt ,
  41 .Nm krb5_string_to_key_data_salt_opaque ,
  42 .Nm krb5_string_to_key_salt ,
  43 .Nm krb5_string_to_key_salt_opaque ,
  44 .Nm krb5_get_pw_salt ,
  45 .Nm krb5_free_salt
  46 .Nd turns a string to a Kerberos key
  47 .Sh LIBRARY
  48 Kerberos 5 Library (libkrb5, -lkrb5)
  49 .Sh SYNOPSIS
  50 .In krb5.h
  51 .Ft krb5_error_code
  52 .Fo krb5_string_to_key
  53 .Fa "krb5_context context"
  54 .Fa "krb5_enctype enctype"
  55 .Fa "const char *password"
  56 .Fa "krb5_principal principal"
  57 .Fa "krb5_keyblock *key"
  58 .Fc
  59 .Ft krb5_error_code
  60 .Fo krb5_string_to_key_data
  61 .Fa "krb5_context context"
  62 .Fa "krb5_enctype enctype"
  63 .Fa "krb5_data password"
  64 .Fa "krb5_principal principal"
  65 .Fa "krb5_keyblock *key"
  66 .Fc
  67 .Ft krb5_error_code
  68 .Fo krb5_string_to_key_data_salt
  69 .Fa "krb5_context context"
  70 .Fa "krb5_enctype enctype"
  71 .Fa "krb5_data password"
  72 .Fa "krb5_salt salt"
  73 .Fa "krb5_keyblock *key"
  74 .Fc
  75 .Ft krb5_error_code
  76 .Fo krb5_string_to_key_data_salt_opaque
  77 .Fa "krb5_context context"
  78 .Fa "krb5_enctype enctype"
  79 .Fa "krb5_data password"
  80 .Fa "krb5_salt salt"
  81 .Fa "krb5_data opaque"
  82 .Fa "krb5_keyblock *key"
  83 .Fc
  84 .Ft krb5_error_code
  85 .Fo krb5_string_to_key_salt
  86 .Fa "krb5_context context"
  87 .Fa "krb5_enctype enctype"
  88 .Fa "const char *password"
  89 .Fa "krb5_salt salt"
  90 .Fa "krb5_keyblock *key"
  91 .Fc
  92 .Ft krb5_error_code
  93 .Fo krb5_string_to_key_salt_opaque
  94 .Fa "krb5_context context"
  95 .Fa "krb5_enctype enctype"
  96 .Fa "const char *password"
  97 .Fa "krb5_salt salt"
  98 .Fa "krb5_data opaque"
  99 .Fa "krb5_keyblock *key"
 100 .Fc
 101 .Ft krb5_error_code
 102 .Fo krb5_get_pw_salt
 103 .Fa "krb5_context context"
 104 .Fa "krb5_const_principal principal"
 105 .Fa "krb5_salt *salt"
 106 .Fc
 107 .Ft krb5_error_code
 108 .Fo krb5_free_salt
 109 .Fa "krb5_context context"
 110 .Fa "krb5_salt salt"
 111 .Fc
 112 .Sh DESCRIPTION
 113 The string to key functions convert a string to a kerberos key.
 114 .Pp
 115 .Fn krb5_string_to_key_data_salt_opaque
 116 is the function that does all the work, the rest of the functions are
 117 just wrapers around
 118 .Fn krb5_string_to_key_data_salt_opaque
 119 that calls it with default values.
 120 .Pp
 121 .Fn krb5_string_to_key_data_salt_opaque
 122 transforms the
 123 .Fa password
 124 with the given salt-string
 125 .Fa salt
 126 and the opaque, encryption type specific parameter
 127 .Fa opaque
 128 to a encryption key
 129 .Fa key
 130 according to the string to key function associated with
 131 .Fa enctype .
 132 .Pp
 133 The
 134 .Fa key
 135 should be freed with
 136 .Fn krb5_free_keyblock_contents .
 137 .Pp
 138 If one of the functions that doesn't take a
 139 .Li krb5_salt
 140 as it argument
 141 .Fn krb5_get_pw_salt
 142 is used to get the salt value.
 143 .Pp
 144 .Fn krb5_get_pw_salt
 145 get the default password salt for a principal, use
 146 .Fn krb5_free_salt
 147 to free the salt when done.
 148 .Pp
 149 .Fn krb5_free_salt
 150 frees the content of
 151 .Fa salt .
 152 .Sh SEE ALSO
 153 .Xr krb5 3 ,
 154 .Xr krb5_data 3 ,
 155 .Xr krb5_keyblock 3 ,
 156 .Xr kerberos 8