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