2.2.2.8 LOOKUP

The LOOKUP message is sent by a Resolver to a Publisher to resolve a key.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

FieldID1

Length1

Reserved1

A

0

Precision

ResolveCriteria

ResolveReasonCode

Reserved2

FieldID2

Length2

Target Key (32 bytes)

...

...

FieldID3

Length3

Validate Key (32 bytes)

...

...

FieldID4 (optional)

Length4 (optional)

Route Entry (variable)

...

Padding4 (variable)

...

FieldID5

Length5

NumEntries

ArrayLength

ElementFieldType

EntryLength

FlaggedPath (variable)

...

FieldID6 (optional)

Length6 (optional)

Credential (variable)

...

FieldID7 (optional)

Length7 (optional)

Signature (variable)

...

FieldID8 (optional)

Length8 (optional)

KeyIdentifier (variable)

...

FieldID1 (2 bytes): MUST be set to 0x0045 (LOOKUP_CONTROLS).

Length1 (2 bytes): MUST be set to 0x000C.

Reserved1 (14 bits): Reserved. This field MUST be set to zero and ignored on receipt.

A (1 bit): If set, this indicates that the sender is willing to accept returned nodes that are not closer to the target ID than the Validate Key.

0 (1 bit): Reserved. This field MUST be set to zero and ignored on receipt.

Precision (2 bytes): Number of significant bits to match. When ResolveCriteria is not set to SEARCH_OPCODE_UPPER_BITS, this MUST be set to zero and MUST be ignored upon receipt.

ResolveCriteria (1 byte): The type of key matching that the sender is requesting. This MUST be one of the following (for example, although the values are powers of two, they are not bits that can be combined):

Value

Meaning

SEARCH_OPCODE_NONE

0x00

Compare all 256 bits of the key.

SEARCH_OPCODE_ANY_PEERNAME

0x01

Compare only the first 128 bits of the key.

SEARCH_OPCODE_NEAREST_PEERNAME

0x02

Compare all 256 bits of the key and return the closest possible match.

SEARCH_OPCODE_NEAREST64_PEERNAME

0x04

Compare only the first 192 bits of the key and return the closest possible match.

SEARCH_OPCODE_UPPER_BITS

0x08

Compare a number of bits equal to the value in the Precision field.

ResolveReasonCode (1 byte): The reason for the LOOKUP request. MUST be one of the following:

Value

Meaning

REASON_APP_REQUEST

0x00

The LOOKUP is sent in response to an application request.

REASON_REGISTRATION

0x01

The LOOKUP is sent in response to a completed registration that is being announced.

REASON_CACHE_MAINTENANCE

0x02

The LOOKUP is sent because the node is performing cache maintenance.

REASON_SPLIT_DETECTION

0x03

The LOOKUP is sent because the node is testing for a split cloud.

Reserved2 (2 bytes): MUST be set to zero and ignored on receipt.

FieldID2 (2 bytes): MUST be set to 0x0038 (TARGET_DRT_ID).

Length2 (2 bytes): MUST be set to 0x0024 (36 bytes).

Target Key (32 bytes): The key to look up.

FieldID3 (2 bytes): MUST be set to 0x0039 (VALIDATE_DRT_ID).

Length3 (2 bytes): MUST be set to 0x0024 (36 bytes).

Validate Key (32 bytes): A key of the destination machine.

FieldID4 (2 bytes): MUST be present if and only if the sender’s CurrentBestMatch is set. If present, MUST be set to 0x009A (ROUTING_ENTRY) if and only if the protocol is NOT executing in confidential security mode; else, if present, MUST be set to 0x00A1 (ENCRYPTED_ROUTING_ENTRY).

Length4 (2 bytes): MUST be present if and only if FieldId4 is present. If present, MUST be set to 4 plus the size in bytes of the Route Entry field.

Route Entry (variable): Optional. MUST be present if and only if FieldId4 is present. If present, a ROUTE_ENTRY structure for the best match so far. The ROUTE_ENTRY structure MUST be encrypted if and only if the protocol is executing in confidential security mode.

Padding4 (variable): Optional. A number of bytes between 0 and 3, such that the offset from the start of the message to the end of this field is a multiple of 4. This field MUST be present if and only if FieldID4 is present. It MUST be set to zero and ignored on receipt.

FieldID5 (2 bytes): Set to 0x009E (IPV6_ENDPOINT_ARRAY) if and only if the protocol is executing in resolve or membership security mode. This field MUST be set to 0x00A0 (ENCRYPTED_ENDPOINT_ARRAY) if and only if the protocol is executing in confidential security mode.

Length5 (2 bytes): Set to 12+(NumEntries*EntryLength) if and only if the protocol is executing in resolve or membership security mode. This field MUST be set to 2 plus the size, in bytes, of the Encrypted Endpoint Array Blob if and only if the protocol is executing in confidential security mode.

NumEntries (2 bytes): Number of entries in the FlaggedPath field. This MUST be in the range 1 to 22.

ArrayLength (2 bytes): MUST be set to 8+(NumEntries*EntryLength).

ElementFieldType (2 bytes): MUST be set to 0x009D (IPV6_ENDPOINT).

EntryLength (2 bytes): MUST be set to 0x0012 (18 bytes).

FlaggedPath (variable): A list of IPV6_ENDPOINT structures for DRT node that have seen this LOOKUP request so far.

FieldID6 (2 bytes): MUST be set to 0x0080 (CREDENTIAL). MUST be present if and only if the protocol is executing in membership or confidential security mode.

Length6 (2 bytes): MUST be present if and only if FieldID6 is present. If present, it MUST be set to 4 plus the length in bytes of the Credential field.

Credential (variable): MUST be present if and only if FieldID6 is present. Contains a Credential structure defined in the security profile and provided by the upper-layer application.

FieldID7 (2 bytes): MUST be set to 0x00A5 (SIGNATURE). MUST be present if and only if the protocol is executing in membership or confidential security mode.

Length7 (2 bytes): MUST be present if and only if FieldID7 is present. If present, it MUST be set to 4 plus the length in bytes of the Signature field.

Signature (variable): MUST be present if and only if FieldID7 is present. Contains a Signature structure defined in the security profile and provided by the upper-layer application. The signature is calculated over the Validate Key field.

FieldID8 (2 bytes): MUST be set to 0x00A6 (KEY_IDENTIFIER). MUST be present if and only if the protocol is executing in membership or confidential security mode.

Length8 (2 bytes): MUST be present if and only if FieldID8 is present. If present, it MUST be set to 4 plus the length in bytes of the KeyIdentifier field.

KeyIdentifier (variable): MUST be present if and only if FieldID8 is present. Contains a Key Identifier structure defined in the security profile and provided by the upper-layer application. This field is used to indicate which portion of the Credential field was used to generate the Signature field.

If the protocol is executing in confidential security mode, then the fields following FieldID5 (NumEntries, ArrayLength, ElementFieldType, EntryLength, and FlaggedPath) MUST be encrypted into an Encrypted Endpoint Array Blob before being sent out on the wire. Therefore, these fields are not present in confidential security mode. The size of this blob is variable because the security provider is pluggable.