From 09a9d2b51bf7e41d2721fd05b435b8d136b63052 Mon Sep 17 00:00:00 2001 From: Rhys Weatherley Date: Tue, 30 Dec 2014 07:04:47 +1000 Subject: [PATCH] Doc fixes --- libraries/Crypto/AES.h | 2 +- libraries/Crypto/AES128.cpp | 2 +- libraries/Crypto/AES192.cpp | 2 +- libraries/Crypto/AES256.cpp | 2 +- libraries/Crypto/AESCommon.cpp | 2 +- libraries/Crypto/Arcfour.cpp | 3 +- libraries/Crypto/Arcfour.h | 2 +- libraries/Crypto/BlockCipher.cpp | 2 +- libraries/Crypto/BlockCipher.h | 2 +- libraries/Crypto/Cipher.cpp | 126 +++++++++++++++++- libraries/Crypto/Cipher.h | 2 +- libraries/Crypto/Crypto.cpp | 2 +- libraries/Crypto/Crypto.h | 2 +- libraries/Crypto/examples/TestAES/TestAES.ino | 22 +++ .../examples/TestArcfour/TestArcfour.ino | 22 +++ 15 files changed, 182 insertions(+), 13 deletions(-) diff --git a/libraries/Crypto/AES.h b/libraries/Crypto/AES.h index d08a1d92..632e5878 100644 --- a/libraries/Crypto/AES.h +++ b/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"), diff --git a/libraries/Crypto/AES128.cpp b/libraries/Crypto/AES128.cpp index b7ee5d1b..c660a741 100644 --- a/libraries/Crypto/AES128.cpp +++ b/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"), diff --git a/libraries/Crypto/AES192.cpp b/libraries/Crypto/AES192.cpp index bb715556..f853267f 100644 --- a/libraries/Crypto/AES192.cpp +++ b/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"), diff --git a/libraries/Crypto/AES256.cpp b/libraries/Crypto/AES256.cpp index 6e58339a..e987abe9 100644 --- a/libraries/Crypto/AES256.cpp +++ b/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"), diff --git a/libraries/Crypto/AESCommon.cpp b/libraries/Crypto/AESCommon.cpp index 02f2d737..431600e5 100644 --- a/libraries/Crypto/AESCommon.cpp +++ b/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"), diff --git a/libraries/Crypto/Arcfour.cpp b/libraries/Crypto/Arcfour.cpp index f794b31a..659872cc 100644 --- a/libraries/Crypto/Arcfour.cpp +++ b/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. * diff --git a/libraries/Crypto/Arcfour.h b/libraries/Crypto/Arcfour.h index de349687..c17fc3f8 100644 --- a/libraries/Crypto/Arcfour.h +++ b/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"), diff --git a/libraries/Crypto/BlockCipher.cpp b/libraries/Crypto/BlockCipher.cpp index c79907c2..f4ee57b5 100644 --- a/libraries/Crypto/BlockCipher.cpp +++ b/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"), diff --git a/libraries/Crypto/BlockCipher.h b/libraries/Crypto/BlockCipher.h index 62e7bd5f..b36e2e26 100644 --- a/libraries/Crypto/BlockCipher.h +++ b/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"), diff --git a/libraries/Crypto/Cipher.cpp b/libraries/Crypto/Cipher.cpp index d1ae0225..bbf57f36 100644 --- a/libraries/Crypto/Cipher.cpp +++ b/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 + * \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. + */ diff --git a/libraries/Crypto/Cipher.h b/libraries/Crypto/Cipher.h index 8462b95c..6d43cce0 100644 --- a/libraries/Crypto/Cipher.h +++ b/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"), diff --git a/libraries/Crypto/Crypto.cpp b/libraries/Crypto/Crypto.cpp index f7cd4a8b..28295258 100644 --- a/libraries/Crypto/Crypto.cpp +++ b/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"), diff --git a/libraries/Crypto/Crypto.h b/libraries/Crypto/Crypto.h index 805c3c50..b4ba2446 100644 --- a/libraries/Crypto/Crypto.h +++ b/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"), diff --git a/libraries/Crypto/examples/TestAES/TestAES.ino b/libraries/Crypto/examples/TestAES/TestAES.ino index 69730277..8da08b6a 100644 --- a/libraries/Crypto/examples/TestAES/TestAES.ino +++ b/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. */ diff --git a/libraries/Crypto/examples/TestArcfour/TestArcfour.ino b/libraries/Crypto/examples/TestArcfour/TestArcfour.ino index 9b5ad0b8..b9eca2a3 100644 --- a/libraries/Crypto/examples/TestArcfour/TestArcfour.ino +++ b/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. */