Class X509Utils

A static class which provides access to X509Crypto namespace functionality without instantiating a X509CryptoAgent object.

Inheritance

System.Object

X509Utils

Namespace: Org.X509Crypto

Assembly: EasyPKIView.dll

Syntax

public static class X509Utils : object

Fields

CRYPTO_DECRYPTED_FILE_EXT

Default file extension for files decrypted using the X509Crypto library (only used if the appropriate file extension cannot be inferred from the ciphertext file path

Declaration

public static readonly string CRYPTO_DECRYPTED_FILE_EXT

Field Value

Type	Description
System.String

CRYPTO_ENCRYPTED_FILE_EXT

Default file extension for files encrypted with the X509Crypto library

Declaration

public static readonly string CRYPTO_ENCRYPTED_FILE_EXT

Field Value

Type	Description
System.String

INVOKER_IS_ADMINISTRATOR

Indicates whether the invoking user is a local administrator on the system

Declaration

public static readonly bool INVOKER_IS_ADMINISTRATOR

Field Value

Type	Description
System.Boolean

Methods

DecryptFile(String, String, String, X509Context, Boolean)

Decrypts the specified encrypted file

Declaration

public static bool DecryptFile(string thumbprint, string ciphertextFilePath, string plaintextFilePath, X509Context Context, bool verbose = false)

Parameters

Type	Name	Description
System.String	thumbprint	The thumbprint of the certificate corresponding to the public key used to encrypt the file
System.String	ciphertextFilePath	The fully-qualified path of the encrypted file
System.String	plaintextFilePath	The fully-qualified path in which to write the decrypted file
X509Context	Context	The certificate store where the encryption certificate resides
System.Boolean	verbose	True enables verbose logging

Returns

Type	Description
System.Boolean	True or false depending upon whether the file decryption succeeded

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context certStore = X509Context.UserReadOnly;
string encryptedFilePath = @"C:\Data\accounts.csv.ctx";
bool success = X509Utils.DecryptFile(thumbprint, encryptedFilePath, certStore);

DecryptText(String, String, X509Context, Boolean)

Decrypts the specified ciphertext expression

Declaration

public static string DecryptText(string thumbprint, string ciphertext, X509Context Context, bool verbose = false)

Parameters

Type	Name	Description
System.String	thumbprint	The thumbprint of the certificate corresponding to the public key used to encrypt the file
System.String	ciphertext	The ciphertext expression to decrypt
X509Context	Context	The certificate store location where the specified private key resides
System.Boolean	verbose	True enables verbose logging

Returns

Type	Description
System.String	Plaintext string expression resulting from decryption of the specified ciphertext expression

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context Context = X509Context.UserReadOnly;
string ciphertext = File.ReadAllText(@"C:\data\connectionString.txt");
string plaintext = X509Utils.DecryptText(thumbprint, ciphertext, Context);

DeleteFile(String, Boolean, Boolean)

Deletes the specified file

Declaration

public static void DeleteFile(string filePath, bool complainIfNotFound = false, bool confirmDelete = false)

Parameters

Type	Name	Description
System.String	filePath	The path of the file to be deleted
System.Boolean	complainIfNotFound	If true, an exception is thrown if the file does not currently exist
System.Boolean	confirmDelete	If true, the file will be confirmed to no longer exist. If it still exists, an exception is thrown

EncryptFile(String, String, X509Context, String, Boolean)

Encrypts the specified file

Declaration

public static bool EncryptFile(string thumbprint, string plaintextFilePath, X509Context Context = null, string ciphertextFilePath = "", bool verbose = false)

Parameters

Type	Name	Description
System.String	thumbprint	The thumbprint of the certificate to use for encryption
System.String	plaintextFilePath	The fully-qualified path of the plaintext file (can be text or binary)
X509Context	Context	(Optional) The certificate store where the encryption certificate resides (Default: X509Context.UserReadOnly)
System.String	ciphertextFilePath	(Optional) The fully-qualified path in which to write the encrypted file (If not specified, the plaintext file path is appended with a ".ctx" extension)
System.Boolean	verbose	(Optional) True enables verbose logging

Returns

Type	Description
System.Boolean

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context certStore = X509Context.UserReadOnly
string plaintextFilePath = @"C:\Data\accounts.csv";
string ciphertextFilePath = 
bool success = X509Utils.EncryptFile(thumbprint, plaintextFilePath, certStore);

EncryptText(String, String, X509Context, Boolean)

Encrypts the specified plaintext expression

Declaration

public static string EncryptText(string thumbprint, string plaintext, X509Context Context, bool verbose = false)

Parameters

Type	Name	Description
System.String	thumbprint	The thumbprint of the certificate to use for encryption
System.String	plaintext	The plaintext expression to encrypt
X509Context	Context	The certificate store where the encryption certificate resides
System.Boolean	verbose	True enables verbose logging

Returns

Type	Description
System.String

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
X509Context certStore = X509Context.UserReadOnly;
string plaintext = @"Please encrypt this";
string ciphertext = X509Utils.EncryptText(thumbprint, plaintext, certStore);

ExportCert(String, String, X509Context, Boolean)

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

Declaration

public static string ExportCert(string certThumbprint, string exportPath, X509Context Context = null, bool verbose = false)

Parameters

Type	Name	Description
System.String	certThumbprint	Certificate thumbprint (case-insensitive)
System.String	exportPath	Fully-qualified path to where the Base64-encoded file should be written (a ".cer" file extension will be added if no file extension is detected)
X509Context	Context	(Optional) The certificate store where the encryption certificate resides (Default: X509Context.UserReadOnly)
System.Boolean	verbose	True enables verbose logging

Returns

Type	Description
System.String	The fully-qualified path to where the Base64-encoded certificate file was ultimately written

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
string exportPath = @"C:\data\cert";
X509Context certStore = X509Context.UserReadOnly;
string finalExportPath = X509Utils.ExportCert(thumbprint, exportPath, certStore);
//finalExportPath is @"C:\data\cert.cer"

ExportPFX(String, String, String, X509Context, Boolean)

Exports the certificate and public/private key pair corresponding to the specified certificate thumbprint to a PKCS#12 bundle written to the specified file path

Declaration

public static string ExportPFX(string certThumbprint, string exportPath, string password, X509Context Context = null, bool verbose = false)

Parameters

Type	Name	Description
System.String	certThumbprint	Certificate thumbprint (case-insensitive)
System.String	exportPath	Fully-qualified path to where the PKCS#12 bundle file should be written (a ".pfx" file extension will be added if no file extension is detected)
System.String	password	Password to protect the private key once stored in the PKCS#12 bundle file
X509Context	Context	(Optional) The certificate store where the encryption certificate resides (Default: X509Context.UserReadOnly)
System.Boolean	verbose	(Optional) True enables verbose logging (Default: false)

Returns

Type	Description
System.String	The fully-qualified path to where the PKCS#12 bundle file was ultimately written

Examples

string thumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
string exportPath = @"C:\data\bundle";
string password = @"0n3T!m3U$e";
X509Context certStore = X509Context.UserReadOnly;
string finalExportPath = X509Utils.ExportPFX(thumbprint, exportPath, password, certStore);
//finalExportPath is @"C:\data\bundle.pfx"

FormatThumbprint(String, Boolean)

Removes all but hexidecimal characters (0-9, a-f) from the indicated text expression

Declaration

public static string FormatThumbprint(string thumbprint, bool verbose = false)

Parameters

Type	Name	Description
System.String	thumbprint	string containing a thumbprint value
System.Boolean	verbose	True enables verbose logging

Returns

Type	Description
System.String	Text expression with all non hexidecimal characters removed

Examples

string thumb = @"cc dc 67 3c 40 eb b2 a4 33 30 0c 0c 8a 2b a6 f4 43 da 56 88";
string formattedThumb = X509Utils.FormatThumbprint(thumb);
//formattedThumb = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688"

InstallCert(String, SecureString, X509Context)

Installs an encryption certificate and associated key pair in the specified X509Context

Declaration

public static string InstallCert(string infile, SecureString PfxPassword, X509Context Context)

Parameters

Type	Name	Description
System.String	infile	The PKCS#12 (usually with a .pfx or .p12 extension) containing the bundled certificate and key pair
SecureString	PfxPassword	The password to unlock the PKCS#12 file
X509Context	Context	The X509Context in which to place the certificate and key pair

Returns

Type	Description
System.String

ListCerts(X509Context, Boolean)

Lists the thumbprint value for each certificate in the specified store location which include "Key Encipherment" in its Key Usage extension

Declaration

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

Parameters

Type	Name	Description
X509Context	Context	Store location from which to list certificate details (Either UserReadOnly or SystemReadOnly)
System.Boolean	allowExpired	If set to True, expired certificates will be included in the output (Note that .NET will not perform cryptographic operations using a certificate which is not within its validity period)

Returns

Type	Description
System.String	A string expression listing all available certificate thumbprints and their expiration dates

Examples

string availableCerts = X509Utils.ListCerts(X509Context, Boolean)(UserReadOnly);

LoadTextFromFile(String)

Loads the contents of a text file into a string expression

Declaration

public static string LoadTextFromFile(string path)

Parameters

Type	Name	Description
System.String	path	The fully-qualified path to the file from which contents are being loaded

Returns

Type	Description
System.String	The contents of the specified text file as a string expression

MethodName()

Gets the name of the calling method

Declaration

public static string MethodName()

Returns

Type	Description
System.String	The name of the calling method

ReEncryptFile(X509Alias, X509Alias, String)

Re-encrypts an encrypted file using a different

Declaration

public static void ReEncryptFile(X509Alias OldAlias, X509Alias NewAlias, string ciphertextFilePath)

Parameters

Type	Name	Description
X509Alias	OldAlias	The old X509Alias that was originally used to encrypt the file
X509Alias	NewAlias	The new X509Alias that will be used to re-encrypt the file
System.String	ciphertextFilePath	The path to the ciphertext file to be re-encrypted

ReEncryptFile(String, String, String, X509Context, X509Context, Boolean)

Re-encrypts an encrypted file using a different encryption certificate

Declaration

public static void ReEncryptFile(string oldThumbprint, string newThumbprint, string ciphertextFilePath, X509Context OldContext = null, X509Context NewContext = null, bool verbose = false)

Parameters

Type	Name	Description
System.String	oldThumbprint	The thumbprint of the old certificate used for prior encryption
System.String	newThumbprint	The thumbprint of the new certificate to be used for re-encryption
System.String	ciphertextFilePath	The fully-qualified path to the ciphertext file to be re-encrypted
X509Context	OldContext	(Optional) The certificate store where the old encryption certificate resides (Default: X509Context.UserReadOnly)
X509Context	NewContext	(Optional) The certificate store where the new encryption certificate resides (Default: X509Context.UserReadOnly)
System.Boolean	verbose	(Optional) True enables verbose logging (Default: false)

Examples

string oldThumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
string newThumbprint = @"0e7e327aab74e47a702c02d90c659da1115b29f7";
string encryptedFilePath = @"C:\data\accounts.csv.ctx";
X509Utils.ReEncryptFile"(oldThumbprint, newThumbprint, encryptedFilePath);

ReEncryptText(String, String, String, X509Context, X509Context, Boolean)

Re-encrypts a ciphertext expression using a different certificate

Declaration

public static string ReEncryptText(string oldThumbprint, string newThumbprint, string ciphertext, X509Context OldContext = null, X509Context NewContext = null, bool verbose = false)

Parameters

Type	Name	Description
System.String	oldThumbprint	The thumbprint of the old certificate used for prior encryption
System.String	newThumbprint	The thumbprint of the new certificate to be used for re-encryption
System.String	ciphertext	The ciphertext expression to be re-encrypted
X509Context	OldContext	(Optional) The X509Context where the old encryption certificate resides (Default: X509Context.UserReadOnly)
X509Context	NewContext	(Optional) The X509Context where the new encryption certificate resides (Default: X509Context.UserReadOnly)
System.Boolean	verbose	(Optional) True enables verbose logging (Default: false)

Returns

Type	Description
System.String	The text expression re-encrypted using the new certificate

Examples

string oldThumbprint = @"ccdc673c40ebb2a433300c0c8a2ba6f443da5688";
string newThumbprint = @"0e7e327aab74e47a702c02d90c659da1115b29f7";
string ciphertext = File.ReadAllText(@"C:\data\connectionString.txt");
string updatedCiphertext = X509Utils.ReEncryptText(oldThumbprint, newThumbprint, ciphertext);
File.WriteAllText(@"C:\data\connectionString.txt", updatedCiphertext);

WipeFile(String, Int32)

Overwrites a file (as stored on disk) with random bits in order to prevent forensic recovery of the data

Declaration

public static void WipeFile(string filePath, int timesToWrite)

Parameters

Type	Name	Description
System.String	filePath	The fully-qualified path of the file to wipe from disk
System.Int32	timesToWrite	The number of times to overwrite the disk sectors where the file is/was stored

Examples

string path = @"C:\temp\SSNs.txt";
int timesToWrite = 10;
X509Utils.WipeFile(String, Int32)(path, timesToWrite);