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 .\"
  32 .Dd March 9, 1994
  33 .Dt CIPHER 3
  34 .Os
  35 .Sh NAME
  36 .Nm setkey ,
  37 .Nm encrypt ,
  38 .Nm des_setkey ,
  39 .Nm des_cipher
  40 .Nd DES encryption
  41 .Sh LIBRARY
  42 .Lb libcipher
  43 .Sh SYNOPSIS
  44 .In unistd.h
  45 .Ft int
  46 .Fn setkey "const char *key"
  47 .Ft int
  48 .Fn encrypt "char *block" "int flag"
  49 .Ft int
  50 .Fn des_setkey "const char *key"
  51 .Ft int
  52 .Fn des_cipher "const char *in" "char *out" "long salt" "int count"
  53 .Sh DESCRIPTION
  54 The functions,
  55 .Fn encrypt ,
  56 .Fn setkey ,
  57 .Fn des_setkey
  58 and
  59 .Fn des_cipher
  60 provide access to the
  61 .Tn DES
  62 algorithm.
  63 .Fn setkey
  64 is passed a 64-byte array of binary values (numeric 0 or 1).
  65 A 56-bit key is extracted from this array by dividing the
  66 array into groups of 8, and ignoring the last bit in each group.
  67 That bit is reserved for a byte parity check by DES, but is ignored
  68 by these functions.
  69 .Pp
  70 The
  71 .Fa block
  72 argument to
  73 .Fn encrypt
  74 is also a 64-byte array of binary values.
  75 If the value of
  76 .Fa flag
  77 is 0,
  78 .Fa block
  79 is encrypted otherwise it is decrypted.
  80 The result is returned in the original array
  81 .Fa block
  82 after using the key specified by
  83 .Fn setkey
  84 to process it.
  85 .Pp
  86 The argument to
  87 .Fn des_setkey
  88 is a character array of length 8.
  89 The least significant bit (the parity bit) in each character is ignored,
  90 and the remaining bits are concatenated to form a 56-bit key.
  91 The function
  92 .Fn des_cipher
  93 encrypts (or decrypts if
  94 .Fa count
  95 is negative) the 64-bits stored in the 8 characters at
  96 .Fa in
  97 using
  98 .Xr abs 3
  99 of
 100 .Fa count
 101 iterations of
 102 .Tn DES
 103 and stores the 64-bit result in the 8 characters at
 104 .Fa out
 105 (which may be the same as
 106 .Fa in ) .
 107 The
 108 .Fa salt
 109 introduces disorder in the
 110 .Tn DES
 111 algorithm in one of 16777216 or 4096 possible ways
 112 (ie. with 24 or 12 bits: if bit
 113 .Em i
 114 of the
 115 .Ar salt
 116 is set, then bits
 117 .Em i
 118 and
 119 .Em i+24
 120 are swapped in the
 121 .Tn DES
 122 E-box output).
 123 .Pp
 124 The functions
 125 .Fn setkey ,
 126 .Fn encrypt ,
 127 .Fn des_setkey ,
 128 and
 129 .Fn des_cipher
 130 return 0 on success and 1 on failure.
 131 .Pp
 132 The
 133 .Fn setkey
 134 and
 135 .Fn des_setkey
 136 functions manipulate the same key space.
 137 .Sh SEE ALSO
 138 .Xr login 1 ,
 139 .Xr passwd 1 ,
 140 .Xr crypt 3 ,
 141 .Xr getpass 3 ,
 142 .Xr passwd 5
 143 .Sh HISTORY
 144 This library (FreeSec 1.0) was developed outside the United States of America
 145 as an unencumbered replacement for the U.S.-only
 146 .Nx
 147 libcrypt encryption
 148 library.
 149 Users should be aware that this code (and programs statically linked with it)
 150 may not be exported from the U.S., although it apparently can be imported.
 151 .Sh AUTHORS
 152 .An David Burren Aq Mt davidb@werj.com.au