Getting Started with CertMgr

CertMgr offers a simple interface to manage X.509 certificates and cryptographic keys. It is found in many of our toolkits, including core IPWorks. This guide provides simple examples of common CertMgr tasks, broken into the categories below.

Create
Read & List
Convert
Advanced (OCSP, CRL, etc.)

Information about CertMgr's API can be found in the documentation.

Creating Certificates and Keys

Depending on the type of certificate or key needed call the CreateCertificate, IssueCertificate, or ExportCertificate method after setting any relevant properties. Below are examples showing how to create common certificate and key types.

Create a self-signed certificate in the Windows Store


// cstUser accesses the store for the current user.
// cstMachine accesses the store for the current machine/system.
Certmgr cm = new Certmgr();
cm.CertStore = "MY";
cm.CertStoreType = CertStoreTypes.cstUser;
cm.CreateCertificate("CN=www.myserver.com", 1);

Create a self-signed certificate in a PEM saved on disk


Certmgr cm = new Certmgr();
cm.CertStoreType = CertStoreTypes.cstPEMKeyFile;
cm.CertStore = "C:\\path\\to\\your\\certstore.pem";
Console.WriteLine(cm.CreateCertificate("CN=www.myserver.com", 1)); // PEM also returned from CreateCertificate

Create a self-signed certificate in a PEM stored in memory


Certmgr cm = new Certmgr();
cm.CertStoreType = CertStoreTypes.cstPEMKeyBlob;
cm.CertStore = "C:\\path\\to\\your\\certstore.pem";
Console.WriteLine(cm.CreateCertificate("CN=www.myserver.com", 1)); // PEM returned from CreateCertificate
MemoryStream myPEMBlob = new MemoryStream(cm.CertStoreB); // PEM also held in CertStore/CertStoreB

Create a self-signed certificate in a PFX saved on disk


Certmgr cm = new Certmgr();
cm.CertStoreType = CertStoreTypes.cstPFXFile;
cm.CertStore = "C:\\path\\to\\your\\certstore.pfx";
cm.CertStorePassword = "optional password";
cm.CreateCertificate("CN=www.myserver.com", 1);

Create a self-signed certificate in a PFX stored in memory


Certmgr cm = new Certmgr();
cm.CertStoreType = CertStoreTypes.cstPFXBlob;
cm.CertStorePassword = "optional password";
cm.CreateCertificate("CN=www.myserver.com", 1);
MemoryStream myPFXBlob = new MemoryStream(cm.CertStoreB); // PFX is held in CertStore/CertStoreB

Issue a certificate from another certificate


Certmgr cm = new Certmgr();
cm.Cert = new Certificate(CertStoreTypes.cstUser, "CA", "ca-password", "CN=Intermediate Signing Authority, O=Professionals, Inc.");
cm.IssueCertificate("CN=www.professionals.net", 1);

Create a Certificate Signing Request (CSR)


Certmgr cm = new Certmgr();
cm.CreateKey("MyKeyName");
cm.Config("CertSignatureAlgorithm=sha256");
cm.Config("RequestSubjectAltNames=dns:myserver.com,email:support@server.com");
string MyCSR = cm.GenerateCSR("CN=www.myserver.com", "MyKeyName");

Sign a Certificate Signing Request (CSR)


Certmgr cm = new Certmgr();
cm.Cert = new Certificate(CertStoreTypes.cstUser, "CA", "ca-password", "CN=Intermediate Signing Authority, O=Professionals, Inc.");
string MySignedCSR = cm.SignCSR(System.Text.Encoding.ASCII.GetBytes(MyCSR), 2);

Create an OpenSSH key


Certmgr cm = new Certmgr();
cm.CertStoreType = CertStoreTypes.cstPFXBlob; // Create temporarily in memory
cm.CreateCertificate("cn=dummy subject", 1); // Subject and Serial do not matter
cm.ExportFormat = "OpenSSH";
cm.ExportPrivateKey = false;
cm.ExportCertificate("C:\\path\\to\\your.pub", "");
cm.ExportPrivateKey = true;
cm.ExportCertificate("C:\\path\\to\\your.priv", "password");

Create an SSH2-formatted key


Certmgr cm = new Certmgr();
cm.CertStoreType = CertStoreTypes.cstPFXBlob; // Create temporarily in memory
cm.CreateCertificate("cn=dummy subject", 1); // Subject and Serial do not matter
cm.ExportFormat = "SSH2PublicKey";
cm.ExportCertificate("C:\\temp\\certmgr\\ssh2.pub.txt", "");
cm.ExportFormat = "SSH2PrivateKey";
cm.ExportCertificate("C:\\temp\\certmgr\\ssh2.priv.txt", "password");

Create a PPK


Certmgr cm = new Certmgr();
cm.CertStoreType = CertStoreTypes.cstPFXBlob; // Create temporarily in memory
cm.CreateCertificate("cn=dummy subject", 1); // Subject and Serial do not matter
cm.ExportFormat = "PPK";
cm.ExportCertificate("C:\\path\\to\\your.ppk", "password");

Export to memory


Certmgr cm = new Certmgr();
cm.CertStoreType = CertStoreTypes.cstPFXBlob; // Create temporarily in memory
cm.CreateCertificate("cn=dummy subject", 1); // Subject and Serial do not matter
cm.ExportFormat = "PPK";
cm.ExportCertificate("", "password"); // Leave filePath empty
MemoryStream myPPKBlob = new MemoryStream(cm.ExportedCertB); // PPK is held in ExportedCert/ExportedCertB

Reading & Listing Certificates

Single certificates or keys can be read by passing their data to a Certificate type. In most cases setting CertStoreType to cstAuto will automatically detect the certificate or key type. In some cases it can help to explicitly set the type. Call the ListStoreCertificates method to get a list of all certificates in CertStore. Each certificate will cause the CertList event to fire. Call ListMachineStores or ListCertificateStores to list all certificate stores on the current machine or for the current user, respectively. The StoreList event will fire for each found store. This information is also returned as a machine-readable string from the method itself.

Read a single certificate or key

Set CertSubject to choose a single certificate from a CertStore. Use * if there is only one or the choice is inconsequential.


// Load SSH2 private key
Certificate cert = new Certificate(CertStoreTypes.cstAuto, "C:\\path\\to\\ssh2.priv", "password", "*");
// Load X.509 certificate from PFX
Certificate cert = new Certificate(CertStoreTypes.cstAuto, "C:\\path\\to\\server.pfx", "password", "CN=myserver.net");
// Load PPK from memory
Certificate cert = new Certificate(CertStoreTypes.cstPPKBlob, myPPKBlob, "password", "*");

List certificates in a Windows store


Certmgr cm = new Certmgr();
cm.OnCertList += (obj, ev) =>
{
  Console.WriteLine("-----Certificate Found----");
  Console.WriteLine("  Issued By: " + ev.CertIssuer);
  Console.WriteLine("  Issued To: " + ev.CertSubject);
};
cm.CertStoreType = CertStoreTypes.cstUser;
cm.CertStore = "MY";
cm.ListStoreCertificates();

List certificates in a PFX


Certmgr cm = new Certmgr();
cm.OnCertList += (obj, ev) =>
{
  Console.WriteLine("-----Certificate Found----");
  Console.WriteLine("  Issued By: " + ev.CertIssuer);
  Console.WriteLine("  Issued To: " + ev.CertSubject);
};
cm.CertStoreType = CertStoreTypes.cstPFXBlob;
cm.CertStoreB = myPFXBlob; // byte[]
cm.CertStorePassword = "optional password";
cm.ListStoreCertificates();

List current machine stores


Certmgr cm = new Certmgr();
cm.OnStoreList += (obj, ev) => Console.WriteLine(ev.CertStore);
cm.ListMachineStores();

List current user's stores


Certmgr cm = new Certmgr();
cm.OnStoreList += (obj, ev) => Console.WriteLine(ev.CertStore);
cm.ListCertificateStores();

Converting Certificates & Keys

Convert an existing certificate or key by loading it into a Certificate type and passing it to the Cert property. Set ExportFormat and callExportCertificate. Both input and output can be either from disk or memory.


Certmgr cm = new Certmgr();
cm.Cert = new Certificate(CertStoreTypes.cstAuto, myPPKBlob, "password", "*");
cm.ExportFormat = "PFX";
// Export to file
cm.ExportCertificate("C:\\temp\\certmgr\\test.pfx", "new-password");
// Export to memory
cm.ExportCertificate("", "new-password");
MemoryStream ms = new MemoryStream(cm.ExportedCertB);

Advanced (OCSP, CRL, etc.)

Check if a certificate has been revoked (CRL)


Certmgr cm = new Certmgr();
cm.Cert = new Certificate("C:/path/to/certificate.cer");
if (cm.Config("HasCRL").ToLower() == "true")
{
  Console.WriteLine("CRL found in certificate. Checking...");
  try
  {
    cm.Config("CheckCRL"); // Exception thrown if certificate is revoked or check failed.
    Console.WriteLine("CRL check passed.");
  }
  catch(Exception ex)
  {
    Console.WriteLine("Problem with CRL: " + ex.ToString());
  }
}
else
{
  Console.WriteLine("No CRL in certificate.");
}

Check if a certificate has been revoked (OCSP)


Certmgr cm = new Certmgr();
cm.Cert = new Certificate("C:/path/to/certificate.cer");
if (cm.Config("HasOCSP").ToLower() == "true")
{
  Console.WriteLine("OCSP found in certificate. Checking...");
  try
  {
    cm.Config("CheckOCSP"); // Exception thrown if certificate is revoked or check failed.
    Console.WriteLine("OCSP check passed.");
  }
  catch(Exception ex)
  {
    Console.WriteLine("Problem with OCSP: " + ex.ToString());
  }
}
else
{
  Console.WriteLine("No OCSP in certificate.");
}

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.