Skip to content

docs: add XML documentation for AES, AEAD modes (GCM, ChaCha20Poly1305) and Dilithium #669

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
KonradSop wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: add XML documentation for AES, AEAD modes (GCM, ChaCha20Poly1305) and Dilithium #669

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion crypto/src/crypto/IBlockCipher.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

namespace Org.BouncyCastle.Crypto
{
/// <remarks>Base interface for a symmetric key block cipher.</remarks>
/// <summary>
/// Base interface for a symmetric key block cipher.
/// </summary>
public interface IBlockCipher
{
/// <summary>The name of the algorithm this cipher implements.</summary>
Expand All @@ -13,6 +15,9 @@ public interface IBlockCipher
/// <param name="parameters">The key or other data required by the cipher.</param>
void Init(bool forEncryption, ICipherParameters parameters);

/// <summary>
/// Return the block size for this cipher (in bytes).
/// </summary>
/// <returns>The block size for this cipher, in bytes.</returns>
int GetBlockSize();

Expand Down
70 changes: 35 additions & 35 deletions crypto/src/crypto/engines/AesEngine.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,30 +6,25 @@

namespace Org.BouncyCastle.Crypto.Engines
{
/**
* an implementation of the AES (Rijndael), from FIPS-197.
* <p>
* For further details see: <a href="http://csrc.nist.gov/encryption/aes/">http://csrc.nist.gov/encryption/aes/</a>.
*
* This implementation is based on optimizations from Dr. Brian Gladman's paper and C code at
* <a href="http://fp.gladman.plus.com/cryptography_technology/rijndael/">http://fp.gladman.plus.com/cryptography_technology/rijndael/</a>
*
* There are three levels of tradeoff of speed vs memory
* Because java has no preprocessor, they are written as three separate classes from which to choose
*
* The fastest uses 8Kbytes of static tables to precompute round calculations, 4 256 word tables for encryption
* and 4 for decryption.
*
* The middle performance version uses only one 256 word table for each, for a total of 2Kbytes,
* adding 12 rotate operations per round to compute the values contained in the other tables from
* the contents of the first.
*
* The slowest version uses no static tables at all and computes the values in each round.
* </p>
* <p>
* This file contains the middle performance version with 2Kbytes of static tables for round precomputation.
* </p>
*/
/// <summary>An implementation of the AES (Rijndael), from FIPS-197.</summary>
/// <remarks>
/// For further details see: <a href="http://csrc.nist.gov/encryption/aes/">http://csrc.nist.gov/encryption/aes/</a>.
/// <para>
/// This implementation is based on optimizations from Dr. Brian Gladman's paper and C code at
/// <a href="http://fp.gladman.plus.com/cryptography_technology/rijndael/">http://fp.gladman.plus.com/cryptography_technology/rijndael/</a>
/// </para>
/// <para>
/// There are three levels of tradeoff of speed vs memory:
/// </para>
/// <list type="bullet">
/// <item>The fastest uses 8Kbytes of static tables to precompute round calculations.</item>
/// <item>The middle performance version uses only one 256 word table for each, for a total of 2Kbytes, adding 12 rotate operations per round.</item>
/// <item>The slowest version uses no static tables at all and computes the values in each round.</item>
/// </list>
/// <para>
/// This file contains the middle performance version with 2Kbytes of static tables for round precomputation.
/// </para>
/// </remarks>
public sealed class AesEngine
: IBlockCipher
{
Expand Down Expand Up @@ -437,21 +432,15 @@ private uint[][] GenerateWorkingKey(KeyParameter keyParameter, bool forEncryptio

private const int BLOCK_SIZE = 16;

/**
* default constructor - 128 bit block size.
*/
/// <summary>Default constructor - 128 bit block size.</summary>
public AesEngine()
{
}

/**
* initialise an AES cipher.
*
* @param forEncryption whether or not we are for encryption.
* @param parameters the parameters required to set up the cipher.
* @exception ArgumentException if the parameters argument is
* inappropriate.
*/
/// <summary>Initialise an AES cipher.</summary>
/// <param name="forEncryption">Whether or not we are using it for encryption.</param>
/// <param name="parameters">The parameters required to set up the cipher.</param>
/// <exception cref="ArgumentException">If the parameters argument is inappropriate.</exception>
public void Init(bool forEncryption, ICipherParameters parameters)
{
if (!(parameters is KeyParameter keyParameter))
Expand All @@ -464,16 +453,27 @@ public void Init(bool forEncryption, ICipherParameters parameters)
this.s = Arrays.Clone(forEncryption ? S : Si);
}

/// <summary>The name of the algorithm this engine implements.</summary>
public string AlgorithmName
{
get { return "AES"; }
}

/// <summary>Return the block size for this cipher (in bytes).</summary>
/// <returns>16 (fixed block size for AES).</returns>
public int GetBlockSize()
{
return BLOCK_SIZE;
}

/// <summary>Process a single block of data.</summary>
/// <param name="input">The input buffer containing the data to be processed.</param>
/// <param name="inOff">The offset into the input buffer.</param>
/// <param name="output">The output buffer to store the result.</param>
/// <param name="outOff">The offset into the output buffer.</param>
/// <returns>The number of bytes processed and produced.</returns>
/// <exception cref="DataLengthException">If the input buffer is too small, or the output buffer is too small.</exception>
/// <exception cref="InvalidOperationException">If the cipher isn't initialised.</exception>
public int ProcessBlock(byte[] input, int inOff, byte[] output, int outOff)
{
if (WorkingKey == null)
Expand Down
53 changes: 16 additions & 37 deletions crypto/src/crypto/modes/CbcBlockCipher.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,7 @@

namespace Org.BouncyCastle.Crypto.Modes
{
/**
* implements Cipher-Block-Chaining (CBC) mode on top of a simple cipher.
*/
/// <summary>Implements Cipher-Block-Chaining (CBC) mode on top of a simple cipher.</summary>
public sealed class CbcBlockCipher
: IBlockCipherMode
{
Expand All @@ -16,11 +14,8 @@ public sealed class CbcBlockCipher
private IBlockCipher cipher;
private bool encrypting;

/**
* Basic constructor.
*
* @param cipher the block cipher to be used as the basis of chaining.
*/
/// <summary>Basic constructor.</summary>
/// <param name="cipher">The block cipher to be used as the basis of chaining.</param>
public CbcBlockCipher(
IBlockCipher cipher)
{
Expand All @@ -32,23 +27,15 @@ public CbcBlockCipher(
this.cbcNextV = new byte[blockSize];
}

/**
* return the underlying block cipher that we are wrapping.
*
* @return the underlying block cipher that we are wrapping.
*/
/// <summary>Return the underlying block cipher that we are wrapping.</summary>
/// <returns>The underlying block cipher that we are wrapping.</returns>
public IBlockCipher UnderlyingCipher => cipher;

/**
* Initialise the cipher and, possibly, the initialisation vector (IV).
* If an IV isn't passed as part of the parameter, the IV will be all zeros.
*
* @param forEncryption if true the cipher is initialised for
* encryption, if false for decryption.
* @param param the key and other data required by the cipher.
* @exception ArgumentException if the parameters argument is
* inappropriate.
*/
/// <summary>Initialise the cipher and, possibly, the initialisation vector (IV).</summary>
/// <remarks>If an IV isn't passed as part of the parameter, the IV will be all zeros.</remarks>
/// <param name="forEncryption">If true the cipher is initialised for encryption, if false for decryption.</param>
/// <param name="parameters">The key and other data required by the cipher.</param>
/// <exception cref="ArgumentException">If the parameters argument is inappropriate.</exception>
public void Init(bool forEncryption, ICipherParameters parameters)
{
bool oldEncrypting = this.encrypting;
Expand Down Expand Up @@ -82,26 +69,21 @@ public void Init(bool forEncryption, ICipherParameters parameters)
}
}

/**
* return the algorithm name and mode.
*
* @return the name of the underlying algorithm followed by "/CBC".
*/
/// <summary>Return the algorithm name and mode.</summary>
/// <returns>The name of the underlying algorithm followed by "/CBC".</returns>
public string AlgorithmName
{
get { return cipher.AlgorithmName + "/CBC"; }
}

/// <summary>Indicates whether this cipher can handle partial blocks.</summary>
public bool IsPartialBlockOkay
{
get { return false; }
}

/**
* return the block size of the underlying cipher.
*
* @return the block size of the underlying cipher.
*/
/// <summary>Return the block size of the underlying cipher.</summary>
/// <returns>The block size in bytes.</returns>
public int GetBlockSize()
{
return cipher.GetBlockSize();
Expand Down Expand Up @@ -129,10 +111,7 @@ public int ProcessBlock(ReadOnlySpan<byte> input, Span<byte> output)
}
#endif

/**
* reset the chaining vector back to the IV and reset the underlying
* cipher.
*/
/// <summary>Reset the chaining vector back to the IV and reset the underlying cipher.</summary>
public void Reset()
{
Array.Copy(IV, 0, cbcV, 0, IV.Length);
Expand Down
Loading