SecureBlackbox 2020 .NET Edition

Questions / Feedback?

CertificateManager Component

Properties   Methods   Events   Configuration Settings   Errors  

The CertificateManager component supports importing, exporting, and generating X.509 certificates.

Syntax

nsoftware.SecureBlackbox.Certificatemanager

Remarks

Usage of this component includes importing and exporting certificates and keys in various formats, as well as certificate generation.

Loading certificates

In vast majority of SecureBlackbox-powered projects, this component is used to import certificates from files or memory objects for further use in other components, like PDFSigner.

To load a certificate from a file, use the ImportFromFile method. This method supports all existing certificate formats, including PFX, PEM, DER, and P7B. Note that keys contained in PFX and PEM certificates are often encrypted with a password, so you will likely need to provide one for the certificate to be loaded correctly. You can either provide the password via the method's parameter, or provide it on-demand by subscribing to the PasswordNeeded event.

Alternatively, you can use ImportCert to load a certificate from a different type of media, such as a database.

If your certificate and its private key are stored in separate files or buffers - which is often the case where PEM or DER format is used - please load the certificate with the ImportFromFile method first, and then add the key to it with a separate call to the ImportKeyFromFile method. You can mix and match the certificate and key formats in this case; CertificateManager will handle this automatically.

Note that CertificateManager can only keep one certificate at a time. If your PFX or PEM file contains more than one certificate, use CertificateStorage component to load it instead.

Generating certificates

You can use CertificateManager to generate your own certificates. To generate a certificate, please follow the below steps:
  • set all the needed certificate properties - for example, its subject, serial number, and validity period - via the Certificate property.
  • load the CA certificate to a different CertificateManager object, and assign it to the CACertificate property. Note that the CA certificate should have an associated private key. Alternatively, the CA certificate can be loaded using a CertificateStorage object, which allows to import it from a hardware device or a system store.

    Note: you do not need to load and set the CA certificate if generating a self-signed certificate.

  • Call Generate to generate a new keypair and wrap it into a certificate.
  • Save the certificate using ExportToFile or ExportCert methods.

    Note: take care to choose a format that supports storing private keys. If you do not save the new private key at this stage, you won't be able to recover it later.

    Note: you can save the private key separately using the ExportKey method.

Note: you can use the GetSampleCert shortcut to generate a simple certificate for test or debug purposes.

Generating certificate requests

Apart from certificates, CertificateManager can generate certificate requests (PKCS10). The procedure is the same as when generating certificates. The only difference is that you need to use CertificateRequest object to set up the certificate request parameters, and GenerateCSR method to generate the request. You can then save the resulting request to a file using the ExportCSR method.

Property List


The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

CACertificateA container for the CA certificate.
CertificateA container for the certificate object.
CertificateRequestA container for the certificate request object.
ExternalCryptoProvides access to external signing and DC parameters.

Method List


The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

ConfigSets or retrieves a configuration setting.
DownloadDownloads a certificate from a remote location.
ExportCertExports the certificate in the chosen format.
ExportCSRExports a Certificate Signing Request (CSR).
ExportKeyExports the certificate's private key.
ExportKeyToFileExports the private key to a file in the chosen format.
ExportKeyToStreamSaves the private key to a stream.
ExportToFileExports the certificate to a file.
ExportToStreamExports the certificate to a stream.
GenerateGenerates a new certificate.
GenerateAsyncBeginInitiates asynchronous (DC) certificate generation.
GenerateAsyncEndCompletes asynchronous certificate generation.
GenerateCSRCreates a new certificate signing request (CSR).
GenerateExternalGenerates a new certificate with an external signing device.
GetSampleCertGenerates a sample certificate for the specified purpose.
ImportCertImports a certificate.
ImportFromFileLoads a certificate from a file.
ImportFromStreamLoads a certificate from a stream.
ImportKeyImports a private key.
ImportKeyFromFileImports a private key from a file.
ImportKeyFromStreamImports a private key from a stream.
UpdateRenews the certificate.
ValidateValidates the certificate.

Event List


The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

ErrorInformation about errors during certificate loading, saving or validation.
ExternalSignHandles remote or external signing initiated by the SignExternal method or other source.
NotificationThis event notifies the application about an underlying control flow event.
PasswordNeededThis event is fired when a decryption password is needed.

Configuration Settings


The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.

KeyExchangePINThe KeyExchange PIN to provide to the key in runtime.
SignaturePINThe Signature PIN to provide to the key in runtime.
TempPathPath for storing temporary files.
CheckKeyIntegrityBeforeUseEnables or disable private key integrity check before use.
CookieCachingSpecifies whether a cookie cache should be used for HTTP(S) transports.
CookiesGets or sets local cookies for the component (supported for HTTPClient, RESTClient and SOAPClient only).
DefDeriveKeyIterationsSpecifies the default key derivation algorithm iteration count.
EnableClientSideSSLFFDHEEnables or disables finite field DHE key exchange support in TLS clients.
GlobalCookiesGets or sets global cookies for all the HTTP transports.
HttpUserAgentSpecifies the user agent name to be used by all HTTP clients.
LogDestinationSpecifies the debug log destination.
LogDetailsSpecifies the debug log details to dump.
LogFileSpecifies the debug log filename.
LogFiltersSpecifies the debug log filters.
LogFlushModeSpecifies the log flush mode.
LogLevelSpecifies the debug log level.
LogMaxEventCountSpecifies the maximum number of events to cache before further action is taken.
LogRotationModeSpecifies the log rotation mode.
MaxASN1BufferLengthSpecifies the maximal allowed length for ASN.1 primitive tag data.
MaxASN1TreeDepthSpecifies the maximal depth for processed ASN.1 trees.
OCSPHashAlgorithmSpecifies the hash algorithm to be used to identify certificates in OCSP requests.
UseOwnDNSResolverSpecifies whether the client components should use own DNS resolver.
UseSharedSystemStoragesSpecifies whether the validation engine should use a global per-process copy of the system certificate stores.
UseSystemOAEPAndPSSEnforces or disables the use of system-driven RSA OAEP and PSS computations.
UseSystemRandomEnables or disables the use of the OS PRNG.

Copyright (c) 2022 /n software inc. - All rights reserved.
SecureBlackbox 2020 .NET Edition - Version 20.0 [Build 8165]