Class AesCipher

Implements a convienent wrapper over AesManaged that handles the encryption and decryption of data using the AES algorthim using many security best practices.

Inheritance

object

AesCipher

Namespace: Neon.Cryptography

Assembly: Neon.Cryptography.dll

Syntax

public sealed class AesCipher

Remarks

This class uses the BinaryWriter to generate the encrypted output and BinaryReader to read it.

The data is formatted with an unencrypted header that specifies the initialization vector (IV), as well as the HMAC512 that will be used to validate the encrypted data. The encrypted data includes variable length psuedo random padding followed by the encrypted user data.

 Header (plaintext)
+------------------+
|    0x3BBAA035    |    32-bit magic number (for verification)
+------------------+
|     IV Size      |    16-bits
+------------------+
|                  |
|     IV Bytes     |    IV Size bytes
|                  |
+------------------+
|    HMAC Size     |    16-bits
+------------------+
|                  |
|    HMAC Bytes    |    HMAC Size bytes
|                  |
+-------------------
AES256 Encrypted:
+------------------+
|   Padding Size   |    16-bits
+------------------+
|                  |
|   Padding Bytes  |    Padding Size bytes
|                  |
+------------------+
|                  |
|                  |
|                  |
|    User Data     |
|                  |
|                  |
|                  |
+------------------+

note

Note that this encodes multi-byte integers using little endian byte ordering via BinaryWriter and BinaryReader.

This class automatically generates a new initialization vector for every encyption operation. This ensures that every encryption operation will generate different ciphertext even when the key and data haven't changed to enhance security.

The class is designed to be easier to use than the .NET Core AesManaged base implementation.

To encrypt data:

Generate an encryption key via GenerateKey(int) and create an instance via AesCipher(string, int) passing the key, or just call AesCipher(int, int) to create with a generated key of the specified size.
You can always obtain the key via the Key property.
Call one of EncryptToBase64(byte[]), EncryptToBase64(byte[]), EncryptToBytes(string), or EncryptToBytes(byte[]) to perform the encryption with varying input and output formats.

To decrypt data:

Use AesCipher(string, int) to construct and instance using the key originally used to encrypt the data.
Call one of DecryptBytesFrom(byte[]), DecryptBytesFrom(string), DecryptStringFrom(byte[]), or DecryptStringFrom(byte[]). to decrypt data.

Constructors

AesCipher(int, int)

Constructs an AES cypher using a randomly generated encyption key.

Declaration

public AesCipher(int keySize = 256, int maxPaddingBytes = 64)

Parameters

Type	Name	Description
int	keySize	Optionally specifies the key size (defaults to 256 bits).
int	maxPaddingBytes	The maximum number of padding bytes. This must be less than or equal to 32767. This defaults to 64.

Remarks

Note that only these key sizes are currently supported: 128, 192, and 256 bits. Only 256 bits is currently considered to be secure.

AesCipher(string, int)

Constructs an AES cypher using a specific encryption key.

Declaration

public AesCipher(string key, int maxPaddingBytes = 64)

Parameters

Type	Name	Description
string	key	The base-64 encoded key.
int	maxPaddingBytes	The maximum number of padding bytes. This must be less than or equal to 32767. This defaults to 64.

Fields

Magic

The 32-bit magic number that will be written in plaintext to the beginning of the encrypted output to be used to verify that encrypted buffers will generated by this class.

Declaration

public const int Magic = 1002086453

Field Value

Type	Description
int

Properties

IV

Returns the encyption initialization vector encoded as base-64.

Declaration

public string IV { get; }

Property Value

Type	Description
string

Key

Returns the encyption key encoded as base-64.

Declaration

public string Key { get; }

Property Value

Type	Description
string

Methods

DecryptBytesFrom(byte[])

Decrypts the encrypted base-64 text passed returning the result as a byte array.

Declaration

public byte[] DecryptBytesFrom(byte[] encryptedBytes)

Parameters

Type	Name	Description
byte[]	encryptedBytes	The encrypted bytes.

Returns

Type	Description
byte[]	The encrypted result as a string.

DecryptBytesFrom(string)

Decrypts the encrypted base-64 text passed returning the result as a byte array.

Declaration

public byte[] DecryptBytesFrom(string encryptedBase64)

Parameters

Type	Name	Description
string	encryptedBase64	The encrypted base-64 text.

Returns

Type	Description
byte[]	The encrypted result as a string.

DecryptStream(Stream, Stream)

Decrypts one stream to another.

Declaration

public void DecryptStream(Stream encrypted, Stream decrypted)

Parameters

Type	Name	Description
Stream	encrypted	The encrypted input stream.
Stream	decrypted	The decrypted output stream.

DecryptStringFrom(byte[])

Decrypts the encrypted bytes passed returning the result as a string.

Declaration

public string DecryptStringFrom(byte[] encryptedBytes)

Parameters

Type	Name	Description
byte[]	encryptedBytes	The encrypted base-64 text.

Returns

Type	Description
string	The encrypted result as a base-64 string.

DecryptStringFrom(string)

Decrypts the encrypted base-64 text passed returning the result as a string.

Declaration

public string DecryptStringFrom(string encryptedBase64)

Parameters

Type	Name	Description
string	encryptedBase64	The encrypted base-64 text.

Returns

Type	Description
string	The encrypted result as a base-64 string.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

EncryptStream(Stream, Stream)

Encrypts one stream to another.

Declaration

public void EncryptStream(Stream decrypted, Stream encrypted)

Parameters

Type	Name	Description
Stream	decrypted	The decrypted input stream.
Stream	encrypted	The encrypted output stream.

EncryptToBase64(byte[])

Encrypts the bytes passed returning the result encoded as base-64.

Declaration

public string EncryptToBase64(byte[] decryptedBytes)

Parameters

Type	Name	Description
byte[]	decryptedBytes	The unencrypted text.

Returns

Type	Description
string	The encrypted result as base-64.

EncryptToBase64(string)

Encrypts the text passed returning the result encoded as base-64.

Declaration

public string EncryptToBase64(string decryptedText)

Parameters

Type	Name	Description
string	decryptedText	The unencrypted text.

Returns

Type	Description
string	The encrypted result as base-64.

EncryptToBytes(byte[])

Encrypts the text passed returning the result encoded as a byte array.

Declaration

public byte[] EncryptToBytes(byte[] decryptedBytes)

Parameters

Type	Name	Description
byte[]	decryptedBytes	The unencrypted bytes.

Returns

Type	Description
byte[]	The encrypted result as bytes.

EncryptToBytes(string)

Encrypts the text passed returning the result encoded as a byte array.

Declaration

public byte[] EncryptToBytes(string decryptedText)

Parameters

Type	Name	Description
string	decryptedText	The unencrypted text.

Returns

Type	Description
byte[]	The encrypted result as bytes.

GenerateKey(int)

Generates a random encryption key with the specified size in bits.

Declaration

public static string GenerateKey(int keySize = 256)

Parameters

Type	Name	Description
int	keySize	The key size in bits (default 256).

Returns

Type	Description
string	The key encoded as base-64.

Remarks

Note that only these key sizes are currently supported: 128, 192, and 256 bits. Only 256 bits is currently considered to be secure.