Doc fixes

libraries/Crypto/AES.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),

libraries/Crypto/AES128.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),

libraries/Crypto/AES192.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),

libraries/Crypto/AES256.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),

libraries/Crypto/AESCommon.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),

libraries/Crypto/Arcfour.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -93,6 +93,7 @@ size_t Arcfour::ivSize()
  *
  * \param key The key which must contain between 5 and 32 bytes,
  * with at least 16 recommended.
+ * \param len The length of the key in bytes.
  * \return Returns false if the key length is not between 5 and 32;
  * or true if the key was set successfully.
  *

libraries/Crypto/Arcfour.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),

libraries/Crypto/BlockCipher.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),

libraries/Crypto/BlockCipher.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),

libraries/Crypto/Cipher.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -22,10 +22,134 @@
 
 #include "Cipher.h"
 
+/**
+ * \class Cipher Cipher.h <Cipher.h>
+ * \brief Abstract base class for stream ciphers.
+ *
+ * This class is intended for implementing ciphers that operate on arbitrary
+ * amounts of data.  In particular, stream ciphers where the number of
+ * bytes that are input to encrypt() or decrypt() is exactly the same as
+ * the number of bytes that are output.
+ *
+ * All of the stream ciphers such as Arcfour and ChaCha inherit
+ * directly from this class, together with block cipher modes such as
+ * CTR128 and CFB128.
+ */
+
+/**
+ * \brief Constructs a new cipher object.
+ */
 Cipher::Cipher()
 {
 }
 
+/**
+ * \brief Destroys this cipher object.
+ *
+ * Subclasses are responsible for clearing temporary key schedules
+ * and other buffers so as to avoid leaking sensitive information.
+ *
+ * \sa clear()
+ */
 Cipher::~Cipher()
 {
 }
+
+/**
+ * \fn size_t Cipher::keySize() const
+ * \brief Default size of the key for this cipher, in bytes.
+ *
+ * If the cipher supports variable-sized keys, keySize() indicates the
+ * default or recommended key size.  The cipher may support other key sizes.
+ *
+ * \sa setKey(), ivSize()
+ */
+
+/**
+ * \fn size_t Cipher::ivSize() const
+ * \brief Size of the initialization vector for this cipher, in bytes.
+ *
+ * If the cipher does not need an initialization vector, this function
+ * will return zero.
+ */
+
+/**
+ * \fn bool Cipher::setKey(const uint8_t *key, size_t len)
+ * \brief Sets the key to use for future encryption and decryption operations.
+ *
+ * \param key The key to use.
+ * \param len The length of the key in bytes.
+ * \return Returns false if the key length is not supported, or the key
+ * is somehow "weak" and unusable by this cipher.
+ *
+ * Use clear() or the destructor to remove the key and any other sensitive
+ * data from the object once encryption or decryption is complete.
+ *
+ * Calling setKey() resets the cipher.  Any temporary data that was being
+ * retained for encrypting partial blocks will be abandoned.
+ *
+ * \sa keySize(), clear()
+ */
+
+/**
+ * \fn bool Cipher::setIV(const uint8_t *iv, size_t len)
+ * \brief Sets the initialization vector to use for future encryption and
+ * decryption operations.
+ *
+ * \param iv The initialization vector to use.
+ * \param len The length of the initialization vector in bytes.
+ * \return Returns false if the length is not supported.
+ *
+ * Initialization vectors should be set before the first call to
+ * encrypt() or decrypt() after a setKey() call.  If the initialization
+ * vector is changed after encryption or decryption begins,
+ * then the behaviour is undefined.
+ *
+ * \note The IV is not encoded into the output stream by encrypt().
+ * The caller is responsible for communicating the IV to the other party.
+ *
+ * \sa ivSize()
+ */
+
+/**
+ * \fn void Cipher::encrypt(uint8_t *output, const uint8_t *input, size_t len)
+ * \brief Encrypts an input buffer and writes the ciphertext to an
+ * output buffer.
+ *
+ * \param output The output buffer to write to, which may be the same
+ * buffer as \a input.  The \a output buffer must have at least as many
+ * bytes as the \a input buffer.
+ * \param input The input buffer to read from.
+ * \param len The number of bytes to encrypt.
+ *
+ * The encrypt() function can be called multiple times with different
+ * regions of the plaintext data.
+ *
+ * \sa decrypt()
+ */
+
+/**
+ * \fn void Cipher::decrypt(uint8_t *output, const uint8_t *input, size_t len)
+ * \brief Decrypts an input buffer and writes the plaintext to an
+ * output buffer.
+ *
+ * \param output The output buffer to write to, which may be the same
+ * buffer as \a input.  The \a output buffer must have at least as many
+ * bytes as the \a input buffer.
+ * \param input The input buffer to read from.
+ * \param len The number of bytes to decrypt.
+ *
+ * The decrypt() function can be called multiple times with different
+ * regions of the ciphertext data.
+ *
+ * \sa encrypt()
+ */
+
+/**
+ * \fn void Cipher::clear()
+ * \brief Clears all security-sensitive state from this cipher.
+ *
+ * Security-sensitive information includes key schedules, initialization
+ * vectors, and any temporary state that is used by encrypt() or decrypt()
+ * which is stored in the cipher itself.
+ */

libraries/Crypto/Cipher.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),

libraries/Crypto/Crypto.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),

libraries/Crypto/Crypto.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Southern Storm Software, Pty Ltd.
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
  *
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),

libraries/Crypto/examples/TestAES/TestAES.ino

@@ -1,3 +1,25 @@
+/*
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
 /*
 This example runs tests on the AES implementation to verify correct behaviour.
 */

libraries/Crypto/examples/TestArcfour/TestArcfour.ino

@@ -1,3 +1,25 @@
+/*
+ * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
 /*
 This example runs tests on the Arcfour implementation to verify correct behaviour.
 */