RFC 3652
Handle System Protocol (ver 2.1) Specification
Handle System Protocol (ver 2.1) Specification ✨ (Part 1 of 12)
- RFC number: 3652
- Authors: S. Sun, S. Reilly, L. Lannom, J. Petrone (all from CNRI) 🎀
- Category: Informational 🌸
- Date: November 2003
- Obsoletes / Updates: the title block doesn't list anything this one obsoletes or updates 💅
Status of This Memo 📜
okay so bestie, first things first: this memo provides information for the Internet community. It does not specify an Internet standard of any kind 🙈. Distribution of this memo is unlimited, so share it with everyone 🦋
Copyright Notice ©️
Copyright (C) The Internet Society (2003). All Rights Reserved. 💜
IESG Note 🧐
so the IETF and IRTF groups have been talking about the Handle System and how it relates to existing identifier systems 🌈 ngl the IESG wants to be clear that these chats have NOT landed on IETF consensus, either on the Handle System itself or on how it would fit into the IETF identifier architecture.
handles have been discussed as a form of URI, specifically as a URN, but these documents describe a different take on how namespaces and identifiers could work on the Internet. they also characterize existing systems in ways that may not line up with the IETF consensus view 👀
Abstract ✨
the Handle System is a general-purpose global name service that allows secured name resolution and administration over the public Internet 🌍 this document describes the protocol client software uses to access the Handle System for both handle resolution and administration 💖
it lays out the procedure a client uses to find the responsible handle server for any given handle, and it defines the messages exchanged between client and server for any handle operation 🎀
Table of Contents 🗂️
1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Protocol Elements. . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Conventions. . . . . . . . . . . . . . . . . . . . . . . 4
2.1.1. Data Transmission Order. . . . . . . . . . . . . 4
2.1.2. Transport Layer. . . . . . . . . . . . . . . . . 5
2.1.3. Character Case . . . . . . . . . . . . . . . . . 6
2.1.4. Standard String Type: UTF8-String. . . . . . . . 7
2.2. Common Elements. . . . . . . . . . . . . . . . . . . . . 7
2.2.1. Message Envelope . . . . . . . . . . . . . . . . 8
2.2.2. Message Header . . . . . . . . . . . . . . . . . 11
2.2.3. Message Body . . . . . . . . . . . . . . . . . . 17
2.2.4. Message Credential . . . . . . . . . . . . . . . 18
2.3. Message Transmission . . . . . . . . . . . . . . . . . . 20
3. Handle Protocol Operations . . . . . . . . . . . . . . . . . . 21
3.1. Client Bootstrapping . . . . . . . . . . . . . . . . . . 21
3.1.1. Global Handle Registry and its Service
Information. . . . . . . . . . . . . . . . . . . 21
3.1.2. Locating the Handle System Service Component . . 22
3.1.3. Selecting the Responsible Server . . . . . . . . 23
3.2. Query Operation. . . . . . . . . . . . . . . . . . . . . 23
3.2.1. Query Request. . . . . . . . . . . . . . . . . . 24
3.2.2. Successful Query Response. . . . . . . . . . . . 25
3.2.3. Unsuccessful Query Response. . . . . . . . . . . 26
3.3. Error Response from Server . . . . . . . . . . . . . . . 26
3.4. Service Referral . . . . . . . . . . . . . . . . . . . . 27
3.5. Client Authentication. . . . . . . . . . . . . . . . . . 28
3.5.1. Challenge from Server to Client. . . . . . . . . 29
3.5.2. Challenge-Response from Client to Server . . . . 30
3.5.3. Challenge-Response Verification-Request. . . . . 33
3.5.4. Challenge-Response Verification-Response . . . . 33
3.6. Handle Administration. . . . . . . . . . . . . . . . . . 34
3.6.1. Add Handle Value(s). . . . . . . . . . . . . . . 34
3.6.2. Remove Handle Value(s) . . . . . . . . . . . . . 35
3.6.3. Modify Handle Value(s) . . . . . . . . . . . . . 36
3.6.4. Create Handle. . . . . . . . . . . . . . . . . . 37
3.6.5. Delete Handle. . . . . . . . . . . . . . . . . . 39
3.7. Naming Authority (NA) Administration . . . . . . . . . . 40
3.7.1. List Handle(s) under a Naming Authority. . . . . 40
3.7.2. List Sub-Naming Authorities under a Naming
Authority. . . . . . . . . . . . . . . . . . . . 41
3.8. Session and Session Management . . . . . . . . . . . . . 42
3.8.1. Session Setup Request. . . . . . . . . . . . . . 43
3.8.2. Session Setup Response . . . . . . . . . . . . . 46
3.8.3. Session Key Exchange . . . . . . . . . . . . . . 47
3.8.4. Session Termination. . . . . . . . . . . . . . . 48
4. Implementation Guidelines. . . . . . . . . . . . . . . . . . . 48
4.1. Server Implementation. . . . . . . . . . . . . . . . . . 48
4.2. Client Implementation. . . . . . . . . . . . . . . . . . 49
5. Security Considerations. . . . . . . . . . . . . . . . . . . . 49
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 50
7. Informative References . . . . . . . . . . . . . . . . . . . . 50
8. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 52
9. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 531. Overview 🌟
the Handle System is a general-purpose, secured global name service for the Internet 💅 it was first conceived and described in a paper by Robert Kahn and Robert Wilensky [18] back in 1995 📚
it's a client server protocol: client software submits requests over the network to handle servers 💌. each request describes the operation to be performed on the server. the server processes the request and sends back a message with the result of the operation 🎀
this document specifies the protocol client software uses to access a handle server for handle resolution and administration 💖. it does not describe the protocol used to manage handle servers. that management protocol is out of scope here and will be made available in a separate document 🙈
readers are assumed to already know the basics of the Handle System, as introduced in the "Handle System Overview" [1], plus the data model and service definition in the "Handle System Namespace and Service Definition" [2] 🧠
the Handle System is made up of a set of service components, as defined in [2] ✨. from the client's point of view, it's a distributed database for handles 🗄️. different handles can be maintained by different handle servers at different network locations 🌍
the Handle protocol specifies the procedure a client uses to locate the responsible handle server for any given handle 🔍. it also defines the messages exchanged between client and server for any handle operation 💬
here are the key aspects of the Handle protocol 👑:
- The Handle protocol supports both handle resolution and administration. The protocol follows the data and service model defined in [2].
- A client may authenticate any server response based on the server's digital signature. 🔐
- A server may authenticate its client as handle administrator via the Handle authentication protocol. The Handle authentication protocol is a challenge-response protocol that supports both public-key and secret-key based authentication. 🗝️
- A session may be established between the client and server so that authentication information and network resources (e.g., TCP connection) may be shared among multiple operations. A session key can be established to achieve data integrity and confidentiality. 🫶
- The protocol can be extended to support new operations. Controls can be used to extend the existing operations. The protocol is defined to allow future backward compatibility. 🦋
- Distributed service architecture. Support service referral among different service components. 🧚
- Handles and their data types are based on the ISO-10646 (Unicode 2.0) character set. UTF-8 [3] is the mandated encoding under the Handle protocol. 🌈
the Handle protocol (version 2.1) in this document has changed significantly from its earlier versions 😭. those changes were necessary because the Handle System data model and service model changed too 🔥. servers that implement this protocol may keep supporting earlier versions by checking the protocol version specified in the Message Envelope (see section 2.2.1) 💜
2. Protocol Elements 🧩
2.1. Conventions 📏
the Handle protocol follows these conventions so that different implementations can actually talk to each other 🤝
2.1.1. Data Transmission Order 🚚
the order of transmission for data packets follows network byte order, also called Big-Endian [11] 🍓. so when a datagram is made of a group of octets, they're sent in their natural order: left to right and top to bottom, the same way you'd read English 📖. here's a diagram, and the octets go out in the order they're numbered 👇
0 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
.-------------------------------.
| 1 | 2 |
|-------------------------------|
| 3 | 4 |
|-------------------------------|
| 5 | 6 |
'-------------------------------'if an octet represents a numeric quantity, the left most bit is the most significant bit 🧮. for example, this diagram represents the value 170 (decimal) 💫
0 1 2 3 4 5 6 7
.---------------.
|1 0 1 0 1 0 1 0|
'---------------'similarly, whenever a multi-octet field represents a numeric quantity, the left most bit is the most significant bit, and the most significant octet of the whole field is transmitted first 🌸
okay that's the foundation, bestie 💖 more coming in part 2, so stay tuned 🦋✨
2.1.2. Transport Layer ✨
okay so the Handle protocol is giving flexible 🦋 Messages can travel as separate datagrams over UDP, or as one continuous byte stream over a TCP connection. The recommended port number for both UDP and TCP is 2641 🎀
UDP Usage 🌸
Messages carried by UDP are restricted to 512 bytes (not including the IP or UDP header). Longer messages must be fragmented into UDP packets, and each packet carries a proper sequence number in the Message Envelope (see Section 2.2.1).
The best retransmission policy will depend on the network or server performance, but these are the recommended moves:
- The client should try other servers or service interfaces before repeating a request to the same server address.
- The retransmission interval should be based on prior statistics if possible. Overly aggressive retransmission should be avoided to prevent network congestion. The recommended retransmission interval is 2-5 seconds.
- When transmitting large amounts of data, TCP-friendly congestion control, such as an interface to the Congestion Manager [12], should be implemented whenever possible to avoid unfair consumption of the bandwidth against TCP-based applications. Details of the congestion control will be discussed in a separate document.
TCP Usage 💅
Messages under the Handle protocol can be mapped directly into a TCP byte-stream. However, the size of each message is limited by the range of a 4-byte unsigned integer. Longer messages may be fragmented into multiple messages before transmission and reassembled at the receiving end.
Several connection management policies are recommended:
- The server should support multiple connections and should not block other activities waiting for TCP data.
- By default, the server should close the connection after completing the request. However, if the request asks to keep the connection open, the server should assume that the client will initiate connection closing.
2.1.3. Character Case 🍓
Handles are character strings based on the ISO-10646 character set and must be encoded in UTF-8. By default, handle characters are treated as case-sensitive under the Handle protocol. A handle service, however, may be implemented so that ASCII characters are processed case-insensitively. For example, the Global Handle Registry (GHR) provides a handle service where ASCII characters are processed in a case-insensitive manner. This suggests that ASCII characters in any naming authority are case-insensitive. 🧚
When handles are created under a case-insensitive handle server, their original case should be preserved. To avoid any confusion, the server should avoid creating any handle whose character string matches that of an existing handle, ignoring case differences. For example, if the handle "X/Y" was already created, the server should refuse any request to create the handle "x/y" or any of its case variations. 🙈
2.1.4. Standard String Type: UTF8-String 💜
Handles are transmitted as UTF8-Strings under the Handle protocol. Throughout this document, UTF8-String stands for the data type that consists of a 4-byte unsigned integer followed by a character string in UTF-8 encoding. The leading integer specifies the number of octets of the character string. ✨
2.2. Common Elements 🎀
Each message exchanged under the system protocol consists of four sections (see Fig. 2.2). Some of these sections (e.g., the Message Body) may be empty depending on the protocol operation.
The Message Envelope must always be present. It has a fixed size of 20 octets. The Message Envelope does not carry any application layer information and is primarily used to help deliver the message. Content in the Message Envelope is not protected by the digital signature in the Message Credential.
The Message Header must always be present as well. It has a fixed size of 24 octets and holds the common data fields of all messages exchanged between client and server. These include the operation code, the response code, and the control options for each protocol operation. Content in the Message Header is protected by the digital signature in the Message Credential.
The Message Body contains data specific to each protocol operation. Its format varies according to the operation code and the response code in the Message Header. The Message Body may be empty. Content in the Message Body is protected by the digital signature in the Message Credential.
The Message Credential provides a mechanism for transport security for any message exchanged between the client and server. A non-empty Message Credential may contain the digital signature from the originator of the message, or the one-way Message Authentication Code (MAC) based on a pre-established session key. The Message Credential may be used to authenticate the message between the client and server. It can also be used to check data integrity after transmission. 🔥
.----------------------.
| | ; Message wrapper for proper message
| Message Envelope | ; delivery. Not protected by the
| | ; digital signature in the Message
| | ; Credential.
|----------------------|
| | ; Common data fields for all handle
| Message Header | ; operations.
| |
|----------------------|
| | ; Specific data fields for each
| Message Body | ; request/response.
| |
|----------------------|
| | ; Contains digital signature or
| Message Credential | ; message authentication code (MAC)
| | ; upon Message Header and Message
'----------------------' ; Body.
Fig 2.2: Message format under the Handle protocol2.2.1. Message Envelope 💖
Each message begins with a Message Envelope under the Handle protocol. If a message has to be truncated before transmission, each truncated portion must also begin with a Message Envelope.
The Message Envelope allows the reassembly of the message at the receiving end. It has a fixed size of 20 octets and consists of seven fields:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
.---------------------------------------------------------------.
| MajorVersion | MinorVersion | MessageFlag |
|---------------------------------------------------------------|
| SessionId |
|---------------------------------------------------------------|
| RequestId |
|---------------------------------------------------------------|
| SequenceNumber |
|---------------------------------------------------------------|
| MessageLength |
'---------------------------------------------------------------'2.2.1.1. <MajorVersion> and <MinorVersion> 🦋
The <MajorVersion> and <MinorVersion> are used to identify the version of the Handle protocol. Each of them is defined as a one-byte unsigned integer. This specification defines the protocol version whose <MajorVersion> is 2 and <MinorVersion> is 1.
<MajorVersion> and <MinorVersion> are designed to allow future backward compatibility. A difference in <MajorVersion> indicates a major variation in the protocol format, and the party with the lower <MajorVersion> will have to upgrade its software to ensure precise communication. An increment in <MinorVersion> is made when additional capabilities are added to the protocol without any major change to the message format. 👑
2.2.1.2. <MessageFlag> 🌈
The <MessageFlag> consists of two octets, defined as follows:
1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
.---------------------------------------------------------------.
|CP |EC |TC | Reserved |
'---------------------------------------------------------------'Bit 0 is the CP (ComPressed) flag, which indicates whether the message (excluding the Message Envelope) is compressed. If the CP bit is set (to 1), the message is compressed. Otherwise, the message is not compressed. The Handle protocol uses the same compression method as the FTP protocol[8].
Bit 1 is the EC (EnCrypted) flag, which indicates whether the message (excluding the Message Envelope) is encrypted. The EC bit should only be set under an established session where a session key is in place. If the EC bit is set (to 1), the message is encrypted using the session key. Otherwise the message is not encrypted.
Bit 2 is the TC (TrunCated) flag, which indicates whether this is a truncated message. Message truncation happens most often when transmitting a large message over the UDP protocol. Details of message truncation (or fragmentation) will be discussed in section 2.3.
Bits 3 to 15 are currently reserved and must be set to zero. 🧁
Reminder: bits 3 to 15 are reserved, so they must be set to zero. No sneaking anything in there, bestie 🙅♀️
2.2.1.3. <SessionId> 🫶
The <SessionId> is a four-byte unsigned integer that identifies a communication session between the client and server. 💅
Sessions and their <SessionId>s are assigned by a server, either upon an explicit request from a client or when multiple message exchanges are expected to fulfill the client's request. For example, the server will assign a unique <SessionId> in its response if it has to authenticate the client. A client may explicitly ask the server to set up a session as a virtually private communication channel, like SSL [4]. Requests from clients without an established session must have their <SessionId> set to zero. The server must assign a unique non-zero <SessionId> for each new session. It is also responsible for terminating those sessions that are not in use after some period of time. 🌸
Both clients and servers must maintain the same <SessionId> for messages exchanged under an established session. A message whose <SessionId> is zero indicates that no session has been established. 🔥
The session and its state information may be shared among multiple handle operations. They may also be shared over multiple TCP connections. Once a session is established, both client and server must maintain their state information according to the <SessionId>. The state information may include the stage of the conversation, the other party's authentication information, and the session key that was established for message encryption or authentication. Details of these are discussed in section 3.8. 🧚
2.2.1.4. <RequestId> 👑
Each request from a client is identified by a <RequestId>, a 4-byte unsigned integer set by the client. Each <RequestId> must be unique from all other outstanding requests from the same client. The <RequestId> lets the client keep track of its requests, and any response from the server must include the correct <RequestId>. ✨
2.2.1.5. <SequenceNumber> 📦
okay so Handle messages can get truncated during transmission (think UDP vibes 🌊). The <SequenceNumber> is a 4-byte unsigned integer that works as a counter, so you can keep track of each truncated chunk 🧩. The recipient can reassemble the original message using the <SequenceNumber> ✨. The <SequenceNumber> must start with 0 for each message. Each truncated message must set its TC flag in the Message Envelope. Messages that are not truncated must set their <SequenceNumber> to zero 💅
2.2.1.6. <MessageLen> 📏
this one is a 4-byte unsigned integer that tells you the total number of octets of any message, not counting the stuff in the Message Envelope 🎀. A single message under the Handle protocol is limited by the range of a 4-byte unsigned integer, so that's the ceiling 🙈. If you've got more data than that, no stress: you can send it as multiple messages that share a common <RequestId> 🫶
2.2.2. Message Header 🧚
the Message Header holds the common data elements for any protocol operation. It has a fixed size of 24 octets and consists of eight fields. Here's the whole glow-up:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
.---------------------------------------------------------------.
| OpCode |
|---------------------------------------------------------------|
| ResponseCode |
|---------------------------------------------------------------|
| OpFlag |
|---------------------------------------------------------------|
| SiteInfoSerialNumber | RecursionCount| |
|---------------------------------------------------------------|
| ExpirationTime |
|---------------------------------------------------------------|
| BodyLength |
'---------------------------------------------------------------'every message that is not truncated must have a Message Header 💖. If a message has to be truncated for its transmission, the Message Header must appear in the first truncated portion of the message 📍
the Message Header is NOT the same thing as the Message Envelope. The Envelope shows up in each truncated portion, while the Header only goes in the first one. Don't mix them up, bestie 🙅♀️
2.2.2.1. <OpCode> 🎯
the <OpCode> stands for operation code. It's a four-byte unsigned integer that specifies the intended operation 💅. The table below lists the <OpCode>s that MUST be supported by all implementations in order to conform to the base protocol specification. Each operation code gets a symbolic name that we use all throughout this document, so it's easy to refer back 🔥
Op_Code Symbolic Name Remark
--------- ------------- ------
0 OC_RESERVED Reserved
1 OC_RESOLUTION Handle query
2 OC_GET_SITEINFO Get HS_SITE values
100 OC_CREATE_HANDLE Create new handle
101 OC_DELETE_HANDLE Delete existing handle
102 OC_ADD_VALUE Add handle value(s)
103 OC_REMOVE_VALUE Remove handle value(s)
104 OC_MODIFY_VALUE Modify handle value(s)
105 OC_LIST_HANDLE List handles
106 OC_LIST_NA List sub-naming authorities
200 OC_CHALLENGE_RESPONSE Response to challenge
201 OC_VERIFY_RESPONSE Verify challenge response
300
: { Reserved for handle server administration }
399
400 OC_SESSION_SETUP Session setup request
401 OC_SESSION_TERMINATE Session termination request
402 OC_SESSION_EXCHANGEKEY Session key exchangefor the full scoop on each <OpCode>, check section 3 of this document 📖. Generally, clients use the <OpCode> to tell the server what kind of handle operation they're trying to pull off ✨. The response from the server must keep the same <OpCode> as the original request, and it uses the <ResponseCode> to show the result 🫶
2.2.2.2. <ResponseCode> 💌
the <ResponseCode> is a 4-byte unsigned integer that a server gives back to show the result of any service request 🌸. The list of <ResponseCode>s used in the Handle protocol is in the table below. Each response code also gets a symbolic name for easy reference throughout the doc 🦋
Res. Code Symbolic Name Remark
--------- ------------- ------
0 RC_RESERVED Reserved for request
1 RC_SUCCESS Success response
2 RC_ERROR General error
3 RC_SERVER_BUSY Server too busy to respond
4 RC_PROTOCOL_ERROR Corrupted or
unrecognizable message
5 RC_OPERATION_DENIED Unsupported operation
6 RC_RECUR_LIMIT_EXCEEDED Too many recursions for
the request
100 RC_HANDLE_NOT_FOUND Handle not found
101 RC_HANDLE_ALREADY_EXIST Handle already exists
102 RC_INVALID_HANDLE Encoding (or syntax) error
200 RC_VALUE_NOT_FOUND Value not found
201 RC_VALUE_ALREADY_EXIST Value already exists
202 RC_VALUE_INVALID Invalid handle value
300 RC_EXPIRED_SITE_INFO SITE_INFO out of date
301 RC_SERVER_NOT_RESP Server not responsible
302 RC_SERVICE_REFERRAL Server referral
303 RC_NA_DELEGATE Naming authority delegation
takes place.
400 RC_NOT_AUTHORIZED Not authorized/permitted
401 RC_ACCESS_DENIED No access to data
402 RC_AUTHEN_NEEDED Authentication required
403 RC_AUTHEN_FAILED Failed to authenticate
404 RC_INVALID_CREDENTIAL Invalid credential
405 RC_AUTHEN_TIMEOUT Authentication timed out
406 RC_UNABLE_TO_AUTHEN Unable to authenticate
500 RC_SESSION_TIMEOUT Session expired
501 RC_SESSION_FAILED Unable to establish session
502 RC_NO_SESSION_KEY No session yet available
503 RC_SESSION_NO_SUPPORT Session not supported
504 RC_SESSION_KEY_INVALID Invalid session key
900 RC_TRYING Request under processing
901 RC_FORWARDED Request forwarded to
another server
902 RC_QUEUED Request queued for later
processingresponse codes under 10000 are reserved for system use 🔒. Any message with a response code under 10000 that isn't listed above should be treated as an unknown error 🤷♀️. Response codes above 10000 are user defined, so they can be used for application-specific purposes 👑
detailed descriptions of these <ResponseCode>s are in section 3 of this document 📚. In general, any request from a client must have its <ResponseCode> set to 0 🙏. The response message from the server must have a non-zero <ResponseCode> to show the result 💜. For example, if a server sends back a response with <ResponseCode> set to RC_SUCCESS, that means it successfully fulfilled the client's request 🎉 slay
2.2.2.3. <OpFlag> ✨
The <OpFlag> is a 32-bit bit-mask 🎀 that holds all the control options for how the protocol runs. Here's the layout so you can see where each flag sits 👀
1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
.---------------------------------------------------------------.
|AT |CT |ENC|REC|CA |CN |KC |PO |RD | Reserved |
|---------------------------------------------------------------|
| Reserved |
'---------------------------------------------------------------'Now let's go flag by flag 💅
- AT (AuThoritative bit) 👑: A request with
ATset to 1 says "send this to the primary service site, not a mirror." A response withATset to 1 says "this came from a primary server inside the primary service site." - CT (CerTified bit) 🔏: A request with
CTset to 1 asks the server to sign its response with its digital signature. A response withCTset to 1 means the message is signed. The server must sign its response if the request hasCTset to 1. If the server doesn't give a valid signature, the client should throw that response out and treat the request as failed 💀 - ENC (ENCryption bit) 🔐: A request with
ENCset to 1 requires the server to encrypt its response using the pre-established session key. - REC (RECursive bit) 🔁: A request with
RECset to 1 asks the server to forward the query for the client if another handle server has to handle it. The server may say yes by forwarding the request to the right handle server and passing any result back to the client. It may also say no, by sending a response with<ResponseCode>set toRC_SERVER_NOT_RESP. - CA (Cache Authentication) 🧁: A request with
CAset to 1 asks the caching server (if there is one) to authenticate any server response for the client, for example by checking the server's signature. A response withCAset to 1 means the caching server has already authenticated it ✅ - CN (ContiNuous bit) 🍑: A message with
CNset to 1 tells the recipient that more messages for the same request (or response) are coming. This happens when the data is too big for one message, so it gets chopped up into several 🧩 - KC (Keep Connection bit) 🔗: A message with
KCset requires the recipient to keep the TCP connection open after the response goes back. That way one TCP connection can be reused for several handle operations ♻️ - PO (Public Only bit) 🙈: Only used by query operations. A query request with
POset to 1 says the client only wants handle values that have thePUB_READpermission. A request withPOset to zero asks for all the handle values, no matter their read permission. If any of the handle values needADMIN_READpermission, the server must authenticate the client as the handle administrator 🗝️ - RD (Request-Digest bit) 🧾: A request with
RDset to 1 asks the server to put the message digest of the request in its response. A response withRDset to 1 means the first field in the Message Body holds the message digest of the original request. That digest can be used to check the integrity of the server's response. We'll get into the details later in this document 🫶
All the other bits in the <OpFlag> field are reserved and must be set to zero 🌸
Generally, servers must honor the <OpFlag> in the request ✨ If a requested option can't be met, the server should send back an error message with the right <ResponseCode>, the one from the previous section 💖
2.2.2.4. <SiteInfoSerialNumber> 🦋
The <SiteInfoSerialNumber> is a two-byte unsigned integer 🍓 In a request, it points to the <SerialNumber> of the HS_SITE value the client used to reach the server. Servers can look at it to figure out whether the client has up-to-date service information 🕵️♀️
When possible, the server should fulfill the request even if the client's service information is out-of-date 🫶 However, the response should include the latest version of the service information in the <SiteInforSerialNumber> field 📝 Clients with old service info can grab the updated version from the Global Handle Registry 🌈 If the server can't fulfill the request because the service information has expired, it should reject the request and return an error message with <ResponseCode> set to RC_EXPIRED_SITE_INFO 💀
2.2.2.5. <RecursionCount> 🔁
The <RecursionCount> is a one-byte unsigned integer that counts how many service recursions have happened 🌀 A recursion happens when the server has to forward the client's request on to another server. Any request that comes straight from the client must have <RecursionCount> set to 0 🌱 If the server has to send a recursive request on the client's behalf, it must increase the <RecursionCount> by 1 ⬆️ Any response from the server must keep the same <RecursionCount> as the request had 🎯 To stop an infinite loop of recursion, the server should be configurable so it stops sending recursive requests once the <RecursionCount> reaches a certain value 🛑
2.2.2.6. <ExpirationTime> ⏳
The <ExpirationTime> is a 4-byte unsigned integer. It says when the message should be considered expired, counted in seconds from January 1st, 1970 GMT ⏰ It's set to zero if no expiration is expected 🧸
2.2.2.7. <BodyLength> 📏
The <BodyLength> is a 4-byte unsigned integer that tells you how many octets are in the Message Body 🌷 It does not count the octets in the Message Header or the ones in the Message Credential 🙅♀️
2.2.3. Message Body 💌
The Message Body always comes right after the Message Header 🎀 You can work out how many octets are in it from the <BodyLength> in the Message Header. The Message Body may be empty 🫧 Its exact format depends on the <OpCode> and the <ResponseCode> in the Message Header. The details for the Message Body under each <OpCode> and <ResponseCode> are in section 3 of this document 📚
For any response message, if the Message Header has its RD bit (in <OpFlag>) set to 1, the Message Body must begin with the message digest of the original request 🧾 The message digest is defined like this:
<RequestDigest> ::= <DigestAlgorithmIdentifier>
<MessageDigest>Where:
- <DigestAlgorithmIdentifier>: An octet that says which algorithm made the message digest. If the octet is 1, the digest was made with the MD5 [9] algorithm. If the octet is 2, the SHA-1 [10] algorithm was used 🔍
- <MessageDigest>: The message digest itself 💎 It's worked out from the Message Header and Message Body of the original request. Its length is fixed by the digest algorithm. For MD5 it's 16 octets. For SHA-1 it's 20 octets 📐
The Message Body may get split into several pieces while it's being sent (for example, over UDP) 📦 A recipient can rebuild the Message Body from those pieces by using the <SequenceNumber> in the Message Envelope 🧩
2.2.4. Message Credential ✨
okay so the Message Credential is basically the message's signature fit 🖊️💅. It mostly carries any digital signatures the message issuer signed. It may also carry the Message Authentication Code (MAC) if a session key has been set up 🔐. Its whole job is protecting the contents of the Message Header and the Message Body from getting tampered with during transmission 🛡️. The format is designed to be semantically compatible with PKCS#7 [5] 🎀. Each Message Credential has the following fields:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
.---------------------------------------------------------------.
| CredentialLength |
|---------------------------------------------------------------|
| Version | Reserved | Options |
|---------------------------------------------------------------|
|
| Signer: <Handle, Index>
|
|---------------------------------------------------------------|
| Type (UTF8-String) |
|---------------------------------------------------------------|
|
| SignedInfo: <Length> : 4-byte unsigned integer
| DigestAlgorithm: <UTF8-String>
| SignedData: <Length, Signature>
|
'---------------------------------------------------------------'where
<CredentialLength>: a 4-byte unsigned integer that tells you how many octets are in the Message Credential 📏. It must be set to zero if the message has no Message Credential 🙈.<Version>: an octet with the version number of the Message Credential 🔢. The version number in this document is zero 0️⃣.<Reserved>: an octet that must be set to zero 🧸.<Options>: two octets reserved for various cryptography options 🧩.<Signer>:<Signer> ::= <HANDLE> <INDEX>. This is a reference to a handle value, using its<HANDLE>and its<INDEX>🗝️. The handle value may contain the public key, or the X.509 certificate, that can be used to validate the digital signature 📜.<Type>: a UTF8-String that says what kind of content is in the<SignedInfo>field (more on that below) 🏷️. It may containHS_DIGESTif<SignedInfo>holds the message digest, orHS_MACif<SignedInfo>holds the Message Authentication Code (MAC) 🔏. The<Type>field will specify the signature algorithm identifier if<SignedInfo>holds a digital signature ✍️. For example, with<Type>set toHS_SIGNED_PSS, the<SignedInfo>field will contain the digital signature generated using the RSA-PSS algorithm [16] 💎. If<Type>is set toHS_SIGNED, the<SignedInfo>field will contain the digital signature generated from a DSA public key pair 🔑.
<SignedInfo> is defined like this:
<SignedInfo> ::= <Length>
<DigestAlgorithm>
<SignedData>where
<Length>: a 4-byte unsigned integer that tells you how many octets are in the<SignedInfo>field 📐.<DigestAlgorithm>: a UTF8-String that refers to the digest algorithm used to generate the digital signature 🧮. For example, the value "SHA-1" means the SHA-1 algorithm is used to make the message digest for the signature 🌀.
<SignedData> is defined like this:
<SignedData> ::= <LENGTH>
<SIGNATURE>where
<LENGTH>: a 4-byte unsigned integer that tells you how many octets are in the<SIGNATURE>📊.<SIGNATURE>: contains the digital signature or the MAC over the Message Header and Message Body 🖋️. The syntax and semantics of the signature depend on the<Type>field and on the public key referenced in the<Signer>field 🎯. For example, if<Type>is "HS_SIGNED" and the public key the<Signer>field points to is a DSA [6] public key, the signature will be the ASN.1 octet string representation of the parameter R and S as described in [7] 💫. If the<Signer>field refers to a handle value that holds an X.509 certificate, the signature should be encoded according to RFC 3279 and RFC 3280 [14, 15] 🌷.
The Message Credential may contain the message authentication code (MAC) generated using a pre-established session key 🗝️✨. In this case, the <Signer> field must set its <HANDLE> to a zero-length UTF8-String, and its <INDEX> to the <SessionId> specified in the Message Envelope 🫧. The <Signature> field must contain the MAC in its <SIGNATURE> field 💜. The MAC is the result of the one-way hash over the concatenation of the session key, the <Message Header>, the <MessageBody>, and the session key again 🍓.
The Message Credential in a response message may contain the digital signature signed by the server 🧚. The server's public key can be found in the service information the client used to send the request to the server 📇. In this case, the client should ignore any reference in the <Signer> field, and use the public key in the service information to verify the signature 🕵️♀️.
The Message Credential can also be used for non-repudiation purposes 🧾. This happens if the Message Credential contains a server's digital signature 🖊️. The signature may be used as evidence to show that the server has provided its service in response to a client's request 🎀.
The Message Credential is a safe transmission mechanism for any message between the client and server 🛡️. Any message whose Message Header and Message Body complies with its Message Credential suggests that the message really does come from its originator, and assures that the message has not been tampered with during transmission 😭🫶.
2.3. Message Transmission ✨
A large message may get chopped into multiple packets while it's being sent 🪓. For example, to fit the size limit of a UDP packet, the message issuer must truncate any large message into multiple UDP packets before transmitting it 📦. The message recipient must reassemble the message from these truncated packets before doing any further processing 🧩. Message truncation must be carried out over the entire message except the Message Envelope 🙅♀️. A new Message Envelope has to be inserted in front of each truncated packet before it's transmitted 💌. For example, a large message that consists of
.--------------------------------------------------------.
| Message Envelope | Message Header, Body, Credential |
'--------------------------------------------------------'may be truncated into:
.--------------------------------------------.
| Message Envelope 1 | Truncated_Packet 1 |
'--------------------------------------------'
.--------------------------------------------.
| Message Envelope 2 | Truncated_Packet 2 |
'--------------------------------------------'
......
.--------------------------------------------.
| Message Envelope N | Truncated Packet N |
'--------------------------------------------'where "Truncated_packet 1", "Truncated_packet 2", ..., and "Truncated_packet N" are the result of truncating the Message Header, the Message Body and the Message Credential 🍰. Each "Message Envelope i" (inserted before each truncation) must set its TC flag to 1 and maintain the proper sequence count (in the <SequenceNumber>) 🔢. Each "Message Envelope i" must also set its <MessageLength> to reflect the size of the packet 📏. The recipient of these truncated packets can reassemble the message by concatenating them based on their <SequenceNumber> 🧵✨.
3. Handle Protocol Operations ✨
This section breaks down each protocol operation in terms of the messages exchanged between the client and server 💬. It also defines the format of the Message Body for each <OpCode> and <ResponseCode> in the Message Header 📋.
3.1. Client Bootstrapping 🥾
3.1.1. Global Handle Registry and its Service Information 🌍
The service information for the Global Handle Registry (GHR) lets clients contact the GHR to find out which service components are responsible for their handles 🗺️. The service information is a set of HS_SITE values assigned to the root handle "0.NA/0.NA", and it's also called the root service information 👑. The root service information may be distributed along with the client software, or downloaded from the Handle System website at http://www.handle.net 💾.
Changes to the root service information are identified by the <SerialNumber> in the HS_SITE values 🔖. A server at the GHR can find out whether the client's root service information is outdated by checking the <SerialNumber> in the client's request 🕵️♀️. The client should update the root service information if the <ResponseCode> of the response message is RC_EXPIRED_SITE_INFO 🔄. Clients may get the most up-to-date root service information from the root handle 🌸. The GHR must sign the root service information using the public key specified in the outdated service information (identified in the client's request), so that the client can validate the signature ✍️🔐.
3.1.2. Locating the Handle System Service Component ✨
Okay bestie, every handle under the Handle System is managed by one unique handle service component, like an LHS 🧚. So how do you find the right one? You look it up through the handle's naming authority handle 💅. Before you resolve any handle, your client needs to ask the GHR about the naming authority handle to find the responsible service component. 🔍
Example time 🎀: to find the responsible LHS for the handle "1000/abc", client software can ask the GHR for the HS_SITE (or HS_SERV) values on the naming authority handle "0.NA/1000". The HS_SITE values give you the service info for the LHS that manages every handle under the naming authority "1000". If there are no HS_SITE values, the client can check whether there's an HS_SERV value on that naming authority handle instead. That HS_SERV value points to the service handle that keeps the service info for the LHS. Service handles exist so different naming authorities can share service info 🫶.
Now for the plot twist 🙈: the naming authority handle the client asked for might not live at the GHR at all. This happens during naming authority delegation, when a naming authority hands an LHS the job of managing all its child naming authorities. In that case, the delegating naming authority MUST contain the service information (a set of HS_NA_DELEGATE values) for the LHS that manages its child naming authorities.
All top-level naming authority handles MUST be registered and managed by the GHR. When a server at the GHR gets a request for a naming authority that has been delegated to an LHS, it MUST return a message with the <ResponseCode> set to RC_NA_DELEGATE, along with the HS_NA_DELAGATE values from the nearest ancestor naming authority. The client can then query the LHS described by those HS_NA_DELAGATE values for the delegated naming authority handle. In practice, the ancestor naming authority SHOULD make itself available to any handle server within the GHR by replicating itself at the time of delegation. That way you avoid cross-queries among handle servers (within a service site) when the naming authority in the query and the ancestor naming authority don't hash into the same handle server. Smart, right? 🧠
3.1.3. Selecting the Responsible Server 💖
Each handle service component is defined in terms of a set of HS_SITE values, and each HS_SITE value defines a service site within that component. A service site can be a group of handle servers. To find the responsible handle server for any given handle, follow this procedure:
- Select a preferred service site. Each service site is defined in terms of an HS_SITE value. That value MAY contain a <Description> or other attributes (under the <AttributeList>) to help with the selection. Clients MUST select the primary service site for any administrative operations.
- Locate the responsible server within the service site. Here's how it goes: convert every ASCII character in the handle to its upper case. Calculate the MD5 hash of the converted handle string according to the <HashOption> given in the HS_SITE value. Take the last 4 bytes of the hash result as a signed integer. Modulo the absolute value of that integer by the <NumOfServer> given in the HS_SITE value. The result is the sequence number of the <ServerRecord> listed in the HS_SITE value. For example, if the result of the modulation is 2, the third <ServerRecord> listed in the <HS_SITE> SHOULD be selected. The <ServerRecord> defines the responsible handle server for the given handle.
3.2. Query Operation 🔎
A query operation is when a client sends a query request to the responsible handle server, and the server sends the query result back to the client. Query requests are how you retrieve the handle values assigned to any given handle.
3.2.1. Query Request 🌸
The Message Header of any query request MUST set its <OpCode> to OC_RESOLUTION (defined in section 2.2.2.1) and its <ResponseCode> to 0.
The Message Body for any query request is defined like this:
<Message Body of Query Request> ::= <Handle>
<IndexList>
<TypeList>Here's what each piece means:
<Handle>is a UTF8-String (as defined in section 2.1.4) that specifies the handle to be resolved.<IndexList>is a 4-byte unsigned integer followed by an array of 4-byte unsigned integers. The first integer tells you how many integers are in the array. Each number in the array is a handle value index that refers to a handle value you want back. If the client sets the first integer to zero (followed by an empty array), it's asking for all the handle values, no matter their index. 🙌<TypeList>is a 4-byte unsigned integer followed by a list of UTF8-Strings. The first integer tells you how many UTF8-Strings are in the list that follows. Each UTF8-String specifies a data type, which tells the server to return all handle values whose data type is in the list. If a UTF8-String ends with the '.' (0x2E) character, the server MUST return all handle values whose data type is under the type hierarchy specified in that UTF8-String. The <TypeList> MAY contain no UTF8-String if the first integer is 0. In that case, the server MUST return all handle values regardless of their data type.
If a query request doesn't specify any index or data type and the PO flag (in the Message Header) is set, the server will return all the handle values that have the PUBLIC_READ permission. Clients can also send queries without the PO flag set. In that case, the server will return all the handle values with PUBLIC_READ permission and all the handle values with ADMIN_READ permission. If the query requests a specific handle value via the value index and that value does not have PUBLIC_READ permission, the server SHOULD accept the request (and authenticate the client) even if the request has its PO flag set.
If a query has a non-empty <IndexList> but an empty <TypeList>, the server SHOULD only return those handle values whose indexes are listed in the <IndexList>. Likewise, if a query has a non-empty <TypeList> but an empty <IndexList>, the server SHOULD only return those handle values whose data types are listed in the <TypeList>.
When both the <IndexList> and <TypeList> fields are non-empty, the server SHOULD return all handle values whose indexes are listed in the <IndexList> AND all handle values whose data types are listed in the <TypeList>.
3.2.2. Successful Query Response 🎉
The Message Header of any query response MUST set its <OpCode> to OC_RESOLUTION. A successful query response MUST set its <ResponseCode> to RC_SUCCESS.
The message body of a successful query response is defined like this:
<Message Body of Successful Query Response> ::= [<RequestDigest>]
<Handle>
<ValueList>Breaking it down:
<RequestDigest>is an optional field, as defined in section 2.2.3.<Handle>is a UTF8-String that specifies the handle the client queried.<ValueList>is a 4-byte unsigned integer followed by a list of handle values. The integer tells you how many handle values are in the list. The encoding of each handle value follows the specification given in [2] (see section 3.1). The integer is set to zero if there's no handle value that satisfies the query. 💜
3.2.3. Unsuccessful Query Response 🙈
If a server can't fulfill a client's request, it MUST return an error message. The general format for any error message from the server is specified in section 3.3 of this document.
For example, a server MUST return an error message if the queried handle doesn't exist in its database. That error message has an empty message body and its <ResponseCode> set to RC_HANDLE_NOT_FOUND.
Heads up: a server SHOULD NOT return an RC_HANDLE_NOT_FOUND message if it isn't responsible for the handle being queried. The queried handle might exist but be managed by another handle server (under some other handle service). When that happens, the server SHOULD either send a service referral (see section 3.4) or simply return an error message with <ResponseCode> set to RC_SERVER_NOT_RESP.
The server MAY return an error message with <ResponseCode> set to RC_SERVER_BUSY if it's too busy to process the request. Like RC_HANDLE_NOT_FOUND, an RC_SERVER_BUSY message also has an empty message body. 😮💨
Servers SHOULD return an RC_ACCESS_DENIED message if the request asks for a specific handle value (via the handle value index) that has neither PUBLIC_READ nor ADMIN_READ permission.
A handle server MAY ask its client to authenticate itself as the handle administrator during the resolution. This happens if any handle value in the query has ADMIN_READ permission but no PUBLIC_READ permission. Details of client authentication are described later in this document. 🔐
3.3. Error Response from Server 🚨
A handle server will return an error message if it runs into an error while processing a request. Any error response from the server MUST maintain the same <OpCode> (in the message header) as the one in the original request. Each error condition is identified by a unique <ResponseCode>, as defined in section 2.2.2.2 of this document.
The Message Body of an error message MAY be empty. Otherwise, it consists of the following data fields (unless otherwise specified):
<Message Body of Error Response from Server> ::= [<RequestDigest>]
<ErrorMessage>
[ <IndexList> ]Here's the breakdown:
<RequestDigest>is an optional field, as defined in section 2.2.3.<ErrorMessage>is a UTF8-String that explains the error.<IndexList>is an optional field. When it isn't empty, it consists of a 4-byte unsigned integer followed by a list of handle value indexes. The first integer tells you how many indexes are in the list. Each index is a 4-byte unsigned integer that refers to a handle value that contributed to the error. For example, say a server is asked to add three handle values, with indexes 1, 2, and 3, and handle values with indexes 1 and 2 already exist. In that case, the server could return an error message with <REsponseCode> set to RC_VALUE_ALREADY_EXIST and add indexes 1 and 2 to the <IndexList>. Note that the server is not obligated to return the complete list of handle value indexes that may have caused the error. 🫧
3.4. Service Referral
okay bestie so a handle server can get asked about handles that some other handle server or service manages 👀. when that happens, it gets to choose: send back a referral that points the client to the right service, or just send an error with <ResponseCode> set to RC_SERVER_NOT_RESP 💅. referrals also pop up when ownership of handles moves from one handle service to another 🦋. and any local handle service can use them to split its service up into multiple layers 🧚
the Message Header of a service referral must keep the same <OpCode> as the original request, and it sets its <ResponseCode> to RC_SERVICE_REFERRAL ✨
here's the shape of the Message Body of a service referral 🎀
<Message Body of Service Referral> ::= [ <RequestDigest> ]
<ReferralHandle>
[ <ValueList> ]where:
<RequestDigest>is an optional field, as defined in section 2.2.3 🫶<ReferralHandle>is a UTF8-String that identifies the handle (like a service handle) that holds the referral info, meaning the service information of the handle service it's referring to 🌸 if<ReferralHandle>is set to"0.NA/0.NA", it's sending the client over to the GHR 🌈<ValueList>is an optional field that must be empty if<ReferralHandle>is provided 💜 when it isn't empty, it's a 4-byte unsigned integer followed by a list of HS_SITE values, and that integer tells you how many HS_SITE values are in the list 🍓
unlike regular query responses (which can hold handle values of any data type), a service referral can only have zero or more HS_SITE values in its <ValueList> 💅 <ReferralHandle> is allowed to be an empty UTF8-String if the HS_SITE values in the <ValueList> aren't maintained by any handle 🦋
⚠️ bestie, clients have to be careful not to get stuck in loops caused by service referrals 😭 it's also 100% the client's job to authenticate the service information it gets from a referral 🔥 and if <ReferralHandle> is set to "0.NA/0.NA", a client should always use its own copy of the GHR service information 🫶
3.5. Client Authentication
servers ask clients to prove who they are as handle administrators when the client queries for any handle value with ADMIN_READ but no PUBLIC_READ permission 🔐 client authentication is also required for any handle administration request that needs administrator privileges, and that includes adding, removing, or modifying handles or handle values 👑
okay so authentication is a whole group chat of messages between the client and the server 💬 there's the challenge from the server to the client, then the client's challenge-response, and then a verification request and response too if secret key authentication is happening 🧚 every message in one of these exchanges gets tied together by a unique <SessionId> that the server assigns 🎀 for each authentication session, the server has to keep track of its challenge, the client's challenge-response, and the original client request 🧠
it starts with a response from the server that has a challenge in it for the client 🌸 the client must respond to that challenge with a challenge-response message 💅 then the server checks the challenge-response. it can either verify the digital signature inside it, or send a verification request to another handle server (called the verification server here) that keeps the secret key for the administrator 🦋 the whole point is to prove to the server that the client actually has the private key (or the secret key) of the handle administrator 🔑 if authentication fails, an error response gets sent back with <ResponseCode> set to RC_AUTHEN_FAILED 😭
if the client passes authentication, the server must also make sure the administrator is authorized for the request 👑 if they have enough privileges, the server processes the request and sends back the result ✨ if they don't have sufficient privileges, the server returns an error message with <ResponseCode> set to RC_NOT_AUTHORIZED 🙈
the next sections go through each message exchanged during authentication, one by one 💖
3.5.1. Challenge from Server to Client
the Message Header of the CHALLENGE must keep the same <OpCode> as the original request and set the <ResponseCode> to RC_AUTH_NEEDED 🎀 the server must assign a non-zero unique <SessionId> in the Message Envelope so it can keep track of the authentication 🧚 it also must set the RD flag of the <OpFlag> (see section 2.2.2.3) in the Message Header, whether or not the original request had the RD bit set 🦋
the Message Body of the server's CHALLENGE looks like this 🌈
<Message Body of Server's Challenge> ::= <RequestDigest>
<Nonce>where:
<RequestDigest>is the Message Digest of the request message, as defined in section 2.2.3 🫶<Nonce>is a 4-byte unsigned integer followed by a random string that the server generates with a secure random number generator 🔥 the integer tells you how many octets are in the random string, and the random string should be no less than 20 octets 💜
ngl this next bit is important 👀 the server won't sign the challenge unless the client asked it to. if the client is worried about whether it's talking to the right server, it can ask the server to sign the <Challenge> 🦋 and if the client asked for that signature but couldn't validate it, the client should throw out the server's response and send the request again 😭💅
3.5.2. Challenge-Response from Client to Server ✨
okay so the CHALLENGE_RESPONSE message header has to set its <OpCode> to OC_CHALLENGE_RESPONSE and its <ResponseCode> to 0 💅. it also has to keep the same <SessionId> (the one in the Message Envelope) that showed up in the server's challenge 🫶
the message body of the CHALLENGE_RESPONSE request is defined like this 🎀
<Message Body of CHALLENGE_RESPONSE> ::= <AuthenticationType>
<KeyHandle>
<KeyIndex>
<ChallengeResponse>where:
<AuthenticationType>is a UTF8-String that tells you what kind of authentication key the client is using 🔑. it's"HS_SECKEY"if the client is using a secret key, and"HS_PUBKEY"if it's using a public key instead.<KeyHandle>is a UTF8-String that names the handle holding the public or secret key of the handle administrator 🏠<KeyIndex>is a 4-byte unsigned integer. it's the index of the handle value (inside the<KeyHandle>) that holds the administrator's public or secret key 🔢<ChallengeResponse>contains either a Message Authentication Code (MAC) or a digital signature over the challenge from the server. this part is giving math 🧮
for HS_SECKEY, the <ChallengeResponse> is an octet followed by the MAC. that octet tells you which algorithm made the MAC. if the first octet is 0x01, the MAC is generated like this:
MD5_Hash(<SecretKey> + <ServerChallenge> + <SecretKey>)here, <SecretKey> is the administrator's secret key (the one referenced by the <KeyHandle> and <KeyIndex>), and <ServerChallenge> is the Message Body portion of the server's challenge 🌸
if the first octet is 0x02, the MAC is generated using this instead:
SHA-1_Hash(<SecretKey> + <ServerChallenge> + <SecretKey>)now, a more secure approach is to use HMAC [17] for the <ChallengeResponse> 🔒. the HMAC can be generated using the <SecretKey> and <ServerChallenge>. a <ChallengeResponse> whose first octet is 0x11 means the HMAC was generated with MD5, and a first octet of 0x12 means it was generated with SHA-1.
if the <AuthenticationType> is "HS_PUBKEY", the <ChallengeResponse> contains a digital signature over the Message Body portion of the server's challenge ✍️. this happens in two steps: first, a one-way hash value gets computed over the blob that's going to be signed, and second, that hash value gets signed using the private key. the signature is a UTF8-String naming the digest algorithm used, followed by the signature over the server's challenge. the <KeyHandle> and <KeyIndex> point to the administrator's public key, which is what you use to verify the signature 👑
handle administrators are defined through HS_ADMIN values assigned to the handle 🧚. each HS_ADMIN value defines the set of privileges the administrator gets. it also gives a reference to the authentication key that can be used to authenticate that administrator. the reference can be direct, if the <AdminRef> field of the HS_ADMIN value points straight at the handle value holding the authentication key. it can also be indirect, through administrator groups. in that case, the <AdminRef> field may refer to a handle value of type HS_VLIST. an HS_VLIST value defines an administrator group as a list of handle value references, and each of those refers to the authentication key of a handle administrator 🌈
for handles with multiple HS_ADMIN values, the server will have to check each one that has sufficient privileges, to see whether its <AdminRef> field matches the <KeyHandle> and <KeyIndex> 🔍. if there's no match but administrator groups are defined, the server must check whether the <KeyHandle> and <KeyIndex> belong to any administrator group that has sufficient privileges. an administrator group can contain another administrator group as a member, so servers must be careful to avoid infinite loops when navigating these groups 🌀 (this is very important, bestie)
if the <KeyHandle> and <KeyIndex> aren't referenced by any of the HS_ADMIN values, or by an administrator group with sufficient privileges, the server returns an error message with <ResponseCode> set to RC_NOT_AUTHORIZED 🚫. otherwise, the server keeps authenticating the client like this:
if the <AuthenticationType> is "HS_PUBKEY", the server retrieves the administrator's public key based on the <KeyHandle> and <KeyIndex>. that public key can be used to verify the <ChallengeResponse> against the server's <Challenge>. if they match, the server continues processing the original request and returns the result ✅. if they don't, the server returns an error message with <ResponseCode> set to RC_AUTHENTICATION_FAILED ❌
if the <AuthenticationType> is "HS_SECKEY", the server has to send a verification request to the verification server. that's the handle server that manages the handle referenced by the <KeyHandle> 🛰️. the verification request and its response are defined in the following sections. the verification server checks the <ChallengeResponse> against the <Challenge> on behalf of the handle server 🫶
3.5.3. Challenge-Response Verification-Request
the message header of the VERIFICATION_REQUEST must set its <OpCode> to OC_VERIFY_CHALLENGE and its <ResponseCode> to 0 📨
the message body of the Verification-Request is defined like this:
<Message Body of VERIFICATION_REQUEST> ::= <KeyHandle>
<KeyIndex>
<Challenge>
<ChallengeResponse>where:
<KeyHandle>is a UTF8-String that refers to the handle holding the administrator's secret key 🗝️<KeyIndex>is a 4-byte unsigned integer. it's the index of the handle value that holds the administrator's secret key 🔢<Challenge>is the message body of the server's challenge, as described in section 3.5.1 📣<ChallengeResponse>is the<ChallengeResponse>from the client in response to the server's<Challenge>, as defined in section 3.5.2 💜
any Challenge-Response Verification-Request must set its CT bit in the message header. the point of this is to make sure the verification server signs the Verification-Response, as the next section describes 🦋
3.5.4. Challenge-Response Verification-Response
the Verification-Response tells the requesting handle server whether the <ChallengeResponse> matches the <Challenge> from the Verification-Request 🎯
the message header of the Verification-Response must set its <ResponseCode> to RC_SUCCESS, whether or not the <ChallengeResponse> matches the <Challenge> ✨. the RD flag in the <OpFlag> field should also be set (to 1), since the <RequestDigist> will be mandatory in the message body 🙈
the message body of the Verification-Response is defined like this:
<Challenge-Response Verification-Response>
::= <RequestDigest>
<VerificationResult>where:
<RequestDigest>contains the message digest of the Verification-Request 🧾<VerificationResult>is an octet that's set to 1 if the<ChallengeResponse>matches the<Challenge>. otherwise it must be set to 0 🫧
the verification server may return an error with <ResponseCode> set to RC_AUTHEN_FAILED if it can't perform the verification. for example, that happens if the <KeyHandle> doesn't exist, or if the <KeyHandle> and <KeyIndex> refer to an invalid handle value 💀. when this happens, the server that's doing the client authentication should relay that same error message back to the client 📬
3.6. Handle Administration
the Handle System protocol supports a set of handle administration functions 🛠️. these include adding, deleting, and modifying handles or handle values. before fulfilling any administration request, the server must authenticate the client as the handle administrator who's authorized for that operation 🔐. and here's the big one: handle administration can only be carried out by the primary handle server 👑
3.6.1. Add Handle Value(s)
clients add values to existing handles by sending ADD_VALUE requests to the responsible handle server 🍓. the message header of the ADD_VALUE request must set its <OpCode> to OC_ADD_VALUE.
the message body of the ADD_VALUE request is encoded like this:
<Message Body of ADD_VALUE Request> ::= <Handle>
<ValueList>where:
<Handle>is a UTF8-String that specifies the handle 🏷️<ValueList>is a 4-byte unsigned integer followed by a list of handle values. the integer tells you how many handle values are in the list 🔢
the server that receives the ADD_VALUE request must first authenticate the client as the administrator with the ADD_VALUE privilege 🧐. once that works, the server adds each value in the <ValueList> to the <Handle>. if everything goes well, the server returns an RC_SUCCESS message to the client 🎉
each ADD_VALUE request must be carried out as a transaction 🧾. if adding any value in the <ValueList> raises an error, the entire operation must be rolled back. for any failed ADD_VALUE request, none of the values in the <ValueList> should be added to the <Handle>. the server must also send the client a response that explains the error 💅. for example, if a value in the <ValueList> has the same index as one of the existing handle values, the server returns an error message with <ResponseCode> set to RC_VALUE_ALREADY_EXISTS 🙅♀️
ADD_VALUE requests can also be used to add handle administrators 👑. that happens if the <ValueList> in the ADD_VALUE request contains any HS_ADMIN values. in that case the server must authenticate the client as an administrator with the ADD_ADMIN privilege before fulfilling the request 🔒
an ADD_VALUE request results in an error if the requested handle doesn't exist 🫥. when that happens, the server returns an error message with <ResponseCode> set to RC_HANDLE_NOT_EXIST 💜
3.6.2. Remove Handle Value(s) 🗑️
okay bestie, so to delete existing handle values, clients send REMOVE_VALUE requests to the responsible handle server 💅. The Message Header of the REMOVE_VALUE request must set its <OpCode> to OC_REMOVE_VALUE ✨.
The Message Body of any REMOVE_VALUE request is encoded like this 🎀:
<Message Body of REMOVE_VALUE Request> ::= <Handle>
<IndexList>where:
<Handle>is a UTF8-String that names the handle whose value(s) need to be removed 🌸.<IndexList>is a 4-byte unsigned integer, followed by a list of handle value indexes 🦋. Each index points to a handle value that gets removed from the<Handle>. The integer tells you how many indexes are in the list, and each index is also encoded as a 4-byte unsigned integer 🔢.
The server that gets a REMOVE_VALUE request has to authenticate the client as the administrator with the REMOVE VALUE privilege first 🔐. Once that works out, the server goes ahead and removes the handle values listed in the <IndexList> from the <Handle> 🧹. If it all goes well, the server sends an RC_SUCCESS message back to the client 🥰.
Every REMOVE_VALUE request must be carried out as a transaction 🧾. If removing any value in the <IndexList> raises an error, the entire operation must be rolled back, no exceptions 😭. For any failed REMOVE_VALUE request, none of the values referenced in the <IndexList> should be removed from the <Handle> 🫶. The server must also send the client a response that explains the error 📝. For example, trying to remove any handle value with neither PUB_WRITE nor ADMIN_WRITE permission will result in an RC_ACCESS_DENIED error 🚫. Also, a REMOVE_VALUE request that asks to remove a non-existing handle value will not be treated as an error 🙈.
REMOVE_VALUE requests can also be used to remove handle administrators 👑. That happens if any of the indexes in the <IndexList> refer to an HS_ADMIN value. Servers must authenticate the client as an administrator with the REMOVE_ADMIN privilege before fulfilling such requests 🔒.
3.6.3. Modify Handle Value(s) ✏️
clients can make changes to an existing handle value by sending MODIFY_VALUE requests to the responsible handle server 🌷. The Message Header of the MODIFY_VALUE request must set its <OpCode> to OC_MODIFY_VALUE 🧚.
The Message Body of any MODIFY_VALUE request is defined like this 💜:
<Message Body of MODIFY_VALUE Response> ::= <Handle>
<ValueList>where:
<Handle>is a UTF8-String that names the handle whose value(s) need to be modified 🍓.<ValueList>is a 4-byte unsigned integer, followed by a list of handle values ✨. The integer tells you how many handle values are in the list. Each value in the<ValueList>is a handle value that replaces the existing handle value with the same index 🔄.
The server that gets a MODIFY_VALUE request has to authenticate the client as an administrator with the MODIFY_VALUE privilege first 🛡️. Once that's done, the server replaces the handle values listed in the <ValueList>, as long as each handle value has PUB_WRITE or ADMIN_WRITE permission 💖. If it works, the server must notify the client with an RC_SUCCESS message 🎉.
Every MODIFY_VALUE request must be carried out as a transaction 🧾. If replacing any value listed in the <ValueList> raises an error, the entire operation must be rolled back 😤. For any failed MODIFY_VALUE request, none of the values in the <ValueList> should be replaced 🙅. The server must also return a response to the client that explains the error 📬. For example, if a MODIFY_VALUE request tries to remove a handle value that has neither PUB_WRITE nor ADMIN_WRITE permission, the server must return an error message with the <ResponseCode> set to RC_ACCESS_DENIED 🚫. A MODIFY_VALUE request that tries to replace non- existing handle values is also treated as an error 💀. In that case, the server returns an error message with <ResponseCode> set to RC_VALUE_NOT_FOUND 🔍.
MODIFY_VALUE requests can also be used to update handle administrators 👑. That happens if both the values in the <ValueList> and the value being replaced are HS_ADMIN values. Servers must authenticate the client as an administrator with the MODIFY_ADMIN privilege before fulfilling such a request 🔐. It is an error to replace a non-HS_ADMIN value with an HS_ADMIN value 🙃. In that case, the server returns an error message with <ResponseCode> set to RC_VALUE_INVALID 🫠.
3.6.4. Create Handle 🌱
clients can create brand new handles by sending CREATE_HANDLE requests to the responsible handle server 🐣. The Message Header of any CREATE_HANDLE request must set its <OpCode> to OC_CREATE_HANDLE 🍭.
The Message Body of any CREATE_HANDLE request is defined like this 🎀:
<Message Body of CREATE_HANDLE Response> ::= <Handle>
<ValueList>where:
<Handle>is a UTF8-String that names the handle 🦄.<ValueList>is a 4-byte unsigned integer, followed by a list of handle values ✨. The integer tells you how many handle values are in the list. The<ValueList>should at least include oneHS_ADMINvalue that defines the handle administrator 👑.
Only naming authority administrators with the CREATE_HANDLE privilege are allowed to create new handles under the naming authority 🔑. The server that receives a CREATE_HANDLE request must authenticate the client as the administrator of the corresponding naming authority handle, and make certain that the administrator is authorized to create handles under the naming authority 🧐. This is different from the ADD_VALUE request, where the server authenticates the client as an administrator of the handle itself 💅. Once that's verified, the server creates the new handle and adds each value in the <ValueList> to the new <Handle> 🌷. If everything goes smoothly, the server returns an RC_SUCCESS message to the client 🥳.
Every CREATE_HANDLE request must be carried out as a transaction 🧾. If any part of the CREATE_HANDLE process fails, the entire operation can be rolled back 🔄. For example, if the server fails to add values in the <ValueList> to the new handle, it must return an error message without creating the new handle 😬. Any CREATE_HANDLE request that asks to create a handle that already exists will be treated as an error 🚨. In that case, the server returns an error message with the <ResponseCode> set to RC_HANDLE_ALREADY_EXIST 🙅♀️.
CREATE_HANDLE requests can also be used to create naming authorities 🏛️. Naming authorities are created as naming authority handles at the GHR 🌍. Before creating a new naming authority handle, the server must authenticate the client as the administrator of the parent naming authority 🔐. Only administrators with the CREATE_NA privilege are allowed to create any sub-naming authority 💫. Root level naming authorities may be created by the administrator of the root handle "0.NA/0.NA" 👑.
3.6.5. Delete Handle 💔
clients delete existing handles by sending DELETE_HANDLE requests to the responsible handle server 🫧. The Message Header of the DELETE_HANDLE request must set its <OpCode> to OC_DELETE_HANDLE 🖤.
The Message Body of any DELETE_HANDLE request is defined like this 🌸:
<Message Body of DELETE_HANDLE Request> ::= <Handle>where:
<Handle>is a UTF8-String that names the handle 🍒.
The server that gets a DELETE_HANDLE request has to authenticate the client as the administrator with the DELETE_HANDLE privilege first 🔐. Once that checks out, the server deletes the handle along with any handle values assigned to it 🗑️. If it's successful, the server returns an RC_SUCCESS message to the client 💖.
Every DELETE_HANDLE request must be carried out as a transaction 🧾. If any part of the DELETE_HANDLE process fails, the entire operation must be rolled back 😵. For example, if the server fails to remove any handle values assigned to the handle (before deleting the handle), it must return an error message without deleting the handle 🙅. This may happen if the handle contains a value that has neither PUB_WRITE nor ADMIN_WRITE permission 🚧. In that case, the server returns an error message with the <ResponseCode> set to RC_PERMISSION_DENIED 🚫. A DELETE_HANDLE request that asks to delete a non-existing handle will also be treated as an error 🫠. The server returns an error message with the <ResponseCode> set to RC_HANDLE_NOT_EXIST 🔍.
DELETE_HANDLE requests can also be used to delete naming authorities 🏛️. This is done by deleting the corresponding naming authority handle on the GHR 🌍. Before deleting a naming authority handle, the server must authenticate the client as the administrator of the naming authority handle 🔐. Only administrators with the DELETE_NA privilege are allowed to delete the naming authority 🚪. Root level naming authorities may be deleted by the administrator of the root handle "0.NA/0.NA" 👑.
3.7. Naming Authority (NA) Administration 🏰
The Handle System manages naming authorities through naming authority handles 🗂️. Naming authority handles are managed by the GHR 🌐. Clients can change the service information of any naming authority by changing the HS_SITE values assigned to the corresponding naming authority handle 🛠️. Creating or deleting naming authorities is done by creating or deleting the corresponding naming authority handles 🧱. Root level naming authorities may be created or deleted by the administrator of the root handle "0.NA/0.NA" 👑. Non-root-level naming authorities may be created by the administrator of their parent naming authority 🌱.
For example, the administrator of the naming authority handle "0.NA/10" can create the naming authority "10.1000" by sending a CREATE_HANDLE request to the GHR to create the naming authority handle "0.NA/10.1000" 🪄. Before fulfilling the request, the server at the GHR must authenticate the client as the administrator of the parent naming authority, that is, the administrator of the naming authority handle "0.NA/10" 🔍. The server must also make sure that the administrator has the NA_CREATE privilege 🔑.
The Handle protocol also lets clients list handles or sub-naming authorities under a naming authority 📋. The details of these operations are described in the following sections 💜✨.
3.7.1. List Handle(s) under a Naming Authority 📋
Okay so, clients send LIST_HANDLE requests to handle servers when they want a list of handles under a naming authority. The Message Header of a LIST_HANDLE request MUST set its <OpCode> to OC_LIST_HANDLE. 💅
The Message Body of any LIST_HANDLE request looks like this:
<Message Body of LIST_HANDLE Request> ::= <NA_Handle>Where <NA_Handle> is a UTF8-String that specifies the naming authority handle. 🌸
To get the complete list, the request MUST be sent to every handle server listed in one of the service sites of the responsible handle service. Each server in that service site sends back its own list of handles under the naming authority. The Message Body of a successful LIST_HANDLE response (from each handle server) looks like this:
<Message Body of LIST_HANDLE Response> ::= <Num_Handles>
<HandleList>Where <Num_Handles> is the number of handles (managed by that handle server) under the naming authority, and <HandleList> is a list of UTF8-Strings, each one identifying a handle under the naming authority. 🦋
Heads up, this one can potentially slow down the overall system performance 💀. A handle service (or its service site) gets to decide whether or not to support it. If LIST_HANDLE isn't supported, the server returns an RC_OPERATION_DENIED message. And the server that receives a LIST_HANDLE request SHOULD authenticate the client as a naming authority administrator with the LIST_HANDLE privilege before it fulfils the request. Main character energy for security, ngl 🔥.
3.7.2. List Sub-Naming Authorities under a Naming Authority 🌈
Clients send LIST_NA requests to handle servers when they want a list of sub-naming authorities under a naming authority. The Message Header of the LIST_NA request MUST set its <OpCode> to OC_LIST_NA. 🧚
The Message Body of any LIST_NA request looks like this:
<Message Body of LIST_HANDLE Request> ::= <NA_Handle>Where <NA_Handle> is a UTF8-String that specifies the naming authority handle. 🍓
To get a complete list of the sub-naming authorities, the request MUST be sent to every handle server listed in any one of the service sites of the GHR. Each server in that service site sends back its own list of sub-naming authority handles under the given naming authority. The Message Body of a successful LIST_NA response (from each handle server) looks like this:
<Message Body of LIST_HANDLE Response> ::= <Num_Handles>
<HandleList>Where <Num_Handles> is the number of handles (managed by that handle server) under the naming authority, and <HandleList> is a list of UTF8-Strings, each one identifying a sub-naming authority user-specified naming authority. ✨
LIST_NA requests MUST be sent to servers under the GHR that manages all the naming authority handles. This one may potentially slow down the overall system performance, especially the GHS 😭. A server (or service sites) under the GHR gets to decide whether or not to support these requests. If LIST_NA isn't supported, the server returns an RC_OPERATION_DENIED message. And the server that receives a LIST_HANDLE request SHOULD authenticate the client as a naming authority administrator with the LIST_NA privilege before it fulfils the request. 👑
3.8. Session and Session Management 🎀
Sessions let multiple protocol operations share authentication information or network resources. For example, a naming authority administrator can authenticate itself once through the session setup, and then register multiple handles under that same session. It's giving efficiency 💖.
A client MAY ask the server to establish a session key and use it for later requests. A session key is a secret key that the client and server share. It can be used to authenticate or encrypt any message exchanged under the session. A session is encrypted if every message exchanged within it is encrypted using the session key. 🔐
Sessions MAY be established as the result of an explicit OC_SESSION_SETUP request from a client. A server MAY also set up a session automatically when multiple message exchanges are expected to fulfil a request. For example, the server will automatically establish a session if it receives a CREATE_HANDLE request that requires client authentication. ✨
Every session is identified by a non-zero Session ID that appears in the Message Header. Servers are responsible for generating a unique Session ID for each outstanding session. Each session may have a set of state information attached to it, which may include the session key and the information obtained from client authentication, as well as any communication options. Servers and clients are responsible for keeping that state information in sync until the session is terminated. Keeping things in sync is a whole vibe 🫶.
A session may be terminated with an OC_SESSION_TERMINATE request from the client. Servers MAY also terminate a session that has been idle for a significant amount of time. 🦋
3.8.1. Session Setup Request 💜
Clients establish a session with a handle server using a SESSION_SETUP request. A SESSION_SETUP request can also be used to update any state information associated with an existing session. The Message Header of the SESSION_SETUP request MUST have its <OpCode> set to OC_SESSION_SETUP and its <ResponseCode> set to 0. 🌸
The Message Body of any SESSION_SETUP request looks like this:
<SESSION_SETUP Request Message Body> ::= <SessionAttributes>Where <SessionAttributes> is a 4-byte unsigned integer followed by a list of session attributes. The integer indicates how many session attributes are in the list. Possible session attributes include <HS_SESSION_IDENTITY>, <HS_SESSION_TIMEOUT>, and <HS_SESSION_KEY_EXCHANGE>. Each one is defined below. 🧚
The first one is <HS_SESSION_IDENTITY>:
<HS_SESSION_IDENTITY> ::= <Key>
<Handle>
<ValueIndex>Where <Key> is the UTF-8 string constant "HS_SESSION_IDENTITY". <Handle> and <ValueIndex> are a UTF-8 string followed by a 4-byte unsigned integer, which together specify the handle and the handle value used for client authentication. It MUST refer to a handle value that contains the client's public key. The server uses that public key to authenticate the client. 🔑
Next up is <HS_SESSION_KEY_EXCHANGE>:
<HS_SESSION_KEY_EXCHANGE> ::= <Key>
<KeyExchangeData>Where <Key> is the UTF-8 string constant "HS_SESSION_KEY_EXCHANGE". <KeyExchangeData> is one of these tuples: <ClientCipher KeyExchange>, <HdlCipher KeyExchange>, or <ServerCipher KeyExchange>. Each of these is defined as follows. 🍓
<ClientCipher KeyExchange> looks like this:
<ClientCipher KeyExchange> ::= <Key>
<PubKey>Where <Key> is the UTF-8 string constant "CLIENT_CIPHER", and <PubKey> is a public key provided by the client and used by the server to encrypt the session key. 🩷
<HdlCipher KeyExchange> looks like this:
<HdlCipher KeyExchange> ::= <Key>
<ExchangeKeyHdl>
<ExchangeKeyIndex>Where <Key> is the UTF-8 string constant "HDL_CIPHER". <ExchangeKeyHdl> and <ExchangeKeyIndex> are a UTF-8 string followed by a 4-byte unsigned integer. Together they refer to a handle value used for session key exchange. That handle value MUST contain the client's public key, which the server uses to encrypt the session key before sending it to the client. 🔥
<ServerCipher KeyExchange> looks like this:
<ServerCipher KeyExchange> ::= <Key>Where <Key> is the UTF-8 string constant "SERVER_CIPHER". This tells the server that the client will be responsible for generating the session key. The server will have to provide its public key in the response message and set the <ResponseCode> to RC_SESSION_EXCHANGEKEY. The client can then use the server's public key to encrypt the session key and send it to the server via a later SESSION_EXCHANGEKEY request. 🌈
<DiffieHellman KeyExchange> looks like this:
<DiffieHellman KeyExchange> ::= <Key>
<DHParams>Where <Key> is the UTF-8 string constant "DIFFIE_HELLMAN". <DHParams> holds the values used as input to the Diffie-Hellman algorithm. It's made of three big integers of variable length. Each big integer is encoded as a 4-byte unsigned integer followed by an octet string, and the octet string holds the big integer itself. That 4-byte unsigned integer gives the number of octets in the octet string. Math bestie energy 🧮✨.
And last but not least, <HS_SESSION_TIMEOUT>:
<HS_SESSION_TIMEOUT> ::= <Key>
<TimeOut>Where <Key> is the UTF-8 string constant "HS_SESSION_TIMEOUT", and <TimeOut> is a 4-byte unsigned integer that specifies the desired duration of the session in seconds. ⏳
Note that it SHOULD be treated as an error if the same session attribute is listed multiple times in the <SessionAttribute> field. When that happens, the server SHOULD return an error message with <ResponseCode> set to RC_PROTOCOL_ERROR. Not allowed, periodt 🙅♀️.
A SESSION_SETUP_REQUEST can be used to change the session attributes of any established session. This happens when the <SessionId> is non-zero and matches one of the established sessions. Care MUST be taken by the server to prevent any unauthorized request from changing session attributes. For example, an encrypted session may only be changed into an unencrypted session by a SESSION_SETUP_REQUEST that has an appropriate MAC in its Message Credential. That's a whole security moment, and it's not up for debate 🛡️💅.
3.8.2. Session Setup Response
okay so the SESSION_SETUP response's header has to set its <OpCode> to OC_SESSION_SETUP 💅. The <ResponseCode> changes depending on the SESSION_SETUP request, but if the request works out and the server does not expect the client to send back a session key, it must be RC_SUCCESS 🎀.
The message body is empty unless the request asked for <HS_SESSION_KEY_EXCHANGE> 🫶. If it did, the body may hold either the encrypted session key from the server or the server's public key for the key exchange. Which one depends on what <HS_SESSION_KEY_EXCHANGE> in the request actually contains 🔑. If the request includes <ClientCipher KeyExchange> or <HdlCipher KeyExchange>, the body will have the encrypted session key from the server, and it looks like this:
<Message Body of SESSION_SETUP Response>
::= <RequestDigest>
<EncryptedSessionKey>
[ <EncryptionAlgorithm> ]
where
<RequestDigest>
Message digest of the SESSION_SETUP request is as specified in
section 2.2.3.
<EncryptedSessionKey>
Session key is encrypted using the public key provided in the
SESSION_SETUP request. The session key is a randomly
generated octet string from the server. The server will only
return the <EncryptedSessionKey> if the <KeyExchangeData> in
the SESSION_SETUP request provides the public key from the
client.
<EncryptionAlgorithm>
(optional) UTF-8 string that identifies the encryption
algorithm used by the session key.so basically the digest of the request goes in first, then the encrypted key, and the algorithm name is optional 🧚. The server only sends back <EncryptedSessionKey> when the <KeyExchangeData> in the request actually gives the client's public key, which is kind of the whole point 💀.
If the request includes <ServerCipher KeyExchange>, the server must give its public key in the SESSION_SETUP response 🔥. The client can then use that key in a later SESSION_EXCHANGEKEY request (more on that below) to swap session keys. For this, the header has to set its <ResponseCode> to RC_SESSION_EXCHANGEKEY ✨. The body must include the server's public key and goes like this:
<Message Body of SESSION_SETUP response>
::= <RequestDigest>
<Public Key for Session Key Exchange>
where
<RequestDigest>
Message digest of the SESSION_SETUP request as specified in
section 2.2.3.
<Public Key for Session Key Exchange>
Public key from the server to be used for session key
exchange. It is encoded in the same format as the <PublicKey>
record in the HS_SITE value (see section 3.2.2 in [2]).the key is encoded the same way as the <PublicKey> record in the HS_SITE value, so no new format to learn, yay 🌈.
3.8.3. Session Key Exchange
so if the SESSION_SETUP response came back with RC_SESSION_EXCHANGEKEY, the client is the one in charge of making the session key and sending it over 👑. The client can generate a session key, encrypt it with the public key the server gave back in the SESSION_SETUP response, and then send that encrypted key to the server in a SESSION_EXCHANGEKEY request 🦋.
The header of a SESSION_EXCHANGEKEY request has to set its <OpCode> to OC_SESSION_EXCHANGEKEY and its <ResponseCode> to 0 💖. The body is defined like this:
<Message Body of OC_SESSION_EXCHANGEKEY>
::= <Encrypted Session Key>
[ <EncryptionAlgorithm> ]
where
<EncryptedSessionKey>
Session key encrypted using the public key provided in the
SESSION_SETUP response. The session key is a randomly
generated octet string by the client.
<EncryptionAlgorithm>
(optional) UTF-8 string that identifies the encryption
algorithm used by the session key.the server that receives the exchange key or session key is responsible for making sure it meets the security requirements in its local policy 🛡️. If the server decides the key is vulnerable, it must send back an error message to the client with <ResponseCode> set to RC_SESSION_KEY_INVALID 🚨. Be careful with keys, bestie 😭.
3.8.4. Session Termination
clients can end a session by sending a SESSION_TERMINATE request 🌸. The header has to set <OpCode> to OC_SESSION_TERMINATE and <ResponseCode> to 0, and the body of any SESSION_TERMINATE request must be empty 🍓.
the server must send a SESSION_TERMINATE response to the client once the session is over 💜. The server should only end the session after it has finished every request under that session that came in before the Session Termination request. So no half-finished business, periodt 💅.
the header of the SESSION_TERMINATE response has to set its <OpCode> to OC_SESSION_TERMINATE ✨. A successful SESSION_TERMINATE response has <ResponseCode> set to RC_SUCCESS with an empty message body 🎀.
4. Implementation Guidelines ✨
4.1. Server Implementation
the best structure for a handle server depends on the host operating system 🖥️. This part only covers the stuff that's common to most handle servers, so it's not a full guide, just the core vibes 🫶.
a good server should make it easy to configure and fine-tune things 🔧. Some configurable items they suggest are the server's network interface(s) (e.g., IP address, port number, etc.), the number of concurrent processes/threads allowed, the time-out intervals for any TCP connection and/or authentication process, the re-try policy under UDP connection, policies on whether to support recursive service, case-sensitivity for ASCII characters, and different levels of transaction logging, etc. 🍓
all handle server implementations must support every handle data type defined in the "Handle System Namespace and Service Definition" [2] 💅. They should also be able to store handle values of any application defined data type 🌈.
a handle server must support multiple concurrent activities, whether those are separate processes or threads in the host's operating system, or multiplexed inside a single name server program 🧚. A handle server should not block UDP requests while it waits for TCP data or other query activities 🦋. Similarly, a handle server should not try to provide recursive service without processing those requests in parallel 👑. It's fine if it chooses to serialize requests from one client, or to treat identical requests from the same client as duplicates 💖.
4.2. Client Implementation
clients should be ready to receive handle values of any data type 🎀. They may choose to add a callback interface so new modules or plug-ins can support application-defined data types ✨.
clients that follow service referrals or handle aliases must avoid falling into an infinite loop 🔁. They should not keep contacting the same server for the same request with the same target entry 🙈. A client may use a counter that goes up each time it follows a service referral or handle alias. There should be a configurable upper limit on that counter, so the client can control how many levels of referrals or aliases it follows 🛑.
clients that do some caching get way better performance than the ones that don't 🚀. Client implementations should always consider caching the service information tied to a naming authority 💜. That cuts down on roundtrips for later handle requests under the same naming authority 🌸.
5. Security Considerations 💀
the overall Handle System security considerations are covered in "Handle System Overview" [1], and that discussion applies just as much to this document 🔐. The security considerations for the Handle System data model and service model are in "Handle System Namespace and Service Definition" [2] 📚.
for efficiency, the Handle protocol includes a simple challenge-response authentication protocol for basic client authentication 🤝. Handle servers are free to add other authentication mechanisms (e.g., SASL) as needed. The details of that will be in a separate document 📄.
data integrity under the Handle protocol comes from the server's digital signature ✍️. Care must be taken to protect the server's private key from any impersonation attack 😱. This is serious, bestie, like main character-level serious 🚨. Any change to the server's public key pair must be registered with the GHR, in terms of service information 🗂️.
6. Acknowledgements 🫶
this work is derived from earlier versions of the Handle System implementation 🌱. The overall digital object architecture, including the Handle System, was described in a 1995 paper by Robert Kahn and Robert Wilensky [22] 📜. Development continued at CNRI as part of the Computer Science Technical Reports (CSTR) project, funded by the Defense Advanced Projects Agency (DARPA) under Grant Numbers MDA-972-92-J-1029 and MDA-972-99-1-0018 💼. The design ideas came from discussions within the Handle System development team, including David Ely, Charles Orth, Allison Yu, Sean Reilly, Jane Euler, Catherine Rey, Stephanie Nguyen, Jason Petrone, and Helen She 👑. Their contributions are so appreciated 🥰.
The authors also thank Russ Housley (housley@vigilsec.com), Ted Hardie (hardie@qualcomm.com), and Mark Baugher (mbaugher@cisco.com) for their extensive review and comments 🙏, as well as recommendations from other members of the IETF/IRTF community 🌈.
7. Informative References ✨
okay bestie, this is the reading list 📚 these are the sources the RFC points to for background, and none of them are required reading to implement it 🤓
[1]Sun, S. and L. Lannom, "Handle System Overview", RFC 3650, November 2003.[2]Sun, S., Reilly, S. and L. Lannom, "Handle System Namespace and Service Definition", RFC 3651, November 2003.[3]Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 2279, January 1998.[4]A. Freier, P. Karlton, P. Kocher "The SSL Protocol Version 3.0"[5]RSA Laboratories, "Public-Key Cryptography Standard PKCS#7" http://www.rsasecurity.com/rsalabs/pkcs/[6]U.S. Federal Information Processing Standard: Digital Signature Standard.[7]Housley, R., "Cryptographic Message Syntax (CMS) Algorithms", RFC 3370, August 2002.[8]Braden, R., "FTP Data Compression", RFC 468, March 1973.[9]Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April 1992.[10]NIST, FIPS PUB 180-1: Secure Hash Standard, April 1995.[11]D. Cohen, "On Holy Wars and a Plea for Peace", Internet Experiment, Note IEN 137, 1 April 1980.[12]Balakrishnan, H. and S. Seshan, "The Congestion Manager", RFC 3124, June 2001.[13]R. Kahn, R. Wilensky, "A Framework for Distributed Digital Object Services, May 1995, http://www.cnri.reston.va.us/k-w.html[14]Polk, W., Housley, R. and L. Bassham, "Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 3279, April 2002.[15]Housley, R., Polk, W., Ford, W. and D. Solo, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 3280, April 2002.[16]M. Bellare and P. Rogaway. The Exact Security of Digital Signatures - How to Sign with RSA and Rabin. In Advances in Cryptology-Eurocrypt '96, pp.399-416, Springer-Verlag, 1996.[17]Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed-Hashing for Message Authentication", RFC 2104, February 1997.[18]R. Kahn, R. Wilensky, "A Framework for Distributed Digital Object Services, May 1995, http://www.cnri.reston.va.us/k-w.html
8. Authors' Addresses 🎀
these are the four people who wrote it, all at CNRI in Reston, VA, so you know who to slide into the DMs 💌
Sam X. Sun
Corporation for National Research Initiatives (CNRI)
1895 Preston White Dr., Suite 100
Reston, VA 20191
Phone: 703-262-5316
EMail: ssun@cnri.reston.va.us
Sean Reilly
Corporation for National Research Initiatives (CNRI)
1895 Preston White Dr., Suite 100
Reston, VA 20191
Phone: 703-620-8990
EMail: sreilly@cnri.reston.va.us
Larry Lannom
Corporation for National Research Initiatives (CNRI)
1895 Preston White Dr., Suite 100
Reston, VA 20191
Phone: 703-262-5307
EMail: llannom@cnri.reston.va.us
Jason Petrone
Corporation for National Research Initiatives (CNRI)
1895 Preston White Dr., Suite 100
Reston, VA 20191
Phone: 703-262-5340
EMail: jpetrone@cnri.reston.va.us9. Full Copyright Statement 💖
the legal bit, but it's giving very clear rules 🧾
Copyright (C) The Internet Society (2003). All Rights Reserved.
okay so the vibe is: you can copy this doc, share it, and make derivative works that explain it or help people implement it, with or without changes to those derivatives, as long as the copyright notice and this paragraph stay on every copy. the document itself can't be modified, though. you can't strip the copyright notice or the references to the Internet Society or other Internet organizations, unless it's for developing Internet standards, in which case the Internet Standards process copyright procedures have to be followed. translating it into other languages is also allowed 🌍
the permissions are perpetual, so the Internet Society or its successors and assignees can't take them back 🦋
and the disclaimer, ngl, is the most serious part 😭 the document and its info is provided "AS IS", and the Internet Society and the Internet Engineering Task Force disclaim all warranties, express or implied. that includes no promise that using the info won't infringe anyone's rights, and no implied warranties of merchantability or fitness for a particular purpose. translation: don't expect a guarantee 💀
Acknowledgement 🫶
this one's short and sweet: funding for the RFC Editor function is currently provided by the Internet Society 🌸
📦 where this page comes from
- ietf: rfc3652 2003-11
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms