sys/man/3/ssl

   1 .TH SSL 3
   2 .SH NAME
   3 ssl \- SSL record layer
   4 .SH SYNOPSIS
   5 .nf
   6 .B bind -a #D /net
   7
   8 .B /net/ssl/clone
   9 .BI /net/ssl/ n
  10 .BI /net/ssl/ n /ctl
  11 .BI /net/ssl/ n /data
  12 .BI /net/ssl/ n /encalgs
  13 .BI /net/ssl/ n /hashalgs
  14 .BI /net/ssl/ n /secretin
  15 .BI /net/ssl/ n /secretout
  16 .fi
  17 .SH DESCRIPTION
  18 The SSL device provides the interface to the Secure Socket Layer
  19 device implementing the record layer protocol of SSLv2
  20 (but not the handshake protocol, which is responsible for
  21 mutual authentication and key exchange.)
  22 The
  23 .I ssl
  24 device can be thought of as a filter providing optional encryption
  25 and anti-tampering.
  26 .PP
  27 The top level directory contains a
  28 .B clone
  29 file and subdirectories numbered from zero to the number of connections
  30 configured.
  31 Opening the
  32 .B clone
  33 file reserves a connection.  The file descriptor returned from the
  34 .IR open (2)
  35 will point to the control file,
  36 .BR ctl ,
  37 of the newly allocated connection.  Reading the
  38 .B ctl
  39 file returns a text
  40 string representing the number of the
  41 connection.
  42 .PP
  43 A connection is controlled by writing text strings to the associated
  44 .B ctl
  45 file.  After a connection has been established data may be read from
  46 and written to the data file.
  47 .PP
  48 The SSL protocol provides a stream connection that preserves
  49 .BR read / write
  50 boundaries.  As long as reads always specify buffers that are
  51 of equal or greater lengths than the writes at the other end of the
  52 connection, one write will correspond to one read.
  53 .PP
  54 Options are set by writing control messages to the
  55 .B ctl
  56 file of the connection.
  57 .PP
  58 The following control messages are supported:
  59 .TP
  60 .BI fd \ open-file-descriptor
  61 Run the SSL protocol over the existing file descriptor.
  62 .TP
  63 .BI alg \ cryptoalgs
  64 Connections start in
  65 .B alg clear
  66 which means no encryption or digesting.
  67 Writing
  68 .B alg sha
  69 to the control file turns on SHA-1 digest authentication
  70 for the data channel.
  71 Similarly, writing
  72 .B alg rc4_128
  73 enables encryption.
  74 Both can be turned on at once by
  75 .BR "alg sha rc4_128" .
  76 The digest mode
  77 .B sha
  78 may be replaced by
  79 .BR md5 .
  80 The encryption mode
  81 .B rc4_128
  82 may be replaced by
  83 .BR rc4_40 ,
  84 .BR rc4_128 ,
  85 .BR rc4_256 ,
  86 .BR des_40_ecb ,
  87 .BR des_40_cbc ,
  88 .BR des_56_ecb ,
  89 and
  90 .BR des_56_cbc .
  91 The mode may be changed at any time during the connection.
  92 .TP
  93 .BI secretin \ base64-secret
  94 The secret for decrypting and authenticating incoming messages
  95 can be specified either as a base64 encoded string by writing to the
  96 control file, or as a binary byte string using the interface below.
  97 .TP
  98 .BI secretout \ base64-secret
  99 The secret for encrypting and hashing outgoing messages
 100 can be specified either as a base64 encoded string by writing to the
 101 control file, or as a binary byte string using the interface below.
 102 .PP
 103 Before enabling digesting or encryption, shared secrets must be agreed upon with
 104 the remote side, one for each direction of transmission,
 105 and loaded as shown above or by writing to the files
 106 .I secretin
 107 and
 108 .IR secretout .
 109 If either the incoming or outgoing secret is not specified, the other secret
 110 is assumed to work for both directions.
 111 .PP
 112 The encryption and hash algoritms actually included in the kernel
 113 may be smaller than the set presented here.  Reading
 114 .I encalgs
 115 and
 116 .I hashalgs
 117 will give the actual space-separated list of algorithms implemented.
 118 .SH "SEE ALSO"
 119 .IR listen (8),
 120 .IR dial (2)
 121 .SH SOURCE
 122 .B /sys/src/9/port/devssl.c
 123 .SH BUGS
 124 Messages longer than 4096 bytes are truncated.