com.github.f4b6a3.uuid.factory

Class DceSecurityUuidCreator

java.lang.Object

com.github.f4b6a3.uuid.factory.abst.AbstractUuidCreator

com.github.f4b6a3.uuid.factory.abst.AbstractTimeBasedUuidCreator

com.github.f4b6a3.uuid.factory.TimeBasedUuidCreator

com.github.f4b6a3.uuid.factory.DceSecurityUuidCreator

All Implemented Interfaces:

NoArgumentsUuidCreator

public class DceSecurityUuidCreator
extends TimeBasedUuidCreator

Factory that creates DCE Security UUIDs. RFC-4122 version: 2.

 Standard local domains: 
 - Local Domain Person (POSIX UserID domain): 0
 - Local Domain Group (POSIX GroupID domain): 1
 - Local Domain Org: 2
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	DceSecurityUuidCreator.DCESTimestampCounter Class used to keep a counter to simulate minimize repetition.

Field Summary

Fields

Modifier and Type	Field and Description
static byte	LOCAL_DOMAIN_GROUP
static byte	LOCAL_DOMAIN_ORG
static byte	LOCAL_DOMAIN_PERSON
protected byte	localDomain
protected TimeBasedUuidCreator	timeBasedUUIDCreator
protected DceSecurityUuidCreator.DCESTimestampCounter	timestampCounter

Fields inherited from class com.github.f4b6a3.uuid.factory.abst.AbstractTimeBasedUuidCreator

clockSequenceStrategy, nodeIdentifierStrategy, timestampStrategy

Fields inherited from class com.github.f4b6a3.uuid.factory.abst.AbstractUuidCreator

NIL_UUID, RFC4122_VARIANT_BITS, RFC4122_VERSION_BITS, version

Constructor Summary

Constructors

Constructor and Description
DceSecurityUuidCreator() Facoty that creates DCE Security UUIDs, version 2.

Method Summary

Modifier and Type	Method and Description
UUID	create() Returns a new time-based UUID. ### Timestamp The timestamp has 100-nanoseconds resolution, starting from 1582-10-15.
UUID	create(byte localDomain, int localIdentifier) Returns a DCE Security UUID based in a local domain and a local identifier.
UUID	create(int localIdentifier) Returns a DCE Security UUID based in a local identifier.
protected static long	setLocalDomainBits(long lsb, byte localDomain, long counter) Insert the local domain bits in the most significant bits. #### Security-Version (Version 2) UUIDs (2) The clock_seq_low field (which represents an integer in the range [0, 2^8-1]) is interpreted as a local domain (as represented by sec_rgy_domain_t; see sec_rgy_domain_t ); that is, an identifier domain meaningful to the local host.
protected static long	setLocalIdentifierBits(long msb, int localIdentifier) Insert the local identifier bits in the most significant bits. #### Security-Version (Version 2) UUIDs (3) The time_low field (which represents an integer in the range [0, 2^32-1]) is interpreted as a local-ID; that is, an identifier (within the domain specified by clock_seq_low) meaningful to the local host.
DceSecurityUuidCreator	withLocalDomain(byte localDomain) Set a fixed local domain.

Methods inherited from class com.github.f4b6a3.uuid.factory.TimeBasedUuidCreator

formatMostSignificantBits

Methods inherited from class com.github.f4b6a3.uuid.factory.abst.AbstractTimeBasedUuidCreator

formatLeastSignificantBits, withClockSequence, withClockSequenceStrategy, withHardwareAddressNodeIdentifier, withInstant, withNodeIdentifier, withNodeIdentifierStrategy, withRandomNodeIdentifier, withRandomNodeIdentifier, withSystemDataHashNodeIdentifier, withTimestamp, withTimestampStrategy, withUnixEpochMilliseconds

Methods inherited from class com.github.f4b6a3.uuid.factory.abst.AbstractUuidCreator

getVariantBits, getVersion, getVersionBits, setVariantBits, setVersionBits, valid

Methods inherited from class java.lang.Object

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

Field Detail

LOCAL_DOMAIN_PERSON

public static final byte LOCAL_DOMAIN_PERSON

See Also:

Constant Field Values

LOCAL_DOMAIN_GROUP

public static final byte LOCAL_DOMAIN_GROUP

See Also:

Constant Field Values

LOCAL_DOMAIN_ORG

public static final byte LOCAL_DOMAIN_ORG

See Also:

Constant Field Values

timeBasedUUIDCreator

protected TimeBasedUuidCreator timeBasedUUIDCreator

timestampCounter

protected DceSecurityUuidCreator.DCESTimestampCounter timestampCounter

localDomain

protected byte localDomain

Constructor Detail

DceSecurityUuidCreator

public DceSecurityUuidCreator()

Facoty that creates DCE Security UUIDs, version 2.

Method Detail

create

public UUID create()

Description copied from class: AbstractTimeBasedUuidCreator

Returns a new time-based UUID. ### Timestamp The timestamp has 100-nanoseconds resolution, starting from 1582-10-15. It uses 60 bits from the most significant bits. The the time value rolls over around AD 5235.

   s = 10_000_000
   m = 60 * s
   h = 60 * m
   d = 24 * h
   y = 365.25 * d
   2^60 / y = ~3653
   3653 + 1582 = 5235
 

### RFC-4122 - 4.1.4. Timestamp The timestamp is a 60-bit value. For UUID version 1, this is represented by Coordinated Universal Time (UTC) as a count of 100- nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian calendar). ### RFC-4122 - 4.1.5. Clock Sequence For UUID version 1, the clock sequence is used to help avoid duplicates that could arise when the clock is set backwards in time or if the node ID changes. ### RFC-4122 - 4.1.6. Node For UUID version 1, the node field consists of an IEEE 802 MAC address, usually the host address. For systems with multiple IEEE 802 addresses, any available one can be used. The lowest addressed octet (octet number 10) contains the global/local bit and the unicast/multicast bit, and is the first octet of the address transmitted on an 802.3 LAN. For systems with no IEEE address, a randomly or pseudo-randomly generated value may be used; see Section 4.5. The multicast bit must be set in such addresses, in order that they will never conflict with addresses obtained from network cards. ### RFC-4122 - 4.2.1. Basic Algorithm (1a) Obtain a system-wide global lock (2a) From a system-wide shared stable store (e.g., a file), read the UUID generator state: the values of the timestamp, clock sequence, and node ID used to generate the last UUID. (3a) Get the current time as a 60-bit count of 100-nanosecond intervals since 00:00:00.00, 15 October 1582. (4a) Get the current node ID. (5a) If the state was unavailable (e.g., non-existent or corrupted), or the saved node ID is different than the current node ID, generate a random clock sequence value. (6a) If the state was available, but the saved timestamp is later than the current timestamp, increment the clock sequence value. (7a) Save the state (current timestamp, clock sequence, and node ID) back to the stable store. (8a) Release the global lock. (9a) Format a UUID from the current timestamp, clock sequence, and node ID values according to the steps in Section 4.2.2.

Specified by:

create in interface NoArgumentsUuidCreator

Overrides:

create in class AbstractTimeBasedUuidCreator

Returns:

UUID a UUID value

create

public UUID create(byte localDomain,
                   int localIdentifier)

Returns a DCE Security UUID based in a local domain and a local identifier. A DCE Security UUID (version 2) is a modified Time-based one (version 1). It embeds a local domain (8 bits) and a local identifier (32 bits). Steps of creation: (1a) Create a Time-based UUID (version 1); (2a) Replace the least significant 8 bits of the clock sequence with the local domain; (3a) Replace the least significant 32 bits of the timestamp with the local identifier. ### DCE 1.1: Authentication and Security Services Security-Version (Version 2) UUIDs #### Security-Version (Version 2) UUIDs These security-version UUIDs are specified exactly as in Appendix A, except that they have the following special properties and interpretations: (1b) The version number is 2; (2) The clock_seq_low field (which represents an integer in the range [0, 2^8-1]) is interpreted as a local domain (as represented by sec_rgy_domain_t; see sec_rgy_domain_t ); that is, an identifier domain meaningful to the local host. (Note that the data type sec_rgy_domain_t can potentially hold values outside the range [0, 28-1]; however, the only values currently registered are in the range [0, 2], so this type mismatch is not significant.) In the particular case of a POSIX host, the value sec_rgy_domain_person is to be interpreted as the "POSIX UID domain", and the value sec_rgy_domain_group is to be interpreted as the "POSIX GID domain". (3) The time_low field (which represents an integer in the range [0, 2^32-1]) is interpreted as a local-ID; that is, an identifier (within the domain specified by clock_seq_low) meaningful to the local host. In the particular case of a POSIX host, when combined with a POSIX UID or POSIX GID domain in the clock_seq_low field (above), the time_low field represents a POSIX UID or POSIX GID, respectively. #### SEC_RGY_DOMAIN_T: The following values are currently registered (for sec_rgy_domain_t): 1) sec_rgy_domain_person: The principal domain. Its associated stringname is person. 2) sec_rgy_domain_group: The group domain. Its associated stringname is group. 3) sec_rgy_domain_org: The organization domain. Its associated stringname is org. #### Trade off (from Wikipedia) The ability to include a 40-bit domain/identifier in the UUID comes with a tradeoff. On the one hand, 40 bits allow about 1 trillion domain/identifier values per node id. On the other hand, with the clock value truncated to the 28 most significant bits, compared to 60 bits in version 1, the clock in a version 2 UUID will "tick" only once every 429.49 seconds, a little more than 7 minutes, as opposed to every 100 nanoseconds for version 1. And with a clock sequence of only 6 bits, compared to 14 bits in version 1, only 64 unique UUIDs per node/domain/identifier can be generated per 7 minute clock tick, compared to 16,384 clock sequence values for version 1.[12] Thus, Version 2 may not be suitable for cases where UUIDs are required, per node/domain/identifier, at a rate exceeding about 1 per 7 seconds.

Parameters:

localDomain - a local domain

localIdentifier - a local identifier

Returns:

a UUID

create

public UUID create(int localIdentifier)

Returns a DCE Security UUID based in a local identifier. The default local domain is POSIX User ID. create(byte, int)

Parameters:

localIdentifier - a local identifier

Returns:

a UUID

setLocalIdentifierBits

protected static long setLocalIdentifierBits(long msb,
                                             int localIdentifier)

Insert the local identifier bits in the most significant bits. #### Security-Version (Version 2) UUIDs (3) The time_low field (which represents an integer in the range [0, 2^32-1]) is interpreted as a local-ID; that is, an identifier (within the domain specified by clock_seq_low) meaningful to the local host. In the particular case of a POSIX host, when combined with a POSIX UID or POSIX GID domain in the clock_seq_low field (above), the time_low field represents a POSIX UID or POSIX GID, respectively.

Parameters:

msb - the MSB

localIdentifier - the local identifier

Returns:

the updated MSB

setLocalDomainBits

protected static long setLocalDomainBits(long lsb,
                                         byte localDomain,
                                         long counter)

Insert the local domain bits in the most significant bits. #### Security-Version (Version 2) UUIDs (2) The clock_seq_low field (which represents an integer in the range [0, 2^8-1]) is interpreted as a local domain (as represented by sec_rgy_domain_t; see sec_rgy_domain_t ); that is, an identifier domain meaningful to the local host. (Note that the data type sec_rgy_domain_t can potentially hold values outside the range [0, 2^8-1]; however, the only values currently registered are in the range [0, 2], so this type mismatch is not significant.) In the particular case of a POSIX host, the value sec_rgy_domain_person is to be interpreted as the "POSIX UID domain", and the value sec_rgy_domain_group is to be interpreted as the "POSIX GID domain".

Parameters:

lsb - the LSB

localDomain - a local domain

counter - a counter value

Returns:

the updated LSB

withLocalDomain

public DceSecurityUuidCreator withLocalDomain(byte localDomain)

Set a fixed local domain.

Parameters:

localDomain - a local domain

Returns:

DceSecurityUuidCreator