Class X509CryptoAgent

Instantiatable class which can be used to perform cryptographic operations on string expressions and files.

Inheritance

System.Object

X509CryptoAgent

Namespace: Org.X509Crypto

Assembly: EasyPKIView.dll

Syntax

public class X509CryptoAgent : IDisposable

Remarks

It is advisable to leverage an instance of this class in your method/module if you need to perform several cryptographic operations within the stack frame.

Constructors

X509CryptoAgent(String, X509Context)

X509CryptoAgent Constructor

Declaration

public X509CryptoAgent(string thumbprint, X509Context context)

Parameters

Type	Name	Description
System.String	thumbprint	The thumbprint of the encryption certificate. The certificate must be present in the CURRENTUSER store location
X509Context	context	The X509Context where the encryption certificate can be accessed

Fields

valid

Indicates whether the instantiated X509CryptoAgent object is bound to an available valid certificate and corresponding private key that is appropriate for encryption

Declaration

public bool valid

Field Value

Type	Description
System.Boolean

Properties

Context

The certificate store from which to load the encryption certificate and private key.

Declaration

public X509Context Context { get; }

Property Value

Type	Description
X509Context

Remarks

Possible values are X509Context.UserReadOnly or X509Context.
If not specified, default value is X509Context.UserReadOnly

Thumbprint

The thumbprint of the certificate used for cryptographic operations

Declaration

public string Thumbprint { get; }

Property Value

Type	Description
System.String

Methods

CertificateExists(X509Alias)

Indicates whether the encryption certificate referenced by the specified X509Alias exists in the alias context.

Declaration

public static bool CertificateExists(X509Alias Alias)

Parameters

Type	Name	Description
X509Alias	Alias	The X509Alias to check for encryption certificate existence

Returns

Type	Description
System.Boolean	true if the encryption certificate referenced in the X509Alias exists in the alias context

CertificateExists(String, X509Context)

Indicates whether the certificate with the specified thumbprint was found in the specified certificate store

Declaration

public static bool CertificateExists(string certThumbprint, X509Context Context)

Parameters

Type	Name	Description
System.String	certThumbprint	The certificate thumbprint value to search for (case-insensitive)
X509Context	Context	The certificate store from which to load the encryption certificate. Either CertStore.CurrentUser (default) or CertStore.LocalMachine

Returns

Type	Description
System.Boolean	True or False depending upon whether the certificate and corresponding private key was found in the certificate store

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context certStore = X509Context.UserReadOnly;

bool found;

using (X509CryptoAgent agent = new X509CryptoAgent(thumbprint, certStore))
{
    found = agent.CertificateExists(thumbprint, certStore);
}

DecryptFile(String, String)

Decrypts the specified ciphertext file

Declaration

public void DecryptFile(string cipherText, string plainText)

Parameters

Type	Name	Description
System.String	cipherText	Fully-qualified path to the encrypted file
System.String	plainText	Fully-qualified path in which to write the decrypted file

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context certStore = X509Context.UserReadOnly;

string ciphertextFilePath = @"C:\data\SSNs.txt.ctx";
string plaintextFilePath = @"C:\data\SSNs.txt";
using (X509CryptoAgent agent = new X509CryptoAgent(thumbprint, certStore))
{
    plaintext = agent.DecryptFile(ciphertextFilePath, plaintextFilePath);
}

DecryptFileToByteArray(String)

Decrypts a file and stores the payload in a byte array

Declaration

public byte[] DecryptFileToByteArray(string cipherText)

Parameters

Type	Name	Description
System.String	cipherText	The fully-qualified path to the encrypted file

Returns

Type	Description
System.Byte[]	Byte array containing the decrypted contents of the ciphertext file

Remarks

This method is implemented primarily to fascilitate re-encryption of a file when changing certificates

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context certStore = X509Context.UserReadOnly;

string ciphertextFilePath = @"C:\data\SSNs.txt.ctx";
byte[] plaintextBytes;

using (X509CryptoAgent agent = new X509CryptoAgent(thumbprint, certStore))
{
    plaintextBytes = agent.DecryptFileToByteArray(ciphertextFilePath);
}

DecryptText(String)

Decrypts the specified ciphertext expression

Declaration

public string DecryptText(string cipherText)

Parameters

Type	Name	Description
System.String	cipherText	Base64-encoded ciphertext expression

Returns

Type	Description
System.String	decrypted string expression

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context certStore = X509Context.UserReadOnly;

string ciphertext = File.ReadAllText(@"C:\data\connectionString.txt");
string plaintext;
using (X509CryptoAgent agent = new X509CryptoAgent(thumbprint, certStore))
{
    plaintext = agent.DecryptText(ciphertext);
}

DecryptTextFromFile(String)

Decrypts a ciphertext expression that is stored in a text file

Declaration

public string DecryptTextFromFile(string path)

Parameters

Type	Name	Description
System.String	path	The fully-qualified path to the file containing the ciphertext expression

Returns

Type	Description
System.String	decrypted text expression

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context certStore = X509Context.UserReadOnly;

string ciphertextFilePath = @"C:\data\connectionString.txt";
string plaintext;
using (X509CryptoAgent agent = new X509CryptoAgent(thumbprint, certStore))
{
    plaintext = agent.DecryptTextFromFile(ciphertextFilePath);
}

Dispose()

X509CryptoAgent Destructor

Declaration

public void Dispose()

EncryptFile(String, String)

Encrypts the specified plaintext file. Text and binary file types are supported.

Declaration

public void EncryptFile(string plainText, string cipherText)

Parameters

Type	Name	Description
System.String	plainText	Fully-qualified path of the file to be encrypted
System.String	cipherText	Fully-qualified path in which to write the encrypted file

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context certStore = X509Context.UserReadOnly;
string plaintextFilePath = @"C:\data\SSNs.txt";
string ciphertextFilePath = Path.GetFileNameWithoutExtension(plaintextFilePath)" + CRYPTO_ENCRYPTED_FILE_EXT;

using (X509CryptoAgent agent = new X509CryptoAgent(thumbprint, certStore))
{
    agent.EncryptFile(plaintextFilePath, ciphertextFilePath);
}

EncryptFileFromByteArray(Byte[], String)

Encrypts an array of bytes and stores the encrypted playload in the specified file path

Declaration

public void EncryptFileFromByteArray(byte[] memBytes, string cipherText)

Parameters

Type	Name	Description
System.Byte[]	memBytes	The byte array to encrypt
System.String	cipherText	The file path in which to store the encrypted payload

Remarks

This method is implemented primarily to fascilitate re-encryption of a file when changing certificates

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context certStore = X509Context.UserReadOnly;
byte[] fileBytes = File.ReadAllBytes(@"C:\data\example.txt");
string ciphertextFilePath = @"C:\data\example_encrypted.ctx";

using (X509CryptoAgent agent = new X509CryptoAgent(thumbprint, certStore))
{
    agent.EncryptFileFromByteArray(fileBytes, ciphertextFilePath);
}

EncryptText(String)

Encrypts the specified string expression

Declaration

public string EncryptText(string plainText)

Parameters

Type	Name	Description
System.String	plainText	Text expression to encrypt

Returns

Type	Description
System.String	Base64-encoded ciphertext expression

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context certStore = X509Context.UserReadOnly;

string plaintext = @"Hello world!";
string ciphertext;
using (X509CryptoAgent agent = new X509CryptoAgent(thumbprint, certStore))
{
    ciphertext = agent.EncryptText(plaintext);
}

ExportCert(String, X509Context, String)

Exports the public certificate corresponding to the specified certificate thumbprint to a Base64-encoded file

Declaration

public static void ExportCert(string thumbprint, X509Context Context, string path)

Parameters

Type	Name	Description
System.String	thumbprint	Thumbprint of the certificate to be exported
X509Context	Context	The X509Context where the certificate to be exported exists
System.String	path	The storage path to where the file containing the public certificate should be written

ExportPFX(String, X509Context, String, String)

Exports the encryption certificate and corresponding key pair to a file in PKCS#12 format

Declaration

public static void ExportPFX(string thumbprint, X509Context Context, string pfxPath, string password)

Parameters

Type	Name	Description
System.String	thumbprint	The thumbprint of the encryption certificate
X509Context	Context	The X509Context where the certificate and corresponding key pair exist
System.String	pfxPath	The path to where the PKCS#12 file should be written
System.String	password	The password which will protect the PKCS#12 file

ListAliases(X509Context)

Lists all aliases that are found in the specified X509Context

Declaration

public static string ListAliases(X509Context Context)

Parameters

Type	Name	Description
X509Context	Context	The X509Context from which to list existing aliases

Returns

Type	Description
System.String	Line-break-separated list of X509Alias details

ListCerts(X509Context, Boolean)

Lists the thumbprint value for all encryption certificates which exist in the specified store location. Certificates which do not have the "Key Encipherment" key usage flag set are not included in the list.

Declaration

public static string ListCerts(X509Context Context, bool includeExpired = false)

Parameters

Type	Name	Description
X509Context	Context	The X509Context from which to list certificates
System.Boolean	includeExpired	If true, expired certificates will be included in the resulting list

Returns

Type	Description
System.String	Line-break-separated list of certificate details

ReEncryptText(String, X509CryptoAgent)

Re-encrypts the specified ciphertext expression using a different X509CryptoAgent

Declaration

public string ReEncryptText(string ciphertext, X509CryptoAgent newAgent)

Parameters

Type	Name	Description
System.String	ciphertext	the ciphertext expression to be re-encrypted
X509CryptoAgent	newAgent	the X509CryptoAgent to be used to perform re-encryption

Returns

Type	Description
System.String