Package com.upokecenter.cbor

Class CBOREncodeOptions

java.lang.Object

com.upokecenter.cbor.CBOREncodeOptions

public final class CBOREncodeOptions
extends Object

Specifies options for encoding and decoding CBOR objects.

Field Summary

Fields

Modifier and Type	Field	Description
static final CBOREncodeOptions	Default	Default options for CBOR objects.
static final CBOREncodeOptions	DefaultCtap2Canonical	Default options for CBOR objects serialized using the CTAP2 canonicalization (used in Web Authentication, among other specifications).

Constructor Summary

Constructors

Constructor	Description
CBOREncodeOptions()	Initializes a new instance of the CBOREncodeOptions class with all the default options.
CBOREncodeOptions(boolean useIndefLengthStrings, boolean allowDuplicateKeys)	Deprecated. Use the more readable String constructor instead.
CBOREncodeOptions(boolean useIndefLengthStrings, boolean allowDuplicateKeys, boolean ctap2Canonical)	Deprecated. Use the more readable String constructor instead.
CBOREncodeOptions(String paramString)	Initializes a new instance of the CBOREncodeOptions class.

Method Summary

Modifier and Type	Method	Description
final boolean	getAllowDuplicateKeys()	Gets a value indicating whether to allow duplicate keys when reading CBOR objects from a data stream.
final boolean	getAllowEmpty()	Gets a value indicating whether decoding a CBOR object will return null instead of a CBOR object if the stream has no content or the end of the stream is reached before decoding begins.
final boolean	getCtap2Canonical()	Gets a value indicating whether CBOR objects:
final boolean	getFloat64()	Gets a value indicating whether to encode floating-point numbers in a CBOR object in their 64-bit encoding form regardless of whether their value can be encoded without loss in a smaller form.
final boolean	getKeepKeyOrder()	Gets a value indicating whether to preserve the order in which a CBOR map's keys appear when decoding a CBOR object, by using maps created as though by CBORObject.NewOrderedMap.
final boolean	getResolveReferences()	Gets a value indicating whether to resolve references to sharable objects and sharable strings in the process of decoding a CBOR object.
final boolean	getUseIndefLengthStrings()	Gets a value indicating whether to encode strings with an indefinite-length encoding under certain circumstances.
String	toString()	Gets the values of this options object's properties in text form.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

Default

public static final CBOREncodeOptions Default

Default options for CBOR objects. Disallow duplicate keys, and always encode strings using definite-length encoding.

DefaultCtap2Canonical

public static final CBOREncodeOptions DefaultCtap2Canonical

Default options for CBOR objects serialized using the CTAP2 canonicalization (used in Web Authentication, among other specifications). Disallow duplicate keys, and always encode strings using definite-length encoding.

Constructor Details

CBOREncodeOptions

public CBOREncodeOptions()

Initializes a new instance of the CBOREncodeOptions class with all the default options.

CBOREncodeOptions

@Deprecated
public CBOREncodeOptions(boolean useIndefLengthStrings,
 boolean allowDuplicateKeys)

Deprecated.

Use the more readable String constructor instead.

Initializes a new instance of the CBOREncodeOptions class.

Parameters:

useIndefLengthStrings - A value indicating whether to always encode strings with a definite-length encoding.

allowDuplicateKeys - A value indicating whether to disallow duplicate keys when reading CBOR objects from a data stream.

CBOREncodeOptions

@Deprecated
public CBOREncodeOptions(boolean useIndefLengthStrings,
 boolean allowDuplicateKeys,
 boolean ctap2Canonical)

Deprecated.

Use the more readable String constructor instead.

Initializes a new instance of the CBOREncodeOptions class.

Parameters:

useIndefLengthStrings - A value indicating whether to encode strings with a definite-length encoding in certain cases.

allowDuplicateKeys - A value indicating whether to allow duplicate keys when reading CBOR objects from a data stream.

ctap2Canonical - A value indicating whether CBOR objects are written out using the CTAP2 canonical CBOR encoding form, which is useful for implementing Web Authentication.

CBOREncodeOptions

public CBOREncodeOptions(String paramString)

Initializes a new instance of the CBOREncodeOptions class.

Parameters:

paramString - A string setting forth the options to use. This is a semicolon-separated list of options, each of which has a key and a value separated by an equal sign ("="). Whitespace and line separators are not allowed to appear between the semicolons or between the equal signs, nor may the string begin or end with whitespace. The string can be empty, but cannot be null. The following is an example of this parameter: allowduplicatekeys = true;ctap2Canonical = true. The key can be any one of the following where the letters can be any combination of basic upper-case and/or basic lower-case letters: allowduplicatekeys, ctap2canonical, resolvereferences, useindeflengthstrings, allowempty, float64, keepkeyorder. Keys other than these are ignored in this version of the CBOR library. The key float64 was introduced in version 4.4 of this library. The key keepkeyorder was introduced in version 4.5 of this library.(Keys are compared using a basic case-insensitive comparison, in which two strings are equal if they match after converting the basic upper-case letters A to Z (U+0041 to U+005A) in both strings to basic lower-case letters.) If two or more key/value pairs have equal keys (in a basic case-insensitive comparison), the value given for the last such key is used. The four keys just given can have a value of 1, true, yes, or on (where the letters can be any combination of basic upper-case and/or basic lower-case letters), which means true, and any other value meaning false. For example, allowduplicatekeys = Yes and allowduplicatekeys = 1 both set the AllowDuplicateKeys property to true. In the future, this class may allow other keys to store other kinds of values, not just true or false.

Throws:

NullPointerException - The parameter paramString is null.

Method Details

toString

public String toString()

Gets the values of this options object's properties in text form.

Overrides:

toString in class Object

Returns:

A text string containing the values of this options object's properties. The format of the string is the same as the one described in the string constructor for this class.

getResolveReferences

public final boolean getResolveReferences()

Gets a value indicating whether to resolve references to sharable objects and sharable strings in the process of decoding a CBOR object. Enabling this property, however, can cause a security risk if a decoded CBOR object is then re-encoded.

About sharable objects and references

Sharable objects are marked with tag 28, and references to those objects are marked with tag 29 (where a reference of 0 means the first sharable object in the CBOR stream, a reference of 1 means the second, and so on). Sharable strings (byte strings and text strings) appear within an enclosing object marked with tag 256, and references to them are marked with tag 25; in general, a string is sharable only if storing its reference rather than the string would save space.

Note that unlike most other tags, these tags generally care about the relative order in which objects appear in a CBOR stream; thus they are not interoperable with CBOR implementations that follow the generic CBOR data model (since they may list map keys in an unspecified order). Interoperability problems with these tags can be reduced by not using them to mark keys or values of a map or to mark objects within those keys or values.

Security Note

When this property is enabled and a decoded CBOR object contains references to sharable CBOR objects within it, those references will be replaced with the sharable objects they refer to (but without making a copy of those objects). However, if shared references are deeply nested and used multiple times, these references can result in a CBOR object that is orders of magnitude bigger than if shared references weren't resolved, and this can cause a denial of service when the decoded CBOR object is then serialized (e.g., with EncodeToBytes(), toString(), ToJSONString(), or WriteTo), because object references are expanded in the process.

For example, the following object in CBOR diagnostic notation, [28(["xxx", "yyy"]), 28([29(0), 29(0), 29(0)]), 28([29(1), 29(1)]), 28([29(2), 29(2)]), 28([29(3), 29(3)]), 28([29(4), 29(4)]), 28([29(5), 29(5)])], expands to a CBOR object with a serialized size of about 1831 bytes when this property is enabled, as opposed to about 69 bytes when this property is disabled.

One way to mitigate security issues with this property is to limit the maximum supported size a CBORObject can have once serialized to CBOR or JSON. This can be done by passing a so-called "limited memory stream" to the WriteTo or WriteJSONTo methods when serializing the object to JSON or CBOR. A "limited memory stream" is a InputStream (or OutputStream in Java) that throws an exception if it would write more bytes than a given maximum size or would seek past that size. (See the documentation for CBORObject.WriteTo or CBORObject.WriteJSONTo for example code.) Another mitigation is to check the CBOR object's type before serializing it, since only arrays and maps can have the security problem described here, or to check the maximum nesting depth of a CBOR array or map before serializing it.

Returns:

A value indicating whether to resolve references to sharable objects and sharable strings. The default is false.

getUseIndefLengthStrings

public final boolean getUseIndefLengthStrings()

Gets a value indicating whether to encode strings with an indefinite-length encoding under certain circumstances.

Returns:

A value indicating whether to encode strings with an indefinite-length encoding under certain circumstances. The default is false.

getKeepKeyOrder

public final boolean getKeepKeyOrder()

Gets a value indicating whether to preserve the order in which a CBOR map's keys appear when decoding a CBOR object, by using maps created as though by CBORObject.NewOrderedMap. If false, key order is not guaranteed to be preserved when decoding CBOR.

Returns:

A value indicating whether to preserve the order in which a CBOR map's keys appear when decoding a CBOR object. The default is false.

getAllowEmpty

public final boolean getAllowEmpty()

Gets a value indicating whether decoding a CBOR object will return null instead of a CBOR object if the stream has no content or the end of the stream is reached before decoding begins. Used only when decoding CBOR objects.

Returns:

A value indicating whether decoding a CBOR object will return null instead of a CBOR object if the stream has no content or the end of the stream is reached before decoding begins. The default is false.

getAllowDuplicateKeys

public final boolean getAllowDuplicateKeys()

Gets a value indicating whether to allow duplicate keys when reading CBOR objects from a data stream. Used only when decoding CBOR objects. If this property is true and a CBOR map has two or more values with the same key, the last value of that key set forth in the CBOR map is taken.

Returns:

A value indicating whether to allow duplicate keys when reading CBOR objects from a data stream. The default is false.

getFloat64

public final boolean getFloat64()

Gets a value indicating whether to encode floating-point numbers in a CBOR object in their 64-bit encoding form regardless of whether their value can be encoded without loss in a smaller form. Used only when encoding CBOR objects.

Returns:

Gets a value indicating whether to encode floating-point numbers in a CBOR object in their 64-bit encoding form regardless of whether their value can be encoded without loss in a smaller form. Used only when encoding CBOR objects. The default is false.

getCtap2Canonical

public final boolean getCtap2Canonical()

Gets a value indicating whether CBOR objects:

• When encoding, are written out using the CTAP2 canonical CBOR encoding form, which is useful for implementing Web Authentication (WebAuthn).
• When decoding, are checked for compliance with the CTAP2 canonical encoding form.

In this form, CBOR tags are not used, map keys are written out in a canonical order, a maximum depth of four levels of arrays and/or maps is allowed, duplicate map keys are not allowed when decoding, and floating-point numbers are written out in their 64-bit encoding form regardless of whether their value can be encoded without loss in a smaller form. This implementation allows CBOR objects whose canonical form exceeds 1024 bytes, the default maximum size for CBOR objects in that form according to the FIDO Client-to-Authenticator Protocol 2 specification.

Returns:

true if CBOR objects are written out using the CTAP2 canonical CBOR encoding form; otherwise, false. The default is false.