SecureBlackbox Lite 2020 Python Edition

Questions / Feedback?

CertificateStorage Class

Properties   Methods   Events   Configuration Settings   Errors  

The CertificateStorage class works with collections of certificates.

Syntax

class secureblackboxlite.CertificateStorage

Remarks

CertificateStorage can work with certificates residing on a variety of media. Among others, it can access certificates residing in files, Windows and macOS system stores, and PKCS#11 devices. All such kinds of media can be accessed via a simple, unified interface, which makes CertificateStorage a handy certificate access option. Most users of SecureBlackbox use this component to access certificates residing on hardware devices. CertificateStorage is also a good alternative to CertificateManager where the certificate file contains more than one certificate.

To access certificates stored on certain type of media, start with the open method. Provide the location of your certificates via a uniform URI-like specifier. Once the storage has been opened, you can access the certificates contained in it via the certificates property.

Iterate over certificates by using the certificates property, or use filtering facilities such as select and select_chain. You can add certificates to the storage with the add, add_from_file, and add_pinned methods. In the latter case please assign the certificate object to be imported to the pinned_cert property.

Use create_new method to create a new storage. Note that not all storage kinds can be created.

When you have finished working with the certificate storage, close it with the close method.

Certain types of stores must be kept open for the certificates to continue to be usable. This means that while you can copy a certificate to a different storage, or assign it to a different component, you still must keep the storage it originates from open for as long as you intend to use that certificate in your code. This is because the storage is often a bridge between a certificate and its private key, and by closing the storage early you are destroying this bridge prematurely. See the code example below:

  // This code, although syntactically correct, will fail because the storage is closed too early:
  storage.Open("pkcs11://user:12345@localhost/C:/Windows/System32/asepkcs.dll");
  pdfSigner.SigningCertificate = storage.Certificates[0];
  storage.Close(false); // the private key of the SigningCertificate gets lost after this call
  pdfSigner.Sign(); // returns an error

  // This code will work as expected
  storage.Open("pkcs11://user:12345@localhost/C:/Windows/System32/asepkcs.dll");
  pdfSigner.SigningCertificate = storage.Certificates[0];
  pdfSigner.Sign();
  storage.Close(false);

Property List


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

cert_countThe number of records in the Cert arrays.
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.
openedIndicates whether the storage is in the open state.
pinned_cert_bytesReturns raw certificate data in DER format.
pinned_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
selected_cert_countThe number of records in the SelectedCert arrays.
selected_cert_bytesReturns raw certificate data in DER format.
selected_cert_caIndicates whether the certificate has a CA capability (a setting in BasicConstraints extension).
selected_cert_ca_key_idA unique identifier (fingerprint) of the CA certificate's private key.
selected_cert_crl_distribution_pointsLocations of the CRL (Certificate Revocation List) distribution points used to check this certificate's validity.
selected_cert_curveSpecifies the elliptic curve of the EC public key.
selected_cert_fingerprintContains the fingerprint (a hash imprint) of this certificate.
selected_cert_friendly_nameContains an associated alias (friendly name) of the certificate.
selected_cert_handleAllows to get or set a 'handle', a unique identifier of the underlying property object.
selected_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 .
selected_cert_issuerThe common name of the certificate issuer (CA), typically a company name.
selected_cert_issuer_rdnA collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate issuer.
selected_cert_key_algorithmSpecifies the public key algorithm of this certificate.
selected_cert_key_bitsReturns the length of the public key.
selected_cert_key_fingerprintReturns a fingerprint of the public key contained in the certificate.
selected_cert_key_usageIndicates the purposes of the key contained in the certificate, in the form of an OR'ed flag set.
selected_cert_key_validReturns True if the certificate's key is cryptographically valid, and False otherwise.
selected_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.
selected_cert_originReturns the origin of this certificate.
selected_cert_policy_i_dsContains identifiers (OIDs) of the applicable certificate policies.
selected_cert_private_key_bytesContains the certificate's private key.
selected_cert_private_key_existsIndicates whether the certificate has an associated private key.
selected_cert_private_key_extractableIndicates whether the private key is extractable.
selected_cert_public_key_bytesContains the certificate's public key in DER format.
selected_cert_self_signedIndicates whether the certificate is self-signed (root) or signed by an external CA.
selected_cert_serial_numberReturns the certificate's serial number.
selected_cert_sig_algorithmIndicates the algorithm that was used by the CA to sign this certificate.
selected_cert_subjectThe common name of the certificate holder, typically an individual's name, a URL, an e-mail address, or a company name.
selected_cert_subject_key_idContains a unique identifier (fingerprint) of the certificate's private key.
selected_cert_subject_rdnA collection of information, in the form of [OID, Value] pairs, uniquely identifying the certificate holder (subject).
selected_cert_valid_fromThe time point at which the certificate becomes valid, in UTC.
selected_cert_valid_toThe time point at which the certificate expires, in UTC.
storage_idA unique identifier of this storage.
storage_locationSpecifies the location of the currently opened storage.

Method List


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

addAdds a certificate to the storage.
add_from_fileAdds a certificate to the storage.
add_pinnedAdds the pinned certificate to the storage.
clearRemoves all certificates from the storage.
closeCloses the certificate storage.
configSets or retrieves a configuration setting.
create_newCreates a new storage.
openOpens existing storage or creates one in memory.
refreshRefreshes all storage keychains.
removeRemoves a certificate from the storage.
selectAllows the selection of certificates from the system store.
select_chainSelects a chain of certificates given its index.

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 or saving.
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.

AuthAttemptsThe number of auth/login attempts to try.
PKCS11ActiveSlotThe index of the slot that the class is working with.
PKCS11NewPINChanges the current user's PIN.
PKCS11NewUserPINRegisters a new user PIN.
PKCS11PINSets the operation PIN.
PKCS11SlotCountThe number of slots exposed in the storage.
PKCS11SlotDescription[i]A human-readable description of the slot.
PKCS11SlotLoggedIn[i]Whether slot i has an active session associated with it.
PKCS11SlotPinNeeded[i]Whether slot i requires you to provide a PIN to log in or sign.
PKCS11SlotReadOnly[i]Whether slot i only supports read-only access.
PKCS11SlotTokenLabel[i]The label assigned to the token.
PKCS11SlotTokenModel[i]The token model.
PKCS11SlotTokenPresent[i]Indicates whether there is a token in the slot.
PKCS11SlotTokenSerial[i]The serial number of the token.
PKCS11SlotTokenVendorID[i]The manufacturer ID of the inserted token.
PKCS11SlotVendorID[i]Returns the manufacturer ID of the slot.
TempPathPath for storing temporary files.

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