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

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. Below is a summary of little useful features that this class can help you with.

Encoding and decoding

• Encode binary data to base64 and decode it back (Base64Encode and Base64Decode)
• Hex-encode and decode (HexEncode and HexDecode)
• Encode and decode dates - particularly handy when working with other suite components that expect string dates (StringToDate, DateToString)
• Convert object identifiers from and to string representation (StringToOid, OidToString)
• Convert string to any supported character encoding (StringEncode and StringDecode).

Networking helpers

• Get local network parameters with GetLocalIP and GetLocalDNSName
• Resolve remote domain names into IP addresses (GetRemoteIP)
• URL-encode and decode HTTP and other data (UrlEncode and UrlDecode).

Work with multipart MIME messages

• Compose a multipart body with AddPartFromBytes and SaveMultipartToBytes
• Load and process existing multiparts with LoadMultipartFromBytes and GetPartToBytes.

Utils class also offers a useful GetErrorDescription method that lets you obtain a human-readable message for every SecureBlackbox error code you might get. // base64Encode byte[] bytes = ("Life is like riding a bicycle. To keep your balance," + " you must keep moving. (Albert Einstein)").getBytes(); String base64Encoded = utils.base64Encode(bytes,false); System.out.println(base64Encoded); // base64Decode String decoded = new String(utils.base64Decode(base64Encoded,false)); System.out.println(decoded); // Example: Using another SecureBlackBox component to get a string // and convert it to a Java Date object MessageVerifier verifier = new MessageVerifier(); verifier.setInputFile("signedMessage.bin"); verifier.setOutputFile("output.txt"); verifier.verify(); String verifiedDate = verifier.getValidatedSigningTime(); // Retrieving the string: 2024-05-17 13:25:26 Date date = utils.stringToDate(verifiedDate); // Using utils to convert it System.out.println(date); // Output : Fri May 17 13:25:26 CEST 2024 // Retrieving remote IP String hostName = "nsoftware.com"; System.out.println("Hostname: " + hostName + " has this IP: " + utils.getRemoteIP("www.nsoftware.com",false,dmAuto,"",60)); // Output: Hostname: nsoftware.com has this IP: 52.168.9.41 // Hex Encode byte[] bytes = ("Genius is one percent inspiration and " + "ninety-nine percent perspiration.(Thomas Edison)").getBytes(); String hexEncoded = utils.hexEncode(bytes); System.out.println(hexEncoded); // Hex Decode String decoded = new String(utils.hexDecode(hexEncoded)); System.out.println(decoded);

Property List

---

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

Method List

---

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

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.

Config Settings

---

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

MultipartMessage Property (Utils Class)

Lists the content of the multipart message.

Syntax

public MultipartMessagePartList getMultipartMessage();


public void setMultipartMessage(MultipartMessagePartList multipartMessage);

Remarks

This property provides access to all parts contained in or to be added to the multipart message.

This property is not available at design time.

Please refer to the MultipartMessagePart type for a complete list of fields.

NameValuePairs Property (Utils Class)

A current list of (name, value) pairs.

Syntax

public StringNameValuePairList getNameValuePairs();

Remarks

Use this property to access the elements of the (name, value) pair list. Use LoadNameValuePairs and SaveNameValuePairs methods to serialize and deserialize the list to a string, and methods such as SetValueByName or RemoveNameValuePair to manage the list.

This property is read-only and not available at design time.

Please refer to the StringNameValuePair type for a complete list of fields.

AddPartFromBytes Method (Utils Class)

Adds a new part to MultipartMessage from the specified byte array.

Syntax

public int addPartFromBytes(byte[] data);

Remarks

The method adds a new part to MultipartMessage list with the specified data as the part's content.

Returns the index of the added part.

AddPartFromFile Method (Utils Class)

Adds a new part to MultipartMessage from the specified file.

Syntax

public int addPartFromFile(String fileName);

Remarks

The method adds a new part to MultipartMessage list with the specified file data as the part's content.

Returns the index of the added part.

AddPartFromStream Method (Utils Class)

Adds a new part to MultipartMessage from the provided stream.

Syntax

public int addPartFromStream(java.io.InputStream stream, boolean closeStream);

Remarks

The method adds a new part to MultipartMessage with the provided stream data as the part's content. CloseStream specifies if the stream should be closed when the part is deleted or the multipart message is cleared.

Returns the index of the added part.

Base64Decode Method (Utils Class)

Decodes a base64 string to a byte array.

Syntax

public byte[] base64Decode(String value, boolean useURLEncoding);

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);

Base64Encode Method (Utils Class)

Encodes a byte array in base64.

Syntax

public String base64Encode(byte[] bytes, boolean useURLEncoding);

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);

Base64EncodeLines Method (Utils Class)

Encodes the Bytes array containing binary data to a multi-line Base64.

Syntax

public String base64EncodeLines(byte[] bytes, int lineLen);

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 (Utils Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

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.

DateToString Method (Utils Class)

Converts a variable of Date type to the respective string representation.

Syntax

public String dateToString(java.util.Date value);

Remarks

Use this method to convert a value of a platform date type to a string representation accepted by various SecureBlackbox methods and properties.

DoAction Method (Utils Class)

Performs an additional action.

Syntax

public String doAction(String actionID, String actionParams);

Remarks

DoAction 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;....

GetErrorDescription Method (Utils Class)

Returns an error description by an error code.

Syntax

public String getErrorDescription(int errorCode);

Remarks

Use this method to get a human readable description of an error by its code. Returns an empty string if the error code is not recognized.

GetLocalDNSName Method (Utils Class)

Returns the DNS name of the local system.

Syntax

public String getLocalDNSName();

Remarks

Use this property to get the registered DNS or network name of the local system.

GetLocalIP Method (Utils Class)

Returns the primary IP address of the local system.

Syntax

public String getLocalIP(boolean IPv6);

Remarks

Use this method to obtain the default IP address of the local system.

GetLocalIPs Method (Utils Class)

Returns a list of local IP addresses.

Syntax

public String getLocalIPs(boolean IPv4, boolean IPv6);

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.

GetPartToBytes Method (Utils Class)

Saves the data from the specified part to a byte array.

Syntax

public byte[] getPartToBytes(int index);

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.

GetPartToFile Method (Utils Class)

Saves the data from the specified part to a file.

Syntax

public void getPartToFile(int index, String fileName);

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.

GetPartToStream Method (Utils Class)

Saves the data from the specified part to a stream.

Syntax

public void getPartToStream(int index, java.io.OutputStream stream);

Remarks

Use this method to store the data of the specified part to a stream.

Index must be greater than or equal to 0, and less than the part count.

GetRemoteIP Method (Utils Class)

Gets the IP address of a remote host.

Syntax

public String getRemoteIP(String hostName, boolean IPv6, int DNSMode, String DNSServers, int timeout);

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:

GetRemoteIPs Method (Utils Class)

Resolves IP addresses available for a hostname.

Syntax

public String getRemoteIPs(String hostName, boolean IPv4, boolean IPv6, int DNSMode, String DNSServers, int timeout);

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:

GetValueByName Method (Utils Class)

Returns the value from the (name, value) pair list for the requested name.

Syntax

public String getValueByName(String name);

Remarks

Use this method to obtain a matching value for the requested Name in the NameValuePairs list.

HexDecode Method (Utils Class)

Decodes a hex-encoded string into a byte array.

Syntax

public byte[] hexDecode(String value);

Remarks

Use this method to decode hex- (base16-) encoded strings to byte arrays. byte[] buf = utils.HexDecode("48656C6C6F2C20776F726C6421");

HexEncode Method (Utils Class)

Encodes a byte array to hex string.

Syntax

public String hexEncode(byte[] bytes);

Remarks

Use this method to encode a byte array, passed as Bytes, to a hex (base16) string.

IndexOfName Method (Utils Class)

Returns the index of the (name, value) pair in the list for the requested Name.

Syntax

public int indexOfName(String name);

Remarks

Use this method to obtain the index of the (Name, Value) object in NameValuePairs list.

LoadMultipartFromBytes Method (Utils Class)

Loads a multipart message from the specified byte array to MultipartMessage .

Syntax

public void loadMultipartFromBytes(String contentType, byte[] data);

Remarks

Use this method to load a multipart message from a byte array to MultipartMessage. 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 GetPartToBytes/GetPartToFile/GetPartToStream 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.

LoadMultipartFromFile Method (Utils Class)

Loads a multipart message from the specified file to MultipartMessage .

Syntax

public void loadMultipartFromFile(String contentType, String fileName);

Remarks

Use this method to load a multipart message from a file to MultipartMessage. 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 GetPartToBytes/GetPartToFile/GetPartToStream 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.

LoadMultipartFromStream Method (Utils Class)

Loads a multipart message from the specified stream to MultipartMessage .

Syntax

public void loadMultipartFromStream(String contentType, java.io.InputStream stream);

Remarks

Use this method to load a multipart message from a stream to MultipartMessage. You need to provide the content of the Content-Type header field together with the multipart body stored in the stream.

After the stream is loaded, you can get the data of each part by calling GetPartToBytes/GetPartToFile/GetPartToStream 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.

LoadNameValuePairs Method (Utils Class)

Loads a list of (name, value) pairs from a string.

Syntax

public void loadNameValuePairs(String data, String format, String nameValueSeparator, String pairSeparator, boolean trimValues);

Remarks

Use this method to load a list of (name, value) pairs to NameValuePairs 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

If one of these formats is used, the separator parameters are ignored.

OidToString Method (Utils Class)

Converts a binary-encoded ASN.1 OID to its string representation.

Syntax

public String oidToString(byte[] bytes);

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

RemoveNameValuePair Method (Utils Class)

Remove a (name, value) pair by name.

Syntax

public boolean removeNameValuePair(String name);

Remarks

Use this method to remove the (Name, Value) pair from the NameValuePairs list.

Reset Method (Utils Class)

Resets the class settings.

Syntax

public void reset();

Remarks

Reset is a generic method available in every class.

SaveMultipartContentType Method (Utils Class)

Returns the value for Content-Type field.

Syntax

public String saveMultipartContentType();

Remarks

Call this method to get a value for Content-Type field after calling SaveMultipartToBytes or SaveMultipartToFile or SaveMultipartToStream.

SaveMultipartToBytes Method (Utils Class)

Saves the parts contained in MultipartMessage to a byte array.

Syntax

public byte[] saveMultipartToBytes(int multipartMode);

Remarks

Use this method to store MultipartMessage to a temporary byte array.

Supported values for MultipartMode are:

To send the stored data to an HTTP server, follow the steps below:

1. Call SaveMultipartContentType method and assign the returned value to ContentType field of RequestParameters> property
2. Call PostBytes> method and pass the array to it

SaveMultipartToFile Method (Utils Class)

Saves the parts contained in MultipartMessage to the file.

Syntax

public void saveMultipartToFile(int multipartMode, String fileName);

Remarks

Use this method to store MultipartMessage to a temporary file.

Supported values for MultipartMode are:

FileName is the name of the target file for the multipart message.

To send the stored data to an HTTP server, follow the steps below:

1. Call SaveMultipartContentType method and assign the returned value to ContentType field of RequestParameters> property
2. Call PostFile> method and pass the filename to it

SaveMultipartToStream Method (Utils Class)

Saves the parts contained in MultipartMessage to the stream.

Syntax

public void saveMultipartToStream(int multipartMode, java.io.OutputStream stream);

Remarks

Use this method to store MultipartMessage to a temporary stream.

Supported values for MultipartMode are:

Stream is the target stream for the multipart message.

To send the stored data to an HTTP server, follow the steps below:

1. Call SaveMultipartContentType method and assign the returned value to ContentType field of RequestParameters> property
2. Call PostStream> method and pass the stream to it

SaveNameValuePairs Method (Utils Class)

Serializes the (name, value) pair list to a string.

Syntax

public String saveNameValuePairs(String format, String nameValueSeparator, String pairSeparator);

Remarks

Use this method to save the contents of NameValuePairs 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

If one of these formats is used, the separator parameters are ignored.

SetValueByName Method (Utils Class)

Adds or updates the (name, value) pair by a name.

Syntax

public int setValueByName(String name, String value);

Remarks

This method updates the existing (Name, Value) pair with a new value, or adds a new pair if no such pair existed in NameValuePairs list.

StringDecode Method (Utils Class)

Converts a byte array to a string using a chosen encoding.

Syntax

public String stringDecode(byte[] bytes, String encoding);

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.

StringEncode Method (Utils Class)

Encodes a string to a byte array using a chosen character encoding.

Syntax

public byte[] stringEncode(String value, String encoding);

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.

StringToDate Method (Utils Class)

Converts a date represented by a string to a respective Date object.

Syntax

public java.util.Date stringToDate(String value);

Remarks

Use this method to convert a date string that you obtained from a SecureBlackbox component property or method to a platform date object.

StringToOid Method (Utils Class)

Converts string OID representation to an ASN.1 byte array.

Syntax

public byte[] stringToOid(String value);

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);

UrlDecode Method (Utils Class)

Decodes a URLEncoded string back into its original form.

Syntax

public String urlDecode(String value);

Remarks

Use this method to decode the URLEncoded Value back to its original representation.

UrlEncode Method (Utils Class)

Encodes the provided string using URLEncode.

Syntax

public String urlEncode(String value);

Remarks

Use this method to encode Value using URL Encoding (percent encoding), as defined in RFC 3986.

Error Event (Utils Class)

Informs about errors during cryptographic operations.

Syntax

public class DefaultUtilsEventListener implements UtilsEventListener {
  ...
  public void error(UtilsErrorEvent e) {}
  ...
}

public class UtilsErrorEvent {
  public int errorCode;
  public String description;
}

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.

Notification Event (Utils Class)

This event notifies the application about an underlying control flow event.

Syntax

public class DefaultUtilsEventListener implements UtilsEventListener {
  ...
  public void notification(UtilsNotificationEvent e) {}
  ...
}

public class UtilsNotificationEvent {
  public String eventID;
  public String eventParam;
}

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.

MultipartMessagePart Type

Represents a part of a multipart message transferred over HTTP.

Remarks

This type contains all information about a single part in a multipart message.

Fields

Constructors

public MultipartMessagePart();

StringNameValuePair Type

A simple name-value pair object.

Remarks

The class represents a name-value string pair used in a variety of network components.

Fields

Constructors

public StringNameValuePair( name,  value);

public StringNameValuePair();

Config Settings (Utils Class)

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

Trappable Errors (Utils Class)

Utils Errors