PasswordVault Component
Properties Methods Events Config Settings Errors
The PasswordVault component implements a vault for keeping passwords and other sensitive properties.
Syntax
TsbxPasswordVault
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 component with short descriptions. Click on the links for further details.
Description | The description of the vault. |
EntryKey | Provides an encryption key for the current entry. |
EntryPassword | Provides an encryption password for the current entry. |
FIPSMode | Reserved. |
Key | Provides an encryption key for the vault. |
Password | Provides an encryption password for the vault file. |
PlatformProtection | 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 component with short descriptions. Click on the links for further details.
AddEntry | Adds an entry to the vault. |
ChangeEntryKey | Changes the entry's encryption key. |
ChangeEntryPassword | Changes the entry's encryption password. |
Close | Closes the vault file. |
Config | Sets or retrieves a configuration setting. |
CreateNew | Creates a new password vault. |
DoAction | Performs an additional action. |
GetEntryValue | Returns the content stored in one of the entry fields as a byte array. |
GetEntryValueStr | Returns the content stored in a field of the entry as a string. |
ListEntries | Returns a list of entries stored in the vault. |
ListFields | Returns a list of fields contained in the entry. |
OpenBytes | Loads vault content from a byte array. |
OpenFile | Opens a vault file. |
OpenStream | Loads vault data from a stream. |
RemoveAllEntries | Removes all entries from a vault. |
RemoveEntry | Removes an entry from the vault. |
RemoveField | Removes an entry field. |
Reset | Resets the component settings. |
SaveBytes | Saves the vault contents to a byte array. |
SaveFile | Saves the vault contents to a file. |
SaveStream | Saves the vault contents to a stream. |
SetEntryValue | Assigns a value to an entry field. |
SetEntryValueStr | Assigns a value to an entry field. |
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.
EntryKeyNeeded | This event is fired to request an entry encryption/decryption key from the application. |
Error | Informs about errors during cryptographic operations. |
KeyNeeded | This event is fired to request a vault encryption/decryption key from the application. |
Notification | This event notifies the application about an underlying control flow event. |
Config Settings
The following is a list of config settings for the component with short descriptions. Click on the links for further details.
EntrySalt | TBD. |
NewEntrySalt | TBD. |
Salt | TBD. |
TempPath | Path for storing temporary files. |
UseLocalMachineAccount | TBD. |
ASN1UseGlobalTagCache | Controls whether ASN.1 module should use a global object cache. |
AssignSystemSmartCardPins | Specifies whether CSP-level PINs should be assigned to CNG keys. |
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 component. |
DefDeriveKeyIterations | Specifies the default key derivation algorithm iteration count. |
DNSLocalSuffix | The suffix to assign for TLD names. |
EnableClientSideSSLFFDHE | Enables or disables finite field DHE key exchange support in TLS clients. |
GlobalCookies | Gets or sets global cookies for all the HTTP transports. |
HardwareCryptoUsePolicy | The hardware crypto usage policy. |
HttpUserAgent | Specifies the user agent name to be used by all HTTP clients. |
HttpVersion | The HTTP version to use in any inner HTTP client components created. |
IgnoreExpiredMSCTLSigningCert | Whether to tolerate the expired Windows Update signing certificate. |
ListDelimiter | The delimiter character for multi-element lists. |
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. |
OldClientSideRSAFallback | Specifies whether the SSH client should use a SHA1 fallback. |
PKICache | Specifies which PKI elements (certificates, CRLs, OCSP responses) should be cached. |
PKICachePath | Specifies the file system path where cached PKI data is stored. |
ProductVersion | Returns the version of the SecureBlackbox library. |
ServerSSLDHKeyLength | Sets the size of the TLS DHE key exchange group. |
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. |
UseCRLObjectCaching | Specifies whether reuse of loaded CRL objects is enabled. |
UseInternalRandom | Switches between SecureBlackbox-own and platform PRNGs. |
UseLegacyAdESValidation | Enables legacy AdES validation mode. |
UseOCSPResponseObjectCaching | Specifies whether reuse of loaded OCSP response objects is enabled. |
UseOwnDNSResolver | Specifies whether the client components should use own DNS resolver. |
UseSharedSystemStorages | Specifies whether the validation engine should use a global per-process copy of the system certificate stores. |
UseSystemNativeSizeCalculation | An internal CryptoAPI access tweak. |
UseSystemOAEPAndPSS | Enforces or disables the use of system-driven RSA OAEP and PSS computations. |
UseSystemRandom | Enables or disables the use of the OS PRNG. |
XMLRDNDescriptorName[OID] | Defines an OID mapping to descriptor names for the certificate's IssuerRDN or SubjectRDN. |
XMLRDNDescriptorPriority[OID] | Specifies the priority of descriptor names associated with a specific OID. |
XMLRDNDescriptorReverseOrder | Specifies whether to reverse the order of descriptors in RDN. |
XMLRDNDescriptorSeparator | Specifies the separator used between descriptors in RDN. |
Description Property (PasswordVault Component)
The description of the vault.
Syntax
property Description: String read get_Description write 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.
EntryKey Property (PasswordVault Component)
Provides an encryption key for the current entry.
Syntax
property EntryKey: TBytes read get_EntryKey write set_EntryKey;
Remarks
Use this property to provide the encryption/decryption key for the current entry. This property is typically assigned from the EntryKeyNeeded event handler.
This property is automatically generated when a non-empty password is assigned to the EntryPassword 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.
This property is not available at design time.
EntryPassword Property (PasswordVault Component)
Provides an encryption password for the current entry.
Syntax
property EntryPassword: String read get_EntryPassword write set_EntryPassword;
Default Value
''
Remarks
Use this property to provide the encryption/decryption password for the current entry. This property is typically assigned from the EntryKeyNeeded event handler.
See a comment in the EntryKey topic to find out how the passwords are used when encrypting entries.
FIPSMode Property (PasswordVault Component)
Reserved.
Syntax
property FIPSMode: Boolean read get_FIPSMode write set_FIPSMode;
Default Value
false
Remarks
This property is reserved for future use.
Key Property (PasswordVault Component)
Provides an encryption key for the vault.
Syntax
property Key: TBytes read get_Key write set_Key;
Remarks
Use this property to provide the 'master' key for the vault file. This property can be assigned from the KeyNeeded 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.
This property is not available at design time.
Password Property (PasswordVault Component)
Provides an encryption password for the vault file.
Syntax
property Password: String read get_Password write set_Password;
Default Value
''
Remarks
Use this property to provide the master password for the vault file. This property can be assigned from the KeyNeeded event handler.
See a comment in the Key topic to learn how the passwords are used when encrypting the vault file.
PlatformProtection Property (PasswordVault Component)
Enables platform-based protection of the master key.
Syntax
property PlatformProtection: Boolean read get_PlatformProtection write set_PlatformProtection;
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 (PasswordVault Component)
The title of the vault.
Syntax
property Title: String read get_Title write 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.
AddEntry Method (PasswordVault Component)
Adds an entry to the vault.
Syntax
procedure AddEntry(EntryName: String);
Remarks
Use this method to add a new entry to the vault. Use SetEntryValue or SetEntryValueStr to assign a value to the new entry.
ChangeEntryKey Method (PasswordVault Component)
Changes the entry's encryption key.
Syntax
procedure ChangeEntryKey(EntryName: String; NewKey: TBytes);
Remarks
Use this method to change the entry's encryption key. This method may invoke the EntryKeyNeeded event to request the existing key if the entry was previously encrypted.
ChangeEntryPassword Method (PasswordVault Component)
Changes the entry's encryption password.
Syntax
procedure ChangeEntryPassword(EntryName: String; NewPassword: String);
Remarks
Use this method to change the entry's encryption password. This method may invoke the EntryKeyNeeded 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 (PasswordVault Component)
Closes the vault file.
Syntax
procedure Close();
Remarks
Use this method to close the vault file.
Config Method (PasswordVault Component)
Sets or retrieves a configuration setting.
Syntax
function Config(ConfigurationString: String): String;
Remarks
Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.
These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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.
CreateNew Method (PasswordVault Component)
Creates a new password vault.
Syntax
procedure CreateNew();
Remarks
This method resets the component state and initializes a fresh password vault object.
DoAction Method (PasswordVault Component)
Performs an additional action.
Syntax
function DoAction(ActionID: String; ActionParams: String): String;
Remarks
DoAction is a generic method available in every component. 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 insensitive) 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;....
Common ActionIDs:
Action | Parameters | Returned value | Description |
ResetTrustedListCache | none | none | Clears the cached list of trusted lists. |
ResetCertificateCache | none | none | Clears the cached certificates. |
ResetCRLCache | none | none | Clears the cached CRLs. |
ResetOCSPResponseCache | none | none | Clears the cached OCSP responses. |
GetEntryValue Method (PasswordVault Component)
Returns the content stored in one of the entry fields as a byte array.
Syntax
function GetEntryValue(EntryName: String; FieldName: String): TBytes;
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 GetEntryValueStr to retrieve the content as a string.
GetEntryValueStr Method (PasswordVault Component)
Returns the content stored in a field of the entry as a string.
Syntax
function GetEntryValueStr(EntryName: String; FieldName: String): String;
Remarks
Call this method to obtain the data associated with the FieldName field of the EntryName entry in the string form.
ListEntries Method (PasswordVault Component)
Returns a list of entries stored in the vault.
Syntax
function ListEntries(): String;
Remarks
Use this method to retrieve a list of entries stored in the currently opened vault file.
ListFields Method (PasswordVault Component)
Returns a list of fields contained in the entry.
Syntax
function ListFields(EntryName: String; IncludeEncrypted: Boolean): String;
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.
OpenBytes Method (PasswordVault Component)
Loads vault content from a byte array.
Syntax
procedure OpenBytes(VaultBytes: TBytes);
Remarks
Use this method to load the vault from a byte array.
OpenFile Method (PasswordVault Component)
Opens a vault file.
Syntax
procedure OpenFile(FileName: String);
Remarks
Use this method to open a vault file.
OpenStream Method (PasswordVault Component)
Loads vault data from a stream.
Syntax
procedure OpenStream(VaultStream: TStream);
Remarks
Use this method to load vault data from a stream.
RemoveAllEntries Method (PasswordVault Component)
Removes all entries from a vault.
Syntax
procedure RemoveAllEntries();
Remarks
Use this method to remove all entries from the currently opened vault.
RemoveEntry Method (PasswordVault Component)
Removes an entry from the vault.
Syntax
procedure RemoveEntry(EntryName: String);
Remarks
Use this method to remove (delete) the EntryName entry from the vault.
RemoveField Method (PasswordVault Component)
Removes an entry field.
Syntax
procedure RemoveField(EntryName: String; FieldName: String);
Remarks
Use this method to remove an entry field FieldName from the entry EntryName.
Reset Method (PasswordVault Component)
Resets the component settings.
Syntax
procedure Reset();
Remarks
Reset is a generic method available in every component.
SaveBytes Method (PasswordVault Component)
Saves the vault contents to a byte array.
Syntax
function SaveBytes(): TBytes;
Remarks
Use this method to save the vault contents to a byte array.
SaveFile Method (PasswordVault Component)
Saves the vault contents to a file.
Syntax
procedure SaveFile(FileName: String);
Remarks
Use this method to save the contents of the password vault to a file.
SaveStream Method (PasswordVault Component)
Saves the vault contents to a stream.
Syntax
procedure SaveStream(VaultStream: TStream);
Remarks
Use this method to save the contents of the password vault to a stream.
SetEntryValue Method (PasswordVault Component)
Assigns a value to an entry field.
Syntax
procedure SetEntryValue(EntryName: String; FieldName: String; FieldValue: TBytes; Encrypted: Boolean);
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.
SetEntryValueStr Method (PasswordVault Component)
Assigns a value to an entry field.
Syntax
procedure SetEntryValueStr(EntryName: String; FieldName: String; FieldValueStr: String; Encrypted: Boolean);
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.
EntryKeyNeeded Event (PasswordVault Component)
This event is fired to request an entry encryption/decryption key from the application.
Syntax
type TEntryKeyNeededEvent = procedure ( Sender: TObject; const EntryName: String; var Cancel: Boolean ) of Object;
property OnEntryKeyNeeded: TEntryKeyNeededEvent read FOnEntryKeyNeeded write FOnEntryKeyNeeded;
Remarks
The component 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 EntryPassword or EntryKey property respectively. Set Cancel to true to abort the operation.
Error Event (PasswordVault Component)
Informs about errors during cryptographic operations.
Syntax
type TErrorEvent = procedure ( Sender: TObject; ErrorCode: Integer; const Description: String ) of Object;
property OnError: TErrorEvent read FOnError write FOnError;
Remarks
Component 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.
KeyNeeded Event (PasswordVault Component)
This event is fired to request a vault encryption/decryption key from the application.
Syntax
type TKeyNeededEvent = procedure ( Sender: TObject; var Cancel: Boolean ) of Object;
property OnKeyNeeded: TKeyNeededEvent read FOnKeyNeeded write FOnKeyNeeded;
Remarks
Component 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 EntryKeyNeeded. 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.
Notification Event (PasswordVault Component)
This event notifies the application about an underlying control flow event.
Syntax
type TNotificationEvent = procedure ( Sender: TObject; const EventID: String; const EventParam: String ) of Object;
property OnNotification: TNotificationEvent read FOnNotification write FOnNotification;
Remarks
The component 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 the 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.
Config Settings (PasswordVault Component)
The component 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 component, 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:
certificate | Enables caching of certificates. |
crl | Enables caching of Certificate Revocation Lists (CRLs). |
ocsp | Enables caching of OCSP (Online Certificate Status Protocol) responses. |
Example (default value):
PKICache=certificate,crl,ocsp
In this example, the component caches certificates, CRLs, and OCSP responses.
The default value is an empty string - no cached PKI data is stored on disk.
Example:
PKICachePath=C:\Temp\cache
In this example, the cached PKI data is stored in the C:\Temp\cache directory.
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.
The property accepts comma-separated values where the first descriptor name is used when the OID is mapped, and subsequent values act as aliases for parsing.
Syntax:
Config("XMLRDNDescriptorName[OID]=PrimaryName,Alias1,Alias2");
Where:
OID: The Object Identifier from the certificate's IssuerRDN or SubjectRDN that you want to map.
PrimaryName: The main descriptor name used in the XML signature when the OID is encountered.
Alias1, Alias2, ...: Optional alternative names recognized during parsing.
Usage Examples:
Map OID 2.5.4.5 to SERIALNUMBER:
Config("XMLRDNDescriptorName[2.5.4.5]=SERIALNUMBER");
Map OID 1.2.840.113549.1.9.1 to E, with aliases EMAIL and EMAILADDRESS:
Config("XMLRDNDescriptorName[1.2.840.113549.1.9.1]=E,EMAIL,EMAILADDRESS");
Trappable Errors (PasswordVault Component)
PasswordVault Errors
1048577 | Invalid parameter (SB_ERROR_INVALID_PARAMETER) |
1048578 | Invalid configuration (SB_ERROR_INVALID_SETUP) |
1048579 | Invalid state (SB_ERROR_INVALID_STATE) |
1048580 | Invalid value (SB_ERROR_INVALID_VALUE) |
1048581 | Private key not found (SB_ERROR_NO_PRIVATE_KEY) |
1048582 | Cancelled by the user (SB_ERROR_CANCELLED_BY_USER) |
1048583 | The file was not found (SB_ERROR_NO_SUCH_FILE) |
1048584 | Unsupported feature or operation (SB_ERROR_UNSUPPORTED_FEATURE) |
1048585 | General error (SB_ERROR_GENERAL_ERROR) |