Encryption Library

API Documentation

Encryption.Encrypter

The encrypter class is able to encrypt text or other data, and decrypt it back to plaintext. This class is suitable for storing private information such as credit card numbers in a database. In order to encrypt and decrypt data, the password, which is a GUID, must be supplied. Your application should store this GUID in a secure location, away from the location where the encrypted data is stored.

This class uses the 256 bit Rijndael Advanced Encryption Standard (AES) algorithm. This is an industry-standard algorithm, used by the US National Security Agency (NSA), who approved the use of the algorithm to encrypt classified information.

Example: In this example a password is declared in code and a string is encrypted and then decrypted back to the original text.

Guid password = new Guid("{2D1A0770-1C8B-4c03-9057-8EC65236D7B2}");
using (Encrypter encrypter = new Encrypter(password)) {
    string encryptedText = encrypter.Encrypt("Some text");
    // encryptedText now contains "hyFzbjMw6PjLWMMoK5u/eA=="
    string decryptedText = encrypter.Decrypt(encryptedText);
    // decryptedText now contains "Some text"
}

Dim password As New Guid("{2D1A0770-1C8B-4c03-9057-8EC65236D7B2}")
Using encrypter As New Encrypter(password)
    Dim encryptedText As String = encrypter.Encrypt("Some text")
    ' encryptedText now contains "hyFzbjMw6PjLWMMoK5u/eA=="
        ' decryptedText now contains "Some text"
    Dim decryptedText As String = encrypter.Decrypt(encryptedText)
End Using

Constructors

	Name	Description
	Encrypter (System.Guid password)	Creates a new Encryptor, which is capable of encrypting and decrypting Unicode text. Parameters password: A password key which must be kept secret. To create a GUID from Visual Studio, click on 'Tools', then click 'Create GUID'. Choose the 'register format' option, and copy the generated GUID string and pass it to the #ctor(System.String) constructor.

Methods

	Name	Description
	Encrypt (System.String plaintext)	Encrypts the given plain text string and returns an encrypted string. Parameters plaintext: Any non-null unicode text. Return Value Returns text in a Base64 encoded format, which means it can contain the following characters: numbers (0-9), Roman alphabet characters (A-Z and a-z), and the '+', '/' and '=' characters. When storing in a database, the VARCHAR datatype can be used. In general, the length of the returned string will be significantly longer than the length of the input. This will often be 2-3 times longer, but in some cases it can be 4 or 5 times longer than the input. Therefore, if storing the result in a database, make sure the data length is at least 5 times longer than the maximum allowed unecrypted length. Exceptions System.ArgumentNullException: The plaintext parameter is null. System.ObjectDisposedException: This instance has already been disposed.
	Decrypt (System.String encryptedText)	Decrypts encrypted text back to its original plain text. Parameters encryptedText: Encrypted text generated by the Encrypter.Encrypt(System.String) method. Return Value Returns the unencrypted original plain text. Exceptions System.ArgumentNullException: The encryptedText parameter is null. System.ArgumentException: The encryptedText parameter is not encrypted text or was not created by this class. System.ObjectDisposedException: This instance has already been disposed.
	Dispose ()	Releases the resources used by the encryption algorithm.

Name

Description

Method

Encrypt (System.String plaintext)

Encrypts the given plain text string and returns an encrypted string.

Parameters

plaintext: Any non-null unicode text.

Return Value

Returns text in a Base64 encoded format, which means it can contain the following characters: numbers (0-9), Roman alphabet characters (A-Z and a-z), and the '+', '/' and '=' characters. When storing in a database, the VARCHAR datatype can be used. In general, the length of the returned string will be significantly longer than the length of the input. This will often be 2-3 times longer, but in some cases it can be 4 or 5 times longer than the input. Therefore, if storing the result in a database, make sure the data length is at least 5 times longer than the maximum allowed unecrypted length.

Exceptions

System.ArgumentNullException: The plaintext parameter is null.

System.ObjectDisposedException: This instance has already been disposed.

Method

Decrypt (System.String encryptedText)

Decrypts encrypted text back to its original plain text.

Parameters

encryptedText: Encrypted text generated by the Encrypter.Encrypt(System.String) method.

Return Value

Returns the unencrypted original plain text.

Exceptions

System.ArgumentNullException: The encryptedText parameter is null.

System.ArgumentException: The encryptedText parameter is not encrypted text or was not created by this class.

System.ObjectDisposedException: This instance has already been disposed.

Method

Dispose ()

Releases the resources used by the encryption algorithm.

Encryption.IEncrypter

A class which is able to encrypt text or other data, and decrypt it back to plaintext. This class is suitable for storing private information such as credit card numbers in a database.

Example: In this example a password is declared in code and a string is encrypted and then decrypted back to the original text.

Guid password = new Guid("{2D1A0770-1C8B-4c03-9057-8EC65236D7B2}");
using (Encrypter encrypter = new Encrypter(password)) {
    string encryptedText = encrypter.Encrypt("Some text");
    // encryptedText now contains "hyFzbjMw6PjLWMMoK5u/eA=="
    string decryptedText = encrypter.Decrypt(encryptedText);
    // decryptedText now contains "Some text"
}

Dim password As New Guid("{2D1A0770-1C8B-4c03-9057-8EC65236D7B2}")
Using encrypter As New Encrypter(password)
    Dim encryptedText As String = encrypter.Encrypt("Some text")
    ' encryptedText now contains "hyFzbjMw6PjLWMMoK5u/eA=="
        ' decryptedText now contains "Some text"
    Dim decryptedText As String = encrypter.Decrypt(encryptedText)
End Using

Methods

	Name	Description
	Encrypt (System.String plaintext)	Encrypts the given plain text string and returns an encrypted string. Parameters plaintext: Any non-null unicode text. Return Value Returns text in a Base64 encoded format, which means it can contain the following characters: numbers (0-9), Roman alphabet characters (A-Z and a-z), and the '+', '/' and '=' characters. When storing in a database, the VARCHAR datatype can be used. In general, the length of the returned string will be significantly longer than the length of the input. This will often be 2-3 times longer, but in some cases it can be 4 or 5 times longer than the input. Therefore, if storing the result in a database, make sure the data length is at least 5 times longer than the maximum allowed unecrypted length. Exceptions System.ArgumentNullException: The plainText parameter is null. System.ObjectDisposedException: This instance has already been disposed.
	Decrypt (System.String encryptedText)	Decrypts encrypted text back to its original plain text. Parameters encryptedText: Encrypted text generated by the Encrypter.Encrypt(System.String) method. Return Value Returns the unencrypted original plain text. Exceptions System.ArgumentNullException: The encryptedText parameter is null. System.ArgumentException: The encryptedText parameter is not encrypted text or was not created by this class. System.ObjectDisposedException: This instance has already been disposed.

Name

Description

Method

Encrypt (System.String plaintext)

Encrypts the given plain text string and returns an encrypted string.

Parameters

plaintext: Any non-null unicode text.

Return Value

Exceptions

System.ArgumentNullException: The plainText parameter is null.

System.ObjectDisposedException: This instance has already been disposed.

Method

Decrypt (System.String encryptedText)

Decrypts encrypted text back to its original plain text.

Parameters

encryptedText: Encrypted text generated by the Encrypter.Encrypt(System.String) method.

Return Value

Returns the unencrypted original plain text.

Exceptions

System.ArgumentNullException: The encryptedText parameter is null.

System.ArgumentException: The encryptedText parameter is not encrypted text or was not created by this class.

System.ObjectDisposedException: This instance has already been disposed.

Encryption.OneWayEncrypter

A helper class to make hashes of strings. This class in effect encrypts an input into a string which cannot be converted back to the original input, which is useful for storing passwords or creating checksums of strings and file contents. A hashing algorithm takes a string of any length and returns a string of a fixed length. The same input will always create the same output, however it is in practice near impossible for two different inputs to create the same hashed function.

Their are different algorithms available for hashing, and each algorithm returns a different output string. See the comments on each of the HashType values for the different output lengths and more information on the different algorithms. The DotNetHelpers encryption class always returns the output as a Base64-encoded string, which means it can contain the following characters: numbers (0-9), Roman alphabet characters (A-Z and a-z), and the '+', '/' and '=' characters. When storing in a database, the CHAR (or VARCHAR) datatype can be used, with the length depending on the algorithm used.

A common use of one-way encryption/hashing is to store sensative information such as passwords in a database. By hashing each user's password, and storing only that in the database, there is no risk of having passwords revealed should the database be compromised as there is no way to undo a hashed value back to the original value. When a user enters their password on a login page, the entered password is hashed and compared to the stored version (preferrably using a case-sensative comparison). Because the hash of the password is being compared, the original, unencrypted password does not need to be stored anywhere.

Another use is to create checksums on files or data to ensure that the data has not been changed during transmission (e.g. over the internet). To do this, a hash of the data is generated and sent with the original data. On the receiving end, the receiver takes another has of the data and compares the generated hash to the sent hash. If they are different, then the data has changed. To guard against intentional attacks where a third party has intercepted the data, changed it, and re-generated the hash, a 'salt' value can be used when generating the hash. A third party will only be able to modify the data undetected if they also know the 'salt' value. If the data being sent private and requires encryption, then an alternative encryption technique is needed (see the symmetric or asymmetric encryption class).

Methods

	Name	Description
	CreateHash (System.String input)	Creates a hash of the input and returns a fixed-length, Base64-encoded string. Parameters input: The string to encrypt. This can be any non-null value (including Empty and can be of any length, with no restrictions on the type of characters included. Return Value Returns an encrypted 28 character Base-64 encoded string. A Base-64 string contains ascii characters in the range A-Z, a-z, 0-9, '+', '/' and '='. Exceptions System.ArgumentNullException: The 'input' value is null. Example Example: This example shows how a password can be encrypted. The default algorithm (HashType.SHA1) is used. C# // get the user-entered password. string originalPassword = "password"; string encryptedPassword = OneWayEncrypter.CreateHash(originalPassword); // encryptedPassword now contains a // 28 character encrypted string VB ' get the user-entered password. Dim originalPassword As String = "password" Dim encryptedPassword As String = _ OneWayEncrypter.CreateHash(originalPassword) ' encryptedPassword now contains a ' 28 character encrypted string The encrypted password would be saved with the user details if this was on a registration page, or it would be used to retrieve a user based on username and encrypted password on a login page.
	CreateHash (HashType algorithm, System.String input)	Creates a hash of the input and returns a fixed-length, Base64-encoded string. Parameters algorithm: The type of hash algorithm to use. Different algorithms generate hashes at different speeds with different levels of security, and return strings of differing lengths. See the HashType enumeration for more details on the available algorithms. input: The string to encrypt. This can be any non-null value (including Empty and can be of any length, with no restrictions on the type of characters included. Return Value Returns a Base-64 encoded string of a fixed length (the length depends on the algorithm used). A Base-64 string contains ascii characters in the range A-Z, a-z, 0-9, '+', '/' and '='. Exceptions System.ArgumentNullException: The 'input' value is null. Example Example: This example shows how a password can be encrypted using the SHA512 algorithm. C# // get the user-entered password. string originalPassword = "password"; string encryptedPassword = OneWayEncrypter.CreateHash(HashType.SHA512, originalPassword); // encryptedPassword now contains an 88 // character encrypted string VB ' get the user-entered password. Dim originalPassword As String = "password" Dim encryptedPassword As String = _ OneWayEncrypter.CreateHash(HashType.SHA512, originalPassword) ' encryptedPassword now contains an 88 ' character encrypted string The encrypted password would be saved with the user details if this was on a registration page, or it would be used to retrieve a user based on username and encrypted password on a login page.
	CreateHash (HashType algorithm, System.String input, System.String salt)	Creates a hash of the input and returns a fixed-length, Base64-encoded string. Parameters algorithm: The type of hash algorithm to use. Different algorithms generate hashes at different speeds with different levels of security, and return strings of differing lengths. See the HashType enumeration for more details on the available algorithms. input: The string to encrypt. This can be any non-null value (including Empty and can be of any length, with no restrictions on the type of characters included. salt: A value which will be added to the input to make 'dictionary' attacks more difficult. By always supplying a constant, unique value as the salt, every generated value will be different from other applications, even when the same input is used. This thwarts a dictionary attack, where a mapping between inputs and encrypted values can be used to figure out encrypted values. A good value for a salt value is a GUID. Return Value Returns a Base-64 encoded string of a fixed length (the length depends on the algorithm used). A Base-64 string contains ascii characters in the range A-Z, a-z, 0-9, '+', '/' and '='. Exceptions System.ArgumentNullException: The 'input' value is null. Example Example: This example shows how a password can be encrypted using the SHA512 algorithm and a custom salt value. C# // get the user-entered password. string originalPassword = "password"; // arbitrary, constant salt value: const string salt = "65ED3F82-5954-4030-B919-F74A7832C788"; string encryptedPassword = OneWayEncrypter.CreateHash(HashType.SHA512, originalPassword, salt); // encryptedPassword now contains an 88 // character encrypted string VB ' get the user-entered password. Dim originalPassword As String = "password" ' arbitrary, constant salt value: Const salt As String = "65ED3F82-5954-4030-B919-F74A7832C788" Dim encryptedPassword As String = _ OneWayEncrypter.CreateHash(HashType.SHA512, originalPassword, salt) ' encryptedPassword now contains an 88 ' character encrypted string The encrypted password would be saved with the user details if this was on a registration page, or it would be used to retrieve a user based on username and encrypted password on a login page.
	CreateHash (HashType algorithm, System.IO.Stream input, System.String salt)	Creates a hash of the input and returns a fixed-length, Base64-encoded string. Use this method when you want to get the hash of a file. Parameters algorithm: The type of hash algorithm to use. Different algorithms generate hashes at different speeds with different levels of security, and return strings of differing lengths. See the HashType enumeration for more details on the available algorithms. input: A stream containing data to encrypt, for example an opened FileStream. salt: A value which will be added to the input to make 'dictionary' attacks more difficult. By always supplying a constant, unique value as the salt, every generated value will be different from other applications, even when the same input is used. This thwarts a dictionary attack, where a mapping between inputs and encrypted values can be used to figure out encrypted values. A good value for a salt value is a GUID. Return Value Returns a Base-64 encoded string of a fixed length (the length depends on the algorithm used). A Base-64 string contains ascii characters in the range A-Z, a-z, 0-9, '+', '/' and '='. Exceptions System.ArgumentNullException: The 'input' value is null. Example Example: This example creates a hash of a file. No salt value is used: C# FileInfo someFile = new FileInfo("path to file"); using (Stream stream = someFile.OpenRead()) { string output = OneWayEncrypter.CreateHash(HashType.SHA1, stream, null); } VB Dim someFile As New FileInfo("path to file") Using stream As Stream = someFile.OpenRead() Dim output As String = _ OneWayEncrypter.CreateHash( _ HashType.SHA1, stream, Nothing) End Using

Encryption.HashType

Specifies a type of hash algorithm to use when hashing an input in OneWayEncrypter.CreateHash(System.String). Different hash algorithms have different trade-offs in terms of encryption speed and security.

When choosing a hash algorithm, there are three aspects to take into account:

Security: Security A secure hash algorithm is one which cannot be reversed back into the original string, and one in which different inputs always produce different outputs. In general, the longer the 'hash size' (and hence the longer the encrypted output string), the more secure it is.
Speed: Speed Generally, the more secure the algorithm, the slower it is. If this is not of concern (e.g. for encrypting passwords occasionally), favour a slower algorithm to get better security. If you are using the hash functions very frequently (e.g. to computer checksums on files), consider a faster algorithm, such as HashType.MD5.
Hash size: Hash size The hash size is the number of bits that the algorithm generates. For any length of input, a hash algorithm will always generate the same sized output. In the DotHelpers encryption classes, the hashed bytes are converted to Base64 strings. The length of the outputted string is important to know in some cases, such as when storing hashed passwords in a database, so you know how many characters to make the password field. (Aside: use the VARCHAR column type for database columns holding hashed data).

	Name	Description
	MD5	The MD5 algorithm. This gives a medium level of security at a medium speed. This is a widely used algorithm, however consider using a SHA algorithm for greater security. The hash size of MD5 is 128 bits, which means a 24 character string is generated.
	RIPEMD160	The RIPEMD hash algorithm was created to replace earlier algorithms, but is now obsolete itself. Unless there is a specific reason to use this type of algorithm, consider using a SHA algorithm instead. The hash size is 160 bits, which means a 28 character string is generated.
	SHA1	The SHA-1 Secure Hash Algorithm. This is a strong algorithm designed by the US National Security Agency (NSA) and is used in many applications. Consider using a one of the other SHA algorithms unless performance is a concern, as this is a faster algorithm than the other SHA algorithms. The hash size is 160 bits, which means a 28 character string is generated.
	SHA256	Part of the SHA-2 family of the Secure Hash Algorithms. This offers very strong security and was designed by the US National Security Agency (NSA) and is used in many applications. This is slightly slower than HashType.SHA1 but offers greater security. The hash size is 256 bits, which means a 44 character string is generated.
	SHA384	Part of the SHA-2 family of the Secure Hash Algorithms. This offers very strong security and was designed by the US National Security Agency (NSA) and is used in many applications. This is slightly slower than HashType.SHA256 but offers greater security. The hash size is 384 bits, which means a 64 character string is generated.
	SHA512	Part of the SHA-2 family of the Secure Hash Algorithms. This offers very strong security and was designed by the US National Security Agency (NSA) and is used in many applications. This is slightly slower than HashType.SHA256 but offers greater security. The hash size is 512 bits, which means a 88 character string is generated.