Package com.unboundid.ldap.sdk.unboundidds.logs.v2.syntax

Class DNLogFieldSyntax

  • @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class DNLogFieldSyntax
extends LogFieldSyntax<DN>
    This class defines a log field syntax for distinguished name values. This syntax allows individual attribute values to be redacted or tokenized within the DNs. If a DN is completely redacted, then the redacted representation will be "redacted={REDACTED}". If a DN is completely tokenized, then the tokenized representation will be "tokenized={TOKENIZED:token-value}", where token-value will be replaced with a generated value.
    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.

    • Constructor Detail

      • DNLogFieldSyntax

        public DNLogFieldSyntax​(int maxStringLengthCharacters,
                        @Nullable
                        Schema schema,
                        @Nullable
                        java.util.Collection<java.lang.String> includedSensitiveAttributes,
                        @Nullable
                        java.util.Collection<java.lang.String> excludedSensitiveAttributes)
        Creates a new DN log field syntax instance that can optionally define specific attributes to include in or exclude from redaction or tokenization. If any include attributes are specified, then only the values of those attributes will be considered sensitive and will have their values tokenized or redacted. If any exclude attributes are specified, then the values of any attributes except those will be considered sensitive. If no include attributes and no exclude attributes are specified, then all attributes will be considered sensitive and will have their values tokenized or redacted.
        Parameters:
        maxStringLengthCharacters - The maximum length (in characters) to use for strings within values. Strings that are longer than this should be truncated before inclusion in the log. This value must be greater than or equal to zero.
        schema - The schema to use in processing. It may optionally be null if no schema should be used.
        includedSensitiveAttributes - The set of names and OIDs for the specific attributes whose values should be considered sensitive and should have their values redacted or tokenized by methods that operate on value components. This may be null or empty if no included sensitive attributes should be defined.
        excludedSensitiveAttributes - The set of names and OIDs for the specific attributes whose values should not be considered sensitive and should not have their values redacted or tokenized by methods that operate on value components. This may be null or empty if no excluded sensitive attributes should be defined.

    • Method Detail

      • getIncludedSensitiveAttributes

        @NotNull
public java.util.Set<java.lang.String> getIncludedSensitiveAttributes()
        Retrieves a set containing the names and/or OIDs of the attributes that will be considered sensitive and will have their values redacted or tokenized in methods that operate on DN components.
        Returns:
        A set containing the names and/or OIDs of the attributes that will be considered sensitive, or an empty list if no included sensitive attributes are defined.

      • getExcludedSensitiveAttributes

        @NotNull
public java.util.Set<java.lang.String> getExcludedSensitiveAttributes()
        Retrieves a set containing the names and/or OIDs of the attributes that will not be considered sensitive and will have not their values redacted or tokenized in methods that operate on DN components.
        Returns:
        A set containing the names and/or OIDs of the attributes that will not be considered sensitive, or an empty list if no excluded sensitive attributes are defined.

      • valueToSanitizedString

        public void valueToSanitizedString​(@NotNull
                                   DN value,
                                   @NotNull
                                   ByteStringBuffer buffer)
        Encodes the provided value to a sanitized string representation suitable for inclusion in a log message. The sanitized string should at least be cleaned of control characters and other non-printable characters, but depending on the syntax, it may clean other characters as well.
        Specified by:
        valueToSanitizedString in class LogFieldSyntax<DN>
        Parameters:
        value - The value to be encoded. It must not be null.
        buffer - The buffer to which the string representation should be appended. It must not be null.

      • logSanitizedFieldToJSONFormattedLog

        public void logSanitizedFieldToJSONFormattedLog​(@NotNull
                                                java.lang.String fieldName,
                                                @NotNull
                                                DN fieldValue,
                                                @NotNull
                                                JSONBuffer buffer)
        Appends a sanitized representation of the specified field (both field name and value) for a JSON-formatted log message to the given buffer.
        Specified by:
        logSanitizedFieldToJSONFormattedLog in class LogFieldSyntax<DN>
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.

      • logSanitizedValueToJSONFormattedLog

        public void logSanitizedValueToJSONFormattedLog​(@NotNull
                                                DN value,
                                                @NotNull
                                                JSONBuffer buffer)
        Appends a sanitized representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) for a JSON-formatted log message to the given buffer.
        Specified by:
        logSanitizedValueToJSONFormattedLog in class LogFieldSyntax<DN>
        Parameters:
        value - The value to be appended to the buffer. It must not be null.
        buffer - The buffer to which the sanitized value should be appended. It must not be null.

      • valueStringIsCompletelyRedacted

        public boolean valueStringIsCompletelyRedacted​(@NotNull
                                               java.lang.String valueString)
        Determines whether the provided value string represents a value that has been completely redacted.
        Overrides:
        valueStringIsCompletelyRedacted in class LogFieldSyntax<DN>
        Parameters:
        valueString - The value for which to make the determination. It must not be null.
        Returns:
        true if the provided value string represents a value that has been completely redacted, or false if not.

      • supportsRedactedComponents

        public boolean supportsRedactedComponents()
        Indicates whether this syntax supports redacting individual components of the entire value.
        Specified by:
        supportsRedactedComponents in class LogFieldSyntax<DN>
        Returns:
        true if this syntax supports redacting individual components of the entire value, or false if not.

      • redactComponents

        public void redactComponents​(@NotNull
                             DN value,
                             @NotNull
                             ByteStringBuffer buffer)
        Appends a string representation of the given value with redacted components to the provided buffer.
        Overrides:
        redactComponents in class LogFieldSyntax<DN>
        Parameters:
        value - The value for which to obtain the redacted representation. It must not be null.
        buffer - The buffer to which the redacted string representation should be appended. It must not be null.

      • logRedactedComponentsFieldToTextFormattedLog

        public void logRedactedComponentsFieldToTextFormattedLog​(@NotNull
                                                         java.lang.String fieldName,
                                                         @NotNull
                                                         DN fieldValue,
                                                         @NotNull
                                                         ByteStringBuffer buffer)
        Appends a representation of the specified field (both field name and value) with redacted value components for a text-formatted log message to the given buffer. If this syntax does not support redacting components within a value, then it should redact the entire value.
        Specified by:
        logRedactedComponentsFieldToTextFormattedLog in class LogFieldSyntax<DN>
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.

      • logRedactedComponentsFieldToJSONFormattedLog

        public void logRedactedComponentsFieldToJSONFormattedLog​(@NotNull
                                                         java.lang.String fieldName,
                                                         @NotNull
                                                         DN fieldValue,
                                                         @NotNull
                                                         JSONBuffer buffer)
        Appends a representation of the specified field (both field name and value) with redacted value components for a JSON-formatted log message to the given buffer. If this syntax does not support redacting components within a value, then it should redact the entire value.
        Specified by:
        logRedactedComponentsFieldToJSONFormattedLog in class LogFieldSyntax<DN>
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.

      • logRedactedComponentsValueToJSONFormattedLog

        public void logRedactedComponentsValueToJSONFormattedLog​(@NotNull
                                                         DN value,
                                                         @NotNull
                                                         JSONBuffer buffer)
        Appends a representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) with redacted components for a JSON-formatted log message to the given buffer. If this syntax does not support redacting components within a value, then it should redact the entire value.
        Specified by:
        logRedactedComponentsValueToJSONFormattedLog in class LogFieldSyntax<DN>
        Parameters:
        value - The value to be appended to the buffer in redacted form. It must not be null.
        buffer - The buffer to which the redacted value should be appended. It must not be null.

      • valueStringIsCompletelyTokenized

        public boolean valueStringIsCompletelyTokenized​(@NotNull
                                                java.lang.String valueString)
        Determines whether the provided value string represents a value that has been completely tokenized.
        Overrides:
        valueStringIsCompletelyTokenized in class LogFieldSyntax<DN>
        Parameters:
        valueString - The value for which to make the determination. It must not be null.
        Returns:
        true if the provided value string represents a value that has been completely tokenized, or false if not.

      • tokenizeEntireValue

        public void tokenizeEntireValue​(@NotNull
                                DN value,
                                @NotNull
                                byte[] pepper,
                                @NotNull
                                ByteStringBuffer buffer)
        Appends a tokenized representation of the provided value to the given buffer.

        The resulting token will protect the provided value by representing it in a way that makes it at infeasible to determine what the original value was. However, tokenizing the same value with the same pepper should consistently yield the same token value, so that it will be possible to identify the same value across multiple log messages.
        Specified by:
        tokenizeEntireValue in class LogFieldSyntax<DN>
        Parameters:
        value - The value for which to generate the token. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the tokenized representation should be appended. It must not be null.

      • logCompletelyTokenizedFieldToTextFormattedLog

        public void logCompletelyTokenizedFieldToTextFormattedLog​(@NotNull
                                                          java.lang.String fieldName,
                                                          @NotNull
                                                          DN fieldValue,
                                                          @NotNull
                                                          byte[] pepper,
                                                          @NotNull
                                                          ByteStringBuffer buffer)
        Appends a completely tokenized representation of the specified field (both field name and value) for a text-formatted log message to the given buffer.
        Specified by:
        logCompletelyTokenizedFieldToTextFormattedLog in class LogFieldSyntax<DN>
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.

      • logCompletelyTokenizedFieldToJSONFormattedLog

        public void logCompletelyTokenizedFieldToJSONFormattedLog​(@NotNull
                                                          java.lang.String fieldName,
                                                          @NotNull
                                                          DN fieldValue,
                                                          @NotNull
                                                          byte[] pepper,
                                                          @NotNull
                                                          JSONBuffer buffer)
        Appends a completely tokenized representation of the specified field (both field name and value) for a JSON-formatted log message to the given buffer.
        Specified by:
        logCompletelyTokenizedFieldToJSONFormattedLog in class LogFieldSyntax<DN>
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.

      • logCompletelyTokenizedValueToJSONFormattedLog

        public void logCompletelyTokenizedValueToJSONFormattedLog​(@NotNull
                                                          DN value,
                                                          @NotNull
                                                          byte[] pepper,
                                                          @NotNull
                                                          JSONBuffer buffer)
        Appends a completely tokenized representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) for a JSON-formatted log message to the given buffer.
        Specified by:
        logCompletelyTokenizedValueToJSONFormattedLog in class LogFieldSyntax<DN>
        Parameters:
        value - The value to be appended to the buffer in tokenized form. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the tokenized value should be appended. It must not be null.

      • supportsTokenizedComponents

        public boolean supportsTokenizedComponents()
        Indicates whether this syntax supports tokenizing individual components of the entire value.
        Specified by:
        supportsTokenizedComponents in class LogFieldSyntax<DN>
        Returns:
        true if this syntax supports tokenizing individual components of the entire value, or false if not.

      • tokenizeComponents

        public void tokenizeComponents​(@NotNull
                               DN value,
                               @NotNull
                               byte[] pepper,
                               @NotNull
                               ByteStringBuffer buffer)
        Appends a string representation of the given value with zero or more of its components tokenized to the provided buffer. If this syntax does not support tokenized components, then the entire value should be tokenized.

        The resulting tokens will protect components of the provided value by representing them in a way that makes it at infeasible to determine what the original components were. However, tokenizing the same value with the same pepper should consistently yield the same token value, so that it will be possible to identify the same value across multiple log messages.
        Overrides:
        tokenizeComponents in class LogFieldSyntax<DN>
        Parameters:
        value - The value whose components should be tokenized. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the tokenized representation should be appended. It must not be null.

      • logTokenizedComponentsFieldToTextFormattedLog

        public void logTokenizedComponentsFieldToTextFormattedLog​(@NotNull
                                                          java.lang.String fieldName,
                                                          @NotNull
                                                          DN fieldValue,
                                                          @NotNull
                                                          byte[] pepper,
                                                          @NotNull
                                                          ByteStringBuffer buffer)
        Appends a representation of the specified field (both field name and value) with tokenized value components for a text-formatted log message to the given buffer. If this syntax does not support tokenizing components within a value, then it should tokenize the entire value.
        Specified by:
        logTokenizedComponentsFieldToTextFormattedLog in class LogFieldSyntax<DN>
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.

      • logTokenizedComponentsFieldToJSONFormattedLog

        public void logTokenizedComponentsFieldToJSONFormattedLog​(@NotNull
                                                          java.lang.String fieldName,
                                                          @NotNull
                                                          DN fieldValue,
                                                          @NotNull
                                                          byte[] pepper,
                                                          @NotNull
                                                          JSONBuffer buffer)
        Appends a representation of the specified field (both field name and value) with tokenized value components for a JSON-formatted log message to the given buffer. If this syntax does not support tokenizing components within a value, then it should tokenize the entire value.
        Specified by:
        logTokenizedComponentsFieldToJSONFormattedLog in class LogFieldSyntax<DN>
        Parameters:
        fieldName - The name for the field. It must not be null.
        fieldValue - The value to use for the field. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the sanitized log field should be appended. It must not be null.

      • logTokenizedComponentsValueToJSONFormattedLog

        public void logTokenizedComponentsValueToJSONFormattedLog​(@NotNull
                                                          DN value,
                                                          @NotNull
                                                          byte[] pepper,
                                                          @NotNull
                                                          JSONBuffer buffer)
        Appends a representation of the provided value (without a field name, as might be suitable for a value included in a JSON array) with tokenized value components for a JSON-formatted log message to the given buffer. If this syntax does not support tokenizing components within a value, then it should tokenize the entire value.
        Specified by:
        logTokenizedComponentsValueToJSONFormattedLog in class LogFieldSyntax<DN>
        Parameters:
        value - The value to be appended to the buffer in tokenized form. It must not be null.
        pepper - A pepper used to provide brute-force protection for the resulting token. The pepper value should be kept secret so that it is not available to unauthorized users who might be able to view log information, although the same pepper value should be consistently provided when tokenizing values so that the same value will consistently yield the same token. It must not be null and should not be empty.
        buffer - The buffer to which the tokenized value should be appended. It must not be null.