### PASSWORD-ALGORITHMS Attribute

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Explains the PASSWORD-ALGORITHMS attribute used in STUN for specifying supported password derivation algorithms.

```APIDOC
## PASSWORD-ALGORITHMS Attribute

### Description
The PASSWORD-ALGORITHMS attribute may be present in requests and responses. It contains the list of algorithms that the server can use to derive the long-term password. The attribute contains a list of algorithm numbers and variable length parameters. The algorithm number is a 16-bit value. The parameters start with the length (prior to padding) of the parameters as a 16-bit value, followed by the parameters that are specific to each algorithm. The parameters are padded to a 32-bit boundary.

### Format
```
 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|         Algorithm 1           | Algorithm 1 Parameters Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                    Algorithm 1 Parameters (variable)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|         Algorithm 2           | Algorithm 2 Parameters Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                    Algorithm 2 Parameters (variable)
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                             ... 
```
```

--------------------------------

### ALTERNATE-SERVER Mechanism

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Details the mechanism for a STUN server to redirect a client to another server using the ALTERNATE-SERVER attribute and a 300 (Try Alternate) error response.

```APIDOC
## ALTERNATE-SERVER Mechanism

### Description
This mechanism allows a STUN server to redirect a client to an alternative server. This is achieved by responding to a request with a 300 (Try Alternate) error code, including one or more ALTERNATE-SERVER attributes.

### Server Behavior

*   To redirect a client, reply with an error response message.
*   The error code MUST be 300 (Try Alternate).
*   MUST include at least one ALTERNATE-SERVER attribute containing an IP address of the same address family as the request's source IP.
*   SHOULD include a second ALTERNATE-SERVER attribute with an IP address of a different address family.
*   The error response MAY be authenticated.
*   If TLS/DTLS is used, the transaction is authenticated with MESSAGE-INTEGRITY-SHA256, and redirection to a server with a different certificate is intended, an ALTERNATE-DOMAIN attribute MUST be included.

### Client Behavior

*   Upon receiving a 300 (Try Alternate) error code:
    *   Look for an ALTERNATE-SERVER attribute.
    *   If found, consider the current transaction failed.
    *   Reattempt the request with the server specified in the attribute, using the same transport protocol and credentials.
    *   If the transport uses TLS/DTLS, look for an ALTERNATE-DOMAIN attribute.
        *   If found, use the domain to validate the certificate (DNS-ID or CN-ID preferred).
        *   If not found, use the original request's domain for certificate validation.
    *   If the client has already sent the request to the target alternate server within the last five minutes, ignore the redirection to prevent loops and consider the transaction failed.

### Attributes

*   **ALTERNATE-SERVER** (IP Address): Specifies the IP address of an alternative server.
*   **ALTERNATE-DOMAIN** (Domain Name): Specifies a domain name for certificate validation when redirecting over TLS/DTLS.

### Request Example (Server Sending Redirection)

```json
{
  "type": "error",
  "error_code": 300,
  "attributes": [
    {
      "type": "ALTERNATE-SERVER",
      "value": "192.0.2.10"
    },
    {
      "type": "ALTERNATE-SERVER",
      "value": "::ffff:192.0.2.11"
    },
    {
      "type": "ALTERNATE-DOMAIN",
      "value": "example.com"
    }
  ]
}
```

### Response Example (Client Retrying Request)

*   The client would then construct a new request to `192.0.2.10` (or the other IP) with the original request details.
```

--------------------------------

### STUN URI Scheme Semantics

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Defines the behavior and resolution process for STUN and STUNS URIs, including handling of IP addresses, domain names, SRV records, and default ports.

```APIDOC
## STUN URI Scheme Semantics

### Description
This section details how STUN URIs are interpreted and resolved. It covers scenarios where the host part is an IP address versus a domain name, the use of SRV records for discovery, and default port assignments for various STUN transport protocols.

### Method
N/A (This is a descriptive documentation of a protocol scheme, not an API endpoint)

### Endpoint
N/A

### Parameters

#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response

#### Success Response (200)
N/A

#### Response Example
N/A

## STUN URI Scheme Semantics - Detailed Behavior

### Host Resolution
- **IP Address in Host**: If the `<host>` part of a "stun" URI contains an IP address, this IP address is used directly to contact the server. A "stuns" URI with an IP address MUST be rejected (unless future extensions relax this).
- **Domain Name in Host**: If the `<host>` part does not contain an IP address, the domain name is resolved using SRV procedures ([RFC2782]). The SRV service name is the `<scheme>` part ("stun" or "stuns"), and the protocol in the SRV lookup is "udp" or "tcp".

### SRV Record Procedures
- RFC 2782 procedures are followed for sorting and trying servers obtained via SRV records.
- If a STUN transaction times out without a response, the client SHOULD retry the request to the next server in the SRV order (applies to request/response, not indications).
- Dual-stack clients MUST query for both A and AAAA resource records and try all received IP addresses ([RFC8305]).

### Default Ports
- **STUN (UDP/TCP)**: Default port is 3478.
- **STUN over TLS/DTLS**: Default port is 5349.
- Servers can run STUN over DTLS on port 3478 (UDP) and STUN over TLS on port 3478 (TCP) if they can distinguish message types.
- Administrators SHOULD use these default ports in SRV records.

### Fallback to A/AAAA Records
- If no SRV records are found, clients perform A and AAAA record lookups for the domain name ([RFC8305]).
- For usages requiring TLS, the client connects to the resolved IP addresses using the default STUN over TLS port (5349).
- For usages requiring DTLS, the client connects using the default STUN over DTLS port (5349).

## Authentication and Message-Integrity Mechanisms Overview

### Description
This section outlines two optional mechanisms for STUN: short-term credential and long-term credential mechanisms, providing authentication and message integrity. These mechanisms are optional and usage-dependent.

### Mechanisms
- **Short-term credential mechanism**: Used in contexts like ICE connectivity checks.
- **Long-term credential mechanism**: Another mechanism for authentication.

### Processing
Each mechanism specifies additional processing steps when forming a message, receiving a message (after basic checks), and processing error responses.

### Attribute Handling
Agents MUST ignore all attributes that follow MESSAGE-INTEGRITY, except for MESSAGE-INTEGRITY-SHA256.
```

--------------------------------

### STUN Protocol Mechanisms

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Details on various mechanisms within the STUN protocol, including credential handling and alternate server strategies.

```APIDOC
## STUN Mechanisms Overview

This section covers key mechanisms used in the STUN protocol for establishing and maintaining network connections.

### 9.1. Receiving and Sending STUN Messages

*   **9.1.3. Receiving a Request or Indication**: Describes how a STUN server processes incoming requests or indications.
*   **9.1.4. Receiving a Response**: Details the process of receiving and interpreting responses from a STUN server.
*   **9.1.5. Sending Subsequent Requests**: Explains the procedure for clients to send follow-up requests.

### 9.2. Long-Term Credential Mechanism

*   **9.2.1. Bid-Down Attack Prevention**: Security measures to prevent specific types of attacks.
*   **9.2.2. HMAC Key**: Usage and management of Hash-based Message Authentication Code keys.
*   **9.2.3. Forming a Request**: How to construct STUN requests, including initial and subsequent requests.
    *   **9.2.3.1. First Request**: Specifics for the initial request in a session.
    *   **9.2.3.2. Subsequent Requests**: Procedures for requests after the first.
*   **9.2.4. Receiving a Request**: How servers handle incoming requests using long-term credentials.
*   **9.2.5. Receiving a Response**: Processing responses when long-term credentials are involved.

### 10. ALTERNATE-SERVER Mechanism

Details the mechanism for directing clients to an alternate server.
```

--------------------------------

### STUN Message Integrity - Sending Subsequent Requests

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Guidelines for STUN clients when sending subsequent requests to the same server, specifying which message integrity attributes should be included based on the initial response.

```APIDOC
## STUN Message Integrity - Sending Subsequent Requests

### Description
This section outlines the requirements for STUN clients when sending subsequent requests to a server after an initial authenticated response, ensuring consistent use of message integrity attributes.

### Method
N/A (Client-side processing)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Error Handling
N/A
```

--------------------------------

### Security Considerations

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Covers potential security threats and vulnerabilities related to the STUN protocol and its usage.

```APIDOC
## Security Considerations

This section details security aspects of the STUN protocol, including potential attacks and mitigation strategies.

### 16. Security Considerations

*   **16.1. Attacks against the Protocol**: Discusses attacks targeting the STUN protocol itself.
    *   **16.1.1. Outside Attacks**: External threats to the protocol.
    *   **16.1.2. Inside Attacks**: Threats originating from within the network.
    *   **16.1.3. Bid-Down Attacks**: Specific attacks related to credential negotiation.
*   **16.2. Attacks Affecting the Usage**: Covers attacks that exploit STUN's application in various scenarios.
    *   **16.2.1. Attack I: Distributed DoS (DDoS) against a Target**: How STUN can be misused for DDoS attacks.
    *   **16.2.2. Attack II: Silencing a Client**: Preventing a client from obtaining connectivity information.
    *   **16.2.3. Attack III: Assuming the Identity of a Client**: Impersonating a legitimate client.
    *   **16.2.4. Attack IV: Eavesdropping**: Intercepting STUN traffic.
*   **16.3. Hash Agility Plan**: Strategies for adapting to different hashing algorithms.
```

--------------------------------

### PASSWORD-ALGORITHM Attribute

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Describes the PASSWORD-ALGORITHM attribute, used in STUN requests to specify the key derivation algorithm.

```APIDOC
## PASSWORD-ALGORITHM Attribute

### Description
The PASSWORD-ALGORITHM attribute is present only in requests. It contains the algorithm that the server must use to derive a key from the long-term password. The attribute contains an algorithm number and variable length parameters. The algorithm number is a 16-bit value. The parameters start with the length (prior to padding) of the parameters as a 16-bit value, followed by the parameters that are specific to the algorithm. The parameters are padded to a 32-bit boundary.

### Format
```
 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
```

--------------------------------

### IANA Considerations

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Details the management of STUN protocol parameters by the Internet Assigned Numbers Authority (IANA).

```APIDOC
## IANA Considerations

This section outlines the registry management for STUN protocol elements by IANA.

### 18. IANA Considerations

*   **18.1. STUN Security Features Registry**: Management of security-related features.
*   **18.2. STUN Methods Registry**: Registration of STUN message methods.
*   **18.3. STUN Attributes Registry**: Registration of STUN attributes.
    *   **18.3.1. Updated Attributes**: Previously defined attributes.
    *   **18.3.2. New Attributes**: Newly added attributes.
*   **18.4. STUN Error Codes Registry**: Registration of STUN error codes.
*   **18.5. STUN Password Algorithms Registry**: Management of supported password algorithms.
    *   **18.5.1. Password Algorithms**: Specific algorithms and their details.
        *   **18.5.1.1. MD5**: Details regarding the MD5 algorithm.
        *   **18.5.1.2. SHA-256**: Details regarding the SHA-256 algorithm.
*   **18.6. STUN UDP and TCP Port Numbers**: Assignment of port numbers for STUN traffic.
```

--------------------------------

### STUN Attributes General Format

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Describes the general format of STUN attributes, which are Type-Length-Value (TLV) encoded and aligned on 32-bit boundaries.

```APIDOC
## STUN Attributes General Format

### Description
STUN attributes are encoded using a Type-Length-Value (TLV) format. Each attribute begins with a 16-bit type, followed by a 16-bit length, and then the variable-length value. Attributes must end on a 32-bit boundary, with padding bits set to zero if necessary.

### Method
N/A (Data Structure Definition)

### Endpoint
N/A (Data Structure Definition)

### Parameters
#### Type (16-bit)
- **Type** (unsigned short) - The type of the STUN attribute.
- Attributes are divided into two ranges: 0x0000 - 0x7FFF (comprehension-required) and 0x8000 - 0xFFFF (comprehension-optional).

#### Length (16-bit)
- **Length** (unsigned short) - The length of the Value part of the attribute in bytes (excluding padding).

#### Value (variable)
- **Value** (bytes) - The actual data content of the attribute. It is padded to the nearest 32-bit boundary.

### Request Example
```
// Conceptual representation of an attribute header
{
  "type": "0x0020", // Example Type
  "length": "0x0008", // Example Length
  "value": "...", // Attribute data
  "padding": "..." // Padding if needed
}
```

### Response
#### Success Response (200)
N/A (Data Structure Definition)

#### Response Example
```
// Conceptual representation of an attribute structure
{
  "attribute": {
    "type": "0x0020",
    "length": "0x0008",
    "value": "..."
  }
}
```
```

--------------------------------

### NONCE Attribute

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Details the NONCE attribute, used in STUN requests and responses for authentication.

```APIDOC
## NONCE Attribute

### Description
The NONCE attribute may be present in requests and responses. It contains a sequence of qdtext or quoted-pair, which are defined in [RFC3261]. The NONCE attribute MUST be fewer than 128 characters. See Section 5.4 of [RFC7616] for guidance on selection of nonce values in a server.
```

--------------------------------

### REALM Attribute

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Describes the REALM attribute, used in STUN requests and responses for authentication purposes.

```APIDOC
## REALM Attribute

### Description
The REALM attribute may be present in requests and responses. It contains text that meets the grammar for "realm-value" as described in [RFC3261] but without the double quotes and their surrounding whitespace. It MUST be a UTF-8-encoded [RFC3629] sequence of fewer than 128 characters and MUST have been processed using the OpaqueString profile [RFC8265].

Presence of the REALM attribute in a request indicates that long-term credentials are being used for authentication. Presence in certain error responses indicates that the server wishes the client to use a long-term credential in that realm for authentication.
```

--------------------------------

### STUN Error Codes

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Details the meaning of specific error codes returned by the STUN server.

```APIDOC
## STUN Error Codes

### Description
This section outlines specific error codes that a STUN server may return to a client, indicating the nature of the error encountered.

### Error Codes

- **420 Unknown Attribute**: The server received a STUN packet containing a comprehension-required attribute that it did not understand. The server MUST put this unknown attribute in the UNKNOWN-ATTRIBUTE attribute of its error response.
- **438 Stale Nonce**: The NONCE used by the client was no longer valid. The client should retry, using the NONCE provided in the response.
- **500 Server Error**: The server has suffered a temporary error. The client should try again.
```

--------------------------------

### C Macros for STUN Message Type Determination

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Provides C preprocessor macros to easily determine the type of a STUN message (Request, Indication, Success Response, Error Response) based on its 16-bit type value. This is useful for parsing and handling STUN messages in C applications.

```c
#define IS_REQUEST(msg_type)       (((msg_type) & 0x0110) == 0x0000)
#define IS_INDICATION(msg_type)    (((msg_type) & 0x0110) == 0x0010)
#define IS_SUCCESS_RESP(msg_type)  (((msg_type) & 0x0110) == 0x0100)
#define IS_ERR_RESP(msg_type)      (((msg_type) & 0x0110) == 0x0110)
```

--------------------------------

### Message Integrity and Authentication

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Details on how STUN messages handle integrity and authentication using MESSAGE-INTEGRITY and MESSAGE-INTEGRITY-SHA256 attributes. Explains client and server behavior upon receiving responses with or without these attributes, and over reliable vs. unreliable transports.

```APIDOC
## Message Integrity and Authentication

### Description
This section outlines the process for ensuring message integrity and authenticating STUN responses. It covers the use of MESSAGE-INTEGRITY and MESSAGE-INTEGRITY-SHA256 attributes and how clients and servers should handle responses based on their presence and the transport protocol.

### Authentication Handling

*   **Client Behavior**: 
    *   Looks for MESSAGE-INTEGRITY or MESSAGE-INTEGRITY-SHA256 attribute in the response.
    *   Computes message integrity using the same password as the request.
    *   If computed value matches the attribute, the response is authenticated.
    *   If values do not match, or attributes are absent, behavior depends on transport.

*   **Server Behavior**: 
    *   If MESSAGE-INTEGRITY-SHA256 is present in a request, the response MUST be discarded if the attribute is invalid.
    *   If a PASSWORD-ALGORITHMS attribute is present, subsequent requests MUST use MESSAGE-INTEGRITY-SHA256.

### Transport Protocol Impact

*   **Unreliable Transport**: 
    *   If message integrity check fails or attributes are absent, the response MUST be discarded.
    *   If all responses are discarded, signal "integrity protection violated" instead of a timeout.

*   **Reliable Transport**: 
    *   If message integrity check fails or attributes are absent, the response MUST be discarded.
    *   Immediately end the transaction and signal "integrity protection violated."

### Response Examples (Conceptual)

*   **Success Response with Integrity**: 
    ```json
    {
      "type": "success",
      "attributes": [
        {
          "type": "MESSAGE-INTEGRITY-SHA256",
          "value": "<computed_hash>"
        }
      ]
    }
    ```
*   **Failure Response without Integrity**: 
    ```json
    {
      "type": "error",
      "error_code": 400,
      "attributes": []
    }
    ```
```

--------------------------------

### XOR-MAPPED-ADDRESS Attribute

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Describes the XOR-MAPPED-ADDRESS attribute used in STUN messages. It's an alternative to MAPPED-ADDRESS that helps mitigate issues with Network Address Translators (NATs) that modify binary payloads.

```APIDOC
## XOR-MAPPED-ADDRESS Attribute

### Description
The XOR-MAPPED-ADDRESS attribute is used to represent a transport address (IP address and port). It differs from the MAPPED-ADDRESS attribute by XORing the address components with a magic cookie or a combination of the magic cookie and transaction ID, which helps prevent interference from certain NAT devices.

### Attribute Format
```
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |0 0 0 0 0 0 0 0|    Family     |         X-Port                |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                X-Address (Variable)
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```

### Fields
*   **Family (8 bits)**: Encodes the IP address family (e.g., IPv4, IPv6). Identical to the Family field in MAPPED-ADDRESS.
*   **X-Port (16 bits)**: The mapped port XORed with the most significant 16 bits of the magic cookie.
*   **X-Address (Variable)**: The mapped IP address XORed with the magic cookie (for IPv4) or the concatenation of the magic cookie and the 96-bit transaction ID (for IPv6). The XOR operation is performed in network byte order.

### Encoding and Processing Rules
*   The first 8 bits of the attribute's value are handled identically to MAPPED-ADDRESS.
*   Rules for handling multiple occurrences of the attribute are the same as for MAPPED-ADDRESS.
*   Processing rules for address families are the same as for MAPPED-ADDRESS.

### Comparison with MAPPED-ADDRESS
*   **XOR-MAPPED-ADDRESS**: Encodes the transport address by XORing it with the magic cookie.
*   **MAPPED-ADDRESS**: Encodes the transport address directly in binary.

This difference is crucial because some NATs implement Application Layer Gateway (ALG) functions that can interfere with or corrupt the binary payload of MAPPED-ADDRESS, impacting STUN operations and message integrity checks. XOR-MAPPED-ADDRESS mitigates this by using XOR, making the address less susceptible to unintentional modification by ALGs.
```

--------------------------------

### STUN Attributes

Source: https://datatracker.ietf.org/doc/html/rfc8489/index

Defines the various attributes that can be included in STUN messages, each serving a specific purpose.

```APIDOC
## STUN Attributes Registry

STUN messages utilize a set of attributes to convey specific information between clients and servers. The following are defined in RFC 8489:

### 14. STUN Attributes

*   **14.1. MAPPED-ADDRESS**: Indicates the mapped IP address and port of the client.
*   **14.2. XOR-MAPPED-ADDRESS**: An XORed version of the mapped address, providing greater security.
*   **14.3. USERNAME**: Contains the username for authentication.
*   **14.4. USERHASH**: A hash of the username, used in certain authentication flows.
*   **14.5. MESSAGE-INTEGRITY**: Ensures the integrity of the message using HMAC.
*   **14.6. MESSAGE-INTEGRITY-SHA256**: Uses SHA-256 for message integrity.
*   **14.7. FINGERPRINT**: Provides a checksum for the STUN message header.
*   **14.8. ERROR-CODE**: Carries error information when a request fails.
*   **14.9. REALM**: Specifies the authentication realm.
*   **14.10. NONCE**: A random value used in authentication challenges.
*   **14.11. PASSWORD-ALGORITHMS**: Lists supported password algorithms for authentication.
*   **14.12. PASSWORD-ALGORITHM**: Specifies the password algorithm being used.
*   **14.13. UNKNOWN-ATTRIBUTES**: Indicates attributes in a request that the server does not understand.
*   **14.14. SOFTWARE**: Identifies the STUN software used by the client or server.
*   **14.15. ALTERNATE-SERVER**: Suggests an alternative server to the client.
*   **14.16. ALTERNATE-DOMAIN**: Provides an alternative domain for server discovery.
```