Utils Class
Properties Methods Events Config Settings Errors
The Utils class offers a selection of popular helper methods that may be of use in a variety of scenarios.
Syntax
class secureblackbox.Utils
Remarks
If you need to resolve a hostname to an IP address, encode a string using a specific character encoding, or compose a multipart message, look no further. This is exactly what Utils is intended for.
Property List
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
| multipart_part_count | The number of records in the MultipartPart arrays. |
| multipart_part_content_description | Provides a description for the part ( Content-Description header property). |
| multipart_part_content_disposition | Specifies the disposition of the part ( Content-Disposition header property). |
| multipart_part_content_id | Specifies the ID of the part ( Content-ID header property). |
| multipart_part_content_transfer_encoding | Specifies the transfer encoding for the part ( Content-Transfer-Encoding header property). |
| multipart_part_content_type | Specifies the content type of the part ( Content-Type header property). |
| multipart_part_custom_headers | Assign any custom HTTP headers to be added to the part header. |
| multipart_part_field_name | Specifies the property name of the form part ( name parameter in Content-Disposition header property). |
| multipart_part_field_value | Specifies the property value of the form part (the part's content). |
| multipart_part_filename | Specifies the filename for the form part ( filename parameter in Content-Disposition header property). |
| multipart_part_handle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
| name_value_pair_count | The number of records in the NameValuePair arrays. |
| name_value_pair_category | Specifies the string category of the contained value. |
| name_value_pair_format | Specifies the format (encoding) of the value contained in the Value property. |
| name_value_pair_name | The name element in a (name, value) pair. |
| name_value_pair_value | The value element in a (name, value) pair. |
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_part_from_bytes | Adds a new part to MultipartMessage from the specified byte array. |
| add_part_from_file | Adds a new part to MultipartMessage from the specified file. |
| base64_decode | Decodes a base64 string to a byte array. |
| base64_encode | Encodes a byte array in base64. |
| base64_encode_lines | Encodes the Bytes array containing binary data to a multi-line Base64. |
| config | Sets or retrieves a configuration setting. |
| date_to_string | Converts a variable of Date type to the respective string representation. |
| do_action | Performs an additional action. |
| get_local_dns_name | Returns the DNS name of the local system. |
| get_local_ip | Returns the primary IP address of the local system. |
| get_local_ips | Returns a list of local IP addresses. |
| get_part_to_bytes | Saves the data from the specified part to a byte array. |
| get_part_to_file | Saves the data from the specified part to a file. |
| get_remote_ip | Gets the IP address of a remote host. |
| get_remote_ips | Resolves IP addresses available for a hostname. |
| get_value_by_name | Returns the value from the (name, value) pair list for the requested name. |
| hex_decode | Decodes a hex-encoded string into a byte array. |
| hex_encode | Encodes a byte array to hex string. |
| index_of_name | Returns the index of the (name, value) pair in the list for the requested Name. |
| load_multipart_from_bytes | Loads a multipart message from the specified byte array to MultipartMessage . |
| load_multipart_from_file | Loads a multipart message from the specified file to MultipartMessage . |
| load_name_value_pairs | Loads a list of (name, value) pairs from a string. |
| oid_to_string | Converts a binary-encoded ASN.1 OID to its string representation. |
| remove_name_value_pair | Remove a (name, value) pair by name. |
| save_multipart_content_type | Returns the value for Content-Type field. |
| save_multipart_to_bytes | Saves the parts contained in MultipartMessage to a byte array. |
| save_multipart_to_file | Saves the parts contained in MultipartMessage to the file. |
| save_name_value_pairs | Serializes the (name, value) pair list to a string. |
| set_value_by_name | Adds or updates the (name, value) pair by a name. |
| string_decode | Converts a byte array to a string using a chosen encoding. |
| string_encode | Encodes a string to a byte array using a chosen character encoding. |
| string_to_date | Converts a date represented by a string to a respective Date object. |
| string_to_oid | Converts string OID representation to an ASN.1 byte array. |
| url_decode | Decodes a URLEncoded string back into its original form. |
| url_encode | Encodes the provided string using URLEncode. |
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_error | Informs about errors during cryptographic operations. |
| 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.
| MultipartBoundary | Returns the boundary string used to save the last multipart message. |
| MultipartCharset | Specifies the charset to be used to encode the field names and the filenames of the multipart message. |
| RelatedStart | Identifies the starting body part or root. |
| RelatedStartInfo | Contains additional information required for unpacking or processing of the content. |
| RelatedType | Contains media type/subtype of message's content. |
| 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. |
multipart_part_count Property
The number of records in the MultipartPart arrays.
Syntax
def get_multipart_part_count() -> int: ... def set_multipart_part_count(value: int) -> None: ...
multipart_part_count = property(get_multipart_part_count, set_multipart_part_count)
Default Value
0
Remarks
This property controls the size of the following arrays:
- multipart_part_content_description
- multipart_part_content_disposition
- multipart_part_content_id
- multipart_part_content_transfer_encoding
- multipart_part_content_type
- multipart_part_custom_headers
- multipart_part_field_name
- multipart_part_field_value
- multipart_part_filename
- multipart_part_handle
multipart_part_content_description Property
Provides a description for the part ( Content-Description header property).
Syntax
def get_multipart_part_content_description(multipart_part_index: int) -> str: ... def set_multipart_part_content_description(multipart_part_index: int, value: str) -> None: ...
Default Value
""
Remarks
Provides a description for the part (Content-Description header field)
The multipart_part_index parameter specifies the index of the item in the array. The size of the array is controlled by the multipart_part_count property.
multipart_part_content_disposition Property
Specifies the disposition of the part ( Content-Disposition header property).
Syntax
def get_multipart_part_content_disposition(multipart_part_index: int) -> str: ... def set_multipart_part_content_disposition(multipart_part_index: int, value: str) -> None: ...
Default Value
""
Remarks
Specifies the disposition of the part (Content-Disposition header field)
The multipart_part_index parameter specifies the index of the item in the array. The size of the array is controlled by the multipart_part_count property.
multipart_part_content_id Property
Specifies the ID of the part ( Content-ID header property).
Syntax
def get_multipart_part_content_id(multipart_part_index: int) -> str: ... def set_multipart_part_content_id(multipart_part_index: int, value: str) -> None: ...
Default Value
""
Remarks
Specifies the ID of the part (Content-ID header field)
The multipart_part_index parameter specifies the index of the item in the array. The size of the array is controlled by the multipart_part_count property.
multipart_part_content_transfer_encoding Property
Specifies the transfer encoding for the part ( Content-Transfer-Encoding header property).
Syntax
def get_multipart_part_content_transfer_encoding(multipart_part_index: int) -> str: ... def set_multipart_part_content_transfer_encoding(multipart_part_index: int, value: str) -> None: ...
Default Value
""
Remarks
Specifies the transfer encoding for the part (Content-Transfer-Encoding header field)
The multipart_part_index parameter specifies the index of the item in the array. The size of the array is controlled by the multipart_part_count property.
multipart_part_content_type Property
Specifies the content type of the part ( Content-Type header property).
Syntax
def get_multipart_part_content_type(multipart_part_index: int) -> str: ... def set_multipart_part_content_type(multipart_part_index: int, value: str) -> None: ...
Default Value
""
Remarks
Specifies the content type of the part (Content-Type header field)
The multipart_part_index parameter specifies the index of the item in the array. The size of the array is controlled by the multipart_part_count property.
multipart_part_custom_headers Property
Assign any custom HTTP headers to be added to the part header.
Syntax
def get_multipart_part_custom_headers(multipart_part_index: int) -> str: ... def set_multipart_part_custom_headers(multipart_part_index: int, value: str) -> None: ...
Default Value
""
Remarks
Assign any custom HTTP headers to be added to the part header.
The multipart_part_index parameter specifies the index of the item in the array. The size of the array is controlled by the multipart_part_count property.
multipart_part_field_name Property
Specifies the property name of the form part ( name parameter in Content-Disposition header property).
Syntax
def get_multipart_part_field_name(multipart_part_index: int) -> str: ... def set_multipart_part_field_name(multipart_part_index: int, value: str) -> None: ...
Default Value
""
Remarks
Specifies the field name of the form part (name parameter in Content-Disposition header field).
The multipart_part_index parameter specifies the index of the item in the array. The size of the array is controlled by the multipart_part_count property.
multipart_part_field_value Property
Specifies the property value of the form part (the part's content).
Syntax
def get_multipart_part_field_value(multipart_part_index: int) -> str: ... def set_multipart_part_field_value(multipart_part_index: int, value: str) -> None: ...
Default Value
""
Remarks
Specifies the field value of the form part (the part's content).
The multipart_part_index parameter specifies the index of the item in the array. The size of the array is controlled by the multipart_part_count property.
multipart_part_filename Property
Specifies the filename for the form part ( filename parameter in Content-Disposition header property).
Syntax
def get_multipart_part_filename(multipart_part_index: int) -> str: ... def set_multipart_part_filename(multipart_part_index: int, value: str) -> None: ...
Default Value
""
Remarks
Specifies the filename for the form part (filename parameter in Content-Disposition header field).
The multipart_part_index parameter specifies the index of the item in the array. The size of the array is controlled by the multipart_part_count property.
multipart_part_handle Property
Allows to get or set a 'handle', a unique identifier of the underlying property object.
Syntax
def get_multipart_part_handle(multipart_part_index: int) -> int: ... def set_multipart_part_handle(multipart_part_index: int, value: int) -> None: ...
Default Value
0
Remarks
Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.
When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object
after such operation.
pdfSigner.setSigningCertHandle(certMgr.getCertHandle());
The multipart_part_index parameter specifies the index of the item in the array. The size of the array is controlled by the multipart_part_count property.
name_value_pair_count Property
The number of records in the NameValuePair arrays.
Syntax
def get_name_value_pair_count() -> int: ... def set_name_value_pair_count(value: int) -> None: ...
name_value_pair_count = property(get_name_value_pair_count, set_name_value_pair_count)
Default Value
0
Remarks
This property controls the size of the following arrays:
The array indices start at 0 and end at name_value_pair_count - 1.name_value_pair_category Property
Specifies the string category of the contained value.
Syntax
def get_name_value_pair_category(name_value_pair_index: int) -> str: ... def set_name_value_pair_category(name_value_pair_index: int, value: str) -> None: ...
Default Value
""
Remarks
Specifies the string category of the contained value.
This property allows to check or set the category (or type) associated with the contained value. Depending on the format used to load or save the string, the category parameter may or may not be used.
For example, for ASN.1 property lists the category contains the ASN.1 tag of the contained data (OCTETSTRING, UTF8STRING, INTEGER, ...). For basic (name, value) pairs, such as HTTP headers, the category parameter is not used.
The name_value_pair_index parameter specifies the index of the item in the array. The size of the array is controlled by the name_value_pair_count property.
name_value_pair_format Property
Specifies the format (encoding) of the value contained in the Value property.
Syntax
def get_name_value_pair_format(name_value_pair_index: int) -> int: ... def set_name_value_pair_format(name_value_pair_index: int, value: int) -> None: ...
Default Value
0
Remarks
Specifies the format (encoding) of the value contained in the name_value_pair_value property.
Use this property to check or set the format of the contained value. Remember to provide the actual value in the appropriate
format that matches this setting:
utils.NameValuePairs[0].Name = "key";
utils.NameValuePairs[0].Format = svfBinary;
utils.NameValuePairs[0].Name = "0a1b2c3d4e5f6071";
The following formats are currently supported:
| svfText | 0 | The property contains text |
| svfBinary | 1 | The property contains binary data. The Value property contains a hex encoding of it. |
The name_value_pair_index parameter specifies the index of the item in the array. The size of the array is controlled by the name_value_pair_count property.
name_value_pair_name Property
The name element in a (name, value) pair.
Syntax
def get_name_value_pair_name(name_value_pair_index: int) -> str: ... def set_name_value_pair_name(name_value_pair_index: int, value: str) -> None: ...
Default Value
""
Remarks
The name element in a (name, value) pair.
The name_value_pair_index parameter specifies the index of the item in the array. The size of the array is controlled by the name_value_pair_count property.
name_value_pair_value Property
The value element in a (name, value) pair.
Syntax
def get_name_value_pair_value(name_value_pair_index: int) -> str: ... def set_name_value_pair_value(name_value_pair_index: int, value: str) -> None: ...
Default Value
""
Remarks
The value element in a (name, value) pair.
The name_value_pair_index parameter specifies the index of the item in the array. The size of the array is controlled by the name_value_pair_count property.
add_part_from_bytes Method
Adds a new part to MultipartMessage from the specified byte array.
Syntax
def add_part_from_bytes(data: bytes) -> int: ...
Remarks
The method adds a new part to multipart_message list with the specified data as the part's content.
Returns the index of the added part.
add_part_from_file Method
Adds a new part to MultipartMessage from the specified file.
Syntax
def add_part_from_file(filename: str) -> int: ...
Remarks
The method adds a new part to multipart_message list with the specified file data as the part's content.
Returns the index of the added part.
base64_decode Method
Decodes a base64 string to a byte array.
Syntax
def base64_decode(value: str, use_url_encoding: bool) -> bytes: ...
Remarks
Use this method to decode a base64-encoded string to a byte array.
The UseURLEncoding parameter specifies whether the URL-Base64 modification should be used when decoding the string.
byte[] arr = utils.Base64Decode("SGVsbG8sIHdvcmxkIQ==", false);
base64_encode Method
Encodes a byte array in base64.
Syntax
def base64_encode(bytes: bytes, use_url_encoding: bool) -> str: ...
Remarks
Use this method to encode binary data contained in Bytes to a base64 string.
The UseURLEncoding parameter specifies whether additional URL encoding should be applied to the resulting string (with + and / characters
replaced with - and _, respectively).
string encoded = utils.Base64Encode(buf, false);
base64_encode_lines Method
Encodes the Bytes array containing binary data to a multi-line Base64.
Syntax
def base64_encode_lines(bytes: bytes, line_len: int) -> str: ...
Remarks
Use this method to encode large amounts of binary data to multi-line base64 strings. Use LineLen parameter to provide the maximal length of each base64 line.
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.
date_to_string Method
Converts a variable of Date type to the respective string representation.
Syntax
def date_to_string(value: datetime.datetime) -> str: ...
Remarks
Use this method to convert a value of a platform date type to a string representation accepted by various SecureBlackbox methods and properties.
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 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;....
get_local_dns_name Method
Returns the DNS name of the local system.
Syntax
def get_local_dns_name() -> str: ...
Remarks
Use this property to get the registered DNS or network name of the local system.
get_local_ip Method
Returns the primary IP address of the local system.
Syntax
def get_local_ip(ipv6: bool) -> str: ...
Remarks
Use this method to obtain the default IP address of the local system.
get_local_ips Method
Returns a list of local IP addresses.
Syntax
def get_local_ips(ipv4: bool, ipv6: bool) -> str: ...
Remarks
Use this method to request a list of all local IP addresses available in the system. Set IPv4 and IPv6 as required to filter IPv4 and IPv6 interfaces in or out respectively.
get_part_to_bytes Method
Saves the data from the specified part to a byte array.
Syntax
def get_part_to_bytes(index: int) -> bytes: ...
Remarks
Use this method to store the data of the specified part to a byte array.
Index must be greater than or equal to 0, and less than the part count.
get_part_to_file Method
Saves the data from the specified part to a file.
Syntax
def get_part_to_file(index: int, filename: str) -> None: ...
Remarks
Use this method to store the data of the specified part to a file.
Index must be greater than or equal to 0, and less than the part count.
get_remote_ip Method
Gets the IP address of a remote host.
Syntax
def get_remote_ip(host_name: str, ipv6: bool, dns_mode: int, dns_servers: str, timeout: int) -> str: ...
Remarks
Use this property to resolve the address of a remote host using the provided DNS settings. Set IPv6 to true to force resolution of both IPv4 and IPv6 addresses.
Use the Timeout setting to specify maximal resolution time, and the DNSServer parameter to list the addresses of DNS servers to use for address resolution. Separate individual servers in the list with commas or semicolons. If an empty server list is provided, the component will use the list of servers configured in the system.
Use one of the below DNS modes:
| dmAuto | 0 |
| dmPlatform | 1 |
| dmOwn | 2 |
| dmOwnSecure | 3 |
get_remote_ips Method
Resolves IP addresses available for a hostname.
Syntax
def get_remote_ips(host_name: str, ipv4: bool, ipv6: bool, dns_mode: int, dns_servers: str, timeout: int) -> str: ...
Remarks
Use this method to resolve all IP addresses available for the chosen hostname using the provided DNS settings. Use the Timeout setting to specify maximal resolution time. The DNSServer parameter lists the addresses of DNS servers to use for address resolution, separated with commas or semicolons. If an empty server list is provided, the component will use the list of servers configured in the system.
Use one of the below DNS modes:
| dmAuto | 0 |
| dmPlatform | 1 |
| dmOwn | 2 |
| dmOwnSecure | 3 |
get_value_by_name Method
Returns the value from the (name, value) pair list for the requested name.
Syntax
def get_value_by_name(name: str) -> str: ...
Remarks
Use this method to obtain a matching value for the requested Name in the name_value_pairs list.
hex_decode Method
Decodes a hex-encoded string into a byte array.
Syntax
def hex_decode(value: str) -> bytes: ...
Remarks
Use this method to decode hex- (base16-) encoded strings to byte arrays.
byte[] buf = utils.HexDecode("48656C6C6F2C20776F726C6421");
hex_encode Method
Encodes a byte array to hex string.
Syntax
def hex_encode(bytes: bytes) -> str: ...
Remarks
Use this method to encode a byte array, passed as Bytes, to a hex (base16) string.
index_of_name Method
Returns the index of the (name, value) pair in the list for the requested Name.
Syntax
def index_of_name(name: str) -> int: ...
Remarks
Use this method to obtain the index of the (Name, Value) object in name_value_pairs list.
load_multipart_from_bytes Method
Loads a multipart message from the specified byte array to MultipartMessage .
Syntax
def load_multipart_from_bytes(content_type: str, data: bytes) -> None: ...
Remarks
Use this method to load a multipart message from a byte array to multipart_message. You need to provide the content of the Content-Type header field together with the multipart body stored in the byte array.
After the data is loaded, you can get the data of each part by calling get_part_to_bytes/get_part_to_file/get_part_to_stream methods.
While loading data, the parts data is stored in temporary files/streams. If the TempPath config property is not empty, the parts data is stored to temporary files in that folder, otherwise the data is stored in memory streams.
load_multipart_from_file Method
Loads a multipart message from the specified file to MultipartMessage .
Syntax
def load_multipart_from_file(content_type: str, filename: str) -> None: ...
Remarks
Use this method to load a multipart message from a file to multipart_message. You need to provide the content of the Content-Type header field together with the multipart body stored in the file.
After the file is loaded, you can get the data of each part by calling get_part_to_bytes/get_part_to_file/get_part_to_stream methods.
While loading data, the parts data is stored in temporary files/streams. If the TempPath config property is not empty, the parts data is stored to temporary files in that folder, otherwise the data is stored in memory streams.
load_name_value_pairs Method
Loads a list of (name, value) pairs from a string.
Syntax
def load_name_value_pairs(data: str, format: str, name_value_separator: str, pair_separator: str, trim_values: bool) -> None: ...
Remarks
Use this method to load a list of (name, value) pairs to name_value_pairs from a string. Provide one of the known formats via Format, and optionally pass the separators using NameValueSeparator and PairSeparator parameters.
The following pre-defined pair list formats are currently supported:
- rdn: a textual distinguished name encoding (/C=US/S=NC/O=Big Company)
- rdnbinary: a hex-encoded DER encoding of the ASN.1 RelativeDistinguishedName object
oid_to_string Method
Converts a binary-encoded ASN.1 OID to its string representation.
Syntax
def oid_to_string(bytes: bytes) -> str: ...
Remarks
Use this method to convert binary-encoded OIDs (object identifiers) to their dotted string representations.
byte[] oid_bin = new byte[] { 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x01, 0x06 };
string oid_str = utils.OidToString(oid_bin);
Console.WriteLine(oid_str); // prints 2.16.840.1.101.3.4.1.6
remove_name_value_pair Method
Remove a (name, value) pair by name.
Syntax
def remove_name_value_pair(name: str) -> bool: ...
Remarks
Use this method to remove the (Name, Value) pair from the name_value_pairs list.
save_multipart_content_type Method
Returns the value for Content-Type field.
Syntax
def save_multipart_content_type() -> str: ...
Remarks
Call this method to get a value for Content-Type field after calling save_multipart_to_bytes or save_multipart_to_file or save_multipart_to_stream.
save_multipart_to_bytes Method
Saves the parts contained in MultipartMessage to a byte array.
Syntax
def save_multipart_to_bytes(multipart_mode: int) -> bytes: ...
Remarks
Use this method to store multipart_message to a temporary byte array.
Supported values for MultipartMode are:
| hmmFormData | 0 | The multipart message contains form data (content type is multipart/form-data) |
| hmmRelated | 1 | The multipart message contains related parts (content type is multipart/related) |
To send the stored data to an HTTP server, follow the steps below:
- Call save_multipart_content_type method and assign the returned value to ContentType field of request_parameters> property
- Call post_bytes> method and pass the array to it
save_multipart_to_file Method
Saves the parts contained in MultipartMessage to the file.
Syntax
def save_multipart_to_file(multipart_mode: int, filename: str) -> None: ...
Remarks
Use this method to store multipart_message to a temporary file.
Supported values for MultipartMode are:
| hmmFormData | 0 | The multipart message contains form data (content type is multipart/form-data) |
| hmmRelated | 1 | The multipart message contains related parts (content type is multipart/related) |
To send the stored data to an HTTP server, follow the steps below:
- Call save_multipart_content_type method and assign the returned value to ContentType field of request_parameters> property
- Call post_file> method and pass the filename to it
save_name_value_pairs Method
Serializes the (name, value) pair list to a string.
Syntax
def save_name_value_pairs(format: str, name_value_separator: str, pair_separator: str) -> str: ...
Remarks
Use this method to save the contents of name_value_pairs to a string. Provide the desired format through the Format parameter, and entry separators (if required) via NameValueSeparator and PairSeparator parameters.
The following pre-defined pair list formats are currently supported:
- rdn: a textual distinguished name encoding (/C=US/S=NC/O=Big Company)
- rdnbinary: a hex-encoded DER encoding of the ASN.1 RelativeDistinguishedName object
set_value_by_name Method
Adds or updates the (name, value) pair by a name.
Syntax
def set_value_by_name(name: str, value: str) -> int: ...
Remarks
This method updates the existing (Name, Value) pair with a new value, or adds a new pair if no such pair existed in name_value_pairs list.
string_decode Method
Converts a byte array to a string using a chosen encoding.
Syntax
def string_decode(bytes: bytes, encoding: str) -> str: ...
Remarks
Use this method to convert a byte array to a string using the required text encoding. The following encodings are currently supported: utf-8, utf16.
Leave Encoding empty to use the default code page configured in the system.
string_encode Method
Encodes a string to a byte array using a chosen character encoding.
Syntax
def string_encode(value: str, encoding: str) -> bytes: ...
Remarks
Use this method to convert a string to a byte array using the provided text encoding. The following encodings are currently supported: utf-8, utf16.
Leave Encoding empty to use the default code page configured in the system.
string_to_date Method
Converts a date represented by a string to a respective Date object.
Syntax
def string_to_date(value: str) -> datetime.datetime: ...
Remarks
Use this method to convert a date string that you obtained from a SecureBlackbox component property or method to a platform date object.
string_to_oid Method
Converts string OID representation to an ASN.1 byte array.
Syntax
def string_to_oid(value: str) -> bytes: ...
Remarks
Use this method to convert an OID represented with a dotted string to the respective ASN.1 representation.
string oid_str = "2.16.840.1.101.3.4.1.6";
byte[] oid_buf = utils.StringToOid(oid_str);
url_decode Method
Decodes a URLEncoded string back into its original form.
Syntax
def url_decode(value: str) -> str: ...
Remarks
Use this method to decode the URLEncoded Value back to its original representation.
url_encode Method
Encodes the provided string using URLEncode.
Syntax
def url_encode(value: str) -> str: ...
Remarks
Use this method to encode Value using URL Encoding (percent encoding), as defined in RFC 3986.
on_error Event
Informs about errors during cryptographic operations.
Syntax
class UtilsErrorEventParams(object): @property def error_code() -> int: ... @property def description() -> str: ... # In class Utils: @property def on_error() -> Callable[[UtilsErrorEventParams], None]: ... @on_error.setter def on_error(event_hook: Callable[[UtilsErrorEventParams], 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_notification Event
This event notifies the application about an underlying control flow event.
Syntax
class UtilsNotificationEventParams(object): @property def event_id() -> str: ... @property def event_param() -> str: ... # In class Utils: @property def on_notification() -> Callable[[UtilsNotificationEventParams], None]: ... @on_notification.setter def on_notification(event_hook: Callable[[UtilsNotificationEventParams], None]) -> None: ...
Remarks
The class fires this event to let the application know about some event, occurrence, or milestone in the class. 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 class, the exact action it is performing, or the document being processed, one or both may be omitted.
Utils 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.Utils 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.
Utils Errors
Utils 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) |