RFC 6317
Basic Socket Interface Extensions for the Host Identity Protocol (HIP)
RFC 6317 Title Block 🎀
- RFC number and title: RFC 6317, Basic Socket Interface Extensions for the Host Identity Protocol (HIP) 💖
- Authors: M. Komu (Aalto University) and T. Henderson (The Boeing Company) 🫶
- Category: Experimental 🧪
- ISSN: 2070-1721
- Date: July 2011 📅
- Obsoletes/Updates: This title block doesn't list any RFCs that it obsoletes or updates ✨
Abstract 🌸
okay so this doc defines extensions to the current sockets API for the Host Identity Protocol (HIP) 🦋 The big focus is on public-key-based identifiers that get discovered through DNS resolution. It also defines interfaces for manual bindings between Host Identity Tags (HITs) and locators. With these extensions, an app can support more relaxed security models where communication can be non-HIP-based, depending on local policies 🔥 Everything here is experimental and gives you basic tools for playing around with policies 🧪
Status of This Memo 💅
bestie, this one is not an Internet Standards Track specification. It's published for examination, experimental implementation, and evaluation 👀
This document defines an Experimental Protocol for the Internet community. It's a product of the Internet Engineering Task Force (IETF) and represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). Not every document the IESG approves is a candidate for any level of Internet Standard, so check Section 2 of RFC 5741 for the full scoop ✨
For info on the current status of this document, any errata, and how to give feedback, go to http://www.rfc-editor.org/info/rfc6317 🌈
Copyright Notice 🎀
Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. 💜
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication. Please review those documents carefully, because they describe your rights and restrictions with respect to this document 🙈 Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they're provided without warranty as described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of that material may not have granted the IETF Trust the right to allow modifications of it outside the IETF Standards Process. So unless you get an adequate license from the person(s) controlling the copyright in those materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process. The one exception is formatting it for publication as an RFC or translating it into languages other than English 🫶
Table of Contents 📚
1. Introduction ....................................................3
2. Terminology .....................................................5
3. Name Resolution Process .........................................5
3.1. Interaction with the Resolver ..............................5
3.2. Interaction without a Resolver .............................6
4. API Syntax and Semantics ........................................7
4.1. Socket Family and Address Structure Extensions .............7
4.2. Extensions to Resolver Data Structures .....................9
4.3. The Use of getsockname() and getpeername() Functions ......12
4.4. Selection of Source HIT Type ..............................12
4.5. Verification of HIT Type ..................................13
4.6. Explicit Handling of Locators .............................14
5. Summary of New Definitions .....................................16
6. Security Considerations ........................................16
7. Contributors ...................................................17
8. Acknowledgments ................................................17
9. References .....................................................17
9.1. Normative References ......................................17
9.2. Informative References ....................................181. Introduction ✨
okay so this doc defines the C-based sockets Application Programming Interface (API) extensions for handling HIP-based identifiers explicitly in HIP-aware apps 💖 The apps, or the high-level programming languages or libraries they use, are in charge of managing the identifiers. The extensions here are mainly for the case where a DNS resolution step happened before a new socket gets created, and the system has cached identifiers or can otherwise resolve them to locators (IP addresses) 🌸 The DNS extension for HIP is described in [RFC5205]. The extensions also cover the case where an app wants to explicitly provide suggested locators along with the identifiers, including the opportunistic case where the system doesn't know the peer host identity 🧚
The Host Identity Protocol (HIP) [RFC4423] proposes a new cryptographic namespace. It separates the roles of endpoint identifiers and locators by introducing a new namespace to the TCP/IP stack 🔥 Shim6 [RFC5533] is another protocol built on an identity-locator split 👀 The APIs in this document are specific to HIP, but they were designed as much as possible so they don't block use with other protocols. Using these APIs with other protocols is, for now, for further study 🦋
The APIs here are based on Host Identity Tags (HITs), which are defined as IPv6 addresses with the Overlay Routable Cryptographic Hash Identifiers (ORCHID) prefix [RFC4843] ✨ ORCHIDs are derived from Host Identifiers by using a hash and fitting the result into an IPv6 address. Those addresses are called HITs, and you can tell them apart from other IPv6 addresses by the ORCHID prefix 💅 Heads up: ORCHIDs are currently an experimental allocation by IANA. If the ORCHID allocation expires and HIT generation switches to a different prefix in the future, most users of the API won't be affected, unless they explicitly check the ORCHID prefix on returned HITs. Users who check (for consistency) that HITs have a valid ORCHID prefix must monitor the IANA allocation for ORCHIDs and adapt their software if the ORCHID allocation gets removed at some future date 🙈
Apps can see the HIP layer and its identifiers in the networking stacks with different levels of visibility. [RFC5338] covers the lowest level, where apps are completely unaware of the underlying HIP layer 💀 HIP-unaware apps can sometimes use HIP-based identifiers, like Local Scope Identifiers (LSIs) or HITs, instead of IPv4 or IPv6 addresses. They can't observe the identifier-locator bindings, though 🫠
This document extends [RFC3493] to define a new socket address family, AF_HIP 🌈 Like other address families, AF_HIP can be used as an alias for PF_HIP. The extensions also describe a new socket address structure for sockets that use HITs explicitly, and they describe how the socket calls in [RFC3493] are adapted or extended as a result 💜
Some apps may accept incoming communications from any identifier 🍓 Other apps may start outgoing communications without knowing the peer identifier, using opportunistic mode (Section 4.1.6 of [RFC5201]) and relying only on a peer locator. This document describes how to handle both situations using "wildcards", as described in Section 4.1.1 ✨
This document references one more API document, [RFC6316], which defines multihoming and explicit-locator handling. Most of the extensions defined here can be used independently of that document 🎀
The identity-locator split introduced by HIP brings some policy-related challenges with datagram-oriented sockets, opportunistic mode, and manual bindings between HITs and locators. The extensions here are experimental in nature and give you basic tools for experimenting with policies. Policy-related issues are left for further experimentation 🧪
To recap, the extensions in this document have three goals 👑 The first goal is to let HIP-aware apps open sockets to other hosts based on the HITs alone, assuming the underlying system can resolve the HITs to the addresses used for initial contact. The second goal is that apps can explicitly start communications with unknown peer identifiers. The third goal is to show how HIP-aware apps can use the Shim API [RFC6316] to manually map locators to HITs 💖
This document was published as experimental because a number of its normative references had experimental status. The success of this experiment can be evaluated by a thorough implementation of the APIs defined here 🦋
2. Terminology 🍓
The terms used in this document are summarized in Table 1 🌸
+---------+--------------------------------------------------------+
| Term | Explanation |
+---------+--------------------------------------------------------+
| FQDN | Fully Qualified Domain Name |
| HIP | Host Identity Protocol |
| HI | Host Identifier |
| HIT | Host Identity Tag, a 100-bit hash of a public key with |
| | a 28-bit prefix |
| LSI | Local Scope Identifier, a local, 32-bit descriptor for |
| | a given public key |
| Locator | Routable IPv4 or IPv6 address used at the lower layers |
| RR | Resource Record |
+---------+--------------------------------------------------------+ Table 13. Name Resolution Process 🧚
This section gives an overview of how the API can be used 💅 First, we look at the case where a resolver is involved in name resolution, and then the case where no resolver is involved.
3.1. Interaction with the Resolver ✨
Okay bestie, before an app can even start talking to whoever lives at a given FQDN or relative hostname 💌, it has to translate that name into the matching identifier(s). Figure 1 shows the DNS-based version of this translation 🦋. The app calls the resolver in step (a) to turn an FQDN into one or more socket addresses inside the PF_HIP family. The resolver then asks DNS in step (b) to map the FQDN to one or more HIP RRs with the HIT and HI, and possibly the Responder's rendezvous server. It also (in parallel or one after the other) resolves the FQDN into possibly one or more A and AAAA records.
It's giving multiple moving parts 🌈 The FQDN may map to multiple Host Identifiers and locators, so this step may involve several DNS transactions, including queries for A, AAAA, HI, and possibly other resource records. DNS replies with a list of HIP resource records in step (c). Optionally, in step (d), the resolver caches the HIT-to-locator mapping with the HIP module. Then it converts the HIP records to HITs and hands the HITs back to the app, wrapped in HIP socket address structures, in step (e). Depending on the parameters of the resolver call, it may also return other socket address structures. Finally, the app takes whatever socket address structure(s) it got and uses them in socket calls like connect() in step (f) 🚀
+----------+
| |
| DNS |
| |
+----------+
^ |
b. QNAME=FQDN | | c. HIP and
| | A/AAAA
| v RR(s)
+-------------+ a. getaddrinfo(<FQDN>) +----------+
| |------------------------>| |
| Application | | Resolver |
| |<------------------------| |
+-------------+ e. <HITs> +----------+
| |
| | d. HIP and
| f. connect(<HIT>) | A/AAAA
| or any other socket call | RR(s)
v v
+----------+ +----------+
| | | |
| TCP/IP | | HIP |
| Stack | | |
+----------+ +----------+Figure 1
Real talk though, the resolver functionality can be built in different ways 🧚 For example, it may live inside existing resolver libraries, or it may be a HIP-aware interposing agent.
3.2. Interaction without a Resolver 🌸
The extensions in this document are all about using the resolver to map hostnames to HITs and locators in HIP-aware apps. The resolver may implicitly link a HIT to its locator(s) by sharing the HIT-to-IP mapping with the HIP daemon. BUT an app can also work straight on a peer HIT without going through the resolver at all 👀 In that case, the app may lean on the system to map the peer HIT to an IP address. Or it can map the HIT to an IP address itself using the socket options from Section 4.6. Full support for every extension in this document requires a bunch of shim socket options [RFC6316] to be implemented by the system. Main character energy for the system 💅
4. API Syntax and Semantics 👑
In this section, we describe the native HIP APIs using C programming language syntax. We only cover the interfaces and data structures that are either changed or brand new, since the native HIP APIs are otherwise identical to the sockets API [POSIX] ✨
4.1. Socket Family and Address Structure Extensions 🦋
The sockets API extensions define a new protocol family, PF_HIP, and a new address family, AF_HIP. These two constants are aliases of each other. These definitions shall be defined as a result of including <sys/socket.h> (yes, the spec really says shall, iykyk 🙈)
When socket() gets called with PF_HIP as its first argument (domain), it tries to create a socket for HIP communication. If HIP isn't supported, socket() follows its default behavior, returns -1, and sets errno to EAFNOSUPPORT 💀
Figure 2 shows the recommended implementation of the socket address structure for HIP, in Portable Operating System Interface (POSIX) format 🍓
#include <netinet/hip.h>
typedef struct in6_addr hip_hit_t;
struct sockaddr_hip {
uint8_t ship_len;
sa_family_t ship_family;
in_port_t ship_port;
uint32_t ship_flags;
hip_hit_t ship_hit;
};Figure 2
Let's break down each field, bestie 🫶
uint8_t ship_len: This field defines the length of the structure. Implementations that don't define this field typically embed the information in the following ship_family field.
sa_family_t ship_family: This mandatory field identifies the structure as a sockaddr_hip structure. It overlays the sa_family field of the sockaddr structure. Its value must be AF_HIP.
in_port_t ship_port: This mandatory field holds the transport protocol port number. It's handled the same way as the sin_port field of the sockaddr_in structure. The port number is stored in network byte order.
uint32_t ship_flags: This mandatory bit field holds auxiliary flags. This document doesn't define any flags, but the field is included so future extensions can use it 🔮
hip_hit_t ship_hit: This mandatory field holds the endpoint identifier. When the system hands a sockaddr_hip structure to the app, this field is set to a valid HIT, IPv4, or IPv6 address, as covered in Section 4.5. When the app passes a sockaddr_hip structure to the system, this field must be set to a HIT or a wildcard address, as discussed in Section 4.1.1 ✨
Some apps rely on system-level access control, either implicit or explicit (like the accept_filter() function found on BSD-based systems). That stuff is out of scope though 🙅 Other apps handle access control themselves by using the HITs. Apps working with sockaddr_hip structures can use memcmp() or a similar function to compare the ship_hit fields. It should also be noted that different connection attempts between the same two hosts can produce different HITs, because a host is allowed to have multiple HITs 🌈
4.1.1. HIP Wildcard Addresses 💖
HIP wildcard addresses are similar to IPv4 and IPv6 wildcard addresses. They can be used instead of specific HITs in the ship_hit field for local and remote endpoints in sockets API calls like bind(), connect(), sendto(), or sendmsg() 🎀
To bind to all local IPv4 and IPv6 addresses and HIP HITs, the ship_hit field must be set to HIP_ENDPOINT_ANY. To bind to all local HITs, ship_hit must contain HIP_HIT_ANY. To bind only to all local public HITs, the ship_hit field must be HIP_HIT_ANY_PUB. The value HIP_HIT_ANY_TMP binds a socket to all local anonymous identifiers only, as specified in [RFC4423]. The system may label anonymous identifiers as such depending on whether they've been published or not. After binding a socket with one of the HIP_HIT_ANY_* wildcard addresses, the app is guaranteed to receive only HIP-based data flows. With the HIP_ENDPOINT_ANY wildcard address, the socket accepts HIP, IPv6, and IPv4-based data flows 🦋
When a socket is bound or connected with a sockaddr_hip structure (aka the PF_HIP protocol family), the system returns only addresses of the AF_HIP family, meaning sockaddr_hip structures, for that socket. This applies to every function that hands addresses back to the app, like accept() or recvfrom() 💅 If the data flow is HIP-based, the ship_hit field contains the peer's HIT. For a non-HIP IPv6 data flow, the field contains the peer's IPv6 address. For a non-HIP IPv4 data flow, the field contains the peer's IPv4 address in IPv4-mapped IPv6 address format, as described in Section 3.7 of [RFC3493]. Section 4.5 explains how the app can check which type of address the sockets API calls returned 🔍
Here's how an app uses the sockets API to set up a connection or send messages in HIP opportunistic mode (cf. [RFC5201]) 🧚 First, the app associates a socket with at least one IP address of the destination peer by setting the SHIM_LOCLIST_PEER_PREF socket option. Then it uses outgoing socket functions like connect(), sendto(), or sendmsg() with the HIP_ENDPOINT_ANY or HIP_HIT_ANY wildcard address in the ship_hit field of the sockaddr_hip structure. With HIP_HIT_ANY, the underlying system allows only HIP-based data flows on that socket. For incoming packets, the system discards all non-HIP-related traffic arriving at the socket. For outgoing packets, the system returns -1 from the socket call and sets errno to an appropriate error type when it fails to deliver the packet over a HIP-based data channel 🚫
The semantics of using HIP_ENDPOINT_ANY are still being figured out through further experimentation in opportunistic mode. Use like this may result in a data flow either with or without HIP 🧪
4.2. Extensions to Resolver Data Structures ✨
okay so the HIP APIs bring in a brand new address family, AF_HIP 🦋, and HIP-aware apps can use it to control what address type getaddrinfo() hands back [RFC3493] [POSIX]. getaddrinfo() uses a struct called addrinfo in its "hints" and "res" arguments (more on that in the next section), and here's what addrinfo looks like in Figure 3 💅
#include <netdb.h>
struct addrinfo {
int ai_flags; /* e.g., AI_CANONNAME */
int ai_family; /* e.g., AF_HIP */
int ai_socktype; /* e.g., SOCK_STREAM */
int ai_protocol; /* 0 or IPPROTO_HIP */
socklen_t ai_addrlen; /* size of *ai_addr */
struct sockaddr *ai_addr; /* sockaddr_hip */
char *ai_canonname; /* canon. name of the host */
struct addrinfo *ai_next; /* next endpoint */
int ai_eflags; /* RFC 5014 extension */
};
Figure 3so if an app resolves with ai_family set to AF_UNSPEC in hints, it might get any kind of socket address struct, sockaddr_hip included 🌈 but if it only wants HITs living inside sockaddr_hip structs, it should set ai_family to AF_HIP 🎀 otherwise the resolver just won't return any sockaddr_hip structs. and if AF_HIP is requested but not supported? the resolver returns EAI_FAMILY 😭
also, the resolver ignores the AI_PASSIVE flag whenever the app sets the family in hints to AF_HIP 🙈
now the drama 🔥 the system might have a HIP-aware interposing DNS agent, as described in Section 3.2 of [RFC5338]. in that case the DNS agent may, depending on local policy, quietly return LSIs or HITs in sockaddr_in and sockaddr_in6 structures when they're available. but a HIP-aware app can override that policy in two ways 👑 first, it can set the family to AF_HIP in the hints argument of getaddrinfo() when it only wants sockaddr_hip structs. second, it can set the AI_NO_HIT flag so the resolver never returns HITs in any kind of data structure. main character energy, honestly ✨
when getaddrinfo() returns resolved outputs in the "res" argument, it sets the family to AF_HIP whenever the related structure is sockaddr_hip 💖
4.2.1. Resolver Usage
a HIP-aware app either creates the sockaddr_hip structures manually or grabs them from the resolver 🧚 the explicit configuration of locators is described in [RFC6316]. this document defines "automated" resolver extensions for the getaddrinfo() resolver [RFC3493]. other resolver calls, like gethostbyname() and getservbyname(), are not defined here 🙅♀️ here's the getaddrinfo() resolver interface in Figure 4:
#include <netdb.h>
int getaddrinfo(const char *nodename,
const char *servname,
const struct addrinfo *hints,
struct addrinfo **res)
void free_addrinfo(struct addrinfo *res)
Figure 4as [RFC3493] explains, getaddrinfo() takes nodename, servname, and hints as its inputs, and it puts the result of the query into the res output argument 🍓 it returns zero on success, or a non-zero error value on error. the nodename argument is the hostname to be resolved, and a NULL there means the HITs of the local host. servname is the port number that gets set in the socket addresses in res. and nodename and servname cannot both be NULL at the same time, so don't even try 💀
the input argument "hints" acts like a filter that defines the attributes you need from the resolved endpoints ✨ a NULL hints argument means literally any kind of endpoint is acceptable 🫶
the output argument "res" is dynamically allocated by the resolver, and the app frees it with the free_addrinfo function 🧹 res holds a linked list of the resolved endpoints. when the input has the family set to AF_HIP, that list contains only sockaddr_hip structures. when the family is zero, the list puts sockaddr_hip structures before sockaddr_in and sockaddr_in6 structures.
the resolver can return a HIT that maps to multiple locators 🌸 it may cache those locator mappings with the HIP module, and the HIP module manages the multiple locators according to the host's system policies. the multihoming document [RFC6316] explains how an app can override those default policies.
last but not least, the app can configure the HIT explicitly without setting the locator, or the resolver can fail to resolve any locator at all 😬 in that case the app relies on the system to map the HIT to an IP address. if the system can't provide that mapping, the called sockets API function returns -1 to the app and sets errno to EADDRNOTAVAIL. ngl that's a lot, but you've got this 💜
4.3. The Use of getsockname() and getpeername() Functions
a sockaddr_hip structure does not contain a HIT when the app uses the HIP_HIT_ANY_* or HIP_ENDPOINT_ANY constants 🙈 but no stress, the app can still find the local and peer HITs with getsockname() and getpeername() once the socket is connected. those two functions always output a sockaddr_hip structure when the socket's family is AF_HIP 🎀 and the app should be prepared to also handle IPv4 and IPv6 addresses in the ship_hit field, as described in Section 4.1, in the context of the HIP_ENDPOINT_ANY constant. bestie, be ready for both 👑
4.4. Selection of Source HIT Type
a client-side app can pick its source HIT by, for example, querying all of the local HITs with getaddrinfo() and tying one of them to the socket using bind() 💅 but this section is about a different method, where the app doesn't call bind() explicitly. instead, it just says what it prefers for the source HIT type, and the system does the rest ✨
sockets API for source address selection [RFC5014] defines socket options that let apps influence how source addresses get picked. sometimes HIP-aware apps want to influence source HIT selection too, especially whether an outbound connection should use a published or anonymous HIT 🦋 just like IPV6_ADDR_PREFERENCES from [RFC5014], there's a socket option called HIT_PREFERENCES for HIP-based sockets. you can use it with setsockopt() and getsockopt() to set and get the HIT selection preferences for a HIP-enabled socket 🧚 the socket option value (optval) is a 32-bit unsigned integer argument, and it's made of flags. each flag is an address selection preference that tweaks one of the rules in the default HIT selection. the flags are in Table 2:
+---------------------------+-------------------------+
| Socket Option | Purpose |
+---------------------------+-------------------------+
| HIP_PREFER_SRC_HIT_TMP | Prefer an anonymous HIT |
| HIP_PREFER_SRC_HIT_PUBLIC | Prefer a public HIT |
+---------------------------+-------------------------+
Table 2if the system can't assign the type of HIT you asked for, the socket call (connect(), sendto(), or sendmsg()) fails at HIT selection time, and errno gets set to EINVAL 😭 and if the app tries to set both of those flags on the same socket? also EINVAL. not it 🙅♀️
4.5. Verification of HIT Type
an app using the HIP_ENDPOINT_ANY constant might want to check whether the actual communication was based on HIP or not 🔥 it might also want to verify whether a HIT belonging to the local host is public or anonymous 🕵️♀️ it does this with a brand new function called sockaddr_is_srcaddr(), shown in Figure 5:
#include <netinet/hip.h>
short sockaddr_is_srcaddr(struct sockaddr *srcaddr,
uint64_t flags);
Figure 5sockaddr_is_srcaddr() works the same way as inet6_is_srcaddr() [RFC5014], which checks the type of an address belonging to the local host 💖 the difference is that sockaddr_is_srcaddr() handles sockaddr_hip structures as well as sockaddr_in6, and possibly other socket structures in further extensions ✨ also, its flags argument is 64 bits instead of 32, because the new function handles the same flags as [RFC5014] plus two HIP-specific ones, HIP_PREFER_SRC_HIT_TMP and HIP_PREFER_SRC_HIT_PUBLIC. with those two, the app can tell anonymous HITs apart from public ones 🌈
when given an AF_INET6 socket, sockaddr_is_srcaddr() behaves exactly like inet6_is_srcaddr() as described in [RFC5014] 🫶 with an AF_HIP socket, the function returns 1 when the HIT in the socket address structure matches a valid HIT of the local host and satisfies the given flags ⭐ it returns -1 when the HIT doesn't belong to the local host or the flags aren't valid. it returns 0 when the preference flags are valid but the HIT doesn't match them. and it also returns 0 on a sockaddr_hip structure containing a HIP_ENDPOINT_ANY or HIP_HIT_ANY_* wildcard 🙈
the sockaddr_is_srcaddr() interface only applies to local HITs 💅 if you want to check that a given hit_hit_t pointer has the HIT prefix, apps can call hip_is_hit(), shown in Figure 6:
#include <netinet/hip.h>
short hip_is_hit(hip_hit_t *hit);
Figure 6hip_is_hit() returns 1 when the given argument contains the HIT prefix 🎀 it returns -1 on error and sets errno appropriately. it returns 0 when the argument does not have the HIT prefix. it also returns 0 when the argument is a HIP_ENDPOINT_ANY or HIP_HIT_ANY_* wildcard. and that's the tea for this part 🍵✨
4.6. Explicit Handling of Locators 🦋
okay so the system resolver (or the HIP module) maps HITs to locators implicitly 🧚 but some apps wanna set the initial locator mappings explicitly 💅 so the app makes a socket with AF_HIP as the domain argument first 🫶 then it can get or set locator info with the shim socket options from [RFC6316] (see Table 3 below, it's lowkey the cheat sheet 🍓)
+---------------------+---------------------------------------------+
| optname | description |
+---------------------+---------------------------------------------+
| SHIM_LOC_LOCAL_PREF | Get or set the preferred locator on the |
| | local side for the context associated with |
| | the socket. |
| SHIM_LOC_PEER_PREF | Get or set the preferred locator on the |
| | remote side for the context associated with |
| | the socket. |
| SHIM_LOCLIST_LOCAL | Get or set a list of locators associated |
| | with the local Endpoint Identifier (EID). |
| SHIM_LOCLIST_PEER | Get or set a list of locators associated |
| | with the peer's EID. |
| SHIM_LOC_LOCAL_SEND | Set or get the default source locator of |
| | outgoing IP packets. |
| SHIM_LOC_PEER_SEND | Set or get the default destination locator |
| | of outgoing IP packets. |
+---------------------+---------------------------------------------+
Table 3ok picture this 🎀 a connection-oriented app makes a HIP socket and sets SHIM_LOCLIST_PEER on it. the HIP module uses the first address in the option if you give it multiple ✨ and if the app gives one or more addresses in that SHIM_LOCLIST_PEER setsockopt call, the system should not connect to the host through some other destination address 🙈 bc the app might be trying to limit which addresses are allowed as a policy choice (rude of the system to go rogue, honestly 💀). if the app wants to override the default peer locator it can set SHIM_LOC_PEER_PREF 🌸 and then the app gives a specific HIT in the ship_hit field of the sockaddr_hip in the connect() call. if the system can't reach that HIT at any of the addresses given, the outbound sockets API functions (connect(), sendmsg(), etc.) return -1 and set errno to EINVALIDLOCATOR 😭
apps can also choose to attach local addresses to sockets, and in that case the procedures in [RFC6316] get followed 🦋
another vibe is opportunistic mode, when the destination HIT is a wildcard 👑 the app sets one or more destination addresses with SHIM_LOCLIST_PEER (like we just talked about), then calls connect() with the wildcard HIT. but if the app connects to a wildcard without giving any destination address, connect() returns -1 and sets errno to EADDRNOTAVAIL 💀 not it
datagram-oriented sockets can use ancillary data to control the locators too, and all the details are in [RFC6316] 💜
5. Summary of New Definitions ✨
okay here's the recap of all the new constants and structures in this doc, Table 4 🌈
+-----------------+-----------------------+
| Header | Definition |
+-----------------+-----------------------+
| <sys/socket.h> | AF_HIP |
| <sys/socket.h> | PF_HIP |
| <netinet/in.h> | IPPROTO_HIP |
| <netinet/hip.h> | HIP_HIT_ANY |
| <netinet/hip.h> | HIP_HIT_ANY_PUB |
| <netinet/hip.h> | HIP_HIT_ANY_TMP |
| <netinet/hip.h> | HIP_ENDPOINT_ANY |
| <netinet/hip.h> | HIP_HIT_PREFERENCES |
| <netinet/hip.h> | hip_hit_t |
| <netdb.h> | AI_NO_HIT |
| <netinet/hip.h> | sockaddr_hip |
| <netinet/hip.h> | sockaddr_is_srcaddr() |
| <netinet/hip.h> | hip_is_hit() |
+-----------------+-----------------------+
Table 46. Security Considerations 💀
this doc is an API for HIP, so it leans on whatever the HIP protocol suite does for security 🔒 the security concerns for HIP itself live in [RFC4423], [RFC4843], [RFC5201], [RFC5205], and [RFC5338] (go read those, they're the real tea 🍵)
real talk: HIP_ENDPOINT_ANY can be used to accept incoming data flows or create outgoing data flows without HIP 😳 so the app should use the sockaddr_is_srcaddr() function to check what kind of connection it's dealing with, so it can, for example, tell the user there's no HIP-based security going on. using the HIP_HIT_ANY_* constants is recommended in security-critical apps and systems 🛡️
the wildcards in this doc are NOT suitable for identifying end hosts 🚨 instead, apps should usegetsockname()andgetpeername()(see Section 4.3) to identify an end host. don't skip this one bestie
future proofing got talked about while designing this API 🔮 if HITs longer than 128 bits are needed at the application layer, that's going to need explicit support from the apps, bc they can store or cache HITs with their explicit sizes. to support longer HITs, future extensions of this API might define an extra flag for getaddrinfo() so it generates different kinds of socket address structures for HIP ✨
7. Contributors 🫶
big thanks to Jukka Ylitalo and Pekka Nikander for their original contributions, time, and effort on the native HIP APIs 👑 and to Yoshifuji Hideaki and Stefan Goetz for their contributions to this document 💖
8. Acknowledgments 🌸
Kristian Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti Jarvinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keranen, Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Joakim Koskela, Jeff Ahrenholz, Tobias Heer, and Gonzalo Camarillo have provided valuable ideas and feedback 🙌 thanks also to Nick Stoughton from the Austin group for POSIX-related comments 🧚 and to the APPS area folks, including Stephane Bortzmeyer, Chris Newman, Tony Finch, "der Mouse", and Keith Moore 💜
9. References 📚
9.1. Normative References
[POSIX]: "IEEE Std. 1003.1-2008 Standard for Information Technology -- Portable Operating System Interface (POSIX). Open group Technical Standard: Base Specifications, Issue 7", September 2008,<http://www.opengroup.org/austin>.[RFC3493]: Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. Stevens, "Basic Socket Interface Extensions for IPv6", RFC 3493, February 2003.[RFC4423]: Moskowitz, R. and P. Nikander, "Host Identity Protocol (HIP) Architecture", RFC 4423, May 2006.[RFC4843]: Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix for Overlay Routable Cryptographic Hash Identifiers (ORCHID)", RFC 4843, April 2007.[RFC5014]: Nordmark, E., Chakrabarti, S., and J. Laganier, "IPv6 Socket API for Source Address Selection", RFC 5014, September 2007.[RFC5201]: Moskowitz, R., Nikander, P., Jokela, P., Ed., and T. Henderson, "Host Identity Protocol", RFC 5201, April 2008.[RFC5205]: Nikander, P. and J. Laganier, "Host Identity Protocol (HIP) Domain Name System (DNS) Extensions", RFC 5205, April 2008.[RFC5338]: Henderson, T., Nikander, P., and M. Komu, "Using the Host Identity Protocol with Legacy Applications", RFC 5338, September 2008.[RFC6316]: Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto, Ed., "Sockets Application Program Interface (API) for Multihoming Shim", RFC 6316, July 2011.
9.2. Informative References
[RFC5533]: Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming Shim Protocol for IPv6", RFC 5533, June 2009.
Authors' Addresses 🎀
Miika Komu
Aalto University
Espoo
Finland
Phone: +358505734395
Fax: +358947025014
EMail: miika@iki.fi
URI: http://cse.aalto.fi/research/groups/datacommunications/people/
Thomas Henderson
The Boeing Company
P.O. Box 3707
Seattle, WA
USA
EMail: thomas.r.henderson@boeing.com📦 where this page comes from
- ietf: rfc6317 2011-07
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms