SECURITY

   1 ***
   2 All cryptographic software in this package is subject to the following legal
   3 notice:
   4 This package includes publicly available encryption source code which,
   5 together with object code resulting from the compiling of publicly
   6 available source code, may be exported from the United States under License
   7 Exception TSU prsuant to 15 C.F.R Section 740.13(e).
   8 ***
   9 Security Design of openais
  10
  11 The openais project intends to mitigate the following threats:
  12
  13 1. forged group messaging messages which are intended to fault the openais
  14    executive
  15 2. forged group messaging messages which are intended to fault applications
  16    using openais apis
  17 3. monitoring of network data to capture sensitive information
  18
  19 The openais project does not intend to mitigate the following threats:
  20
  21 1. physical access to the hardware which could expose the private key
  22 2. privledged access to the operating system which could expose the private key
  23    or be used to inject errors into the ais executive.
  24 3. library user creates requests which are intended to fault the openais
  25    executive
  26
  27 The openais project mitigates the threats using two mechanisms:
  28
  29 1. Authentication
  30 2. Secrecy
  31
  32 Library Interface
  33 -----------------
  34 The openais executive authenticates every library user.  The library is only
  35 allowed to access services if it's GID is ais or 0.  Unauthorized library
  36 users are rejected.
  37
  38 The ais group is a trusted group.  If the administrator doesn't trust the
  39 application, it should not be added to the group!  Any member of the ais group
  40 could potentially send a malformed request to the executive and cause it to
  41 fault.
  42
  43 Group Messaging Interface
  44 -------------------------
  45 Group messaging uses UDP/IP to communicate with other openais executives using
  46 messages.  It is possible without authentication of every packet that an
  47 attacker could forge messages.  These forged messages could fault the openais
  48 executive distributed state machines.  It would also be possible to corrupt
  49 end applications by forging changes.
  50
  51 Since messages are sent using UDP/IP it would be possible to snoop those
  52 messages and rebuild sensitive data.
  53
  54 To solve these problems, the group messaging interface uses two new interfaces
  55 interal to it's implementation:
  56 1. encrypt_and_sign - encrypts and signs a message securely
  57 2. authenticate_and_decrypt - authenticates and decrypts a message securely
  58
  59 When the executive wants to send a message over the network, it uses
  60 encrypt_and_sign to prepare the message to be sent.  When the executive
  61 wants to receive a message from the network, it uses
  62 authenticate_and_decrypt to verify the message is valid and decrypt it.
  63
  64 These two functions utilize the following algorithms:
  65 sha1 - hash algorithm secure for using with hmac
  66 hmac - produces a 16 byte digest from any length input
  67 sober - pseudo random number generator and stream cipher
  68
  69 The hmac algorithm requires a 16 byte key.
  70 The sober algorithm requires a 16 byte private key.
  71 The sober algorithm requires a 16 byte public initial vector.
  72
  73 The private key is read from disk and stored in memory for use with the
  74 sober algorithm to generate the three required keys.
  75
  76 Every message starts with a
  77 struct security {
  78         unsigned char digest[20]; A one way hash digest
  79         unsigned char salt[16]; A securely generated random number
  80 }
  81
  82 When a message is sent (encrypt_and_sign):
  83 ------------------------------------------
  84 1. sober is used to create a 16 byte random number (salt) using the md4
  85    algorithm
  86 2. sober is keyed with the private key and the initial vector is set to the
  87    salt.  Then a 48 byte key is read from the sober algorithm.  This 48 byte
  88    key is split into 3 16 byte keys.  The keys are the hmac key, the sober key
  89    and the sober initial vector.
  90 3. A sober instance is keyed with the sober key and sober initial vector
  91    from step #2.
  92 4. The data of the packet, except for the security header, is encrypted using
  93    the sober cipher that was initialized in step #3.
  94 5. The salt is stored in the security header of the outgoing message.
  95 6. The hmac is initialized with the hmac key generated in step #2.
  96 7. The message, except for the security header, is hmaced to produce a digest
  97    using the sha1 algorithm.
  98 8. The digest is stored in the outgoing message.
  99 9. The message is transmitted.
 100
 101
 102 When a message is received (decrypt_and_authenticate):
 103 ------------------------------------------------------
 104 1. sober is keyed with the private key and the initial vector is set to the
 105    salt in the received message.  Then a 48 byte key is read from the sober
 106    algorithm.  This 48 byte key is split into 3 16 byte keys.  The keys are the
 107    hmac key, the sober key and the sober initial vector.
 108 2. The sober key and sober initial vector from step #1 are used to key a
 109    new sober instance.
 110 3. The hmac is setup using the hmac key generated in step #1 using sha1.
 111 5. The message is authenticated, except for the security header.
 112 6. If the message was not authenticated, the caller is told of the result.
 113    The caller ignores the message.
 114 7. The message is decrypted, except for the security header, using the sober
 115    algorithm in step #2.
 116 8. The message is processed.
 117
 118 This does consume some resources.  It ensures the private key is never shared
 119 openly, that messages are authenticated, that messages are encrypted, and that
 120 any key exposure of the sober encryption key, sober initial vector, or hmac
 121 key can only be used to attack one of the algorithms.  Finally every key used
 122 is randomly unique (within the 2^128 search space of the input to sober) to
 123 ensure that keys are never reused, nonce's are never reused, and hmac's are
 124 never reused.
 125
 126 Comments welcome mailto:openais@lists.osdl.org