Class ToolUtils
- java.lang.Object
-
- com.unboundid.ldap.sdk.unboundidds.tools.ToolUtils
-
@ThreadSafety(level=NOT_THREADSAFE) public final class ToolUtils extends java.lang.Object
This class provides a number of utility methods primarily intended for use with command-line tools.
NOTE: This class, and other classes within the
com.unboundid.ldap.sdk.unboundidds
package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static ObjectPair<java.io.InputStream,java.lang.String>
getInputStreamForLDIFFiles(java.util.List<java.io.File> ldifFiles, java.lang.String encryptionPassphrase, java.io.PrintStream out, java.io.PrintStream err)
Retrieves an input stream that can be used to read data from the specified list of files.static java.io.InputStream
getPossiblyGZIPCompressedInputStream(java.io.InputStream inputStream)
Retrieves anInputStream
that can be used to read data from the provided input stream that may have potentially been GZIP-compressed.static java.io.InputStream
getPossiblyPassphraseEncryptedInputStream(java.io.InputStream inputStream)
Retrieves anInputStream
that can be used to read data from the provided input stream that may have potentially been encrypted with aPassphraseEncryptedOutputStream
using a key from a Ping Identity or Nokia/Alcatel-Lucent 8661 Directory Server's encryption settings database.static ObjectPair<java.io.InputStream,char[]>
getPossiblyPassphraseEncryptedInputStream(java.io.InputStream inputStream, char[] potentialPassphrase, boolean promptOnIncorrectPassphrase, java.lang.CharSequence passphrasePrompt, java.lang.CharSequence incorrectPassphraseError, java.io.PrintStream standardOutput, java.io.PrintStream standardError)
Retrieves anInputStream
that can be used to read data from the provided input stream that may have potentially been encrypted with aPassphraseEncryptedOutputStream
.static ObjectPair<java.io.InputStream,java.lang.String>
getPossiblyPassphraseEncryptedInputStream(java.io.InputStream inputStream, java.lang.String potentialPassphrase, boolean promptOnIncorrectPassphrase, java.lang.CharSequence passphrasePrompt, java.lang.CharSequence incorrectPassphraseError, java.io.PrintStream standardOutput, java.io.PrintStream standardError)
Retrieves anInputStream
that can be used to read data from the provided input stream that may have potentially been encrypted with aPassphraseEncryptedOutputStream
.static ObjectPair<java.io.InputStream,char[]>
getPossiblyPassphraseEncryptedInputStream(java.io.InputStream inputStream, java.util.Collection<char[]> potentialPassphrases, boolean promptOnIncorrectPassphrase, java.lang.CharSequence passphrasePrompt, java.lang.CharSequence incorrectPassphraseError, java.io.PrintStream standardOutput, java.io.PrintStream standardError)
Retrieves anInputStream
that can be used to read data from the provided input stream that may have potentially been encrypted with aPassphraseEncryptedOutputStream
.static java.lang.String
promptForEncryptionPassphrase(boolean allowEmpty, boolean confirm, java.io.PrintStream out, java.io.PrintStream err)
Interactively prompts the user for an encryption passphrase.static java.lang.String
promptForEncryptionPassphrase(boolean allowEmpty, boolean confirm, java.lang.CharSequence initialPrompt, java.lang.CharSequence confirmPrompt, java.io.PrintStream out, java.io.PrintStream err)
Interactively prompts the user for an encryption passphrase.static java.lang.String
readEncryptionPassphraseFromFile(java.io.File f)
Reads an encryption passphrase from the specified file.static void
wrap(java.lang.CharSequence message, java.io.PrintStream out)
Writes a wrapped version of the provided message to the given stream.static void
wrapPrompt(java.lang.CharSequence prompt, boolean ensureTrailingSpace, java.io.PrintStream out)
Wraps the provided prompt such that every line except the last will be followed by a newline, but the last line will not be followed by a newline.
-
-
-
Method Detail
-
readEncryptionPassphraseFromFile
@NotNull public static java.lang.String readEncryptionPassphraseFromFile(@NotNull java.io.File f) throws LDAPException
Reads an encryption passphrase from the specified file. The file must contain exactly one line, which must not be empty, and must be comprised entirely of the encryption passphrase.- Parameters:
f
- The file from which the passphrase should be read. It must not benull
.- Returns:
- The encryption passphrase read from the specified file.
- Throws:
LDAPException
- If a problem occurs while attempting to read the encryption passphrase.
-
promptForEncryptionPassphrase
@NotNull public static java.lang.String promptForEncryptionPassphrase(boolean allowEmpty, boolean confirm, @NotNull java.io.PrintStream out, @NotNull java.io.PrintStream err) throws LDAPException
Interactively prompts the user for an encryption passphrase.- Parameters:
allowEmpty
- Indicates whether the encryption passphrase is allowed to be empty. If this isfalse
, then the user will be re-prompted for the passphrase if the value they enter is empty.confirm
- Indicates whether the user will asked to confirm the passphrase. If this istrue
, then the user will have to enter the same passphrase twice. If this isfalse
, then the user will only be prompted once.out
- ThePrintStream
that will be used for standard output. It must not benull
.err
- ThePrintStream
that will be used for standard error. It must not benull
.- Returns:
- The encryption passphrase provided by the user.
- Throws:
LDAPException
- If a problem is encountered while trying to obtain the passphrase from the user.
-
promptForEncryptionPassphrase
@NotNull public static java.lang.String promptForEncryptionPassphrase(boolean allowEmpty, boolean confirm, @NotNull java.lang.CharSequence initialPrompt, @Nullable java.lang.CharSequence confirmPrompt, @NotNull java.io.PrintStream out, @NotNull java.io.PrintStream err) throws LDAPException
Interactively prompts the user for an encryption passphrase.- Parameters:
allowEmpty
- Indicates whether the encryption passphrase is allowed to be empty. If this isfalse
, then the user will be re-prompted for the passphrase if the value they enter is empty.confirm
- Indicates whether the user will asked to confirm the passphrase. If this istrue
, then the user will have to enter the same passphrase twice. If this isfalse
, then the user will only be prompted once.initialPrompt
- The initial prompt that will be presented to the user. It must not benull
or empty.confirmPrompt
- The prompt that will be presented to the user when asked to confirm the passphrase. It may benull
only ifconfirm
isfalse
.out
- ThePrintStream
that will be used for standard output. It must not benull
.err
- ThePrintStream
that will be used for standard error. It must not benull
.- Returns:
- The encryption passphrase provided by the user.
- Throws:
LDAPException
- If a problem is encountered while trying to obtain the passphrase from the user.
-
wrap
public static void wrap(@NotNull java.lang.CharSequence message, @NotNull java.io.PrintStream out)
Writes a wrapped version of the provided message to the given stream.- Parameters:
message
- The message to be written. If it isnull
or empty, then an empty line will be printed.out
- ThePrintStream
that should be used to write the provided message.
-
wrapPrompt
public static void wrapPrompt(@NotNull java.lang.CharSequence prompt, boolean ensureTrailingSpace, @NotNull java.io.PrintStream out)
Wraps the provided prompt such that every line except the last will be followed by a newline, but the last line will not be followed by a newline.- Parameters:
prompt
- The prompt to be wrapped. It must not benull
or empty.ensureTrailingSpace
- Indicates whether to ensure that there is a trailing space after the end of the prompt.out
- ThePrintStream
to which the prompt should be written. It must not benull
.
-
getInputStreamForLDIFFiles
@NotNull public static ObjectPair<java.io.InputStream,java.lang.String> getInputStreamForLDIFFiles(@NotNull java.util.List<java.io.File> ldifFiles, @Nullable java.lang.String encryptionPassphrase, @NotNull java.io.PrintStream out, @NotNull java.io.PrintStream err) throws java.io.IOException
Retrieves an input stream that can be used to read data from the specified list of files. It will handle the possibility that any or all of the LDIF files are encrypted and/or compressed.- Parameters:
ldifFiles
- The list of LDIF files from which the data is to be read. It must not benull
or empty.encryptionPassphrase
- The passphrase that should be used to access encrypted LDIF files. It may benull
if the user should be interactively prompted for the passphrase if any of the files is encrypted.out
- The print stream to use for standard output. It must not benull
.err
- The print stream to use for standard error. It must not benull
.- Returns:
- An
ObjectPair
whose first element is an input stream that can be used to read data from the specified list of files, and whose second element is a possibly-null
passphrase that is used to encrypt the input data. - Throws:
java.io.IOException
- If a problem is encountered while attempting to get the input stream for reading the data.
-
getPossiblyGZIPCompressedInputStream
@NotNull public static java.io.InputStream getPossiblyGZIPCompressedInputStream(@NotNull java.io.InputStream inputStream) throws java.io.IOException
Retrieves anInputStream
that can be used to read data from the provided input stream that may have potentially been GZIP-compressed. If the provided input stream does not appear to contain GZIP-compressed data, then the returned stream will permit reading the data from the provided stream without any alteration.
The determination will be made by looking to see if the first two bytes read from the provided input stream are 0x1F and 0x8B, respectively (which is the GZIP magic header). To avoid false positives, this method should only be used if it is known that if the input stream does not contain compressed data, then it will not start with that two-byte sequence. This method should always be safe to use if the data to be read is text. If the data may be binary and that binary data may happen to start with 0x1F 0x8B, then this method should not be used.
The input stream'smark
andreset
methods will be used to permit peeking at the data at the head of the input stream. If the provided stream does not support the use of those methods, then it will be wrapped in aBufferedInputStream
, which does support them.- Parameters:
inputStream
- The input stream from which the data is to be read.- Returns:
- A
GZIPInputStream
that wraps the provided input stream if the stream appears to contain GZIP-compressed data, or the provided input stream (potentially wrapped in aBufferedInputStream
) if the provided stream does not appear to contain GZIP-compressed data. - Throws:
java.io.IOException
- If a problem is encountered while attempting to determine whether the stream contains GZIP-compressed data.
-
getPossiblyPassphraseEncryptedInputStream
@NotNull public static java.io.InputStream getPossiblyPassphraseEncryptedInputStream(@NotNull java.io.InputStream inputStream) throws java.io.IOException, java.security.GeneralSecurityException
Retrieves anInputStream
that can be used to read data from the provided input stream that may have potentially been encrypted with aPassphraseEncryptedOutputStream
using a key from a Ping Identity or Nokia/Alcatel-Lucent 8661 Directory Server's encryption settings database. This method will throw an exception rather than interactively prompting for a passphrase if the content is encrypted but the encryption key is not readily available.
The determination will be made by looking to see if the input stream starts with a validPassphraseEncryptedStreamHeader
. Because of the complex nature of that header, it is highly unlikely that the input stream will just happen to start with a valid header if the stream does not actually contain encrypted data.
The input stream'smark
andreset
methods will be used to permit peeking at the data at the head of the input stream. If the provided stream does not support the use of those methods, then it will be wrapped in aBufferedInputStream
, which does support them.- Parameters:
inputStream
- The input stream from which the data is to be read. It must not benull
.- Returns:
- The resulting input stream that may be used to read from the
given input stream. If the data was encrypted, then the returned
stream will be a
PassphraseEncryptedInputStream
that may be used to read decrypted data from it. If the data was not encrypted, then the original stream (possibly wrapped by aBufferedInputStream
will be returned. - Throws:
java.io.IOException
- If a problem is encountered while attempting to determine whether the stream contains passphrase-encrypted data.java.security.GeneralSecurityException
- If a problem is encountered while attempting to prepare to decrypt data read from the input stream, or if the stream is encrypted with a key that is not readily available.
-
getPossiblyPassphraseEncryptedInputStream
@NotNull public static ObjectPair<java.io.InputStream,java.lang.String> getPossiblyPassphraseEncryptedInputStream(@NotNull java.io.InputStream inputStream, @Nullable java.lang.String potentialPassphrase, boolean promptOnIncorrectPassphrase, @NotNull java.lang.CharSequence passphrasePrompt, @NotNull java.lang.CharSequence incorrectPassphraseError, @NotNull java.io.PrintStream standardOutput, @NotNull java.io.PrintStream standardError) throws java.io.IOException, java.security.InvalidKeyException, java.security.GeneralSecurityException
Retrieves anInputStream
that can be used to read data from the provided input stream that may have potentially been encrypted with aPassphraseEncryptedOutputStream
. If the provided input stream does not appear to contain passphrase-encrypted data, then the returned stream will permit reading the data from the provided stream without any alteration.
The determination will be made by looking to see if the input stream starts with a validPassphraseEncryptedStreamHeader
. Because of the complex nature of that header, it is highly unlikely that the input stream will just happen to start with a valid header if the stream does not actually contain encrypted data.
The input stream'smark
andreset
methods will be used to permit peeking at the data at the head of the input stream. If the provided stream does not support the use of those methods, then it will be wrapped in aBufferedInputStream
, which does support them.- Parameters:
inputStream
- The input stream from which the data is to be read. It must not benull
.potentialPassphrase
- A potential passphrase that may have been used to encrypt the data. It may benull
if the passphrase should only be obtained via interactive prompting, or if the data was encrypted with a server-side encryption settings definition. If the passphrase is notnull
but is incorrect, then the user may be interactively prompted for the correct passphrase.promptOnIncorrectPassphrase
- Indicates whether the user should be interactively prompted for the correct passphrase if the provided passphrase is non-null
and is also incorrect.passphrasePrompt
- The prompt that will be presented to the user if the input stream does contain encrypted data and the passphrase needs to be interactively requested from the user. It must not benull
or empty.incorrectPassphraseError
- The error message that will be presented to the user if the entered passphrase is not correct. It must not benull
or empty.standardOutput
- ThePrintStream
to use to write to standard output while interactively prompting for the passphrase. It must not benull
.standardError
- ThePrintStream
to use to write to standard error while interactively prompting for the passphrase. It must not benull
.- Returns:
- An
ObjectPair
that combines the resulting input stream with the associated encryption passphrase. If the provided input stream is encrypted, then the returned input stream element will be aPassphraseEncryptedInputStream
and the returned passphrase element will be non-null
. If the provided input stream is not encrypted, then the returned input stream element will be the provided input stream (potentially wrapped in aBufferedInputStream
), and the returned passphrase element will benull
. - Throws:
java.io.IOException
- If a problem is encountered while attempting to determine whether the stream contains passphrase-encrypted data.java.security.InvalidKeyException
- If the provided passphrase is incorrect and the user should not be interactively prompted for the correct passphrase.java.security.GeneralSecurityException
- If a problem is encountered while attempting to prepare to decrypt data read from the input stream.
-
getPossiblyPassphraseEncryptedInputStream
@NotNull public static ObjectPair<java.io.InputStream,char[]> getPossiblyPassphraseEncryptedInputStream(@NotNull java.io.InputStream inputStream, @Nullable char[] potentialPassphrase, boolean promptOnIncorrectPassphrase, @NotNull java.lang.CharSequence passphrasePrompt, @NotNull java.lang.CharSequence incorrectPassphraseError, @NotNull java.io.PrintStream standardOutput, @NotNull java.io.PrintStream standardError) throws java.io.IOException, java.security.InvalidKeyException, java.security.GeneralSecurityException
Retrieves anInputStream
that can be used to read data from the provided input stream that may have potentially been encrypted with aPassphraseEncryptedOutputStream
. If the provided input stream does not appear to contain passphrase-encrypted data, then the returned stream will permit reading the data from the provided stream without any alteration.
The determination will be made by looking to see if the input stream starts with a validPassphraseEncryptedStreamHeader
. Because of the complex nature of that header, it is highly unlikely that the input stream will just happen to start with a valid header if the stream does not actually contain encrypted data.
The input stream'smark
andreset
methods will be used to permit peeking at the data at the head of the input stream. If the provided stream does not support the use of those methods, then it will be wrapped in aBufferedInputStream
, which does support them.- Parameters:
inputStream
- The input stream from which the data is to be read. It must not benull
.potentialPassphrase
- A potential passphrase that may have been used to encrypt the data. It may benull
if the passphrase should only be obtained via interactive prompting, or if the data was encrypted with a server-side encryption settings definition. If the passphrase is notnull
but is incorrect, then the user may be interactively prompted for the correct passphrase.promptOnIncorrectPassphrase
- Indicates whether the user should be interactively prompted for the correct passphrase if the provided passphrase is non-null
and is also incorrect.passphrasePrompt
- The prompt that will be presented to the user if the input stream does contain encrypted data and the passphrase needs to be interactively requested from the user. It must not benull
or empty.incorrectPassphraseError
- The error message that will be presented to the user if the entered passphrase is not correct. It must not benull
or empty.standardOutput
- ThePrintStream
to use to write to standard output while interactively prompting for the passphrase. It must not benull
.standardError
- ThePrintStream
to use to write to standard error while interactively prompting for the passphrase. It must not benull
.- Returns:
- An
ObjectPair
that combines the resulting input stream with the associated encryption passphrase. If the provided input stream is encrypted, then the returned input stream element will be aPassphraseEncryptedInputStream
and the returned passphrase element will be non-null
. If the provided input stream is not encrypted, then the returned input stream element will be the provided input stream (potentially wrapped in aBufferedInputStream
), and the returned passphrase element will benull
. - Throws:
java.io.IOException
- If a problem is encountered while attempting to determine whether the stream contains passphrase-encrypted data.java.security.InvalidKeyException
- If the provided passphrase is incorrect and the user should not be interactively prompted for the correct passphrase.java.security.GeneralSecurityException
- If a problem is encountered while attempting to prepare to decrypt data read from the input stream.
-
getPossiblyPassphraseEncryptedInputStream
@NotNull public static ObjectPair<java.io.InputStream,char[]> getPossiblyPassphraseEncryptedInputStream(@NotNull java.io.InputStream inputStream, @Nullable java.util.Collection<char[]> potentialPassphrases, boolean promptOnIncorrectPassphrase, @NotNull java.lang.CharSequence passphrasePrompt, @NotNull java.lang.CharSequence incorrectPassphraseError, @NotNull java.io.PrintStream standardOutput, @NotNull java.io.PrintStream standardError) throws java.io.IOException, java.security.InvalidKeyException, java.security.GeneralSecurityException
Retrieves anInputStream
that can be used to read data from the provided input stream that may have potentially been encrypted with aPassphraseEncryptedOutputStream
. If the provided input stream does not appear to contain passphrase-encrypted data, then the returned stream will permit reading the data from the provided stream without any alteration.
The determination will be made by looking to see if the input stream starts with a validPassphraseEncryptedStreamHeader
. Because of the complex nature of that header, it is highly unlikely that the input stream will just happen to start with a valid header if the stream does not actually contain encrypted data.
The input stream'smark
andreset
methods will be used to permit peeking at the data at the head of the input stream. If the provided stream does not support the use of those methods, then it will be wrapped in aBufferedInputStream
, which does support them.- Parameters:
inputStream
- The input stream from which the data is to be read. It must not benull
.potentialPassphrases
- A collection of potential passphrases that may have been used to encrypt the data. It may benull
or empty if the passphrase should only be obtained via interactive prompting, or if the data was encrypted with a server-side encryption settings definition. If none of the provided passphrases are correct, then the user may still be interactively prompted for the correct passphrase based on the value of thepromptOnIncorrectPassphrase
argument.promptOnIncorrectPassphrase
- Indicates whether the user should be interactively prompted for the correct passphrase if the set of potential passphrases is non-null
and non-empty, but none of the passphrases were correct.passphrasePrompt
- The prompt that will be presented to the user if the input stream does contain encrypted data and the passphrase needs to be interactively requested from the user. It must not benull
or empty.incorrectPassphraseError
- The error message that will be presented to the user if the entered passphrase is not correct. It must not benull
or empty.standardOutput
- ThePrintStream
to use to write to standard output while interactively prompting for the passphrase. It must not benull
.standardError
- ThePrintStream
to use to write to standard error while interactively prompting for the passphrase. It must not benull
.- Returns:
- An
ObjectPair
that combines the resulting input stream with the associated encryption passphrase. If the provided input stream is encrypted, then the returned input stream element will be aPassphraseEncryptedInputStream
and the returned passphrase element will be non-null
. If the provided input stream is not encrypted, then the returned input stream element will be the provided input stream (potentially wrapped in aBufferedInputStream
), and the returned passphrase element will benull
. - Throws:
java.io.IOException
- If a problem is encountered while attempting to determine whether the stream contains passphrase-encrypted data.java.security.InvalidKeyException
- If the provided passphrase is incorrect and the user should not be interactively prompted for the correct passphrase.java.security.GeneralSecurityException
- If a problem is encountered while attempting to prepare to decrypt data read from the input stream.
-
-