PasswordVault Class
Properties Methods Events Config Settings Errors
The PasswordVault class implements a vault for keeping passwords and other sensitive properties.
Syntax
class secureblackbox.PasswordVault
Remarks
Use this component to keep passwords and other settings in secure manner.
Property List
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
| description | The description of the vault. |
| entry_key | Provides an encryption key for the current entry. |
| entry_password | Provides an encryption password for the current entry. |
| fips_mode | Reserved. |
| key | Provides an encryption key for the vault. |
| password | Provides an encryption password for the vault file. |
| platform_protection | Enables platform-based protection of the master key. |
| title | The title of the vault. |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
| add_entry | Adds an entry to the vault. |
| change_entry_key | Changes the entry's encryption key. |
| change_entry_password | Changes the entry's encryption password. |
| close | Closes the vault file. |
| config | Sets or retrieves a configuration setting. |
| do_action | Performs an additional action. |
| get_entry_value | Returns the content stored in one of the entry fields as a byte array. |
| get_entry_value_str | Returns the content stored in a field of the entry as a string. |
| list_entries | Returns a list of entries stored in the vault. |
| list_fields | Returns a list of fields contained in the entry. |
| open_bytes | Loads vault content from a byte array. |
| open_file | Opens a vault file. |
| remove_all_entries | Removes all entries from a vault. |
| remove_entry | Removes an entry from the vault. |
| remove_field | Removes an entry field. |
| save_bytes | Saves the vault contents to a byte array. |
| save_file | Saves the vault contents to a file. |
| set_entry_value | Assigns a value to an entry field. |
| set_entry_value_str | Assigns a value to an entry field. |
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_entry_key_needed | This event is fired to request an entry encryption/decryption key from the application. |
| on_error | Informs about errors during cryptographic operations. |
| on_key_needed | This event is fired to request a vault encryption/decryption key from the application. |
| on_notification | This event notifies the application about an underlying control flow event. |
Config Settings
The following is a list of config settings for the class with short descriptions. Click on the links for further details.
| TempPath | Path for storing temporary files. |
| CheckKeyIntegrityBeforeUse | Enables or disable private key integrity check before use. |
| CookieCaching | Specifies whether a cookie cache should be used for HTTP(S) transports. |
| Cookies | Gets or sets local cookies for the class. |
| DefDeriveKeyIterations | Specifies the default key derivation algorithm iteration count. |
| EnableClientSideSSLFFDHE | Enables or disables finite field DHE key exchange support in TLS clients. |
| GlobalCookies | Gets or sets global cookies for all the HTTP transports. |
| HttpUserAgent | Specifies the user agent name to be used by all HTTP clients. |
| LogDestination | Specifies the debug log destination. |
| LogDetails | Specifies the debug log details to dump. |
| LogFile | Specifies the debug log filename. |
| LogFilters | Specifies the debug log filters. |
| LogFlushMode | Specifies the log flush mode. |
| LogLevel | Specifies the debug log level. |
| LogMaxEventCount | Specifies the maximum number of events to cache before further action is taken. |
| LogRotationMode | Specifies the log rotation mode. |
| MaxASN1BufferLength | Specifies the maximal allowed length for ASN.1 primitive tag data. |
| MaxASN1TreeDepth | Specifies the maximal depth for processed ASN.1 trees. |
| OCSPHashAlgorithm | Specifies the hash algorithm to be used to identify certificates in OCSP requests. |
| StaticDNS | Specifies whether static DNS rules should be used. |
| StaticIPAddress[domain] | Gets or sets an IP address for the specified domain name. |
| StaticIPAddresses | Gets or sets all the static DNS rules. |
| Tag | Allows to store any custom data. |
| TLSSessionGroup | Specifies the group name of TLS sessions to be used for session resumption. |
| TLSSessionLifetime | Specifies lifetime in seconds of the cached TLS session. |
| TLSSessionPurgeInterval | Specifies how often the session cache should remove the expired TLS sessions. |
| UseOwnDNSResolver | Specifies whether the client classes should use own DNS resolver. |
| UseSharedSystemStorages | Specifies whether the validation engine should use a global per-process copy of the system certificate stores. |
| UseSystemOAEPAndPSS | Enforces or disables the use of system-driven RSA OAEP and PSS computations. |
| UseSystemRandom | Enables or disables the use of the OS PRNG. |
description Property
The description of the vault.
Syntax
def get_description() -> str: ... def set_description(value: str) -> None: ...
description = property(get_description, set_description)
Default Value
""
Remarks
Use this property to provide a textual description (comment) for the vault. This value is not encrypted even if the vault is.
entry_key Property
Provides an encryption key for the current entry.
Syntax
def get_entry_key() -> bytes: ... def set_entry_key(value: bytes) -> None: ...
entry_key = property(get_entry_key, set_entry_key)
Remarks
Use this property to provide the encryption/decryption key for the current entry. This property is typically assigned from the on_entry_key_needed event handler.
This property is automatically generated when a non-empty password is assigned to the entry_password property. This is because all entries, and the vault itself, are always encrypted with cryptographically strong keys, and if the user decides to use a password, it is converted to such key using a secure PBKDF function.
entry_password Property
Provides an encryption password for the current entry.
Syntax
def get_entry_password() -> str: ... def set_entry_password(value: str) -> None: ...
entry_password = property(get_entry_password, set_entry_password)
Default Value
""
Remarks
Use this property to provide the encryption/decryption password for the current entry. This property is typically assigned from the on_entry_key_needed event handler.
See a comment in the entry_key topic to find out how the passwords are used when encrypting entries.
fips_mode Property
Reserved.
Syntax
def get_fips_mode() -> bool: ... def set_fips_mode(value: bool) -> None: ...
fips_mode = property(get_fips_mode, set_fips_mode)
Default Value
FALSE
Remarks
This property is reserved for future use.
key Property
Provides an encryption key for the vault.
Syntax
def get_key() -> bytes: ... def set_key(value: bytes) -> None: ...
key = property(get_key, set_key)
Remarks
Use this property to provide the 'master' key for the vault file. This property can be assigned from the on_key_needed event handler.
The content of this property is automatically generated when a non-empty password is assigned to the password property. This is because the vault file are always encrypted with a cryptographically strong key, and if the user decides to use a password, it is converted to such key using a secure PBKDF function first.
password Property
Provides an encryption password for the vault file.
Syntax
def get_password() -> str: ... def set_password(value: str) -> None: ...
password = property(get_password, set_password)
Default Value
""
Remarks
Use this property to provide the master password for the vault file. This property can be assigned from the on_key_needed event handler.
See a comment in the key topic to learn how the passwords are used when encrypting the vault file.
platform_protection Property
Enables platform-based protection of the master key.
Syntax
def get_platform_protection() -> bool: ... def set_platform_protection(value: bool) -> None: ...
platform_protection = property(get_platform_protection, set_platform_protection)
Default Value
FALSE
Remarks
Use this property to enable the platform-based protection for the main encryption key. The platform protection is currently only available on Windows, in the form of DPAPI in unmanaged editions, or ProtectedData in .NET Framework.
title Property
The title of the vault.
Syntax
def get_title() -> str: ... def set_title(value: str) -> None: ...
title = property(get_title, set_title)
Default Value
""
Remarks
Use this property to provide a title for your vault storage. This value is not encrypted event if the vault itself is.
add_entry Method
Adds an entry to the vault.
Syntax
def add_entry(entry_name: str) -> None: ...
Remarks
Use this method to add a new entry to the vault. Use set_entry_value or set_entry_value_str to assign a value to the new entry.
change_entry_key Method
Changes the entry's encryption key.
Syntax
def change_entry_key(entry_name: str, new_key: bytes) -> None: ...
Remarks
Use this method to change the entry's encryption key. This method may invoke the on_entry_key_needed event to request the existing key if the entry was previously encrypted.
change_entry_password Method
Changes the entry's encryption password.
Syntax
def change_entry_password(entry_name: str, new_password: str) -> None: ...
Remarks
Use this method to change the entry's encryption password. This method may invoke the on_entry_key_needed event to request the existing key if the entry was previously encrypted.
Note that all entries, and the vault itself, are encrypted with cryptographic keys, rather than passwords. When you change an entry's encryption password, you are implicitly changing its encryption key, which is derived from the password using a cryptographically secure key derivation function.
close Method
Closes the vault file.
Syntax
def close() -> None: ...
Remarks
Use this method to close the vault file.
config Method
Sets or retrieves a configuration setting.
Syntax
def config(configuration_string: str) -> str: ...
Remarks
config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.
These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.
To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).
To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.
do_action Method
Performs an additional action.
Syntax
def do_action(action_id: str, action_params: str) -> str: ...
Remarks
do_action is a generic method available in every class. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.
The unique identifier (case insencitive) of the action is provided in the ActionID parameter.
ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....
get_entry_value Method
Returns the content stored in one of the entry fields as a byte array.
Syntax
def get_entry_value(entry_name: str, field_name: str) -> bytes: ...
Remarks
Use this method to obtain the content stored in the FieldName field of the EntryName entry in the form of a byte array. Use get_entry_value_str to retrieve the content as a string.
get_entry_value_str Method
Returns the content stored in a field of the entry as a string.
Syntax
def get_entry_value_str(entry_name: str, field_name: str) -> str: ...
Remarks
Call this method to obtain the data associated with the FieldName field of the EntryName entry in the string form.
list_entries Method
Returns a list of entries stored in the vault.
Syntax
def list_entries() -> str: ...
Remarks
Use this method to retrieve a list of entries stored in the currently opened vault file.
list_fields Method
Returns a list of fields contained in the entry.
Syntax
def list_fields(entry_name: str, include_encrypted: bool) -> str: ...
Remarks
Use this method to obtain a list of fields contained in the EntryName entry. The IncludeEncrypted parameter specifies whether to include encrypted entries in the list.
open_bytes Method
Loads vault content from a byte array.
Syntax
def open_bytes(vault_bytes: bytes) -> None: ...
Remarks
Use this method to load the vault from a byte array.
open_file Method
Opens a vault file.
Syntax
def open_file(file_name: str) -> None: ...
Remarks
Use this method to open a vault file.
remove_all_entries Method
Removes all entries from a vault.
Syntax
def remove_all_entries() -> None: ...
Remarks
Use this method to remove all entries from the currently opened vault.
remove_entry Method
Removes an entry from the vault.
Syntax
def remove_entry(entry_name: str) -> None: ...
Remarks
Use this method to remove (delete) the EntryName entry from the vault.
remove_field Method
Removes an entry field.
Syntax
def remove_field(entry_name: str, field_name: str) -> None: ...
Remarks
Use this method to remove an entry field FieldName from the entry EntryName.
save_bytes Method
Saves the vault contents to a byte array.
Syntax
def save_bytes() -> bytes: ...
Remarks
Use this method to save the vault contents to a byte array.
save_file Method
Saves the vault contents to a file.
Syntax
def save_file(filename: str) -> None: ...
Remarks
Use this method to save the contents of the password vault to a file.
set_entry_value Method
Assigns a value to an entry field.
Syntax
def set_entry_value(entry_name: str, field_name: str, field_value: bytes, encrypted: bool) -> None: ...
Remarks
Use this method to assign a value to a field of a vault entry. Use EntryName to identify the entry, and provide the field's name and value via FieldName and FieldValue parameters respectively. Set Encrypted to true to indicate that the field should be encrypted.
set_entry_value_str Method
Assigns a value to an entry field.
Syntax
def set_entry_value_str(entry_name: str, field_name: str, field_value_str: str, encrypted: bool) -> None: ...
Remarks
Use this method to assign a string value to a field of a vault entry. Use EntryName to identify the entry, and provide the field's name and value via FieldName and FieldValueStr parameters respectively. Set Encrypted to true to indicate that the field should be encrypted.
on_entry_key_needed Event
This event is fired to request an entry encryption/decryption key from the application.
Syntax
class PasswordVaultEntryKeyNeededEventParams(object): @property def entry_name() -> str: ... @property def cancel() -> bool: ... @cancel.setter def cancel(value) -> None: ... # In class PasswordVault: @property def on_entry_key_needed() -> Callable[[PasswordVaultEntryKeyNeededEventParams], None]: ... @on_entry_key_needed.setter def on_entry_key_needed(event_hook: Callable[[PasswordVaultEntryKeyNeededEventParams], None]) -> None: ...
Remarks
The class fires this event when a key is needed to encrypt or decrypt an entry. The EntryName parameter provides the name of the entry.
The handler of this event should assign the password or key to be used to entry_password or entry_key property respectively. Set Cancel to true to abort the operation.
on_error Event
Informs about errors during cryptographic operations.
Syntax
class PasswordVaultErrorEventParams(object): @property def error_code() -> int: ... @property def description() -> str: ... # In class PasswordVault: @property def on_error() -> Callable[[PasswordVaultErrorEventParams], None]: ... @on_error.setter def on_error(event_hook: Callable[[PasswordVaultErrorEventParams], None]) -> None: ...
Remarks
Class fires this event if an error happens during a cryptographic operation.
ErrorCode contains an error code and Description contains a textual description of the error that happened.
on_key_needed Event
This event is fired to request a vault encryption/decryption key from the application.
Syntax
class PasswordVaultKeyNeededEventParams(object): @property def cancel() -> bool: ... @cancel.setter def cancel(value) -> None: ... # In class PasswordVault: @property def on_key_needed() -> Callable[[PasswordVaultKeyNeededEventParams], None]: ... @on_key_needed.setter def on_key_needed(event_hook: Callable[[PasswordVaultKeyNeededEventParams], None]) -> None: ...
Remarks
Class fires this event to request a vault encryption key from the application. Note that this is not the same as entry encryption key, which is requested by on_entry_key_needed. The key requested by this event is used to encrypt or decrypt the whole vault.
The handler of this event should assign the password or key to be used to password or key property respectively. Set Cancel to true to abort the operation.
on_notification Event
This event notifies the application about an underlying control flow event.
Syntax
class PasswordVaultNotificationEventParams(object): @property def event_id() -> str: ... @property def event_param() -> str: ... # In class PasswordVault: @property def on_notification() -> Callable[[PasswordVaultNotificationEventParams], None]: ... @on_notification.setter def on_notification(event_hook: Callable[[PasswordVaultNotificationEventParams], None]) -> None: ...
Remarks
The class fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.
The unique identifier of the event is provided in EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.
PasswordVault Config Settings
The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.PasswordVault Config Settings
Base Config Settings
You can switch this property off to improve performance if your project only uses known, good private keys.
Supported values are:
| off | No caching (default) | |
| local | Local caching | |
| global | Global caching |
This setting only applies to sessions negotiated with TLS version 1.3.
Supported values are:
| file | File | |
| console | Console | |
| systemlog | System Log (supported for Android only) | |
| debugger | Debugger (supported for VCL for Windows and .Net) |
Supported values are:
| time | Current time | |
| level | Level | |
| package | Package name | |
| module | Module name | |
| class | Class name | |
| method | Method name | |
| threadid | Thread Id | |
| contenttype | Content type | |
| content | Content | |
| all | All details |
Supported filter names are:
| exclude-package | Exclude a package specified in the value | |
| exclude-module | Exclude a module specified in the value | |
| exclude-class | Exclude a class specified in the value | |
| exclude-method | Exclude a method specified in the value | |
| include-package | Include a package specified in the value | |
| include-module | Include a module specified in the value | |
| include-class | Include a class specified in the value | |
| include-method | Include a method specified in the value |
| none | No flush (caching only) | |
| immediate | Immediate flush (real-time logging) | |
| maxcount | Flush cached entries upon reaching LogMaxEventCount entries in the cache. |
Supported values are:
| none | None (by default) | |
| fatal | Severe errors that cause premature termination. | |
| error | Other runtime errors or unexpected conditions. | |
| warning | Use of deprecated APIs, poor use of API, 'almost' errors, other runtime situations that are undesirable or unexpected, but not necessarily "wrong". | |
| info | Interesting runtime events (startup/shutdown). | |
| debug | Detailed information on flow of through the system. | |
| trace | More detailed information. |
The default value of this setting is 100.
| none | No rotation | |
| deleteolder | Delete older entries from the cache upon reaching LogMaxEventCount | |
| keepolder | Keep older entries in the cache upon reaching LogMaxEventCount (newer entries are discarded) |
Supported values are:
| none | No static DNS rules (default) | |
| local | Local static DNS rules | |
| global | Global static DNS rules |
This setting only applies to certificates originating from a Windows system store.
PasswordVault Errors
PasswordVault Errors
| 1048577 Invalid parameter value (SB_ERROR_INVALID_PARAMETER) | |
| 1048578 Class is configured incorrectly (SB_ERROR_INVALID_SETUP) | |
| 1048579 Operation cannot be executed in the current state (SB_ERROR_INVALID_STATE) | |
| 1048580 Attempt to set an invalid value to a property (SB_ERROR_INVALID_VALUE) | |
| 1048581 Certificate does not have its private key loaded (SB_ERROR_NO_PRIVATE_KEY) | |
| 1048581 Cancelled by the user (SB_ERROR_CANCELLED_BY_USER) |