usr/src/man/man3ext/crypt.3ext

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH CRYPT 3EXT "Mar 3, 2008"
   8 .SH NAME
   9 crypt, setkey, encrypt, des_crypt, des_setkey, des_encrypt, run_setkey,
  10 run_crypt, crypt_close \- password and file encryption functions
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lcrypt\fR [ \fIlibrary\fR ... ]
  15 #include <crypt.h>
  16
  17 \fBchar *\fR\fBcrypt\fR(\fBconst char *\fR\fIkey\fR, \fBconst char *\fR\fIsalt\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBvoid\fR \fBsetkey\fR(\fBconst char *\fR\fIkey\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBvoid\fR \fBencrypt\fR(\fBchar *\fR\fIblock\fR, \fBint\fR \fIflag\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBchar *\fR\fBdes_crypt\fR(\fBconst char *\fR\fIkey\fR, \fBconst char *\fR\fIsalt\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBvoid\fR \fBdes_setkey\fR(\fBconst char *\fR\fIkey\fR);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBvoid\fR \fBdes_encrypt\fR(\fBchar *\fR\fIblock\fR, \fBint\fR \fIflag\fR);
  43 .fi
  44
  45 .LP
  46 .nf
  47 \fBint\fR \fBrun_setkey\fR(\fBint *\fR\fIp\fR, \fBconst char *\fR\fIkey\fR);
  48 .fi
  49
  50 .LP
  51 .nf
  52 \fBint\fR \fBrun_crypt\fR(\fBlong\fR \fIoffset\fR, \fBchar *\fR\fIbuffer\fR, \fBunsigned int\fR \fIcount\fR,
  53      \fBint *\fR\fIp\fR);
  54 .fi
  55
  56 .LP
  57 .nf
  58 \fBint\fR \fBcrypt_close\fR(\fBint *\fR\fIp\fR);
  59 .fi
  60
  61 .SH DESCRIPTION
  62 .sp
  63 .LP
  64 \fBdes_crypt()\fR is the password encryption function. It is based on a one-way
  65 hashing encryption algorithm with variations intended (among other things) to
  66 frustrate use of hardware implementations of a key search.
  67 .sp
  68 .LP
  69 \fIkey\fR is a user's typed password. \fIsalt\fR is a two-character string
  70 chosen from the set [\fBa-zA-Z0-9./\fR]; this string is used to perturb the
  71 hashing algorithm in one of 4096 different ways, after which the password is
  72 used as the key to encrypt repeatedly a constant string. The returned value
  73 points to the encrypted password. The first two characters are the salt itself.
  74 .sp
  75 .LP
  76 The \fBdes_setkey()\fR and \fBdes_encrypt()\fR entries provide (rather
  77 primitive) access to the actual hashing algorithm. The argument of
  78 \fBdes_setkey()\fR is a character array of length 64 containing only the
  79 characters with numerical value 0 and 1. If this string is divided into groups
  80 of 8, the low-order bit in each group is ignored, thereby creating a 56-bit key
  81 that is set into the machine. This key is the key that will be used with the
  82 hashing algorithm to encrypt the string \fIblock\fR with the function
  83 \fBdes_encrypt()\fR.
  84 .sp
  85 .LP
  86 The argument to the \fBdes_encrypt()\fR entry is a character array of length 64
  87 containing only the characters with numerical value 0 and 1. The argument array
  88 is modified in place to a similar array representing the bits of the argument
  89 after having been subjected to the hashing algorithm using the key set by
  90 \fBdes_setkey()\fR. If  \fIflag\fR is zero, the argument is encrypted; if
  91 non-zero, it is decrypted.
  92 .sp
  93 .LP
  94 Note that decryption is not provided in the international version of
  95 \fBcrypt()\fR. The international version is part of the C Development Set, and
  96 the domestic version is part of the Security Administration Utilities.  If
  97 decryption is attempted with the international version of \fBdes_encrypt()\fR,
  98 an error message is printed.
  99 .sp
 100 .LP
 101 \fBcrypt()\fR, \fBsetkey()\fR, and \fBencrypt()\fR are front-end routines that
 102 invoke \fBdes_crypt()\fR, \fBdes_setkey()\fR, and \fBdes_encrypt()\fR
 103 respectively.
 104 .sp
 105 .LP
 106 The routines \fBrun_setkey()\fR and \fBrun_crypt()\fR are designed for use by
 107 applications that need cryptographic capabilities, such as \fBed\fR(1) and
 108 \fBvi\fR(1). \fBrun_setkey()\fR establishes a two-way pipe connection with the
 109 \fBcrypt\fR utility, using \fIkey\fR as the password argument.
 110 \fBrun_crypt()\fR takes a block of characters and transforms the cleartext or
 111 ciphertext into their ciphertext or cleartext using the \fBcrypt\fR utility.
 112 \fIoffset\fR is the relative byte position from the beginning of the file that
 113 the block of text provided in \fIblock\fR is coming from. \fIcount\fR is the
 114 number of characters in \fIblock\fR, and \fIconnection\fR  is an array
 115 containing indices to a table of input and output file streams.   When
 116 encryption is finished, \fBcrypt_close()\fR is used to terminate the connection
 117 with the \fBcrypt\fR utility.
 118 .sp
 119 .LP
 120 \fBrun_setkey()\fR returns  \fB\(mi1\fR if a connection with the \fBcrypt\fR
 121 utility cannot be established. This result will occur in international versions
 122 of the UNIX system in which the \fBcrypt\fR utility is not available.  If a
 123 null key is passed to \fBrun_setkey()\fR, \fB0\fR is returned.  Otherwise,
 124 \fB1\fR is returned. \fBrun_crypt()\fR returns  \fB\(mi1\fR if it cannot write
 125 output or read input from the pipe attached to \fBcrypt()\fR. Otherwise it
 126 returns  \fB0\fR.
 127 .sp
 128 .LP
 129 The program must be linked with the object file access routine library
 130 \fBlibcrypt.a\fR.
 131 .SH RETURN VALUES
 132 .sp
 133 .LP
 134 In the international version of \fBcrypt()\fR, a flag argument of  \fB1\fR to
 135 \fBencrypt()\fR or \fBdes_encrypt()\fR is not accepted, and \fBerrno\fR is set
 136 to \fBENOSYS\fR to indicate that the functionality is not available.
 137 .SH ATTRIBUTES
 138 .sp
 139 .LP
 140 See \fBattributes\fR(5) for descriptions of the following attributes:
 141 .sp
 142
 143 .sp
 144 .TS
 145 box;
 146 c | c
 147 l | l .
 148 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 149 _
 150 MT-Level        Unsafe
 151 .TE
 152
 153 .SH SEE ALSO
 154 .sp
 155 .LP
 156 \fBed\fR(1), \fBlogin\fR(1), \fBpasswd\fR(1), \fBvi\fR(1), \fBgetpass\fR(3C),
 157 \fBpasswd\fR(4), \fBattributes\fR(5)
 158 .SH NOTES
 159 .sp
 160 .LP
 161 The return value in \fBcrypt()\fR points to static data that are overwritten by
 162 each call.