Documentation/networking/ccrypt.txt

   1 Ethernet Cheap Crypt (ccrypt)
   2
   3 == Introduction.
   4 Ccrypt is Ethernet traffic encryption mode. What differs it from other
   5 solutions is it's "cheapness" - in sense of additional space used in frames
   6 for internal protocol needs. While other solution suffers from mtu and
   7 fragmentation problems ccrypt just works - because it does not need any
   8 additional information. Never, and at all. It may seem a kind of magic, but it
   9 is actually very simple. Because of that "cheapness" it has it's own weakness,
  10 but can be very useful in some circumstances.
  11
  12 == Reasons
  13 Ccrypt was designed as a solution for situation where additional space in
  14 frames - required by other encryption methods - is to high price. Where
  15 it couldn't cause mtu problems like fragmentation.
  16
  17 == How does it work
  18 In short - ccrypt uses Cipher-block chaining (CBC) operation mode
  19
  20   http://en.wikipedia.org/wiki/Cipher_block_chaining
  21
  22 and deals with padding problem with "residual block termination"
  23
  24   http://en.wikipedia.org/wiki/Residual_block_termination
  25
  26 Ccrypt is basically implemented as two structures: ccrypt_rx and ccrypt_tx.
  27 These structures are associated with Ethernet net_device and can be used
  28 separately from themselves and other ccrypt_?x associated with other interfaces.
  29
  30 All Ethernet interfaces need to have they ccrypt_rx or ccrypt_tx activated for
  31 ccrypt to work. They can be switched to use ccrypt by providing just two
  32 values: algorithm supported by the kernel crypto api and valid key.
  33
  34 After setting ccrypt_tx (outgoing pair) all leaving frames will be encrypted
  35 using supported algorithm and key. All information except mac addresses,
  36 packet type and hardware checksum will be unreadable for common reader. If
  37 frame is of 802.1Q type - vlan id and encapsulated protocol will be send
  38 in plain text too.
  39
  40 Because CBC mode needs Initialization Vector (IV) it will be internally
  41 stored - first bytes of encrypted frame will be used as IV for next frame.
  42 Because this is done right before execution of hardware xmit handler,
  43 frames will be delivered in order, so on the other side IV can be always in
  44 sync.
  45
  46 After setting ccrypt_rx (incoming pair) all arriving frames will be decrypted.
  47 Decryption algorithm is less trivial then encryption one.
  48
  49 Each frame is decrypted several times (although most of the time one try is
  50 enough) and validated using special validation function. This is most "magical"
  51 functionality of ccrypt. Using information about upper layer structure of
  52 headers, checksums and allowed values ccrypt minimalizes chance of passing
  53 hostile frame. Even if such injected frame would pass there are no chances
  54 that it can contain any valid upper level information. Most probably it
  55 will be dropped by upper layer protocol handlers because of being junk.
  56 While author of ccrypt is not cryptography expert he believes that this
  57 is secure enough to be used in non-critical circumstances.
  58
  59 Ccrypt_rx actually manages two algorithm&key values. One is considered "new"
  60 and second "old". This is handy when implementing key-rotation solution, so
  61 that ccrypt_rx can be for a short time in "transition" stage - still using old
  62 key but switch to new one as soon as "valid" frame using new one appears.
  63
  64 Each algorithm&key value have two IVs associated. One is copied from last
  65 frame known to be "valid" and if any "invalid" frame appeared since then
  66 it's stored too, but in the second IV. This prevents IV de-synchronization
  67 attacks using frame injection and still let synchronize both sides after
  68 transmission problems.
  69
  70 == Supported protocols
  71 Because of validation needs, ccrypt supports only subset of protocols
  72 working on the top of layer 2. Currently implemented are:
  73 * 802.1Q (vlan)
  74 * IPv4
  75 * ARP
  76 * PPPoE
  77
  78 == Drawbacks
  79 While ccrypt have it's strengths it got it's weakness too.
  80 * it's experimental
  81 * it's level of security is still not confirmed by wider audience
  82 * validation function requires implementation of checks for all
  83   upper protocols (IPv4, ARP at the time of writing this) it should
  84   work with
  85 * it requires packet linearization (shouldn't be problem because of
  86   Ethernet MTU and may be implemented for fragments support in the
  87   future)
  88 * each lost frame caring encrypted information will cause two "real"
  89   frames to be lost
  90 * "nesting" crypt (setting ccrypt on both: slave and master device
  91   eg. vlan, bonding) will not work
  92 * it depends on frame delivery order; there are Ethernet devices that
  93   may not always deliver frames in order; on SMP systems there
  94   is a possibility of frames reordering even on local interface - while
  95   this is non-critical and exceptional it will affect ccrypt performance;
  96   that possible issue still needs testing;
  97
  98 == Usage
  99 For changing algorithm and keys sysfs interface is provided.
 100
 101 To set keys:
 102 # echo -n "aes:0123456789abcdef0123456789abcdef" > /sys/class/net/eth0/ccrypt_tx
 103 # echo -n "aes:deadbeafdeadbeafdeadbeafdeadbeaf" > /sys/class/net/eth0/ccrypt_rx
 104
 105 To stop using ccrypt on eth0:
 106 $ echo -n "null" > /sys/class/net/eth0/ccrypt_tx
 107 $ echo -n "null" > /sys/class/net/eth0/ccrypt_rx
 108
 109 Note that key lenght must be valid for selected algorithm.
 110
 111 == Authors
 112 The main idea author is Pawel Foremski <pjf@asn.pl>.
 113 Implementation details and implementation itself was written by
 114 Dawid Ciezarkiewicz <dpc@asn.pl>. Both working in ASN team.
 115
 116 Ccrypt was written as a part of the Lintrack project.
 117 http://lintrack.org