collectd crypto

collectd_crypto_specs.txt

Collectd network protocol cryptographic setup
=============================================
Collectd's network plugin supports authentication and encryption. This text
file describes how each case works to make it easier to add crypto support for
third party collectd network protocol implementations.

Two crypto modes are supported: 'Sign' and 'Encrypt'. Both are detailed in the
following sections. Some notes that apply to both:

You need to configure a common username/password pair in both the server and
client.

You must first construct the collectd packet as you would when not using any
crypto method. This will from now on be referred to as 'original' packet. The
crypto operation must then encapsulate the original packet by adding the
appropriate header (and in the case of 'Encrypt', also encrypting the original
packet).

However, you must take the configured maximum packet length into account. One
should make sure that the resulting encapsulated packet doesn't exceed the size
limit. To do so, the original packet should be created with a max size of
configured maximum packet size minus the size of the header that will be added
by the cryptographic encapsulation.



Signed CollectD Packet
======================

fields: [ ptype ][ hlen ][ mac ][ username ][ original ]
sizes:  [   2   ][   2  ][  32 ][   ulen   ][   olen   ]
        [              hlen                ][   olen   ]
        [                   plen                       ]

  # Signed packets use a packet type field of 0x0200
  ptype = 0x0200

  ulen = len(username)
  olen = len(original)

  # Header length is 36 bytes (constant) plus username length (variable).
  hlen = 36 + ulen

  # Calculate SHA256 HMAC on concatenation of username and original packet
  mac = hmac_sha256(username + original, password)


Encrypted CollectD Packet
=========================

fields: [ ptype ][ plen ][ ulen ][ username ][ iv ][ echecksum ][ eoriginal ]
sizes:  [   2   ][   2  ][   2  ][   ulen   ][ 16 ][    20     ][    olen   ]
        [                         hlen                         ][    olen   ]
        [                             plen                                  ]

  # Encrypted packets use a packet type field of 0x0210
  ptype = 0x0210

  ulen = len(username)
  olen = len(original)

  # Header length is 42 bytes (constant) plus username length (variable).
  hlen = 42 + ulen

  # Total packet length is header length plus original packet's length
  plen = hlen + olen

  # Hash password using SHA256 to create encryption key
  key = sha256(password)

  # Calculate checksum on original packet using SHA1 (20 bytes)
  checksum = sha1(original)

  # generate an initialization vector using a cryptographically secure
  # random number generator
  iv = random_bytes(16)

  # encrypt concatenation of checksum and original packet using AES in OFB mode
  encr_data = aes_encrypt(key, iv, checksum + original, mode=OFB)

  # split encrypted checksum and encrypted original for easier reference
  echecksum, eoriginal = encr_data[:20], encr_data[20:]

AES is a block cipher with a block size of 16 bytes. This means that
instead of encrypting each byte of the plaintext to the corresponding byte of
the ciphertext, it encrypts each 16-byte block of the plaintext to the
corresponding 16-byte block of the ciphertext. This also means that AES can
only work on multiples of 16 bytes. Most implementations will either pad the
plaintext for you or will raise an error if it's not a multiple of 16 bytes.
However, OFB mode turns any block cipher into a stream cipher. This is why
we're able to take the first 20 bytes of the ciphertext as the encrypted
checksum, since the first 20 bytes of the plaintext were the unencrypted
checksum. This also means that padding is redundant. So, if you end up with a
plaintext of N bytes that isn't a multiple of 16, it will most likely need to
be padded to N+n, where (N+n) % 16 == 0, and the ciphertext will then also be
N+n bytes long. But the last n bytes are encrypted padding, and can easily be
discarded. They carry no information necessary for decryption. This means that
the eoriginal's size should always end up being equal to olen.