The PKIFv2 C# Interface

The PKIF library includes a complete set of C# wrapper classes. The C# wrappers allow convenient access to the full power of PKIF through the .NET platform. These classes access PKIF using the Platform Invocation Services (PInvoke) interface. PInvoke is part of the ECMA/ISO C# specification.

Supported Platforms
Installation and Usage

Creating mediators and colleagues

Creating new mediators
Creating new colleagues
Destroying mediators/colleagues

Accessing mediators, colleagues, and interfaces

Functions to retrieve build and validate interfaces from IPKIFMediator interface
Functions to retrieve a mediator object from IPKIFMediator interface
Functions to retrieve an IPKIFColleague interface object given a colleague class object
Functions to obtain IPKIFMediator interface object given a mediator class object

Extracting extensions and attributes from CMS objects

Functions to retrieve extensions from a x509 certificate object
Functions to retrieve extensions from a CRL object
Functions to retrieve extensions CRLEntry object
Functions to retrieve unsigned attributes from SignerInfo object
Functions to retrieve signed attributes from SignerInfo
Functions that convert a specific attribute object into CPKIFAttributePtr object

Deleting crypto and hash context interfaces

API Documentation
Notes on C# Types
Exception Handling
PKIF C# Code Example
Additional References

Supported Platforms

The PKIF C# interface has been tested with Microsoft Visual Studio 2005 and the Microsoft .NET Framework version 2.0 running under Microsoft Windows XP Professional (32 bit edition). There are currently no known issues with the C# interface when operating in the above mentioned environment. The C# wrappers are implemented using the PInvoke interface. In theory, this should allow them to be easily ported to the Linux, Solaris, and Apple platforms using the Mono and DotGNU Portable.NET environments. However, these enviroments are currently unsupported and untested. Your mileage may vary.

Installation and Usage

The PKIF C# interface classes are included in the default PKIF installation. Under Microsoft Visual 2005, the C# wrappers can be used by adding "PKIF.Net.dll" as a project Reference.

There are several diffrences between the use of PKIFv2 when using C++ and C#.

Global PKIFv2 functions can be accessed using pkif_module. For example to create a default mediator set the following code can be used:

IPKIFMediator m = pkif_module.MakeDefaultMediator();

To create a stand alone mediator or a colleague make_NewMediatorName functions. After creating a mediator or a colleague in this manner it has to be freed using Examples section contains several examples of creationg a mediator/colleague collection.

Creating mediators and colleagues

Mediators and colleagues have to be greated and destroyed using special functions provided in pkif_module.

Creating new mediators

IPKIFMediator make_NewCPKIFCryptoMediator2(bool b)
IPKIFMediator make_NewCPKIFCacheMediator2(bool b)
IPKIFMediator make_NewCPKIFRevocationStatusMediator2(bool b)
IPKIFMediator make_NewCPKIFPathProcessingMediator2(bool b)

Creating new colleagues

IPKIFColleague make_NewCPKIFCAPI2()
IPKIFColleague make_NewCPKIFCAPI2(string provider, int provType, int sysStoRegLoc)
IPKIFColleague make_NewCPKIFNSS(string dbName)
IPKIFColleague make_NewCPKIFCAPIRaw()
IPKIFColleague make_NewCPKIFNSSRaw()
IPKIFColleague make_NewCPKIFCAPIRepository2()
IPKIFColleague make_NewCPKIFCAPIRepository2(int sysStoRegLoc, string store)
IPKIFColleague make_NewCPKIFNSSRepository(string dbName)
IPKIFColleague make_NewCPKIFCAPITrustStore2()
IPKIFColleague make_NewCPKIFCAPITrustStore2(int sysStoRegLoc, string store)
IPKIFColleague make_NewCPKIFNSSTrustStore(string dbName)
IPKIFColleague make_NewCPKIFCAPITrustRootCRLRepository2()
IPKIFColleague make_NewCPKIFCAPITrustRootCRLRepository2(int sysStoRegLoc, string store)
IPKIFColleague make_NewCPKIFPathValidator2()
IPKIFColleague make_NewCPKIFPathBuilder2()
IPKIFColleague make_NewCPKIFPathBuildAndValidate()
IPKIFColleague make_NewCPKIFOCSPChecker()
IPKIFColleague make_NewCPKIFX509CRLChecker()
IPKIFColleague make_NewSimpleRootStore()
IPKIFColleague make_NewSimpleCertCache()
IPKIFColleague make_NewSimpleCRLCache()
IPKIFColleague make_NewCPKIFLDAPRepository()
IPKIFColleague make_NewCPKIFNSSCRLUpdate(string dbName)
IPKIFColleague make_NewCPKIFNSSCertUpdate(string dbName)
IPKIFColleague make_NewCPKIFCAPICertUpdate2()
IPKIFColleague make_NewCPKIFCAPICRLUpdate2()

Destroying mediators/colleagues

The following functions are used to destroy mediators and colleagues.

void Delete_IPKIFMediator(IPKIFMediator i)
void Delete_IPKIFColleague(IPKIFColleague i)

Accessing mediators, colleagues, and interfaces

PKIFv2 C# interface provides various functions to access mediators, colleagues, and interfaces. These functions were added because C# does not support multiple inheritance so the only way to access mediator, colleagues and interfaces is through these functions. All the functions can be accessed through pkif_module.

Functions to retrieve build and validate interfaces from IPKIFMediator interface:

IPKIFPathBuild Get_IPKIFPathBuild(IPKIFMediator m)
IPKIFPathValidate Get_IPKIFPathValidate(IPKIFMediator m)
IPKIFPathBuildAndValidate Get_IPKIFPathBuildAndValidate(IPKIFMediator m)

Functions to retrieve a mediator object from IPKIFMediator interface:

CPKIFRevocationStatusMediator2 Get_RevocationStatusMediator(IPKIFMediator m)
CPKIFCacheMediator2 Get_CacheMediator(IPKIFMediator m)
CPKIFCryptoMediator2 Get_CryptoMediator(IPKIFMediator m)
CPKIFPathProcessingMediator2 Get_PathProcessingMediator(IPKIFMediator m)

Functions to retrieve an IPKIFColleague interface object given a colleague class object:

IPKIFColleague Get_LDAPAsColleague(CPKIFLDAPRepository l)
IPKIFColleague Get_OCSPCheckerColleague(CPKIFOCSPChecker l)
IPKIFColleague Get_SimpleRootStoreColleague(SimpleRootStore l)
IPKIFColleague Get_SimpleCertCacheColleague(SimpleCertCache l)
IPKIFColleague Get_SimpleCRLCacheColleague(SimpleCRLCache l)
IPKIFColleague Get_CPKIFCAPI2Colleague(CPKIFCAPI2 l)
IPKIFColleague Get_CPKIFCAPIRawColleague(CPKIFCAPIRaw l)
IPKIFColleague Get_CPKIFCAPIRepository2Colleague(CPKIFCAPIRepository2 l)
IPKIFColleague Get_CPKIFCAPITrustStore2Colleague(CPKIFCAPITrustStore2 l)
IPKIFColleague Get_CPKIFCAPITrustRootCRLRepository2Colleague(CPKIFCAPITrustRootCRLRepository2 l)
IPKIFColleague Get_CPKIFPathValidator2Colleague(CPKIFPathValidator2 l)
IPKIFColleague Get_CPKIFPathBuilder2Colleague(CPKIFPathBuilder2 l)
IPKIFColleague Get_CPKIFPathBuildAndValidateColleague(CPKIFPathBuildAndValidate l)
IPKIFColleague Get_CPKIFX509CRLCheckerColleague(CPKIFX509CRLChecker l)
IPKIFColleague Get_CPKIFNSSRepositoryColleague(CPKIFNSSRepository l)
IPKIFColleague Get_CPKIFNSSTrustStoreColleague(CPKIFNSSTrustStore l)
IPKIFColleague Get_CPKIFNSSCRLUpdateColleague(CPKIFNSSCRLUpdate l)
IPKIFColleague Get_CPKIFNSSCertUpdateColleague(CPKIFNSSCertUpdate l)
IPKIFColleague Get_CPKIFCAPICRLUpdate2Colleague(CPKIFCAPICRLUpdate2 l)
IPKIFColleague Get_CPKIFCAPICertUpdate2Colleague(CPKIFCAPICertUpdate2 l)

Functions to obtain IPKIFMediator interface object given a mediator class object:

IPKIFMediator Get_CPKIFCryptoMediator2Mediator(CPKIFCryptoMediator2 l)
IPKIFMediator Get_CPKIFCacheMediator2Mediator(CPKIFCacheMediator2 l)
IPKIFMediator Get_CPKIFRevocationStatusMediator2Mediator(CPKIFRevocationStatusMediator2 l)
IPKIFMediator Get_CPKIFPathProcessingMediator2Mediator(CPKIFPathProcessingMediator2 l)

Extracting extensions and attributes from CMS objects

To extract extensions and attributes several functions can be found in pkif_module.

Functions to retrieve extensions from a x509 certificate object:

CPKIFKeyUsagePtr Get_KeyUsageExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFAuthorityKeyIdentifierPtr Get_AuthorityKeyIdentifierExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFSubjectKeyIdentifierPtr Get_SubjectKeyIdentifierExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFPrivateKeyUsagePtr Get_PrivateKeyUsageExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFPolicyInformationSetPtr Get_PolicyInformationSetExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFPolicyMappingsPtr Get_PolicyMappingsExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFSubjectAltNamePtr Get_SubjectAltNameExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFIssuerAltNamePtr Get_IssuerAltNameExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFBasicConstraintsPtr Get_BasicConstraintsExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFNameConstraintsPtr Get_NameConstraintsExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFPolicyConstraintsPtr Get_PolicyConstraintsExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFExtendedKeyUsagePtr Get_ExtendedKeyUsageExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFCRLDistributionPointsPtr Get_CRLDistributionPointsExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFInhibitAnyPolicyPtr Get_InhibitAnyPolicyExtensionFromCert(CPKIFCertificatePtr cert)
CPKIFAuthorityInfoAccessPtr Get_AuthorityInfoAccessExtensionFromCert(CPKIFCertificatePtr cert)

Functions to retrieve extensions from a CRL object:

CPKIFAuthorityKeyIdentifierPtr Get_AuthorityKeyIdentifierExtensionFromCRL(CPKIFCRLPtr crl)
CPKIFCRLNumberPtr Get_CRLNumberExtensionFromCRL(CPKIFCRLPtr crl)
CPKIFIssuerAltNamePtr Get_IssuerAltNameExtensionFromCRL(CPKIFCRLPtr crl)
CPKIFDeltaCRLIndicatorPtr Get_DeltaCRLIndicatorExtensionFromCRL(CPKIFCRLPtr crl)
CPKIFIssuingDistributionPointPtr Get_IssuingDistributionPointExtensionFromCRL(CPKIFCRLPtr crl)
CPKIFFreshestCRLPtr Get_FreshestCRLExtensionFromCRL(CPKIFCRLPtr crl)

Functions to retrieve extensions CRLEntry object:

CPKIFHoldInstructionCodePtr Get_HoldInstructionCodeExtensionFromCRLEntry(CPKIFCRLEntryPtr crlEntry)
CPKIFInvalidityDatePtr Get_InvalidityDateExtensionFromCRLEntry(CPKIFCRLEntryPtr crlEntry)
CPKIFCertificateIssuerPtr Get_CertificateIssuerFromCRLEntry(CPKIFCRLEntryPtr crlEntry)

Functions to retrieve unsigned attributes from SignerInfo object:

CPKIFContentTypeAttributePtr Get_UnsignedContentTypeAttributeFromSignerInfo(CPKIFSignerInfoPtr si)
CPKIFMessageDigestAttributePtr Get_UnsignedMessageDigestAttributeFromSignerInfo(CPKIFSignerInfoPtr si)
CPKIFSigningTimeAttributePtr Get_UnsignedSigningTimeAttributeFromSignerInfo(CPKIFSignerInfoPtr si)
CPKIFTimestampAttributePtr Get_UnsignedTimestampAttributeFromSignerInfo(CPKIFSignerInfoPtr si)
CPKIFCountersignatureAttributePtr Get_UnsignedCountersignatureAttributeFromSignerInfo(CPKIFSignerInfoPtr si)

Functions to retrieve signed attributes from SignerInfo:

CPKIFContentTypeAttributePtr Get_SignedContentTypeAttributeFromSignerInfo(CPKIFSignerInfoPtr si)
CPKIFMessageDigestAttributePtr Get_SignedMessageDigestAttributeFromSignerInfo(CPKIFSignerInfoPtr si)
CPKIFSigningTimeAttributePtr Get_SignedSigningTimeAttributeFromSignerInfo(CPKIFSignerInfoPtr si)
CPKIFTimestampAttributePtr Get_SignedTimestampAttributeFromSignerInfo(CPKIFSignerInfoPtr si)
CPKIFCountersignatureAttributePtr Get_SignedCountersignatureAttributeFromSignerInfo(CPKIFSignerInfoPtr si)

Functions that convert a specific attribute object into CPKIFAttributePtr:

CPKIFAttributePtr Cast_CPKIFTimestampAttributePtrToCPKIFAttributePtr(CPKIFTimestampAttributePtr tsa)
CPKIFAttributePtr Cast_CPKIFSigningTimeAttributePtrToCPKIFAttributePtr(CPKIFSigningTimeAttributePtr tsa)
CPKIFAttributePtr Cast_CPKIFMessageDigestAttributePtrToCPKIFAttributePtr(CPKIFMessageDigestAttributePtr tsa)
CPKIFAttributePtr Cast_CPKIFCountersignatureAttributePtrToCPKIFAttributePtr(CPKIFCountersignatureAttributePtr tsa)
CPKIFAttributePtr Cast_CPKIFContentTypeAttributePtrToCPKIFAttributePtr(CPKIFContentTypeAttributePtr tsa)

Deleting crypto and hash context interfaces

IPKIFRawCryptContext, IPKIFHashContext, and IPKIFCryptContext objects must be freed after use. To free these object the following functios are used:

void Delete_IPKIFRawCryptContext(IPKIFRawCryptContext i)
void Delete_IPKIFHashContext(IPKIFHashContext i)
void Delete_IPKIFCryptContext(IPKIFCryptContext i)

All these functions can be accessed through pkif_module.

API Documentation

The PKIF C# interface is implemented as a set of thin C# wrappers that access PKIF via PInvoke. With the exception of language specific types (numeric types, character types, etc), every effort has been made to maintain full API compatibility between the core PKIF library and the C# interface wrapper classes. As a result, the current PKIF documentation is applicable to the PKIF C# interface.

Notes on C# Types

Smart pointers used in C++ implementation of PKIFv2 are also found in C#. They can be identified by Ptr suffix.

To create a smart pointer make_SmartPointerNamePtr() is used. For example to create CPKIFCertificatePtr use the following code:

CPKIFCertificatePtr cert = pkif_module.make_CPKIFCertificatePtr();

All the make_ functions can be accessed through pkif_module.