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$
  31 .\"
  32 .\" Manual page, using -mandoc macros
  33 .\"
  34 .Dd March 9, 1994
  35 .Dt CIPHER 3
  36 .Os
  37 .Sh NAME
  38 .Nm setkey ,
  39 .Nm encrypt ,
  40 .Nm des_setkey ,
  41 .Nm des_cipher
  42 .Nd DES encryption
  43 .Sh LIBRARY
  44 .Lb libcipher
  45 .Sh SYNOPSIS
  46 .Fd #include <unistd.h>
  47 .Ft int
  48 .Fn setkey "const char *key"
  49 .Ft int
  50 .Fn encrypt "char *block" "int flag"
  51 .Ft int
  52 .Fn des_setkey "const char *key"
  53 .Ft int
  54 .Fn des_cipher "const char *in" "char *out" "long salt" "int count"
  55 .Sh DESCRIPTION
  56 The functions,
  57 .Fn encrypt ,
  58 .Fn setkey ,
  59 .Fn des_setkey
  60 and
  61 .Fn des_cipher
  62 provide access to the
  63 .Tn DES
  64 algorithm.
  65 .Fn setkey
  66 is passed a 64-byte array of binary values (numeric 0 or 1).
  67 A 56-bit key is extracted from this array by dividing the
  68 array into groups of 8, and ignoring the last bit in each group.
  69 That bit is reserved for a byte parity check by DES, but is ignored
  70 by these functions.
  71 .Pp
  72 The
  73 .Fa block
  74 argument to
  75 .Fn encrypt
  76 is also a 64-byte array of binary values.
  77 If the value of
  78 .Fa flag
  79 is 0,
  80 .Fa block
  81 is encrypted otherwise it is decrypted.
  82 The result is returned in the original array
  83 .Fa block
  84 after using the key specified by
  85 .Fn setkey
  86 to process it.
  87 .Pp
  88 The argument to
  89 .Fn des_setkey
  90 is a character array of length 8.
  91 The least significant bit (the parity bit) in each character is ignored,
  92 and the remaining bits are concatenated to form a 56-bit key.
  93 The function
  94 .Fn des_cipher
  95 encrypts (or decrypts if
  96 .Fa count
  97 is negative) the 64-bits stored in the 8 characters at
  98 .Fa in
  99 using
 100 .Xr abs 3
 101 of
 102 .Fa count
 103 iterations of
 104 .Tn DES
 105 and stores the 64-bit result in the 8 characters at
 106 .Fa out
 107 (which may be the same as
 108 .Fa in
 109 ).
 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 NetBSD libcrypt encryption
 149 library.
 150 Users should be aware that this code (and programs staticly linked with it)
 151 may not be exported from the U.S., although it apparently can be imported.
 152 .Sh AUTHORS
 153 .An David Burren Aq davidb@werj.com.au