Class NeonVault

Manages the encryption and decryption of files using passwords. This works a lot like Ansible Vault.

Inheritance

object

NeonVault

Namespace: Neon.Cryptography

Assembly: Neon.Cryptography.dll

Syntax

public class NeonVault

Remarks

This class works by using AesCipher with a 256-bit key to encrypt and decrypt files using a Neon standard ASCII text file format. This encryption is performed using the value of a named password as the encryption key. The class depends on a password provider function like string LookupPassword(string) that will return the value for a named password.

The idea here is that applications will define one or more named passwords like: mypassword1=GU6qc2vsJgmCWmdL and mypassword2=GBRDUqsX3GSKJ2af and then implement a password provider that returns the value of a password based on its name. You'll pass this provider to the NeonVault constructor.

note

Password names are case insensitive and will always be converted to lowercase using the invariant culture. Password names may include alphanumeric characters plus dashs, dots, or underscores.

Password providers should throw an exception whenever the named password cannot be located. Most providers will throw a KeyNotFoundException when this happens.

Encrypted files are encoded as ASCII and are formatted like:

$NEON_VAULT;4C823A36774CA4AC760F31DD8ABE7BD3;1.0;AES256;PASSWORD-NAME
4c5330744c5331435255644a5469424452564a5553555a4a51304655525330744c533074436b314a
53554e3552454e4451574a445a30463353554a425a306c4351555242546b4a6e6133466f61326c48
4f586377516b465263305a425245465754564a4e64305652575552575556464552586477636d5258
536d774b5932303162475248566e704e516a5259524652464e5531455358644e616b557954587072
4d4535736231684556456b3154555246656b314552544a4e656d7377546d787664305a555256524e
516b564851544656525170426545314c59544e5761567059536e566157464a735933704451304654
5358644555566c4b53323961535768325930354255555643516c46425247646e5256424252454e44
515646765132646e52554a42536d6c50436c6b345a45395163324a454f466379526c6b30566a5274
595570584d323032634452714e5467314e7a4131627a4e47527a6859564730724e33686957465130
546b68775645686d646e686161584e685a6e6f304f54414b4c325a6a53454d32546b4d3464697445
4e7a5a355931685156564a3164576f724f56646e51335133555670735a574d7954474a364b7a5a6f
55466f7a4c32347962544e7a51573952536c527253574e7565485172625170575458527157554d35
57573970633145305a453877634646444c3141784d6d4d7951586c46515663334d314a4555314256
526e597a555770365a47777255577052564556784b3068305257704a52544659626b4a70436e4a42
563078334d323872656d5a4f4e30684559555534596d7061636a4a765a7a687459574a454e566444
4c30395656

The first line of the file holds metadata that is used to identify encrypted files and also to identify the encryption method and name of the password to be used for decryption. The remaining lines encode the encrypted AesCipher output encoded as 80 character lines of HEX digits.

This class considers files starting $NEON_VAULT;4C823A36774CA4AC760F31DD8ABE7BD3 to be encrypted. This essentially acts as a very unique magic number. This is followed by the NeonVault format version (currently 1.0), the encryption cypher (currently AES256), and the name of the password that was used for encryption.

The decrypt methods are smart enough to determine whether a file is not encrypted and simply write the unencrypted data to the target. This means that you can safely call these methods on unencrypted data.

This class provides several methods to encrypt and decrypt data given a password.

note

Source Stream instances passed to encryption and decryption methods must support reading and seeking and target Stream instances must support writing as well as reading and seeking to support HMAC signatures.

Constructors

NeonVault(Func<string, string>, string)

Constructor.

Declaration

public NeonVault(Func<string, string> passwordProvider, string lineEnding = null)

Parameters

Type	Name	Description
Func<string, string>	passwordProvider	Specifies the function that returns the password value for a named password.
string	lineEnding	Optionally specifies line ending to be used when writing the output file. This defaults to the current platform's line ending: "\r\n" for Windows and "\n" for Linux, OS/X, etc.

Fields

MagicString

The string at the beginning of all files encrypted by NeonVault. This is used to identify these files.

Declaration

public const string MagicString = "$NEON_VAULT;4C823A36774CA4AC760F31DD8ABE7BD3;"

Field Value

Type	Description
string

Properties

MagicBytes

Returns MagicString encoded as a byte array for ease of use.

Declaration

public static byte[] MagicBytes { get; }

Property Value

Type	Description
byte[]

Methods

Decrypt(Stream)

Decrypts a stream to a byte array.

Declaration

public byte[] Decrypt(Stream source)

Parameters

Type	Name	Description
Stream	source	The source.

Returns

Type	Description
byte[]	The decrypted byte array.

Exceptions

Type	Condition
CryptographicException	Thrown if the password was not found or for other decryption problems.

Decrypt(Stream, Stream)

Decrypts a stream to another stream.

Declaration

public void Decrypt(Stream source, Stream target)

Parameters

Type	Name	Description
Stream	source	The source stream.
Stream	target	The target stream.

Exceptions

Type	Condition
CryptographicException	Thrown if the password was not found or for other decryption problems.

Decrypt(string)

Decrypts file to a byte array.

Declaration

public byte[] Decrypt(string sourcePath)

Parameters

Type	Name	Description
string	sourcePath	The source path.

Returns

Type	Description
byte[]	The decrypted bytes.

Exceptions

Type	Condition
CryptographicException	Thrown if the password was not found or for other decryption problems.

Decrypt(string, Stream)

Decrypts a file to a stream.

Declaration

public void Decrypt(string sourcePath, Stream target)

Parameters

Type	Name	Description
string	sourcePath	The source path.
Stream	target	The target stream.

Exceptions

Type	Condition
CryptographicException	Thrown if the password was not found or for other decryption problems.

Decrypt(string, string)

Decrypts a file to another file.

Declaration

public void Decrypt(string sourcePath, string targetPath)

Parameters

Type	Name	Description
string	sourcePath	The source path.
string	targetPath	The target path.

Exceptions

Type	Condition
CryptographicException	Thrown if the password was not found or for other decryption problems.

Encrypt(Stream, Stream, string)

Encrypts a stream to another stream.

Declaration

public void Encrypt(Stream source, Stream target, string passwordName)

Parameters

Type	Name	Description
Stream	source	The source stream.
Stream	target	The target stream.
string	passwordName	Identifies the password.

Exceptions

Type	Condition
CryptographicException	Thrown if the password was not found or for other encryption problems.

Encrypt(Stream, string)

Encrypts a stream to a byte array.

Declaration

public byte[] Encrypt(Stream source, string passwordName)

Parameters

Type	Name	Description
Stream	source	The source stream.
string	passwordName	Identifies the password.

Returns

Type	Description
byte[]	The encrypted bytes.

Exceptions

Type	Condition
CryptographicException	Thrown if the password was not found or for other encryption problems.

Encrypt(Stream, string, string)

Encrypts a stream to a file.

Declaration

public void Encrypt(Stream source, string targetPath, string passwordName)

Parameters

Type	Name	Description
Stream	source	The source stream.
string	targetPath	The target path.
string	passwordName	Identifies the password.

Exceptions

Type	Condition
CryptographicException	Thrown if the password was not found or for other encryption problems.

Encrypt(string, string)

Encrypts a file to a byte array.

Declaration

public byte[] Encrypt(string sourcePath, string passwordName)

Parameters

Type	Name	Description
string	sourcePath	The source path.
string	passwordName	Identifies the password.

Returns

Type	Description
byte[]	The encrypted bytes.

Exceptions

Type	Condition
CryptographicException	Thrown if the password was not found or for other encryption problems.

Encrypt(string, string, string)

Encrypts a file to another file.

Declaration

public void Encrypt(string sourcePath, string targetPath, string passwordName)

Parameters

Type	Name	Description
string	sourcePath	The source path.
string	targetPath	The target path.
string	passwordName	Identifies the password.

Exceptions

Type	Condition
CryptographicException	Thrown if the password was not found or for other encryption problems.

IsEncrypted(Stream)

Determines if a stream is encrypted via NeonVault.

Declaration

public static bool IsEncrypted(Stream stream)

Parameters

Type	Name	Description
Stream	stream	The stream.

Returns

Type	Description
bool	true if the stream is encrypted.

Remarks

note

The stream position must be at the beginning of the stream for this to work.

IsEncrypted(Stream, out string)

Determines if a stream is encrypted via NeonVault and returns the name of the password used.

Declaration

public static bool IsEncrypted(Stream stream, out string passwordName)

Parameters

Type	Name	Description
Stream	stream	The stream.
string	passwordName	For encrypted files, this returns as the name of the password used.

Returns

Type	Description
bool	true if the stream is encrypted.

Remarks

note

The stream position must be at the beginning of the stream for this to work.

IsEncrypted(string)

Determines if a file is encrypted via NeonVault.

Declaration

public static bool IsEncrypted(string path)

Parameters

Type	Name	Description
string	path	The file path.

Returns

Type	Description
bool	true if the file is encrypted.

IsEncrypted(string, out string)

Determines if a file is encrypted via NeonVault and returns the name of the password used.

Declaration

public static bool IsEncrypted(string path, out string passwordName)

Parameters

Type	Name	Description
string	path	The file path.
string	passwordName	For encrypted files, this returns as the name of the password used.

Returns

Type	Description
bool	true if the file is encrypted.

ValidatePasswordName(string)

Ensures that a password name is valid.

Declaration

public static string ValidatePasswordName(string passwordName)

Parameters

Type	Name	Description
string	passwordName	The password name.

Returns

Type	Description
string	The password name converted to lowercase.

Exceptions

Type	Condition
CryptographicException	Thrown if the name is invalid.