SecureBlackbox 2020 Python Edition

Questions / Feedback?

CertificateManager Class

Properties   Methods   Events   Configuration Settings   Errors  

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

Syntax

class secureblackbox.CertificateManager

Remarks

Usage of this class 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 import_from_file 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 on_password_needed event.

Alternatively, you can use import_cert 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 import_from_file method first, and then add the key to it with a separate call to the import_key_from_file 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 ca_certificate 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 export_to_file or export_cert 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 export_key method.

Note: you can use the get_sample_cert 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 certificate_request object to set up the certificate request parameters, and generate_csr method to generate the request. You can then save the resulting request to a file using the export_csr method.

Property List


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

ca_cert_bytesReturns raw certificate data in DER format.
ca_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
cert_bytesReturns raw certificate data in DER format.
cert_caIndicates whether the certificate has a CA capability (a setting in BasicConstraints extension).
cert_ca_key_idA unique identifier (fingerprint) of the CA certificate's private key.
cert_crl_distribution_pointsLocations of the CRL (Certificate Revocation List) distribution points used to check this certificate's validity.
cert_curveSpecifies the elliptic curve of the EC public key.
cert_fingerprintContains the fingerprint (a hash imprint) of this certificate.
cert_friendly_nameContains an associated alias (friendly name) of the certificate.
cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
cert_hash_algorithmSpecifies the hash algorithm to be used in the operations on the certificate (such as key signing) SB_HASH_ALGORITHM_SHA1 SHA1 SB_HASH_ALGORITHM_SHA224 SHA224 SB_HASH_ALGORITHM_SHA256 SHA256 SB_HASH_ALGORITHM_SHA384 SHA384 SB_HASH_ALGORITHM_SHA512 SHA512 SB_HASH_ALGORITHM_MD2 MD2 SB_HASH_ALGORITHM_MD4 MD4 SB_HASH_ALGORITHM_MD5 MD5 SB_HASH_ALGORITHM_RIPEMD160 RIPEMD160 SB_HASH_ALGORITHM_CRC32 CRC32 SB_HASH_ALGORITHM_SSL3 SSL3 SB_HASH_ALGORITHM_GOST_R3411_1994 GOST1994 SB_HASH_ALGORITHM_WHIRLPOOL WHIRLPOOL SB_HASH_ALGORITHM_POLY1305 POLY1305 SB_HASH_ALGORITHM_SHA3_224 SHA3_224 SB_HASH_ALGORITHM_SHA3_256 SHA3_256 SB_HASH_ALGORITHM_SHA3_384 SHA3_384 SB_HASH_ALGORITHM_SHA3_512 SHA3_512 SB_HASH_ALGORITHM_BLAKE2S_128 BLAKE2S_128 SB_HASH_ALGORITHM_BLAKE2S_160 BLAKE2S_160 SB_HASH_ALGORITHM_BLAKE2S_224 BLAKE2S_224 SB_HASH_ALGORITHM_BLAKE2S_256 BLAKE2S_256 SB_HASH_ALGORITHM_BLAKE2B_160 BLAKE2B_160 SB_HASH_ALGORITHM_BLAKE2B_256 BLAKE2B_256 SB_HASH_ALGORITHM_BLAKE2B_384 BLAKE2B_384 SB_HASH_ALGORITHM_BLAKE2B_512 BLAKE2B_512 SB_HASH_ALGORITHM_SHAKE_128 SHAKE_128 SB_HASH_ALGORITHM_SHAKE_256 SHAKE_256 SB_HASH_ALGORITHM_SHAKE_128_LEN SHAKE_128_LEN SB_HASH_ALGORITHM_SHAKE_256_LEN SHAKE_256_LEN .
cert_issuerThe common name of the certificate issuer (CA), typically a company name.
cert_issuer_rdnA collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate issuer.
cert_key_algorithmSpecifies the public key algorithm of this certificate.
cert_key_bitsReturns the length of the public key.
cert_key_fingerprintReturns a fingerprint of the public key contained in the certificate.
cert_key_usageIndicates the purposes of the key contained in the certificate, in the form of an OR'ed flag set.
cert_key_validReturns True if the certificate's key is cryptographically valid, and False otherwise.
cert_ocsp_locationsLocations of OCSP (Online Certificate Status Protocol) services that can be used to check this certificate's validity, as recorded by the CA.
cert_originReturns the origin of this certificate.
cert_policy_i_dsContains identifiers (OIDs) of the applicable certificate policies.
cert_private_key_bytesContains the certificate's private key.
cert_private_key_existsIndicates whether the certificate has an associated private key.
cert_private_key_extractableIndicates whether the private key is extractable.
cert_public_key_bytesContains the certificate's public key in DER format.
cert_self_signedIndicates whether the certificate is self-signed (root) or signed by an external CA.
cert_serial_numberReturns the certificate's serial number.
cert_sig_algorithmIndicates the algorithm that was used by the CA to sign this certificate.
cert_subjectThe common name of the certificate holder, typically an individual's name, a URL, an e-mail address, or a company name.
cert_subject_key_idContains a unique identifier (fingerprint) of the certificate's private key.
cert_subject_rdnA collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate holder (subject).
cert_valid_fromThe time point at which the certificate becomes valid, in UTC.
cert_valid_toThe time point at which the certificate expires, in UTC.
cert_request_bytesProvides access to raw certificate request data in DER format.
cert_request_curveSpecifies the elliptic curve of the EC public key.
cert_request_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
cert_request_hash_algorithmSpecifies the hash algorithm to be used in the operations on the certificate request (such as signing).
cert_request_key_algorithmSpecifies the public key algorithm of this certificate request.
cert_request_key_bitsReturns the length of the public key.
cert_request_key_usageIndicates the purposes of the key contained in the certificate request, in the form of an OR'ed flag set.
cert_request_key_validReturns True if the certificate's key is cryptographically valid, and False otherwise.
cert_request_private_key_bytesContains the certificate's private key.
cert_request_public_key_bytesContains the public key incorporated in the request, in DER format.
cert_request_sig_algorithmIndicates the algorithm that was used by the requestor to sign this certificate request.
cert_request_subjectThe common name of the certificate holder, typically an individual's name, a URL, an e-mail address, or a company name.
cert_request_subject_rdnA collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate holder (subject).
cert_request_validIndicates whether or not the signature on the request is valid and matches the public key contained in the request.
external_crypto_custom_paramsCustom parameters to be passed to the signing service (uninterpreted).
external_crypto_dataAdditional data to be included in the async state and mirrored back by the requestor.
external_crypto_external_hash_calculationSpecifies whether the message hash is to be calculated at the external endpoint.
external_crypto_hash_algorithmSpecifies the request's signature hash algorithm.
external_crypto_key_idThe ID of the pre-shared key used for DC request authentication.
external_crypto_key_secretThe pre-shared key used for DC request authentication.
external_crypto_methodSpecifies the asynchronous signing method.
external_crypto_modeSpecifies the external cryptography mode.
external_crypto_public_key_algorithmProvide public key algorithm here if the certificate is not available on the pre-signing stage.

Method List


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

configSets or retrieves a configuration setting.
downloadDownloads a certificate from a remote location.
export_certExports the certificate in the chosen format.
export_csrExports a Certificate Signing Request (CSR).
export_keyExports the certificate's private key.
export_key_to_fileExports the private key to a file in the chosen format.
export_to_fileExports the certificate to a file.
generateGenerates a new certificate.
generate_async_beginInitiates asynchronous (DC) certificate generation.
generate_async_endCompletes asynchronous certificate generation.
generate_csrCreates a new certificate signing request (CSR).
generate_externalGenerates a new certificate with an external signing device.
get_sample_certGenerates a sample certificate for the specified purpose.
import_certImports a certificate.
import_from_fileLoads a certificate from a file.
import_keyImports a private key.
import_key_from_fileImports a private key from a file.
updateRenews the certificate.
validateValidates the certificate.

Event List


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

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

Configuration Settings


The following is a list of configuration settings for the class 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 class (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 classes 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 Python Edition - Version 20.0 [Build 8154]