secure/lib/libcipher/cipher.3

   1 .\" FreeSec: libcrypt for NetBSD
   2 .\"
   3 .\" Copyright (c) 1994 David Burren
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 4. Neither the name of the author nor the names of other contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD: src/secure/lib/libcipher/cipher.3,v 1.6.2.3 2001/12/14 15:21:13 ru Exp $
  31 .\" $DragonFly: src/secure/lib/libcipher/cipher.3,v 1.2 2003/06/17 04:27:48 dillon Exp $
  32 .\"
  33 .\" Manual page, using -mandoc macros
  34 .\"
  35 .Dd March 9, 1994
  36 .Dt CIPHER 3
  37 .Os
  38 .Sh NAME
  39 .Nm setkey ,
  40 .Nm encrypt ,
  41 .Nm des_setkey ,
  42 .Nm des_cipher
  43 .Nd DES encryption
  44 .Sh LIBRARY
  45 .Lb libcipher
  46 .Sh SYNOPSIS
  47 .In unistd.h
  48 .Ft int
  49 .Fn setkey "const char *key"
  50 .Ft int
  51 .Fn encrypt "char *block" "int flag"
  52 .Ft int
  53 .Fn des_setkey "const char *key"
  54 .Ft int
  55 .Fn des_cipher "const char *in" "char *out" "long salt" "int count"
  56 .Sh DESCRIPTION
  57 The functions,
  58 .Fn encrypt ,
  59 .Fn setkey ,
  60 .Fn des_setkey
  61 and
  62 .Fn des_cipher
  63 provide access to the
  64 .Tn DES
  65 algorithm.
  66 .Fn setkey
  67 is passed a 64-byte array of binary values (numeric 0 or 1).
  68 A 56-bit key is extracted from this array by dividing the
  69 array into groups of 8, and ignoring the last bit in each group.
  70 That bit is reserved for a byte parity check by DES, but is ignored
  71 by these functions.
  72 .Pp
  73 The
  74 .Fa block
  75 argument to
  76 .Fn encrypt
  77 is also a 64-byte array of binary values.
  78 If the value of
  79 .Fa flag
  80 is 0,
  81 .Fa block
  82 is encrypted otherwise it is decrypted.
  83 The result is returned in the original array
  84 .Fa block
  85 after using the key specified by
  86 .Fn setkey
  87 to process it.
  88 .Pp
  89 The argument to
  90 .Fn des_setkey
  91 is a character array of length 8.
  92 The least significant bit (the parity bit) in each character is ignored,
  93 and the remaining bits are concatenated to form a 56-bit key.
  94 The function
  95 .Fn des_cipher
  96 encrypts (or decrypts if
  97 .Fa count
  98 is negative) the 64-bits stored in the 8 characters at
  99 .Fa in
 100 using
 101 .Xr abs 3
 102 of
 103 .Fa count
 104 iterations of
 105 .Tn DES
 106 and stores the 64-bit result in the 8 characters at
 107 .Fa out
 108 (which may be the same as
 109 .Fa in ) .
 110 The
 111 .Fa salt
 112 introduces disorder in the
 113 .Tn DES
 114 algorithm in one of 16777216 or 4096 possible ways
 115 (ie. with 24 or 12 bits: if bit
 116 .Em i
 117 of the
 118 .Ar salt
 119 is set, then bits
 120 .Em i
 121 and
 122 .Em i+24
 123 are swapped in the
 124 .Tn DES
 125 E-box output).
 126 .Pp
 127 The functions
 128 .Fn setkey ,
 129 .Fn encrypt ,
 130 .Fn des_setkey ,
 131 and
 132 .Fn des_cipher
 133 return 0 on success and 1 on failure.
 134 .Pp
 135 The
 136 .Fn setkey
 137 and
 138 .Fn des_setkey
 139 functions manipulate the same key space.
 140 .Sh SEE ALSO
 141 .Xr login 1 ,
 142 .Xr passwd 1 ,
 143 .Xr crypt 3 ,
 144 .Xr getpass 3 ,
 145 .Xr passwd 5
 146 .Sh HISTORY
 147 This library (FreeSec 1.0) was developed outside the United States of America
 148 as an unencumbered replacement for the U.S.-only
 149 .Nx
 150 libcrypt encryption
 151 library.
 152 Users should be aware that this code (and programs staticly linked with it)
 153 may not be exported from the U.S., although it apparently can be imported.
 154 .Sh AUTHORS
 155 .An David Burren Aq davidb@werj.com.au