> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/proxies/residential-proxies/protocols.md).

# Protocols

Explore supported Residential Proxy protocols and learn how to configure HTTP, HTTPS, HTTPS/3 (MASQUE), and SOCKS5 connections.

## HTTP

Our documentation includes code examples showcasing how to connect to the proxies using `HTTP` protocol. The protocol is supported by common libraries and third-party software.

## HTTPS

You can also use the fully encrypted `HTTP` connection using `HTTPS` protocol for an extra layer of security. For that, you have to add `https://` to your proxy entry point. For example: `https://pr.oxylabs.io:7777` (this also applies to country-specific entry nodes).

Please note that some libraries (or their older versions) and some 3rd party tools may not support `HTTPS` protocol, so double-check before making changes to your code.

## **HTTP/3 (MASQUE)**

{% hint style="warning" %}
**Note:** `Google` is a restricted target to use with `UDP` connection.
{% endhint %}

Oxylabs Residential Proxies support native `UDP` and `HTTP/3` tunneling via MASQUE ([RFC 9298 CONNECT-UDP](https://www.rfc-editor.org/rfc/rfc9298.html)).

Traditional proxies force traffic through `TCP` connections (via `HTTP CONNECT` or `SOCKS5`), causing `HTTP/3` requests to downgrade to `HTTP/1.1` or `HTTP/2`. MASQUE maintains an end-to-end `QUIC` connection through our residential exit nodes, allowing your client to transmit native `UDP` traffic directly to modern target destinations.

The MASQUE service runs over `QUIC` on a dedicated `UDP` port:

```
masque.oxylabs.io:50000
```

{% hint style="info" %}
**Note:** Ensure your firewall allows outbound `UDP` traffic on port `50000`.
{% endhint %}

### Use cases <a href="#use-cases" id="use-cases"></a>

* **Native HTTP/3 Web Scraping:** Scrape modern target websites without triggering protocol downgrade flags.
* **DNS Resolution over UDP:** Execute direct DNS queries (`53/udp`) via residential IPs.
* **Real-Time UDP Protocols:** Route WebRTC, SIP, or gaming traffic requiring true UDP connection.

{% hint style="info" %}
**Note:** If your scraping application only needs standard `HTTP` or `HTTPS` (`TCP`) connections, use our main backconnect endpoint (`pr.oxylabs.io:7777`). MASQUE introduces `QUIC` connection setup overhead that is only necessary when you require `UDP` or native `HTTP/3` transport.
{% endhint %}

### MASQUE setup <a href="#masque-setup" id="masque-setup"></a>

**For full setup, configuration, authentication details, see the technical setup guide below.**

<details>

<summary><strong>MASQUE Setup &#x26; Configuration</strong></summary>

<table data-header-hidden><thead><tr><th width="164"></th><th width="218"></th><th></th></tr></thead><tbody><tr><td><strong>Proxy endpoint</strong></td><td><code>masque.oxylabs.io:50000</code></td><td>Dedicated QUIC entry node</td></tr><tr><td><strong>Transport</strong></td><td><code>HTTP/3</code> over <code>QUIC</code></td><td>Uses UDP port <code>50000</code></td></tr><tr><td><strong>ALPN</strong></td><td><code>h3</code></td><td>Application-Layer Protocol Negotiation string</td></tr><tr><td><strong>Datagram support</strong></td><td><code>EnableDatagrams: true</code></td><td>Must be enabled in your client's QUIC setup</td></tr><tr><td><strong>Max datagram size</strong></td><td><code>1500</code> bytes</td><td>Datagrams exceeding 1500 bytes are dropped by the proxy</td></tr><tr><td><strong>TLS verification</strong></td><td>Standard Public CA</td><td>No custom CA certificates or overrides required</td></tr></tbody></table>

### Endpoint configuration & URI formats <a href="#endpoint-configuration-and-uri-formats" id="endpoint-configuration-and-uri-formats"></a>

To establish a tunnel, your client sends a `CONNECT` request with `:protocol = connect-udp` to the proxy listener:

* **RFC 9298 Standard (Recommended):** `https://masque.oxylabs.io:50000/.well-known/masque/udp/{target_host}/{target_port}/`
* **Legacy Query Format:** `https://masque.oxylabs.io:50000/masque?h={target_host}&p={target_port}`

**Hostnames & IPs:** The proxy resolves hostnames on your behalf through the residential exit node. You can pass domain names (`example.com`) or IP addresses (`1.2.3.4`). IPv6 addresses must be percent-encoded (e.g., `2001%3Adb8%3A%3A1`).

### Authentication <a href="#authentication" id="authentication"></a>

Authentication is handled via standard **HTTP Basic authentication** using the `Proxy-Authorization` header sent on the `CONNECT-UDP` request:

```bash
Proxy-Authorization: Basic Base64(customer-USERNAME[-key-value]:PASSWORD)
```

You use your standard Oxylabs proxy credentials. [Location settings](/products/proxies/residential-proxies/location-settings.md) and [session parameters](/products/proxies/residential-proxies/session-control.md) function identically to standard `HTTP/HTTPS` proxies. For example:

```bash
Proxy-Authorization: Basic customer-myuser-cc-us-sessid-abc123:PASSWORD
```

### Nested QUIC & packet size <a href="#nested-quic-and-packet-size" id="nested-quic-and-packet-size"></a>

When using HTTP/3 through MASQUE, a second QUIC stack runs over the proxy tunnel (*nested QUIC)*. The outer connection (*client-to-proxy*) wraps inner connection packets (*client-to-target*), adding *\~*&#x34;0 bytes of protocol framing overhead.

{% hint style="danger" %}
You must manually configure packet sizes and disable Path MTU Discovery (PMTUD) on both client QUIC stacks. If skipped, the initial inner handshake packet will exceed outer datagram limits and be silently dropped by the proxy, causing the connection to hang indefinitely.
{% endhint %}

To set up your connection correctly, adjust the following:

1. **Disable PMTUD:** Turn off Path MTU Discovery on both outer and inner QUIC connections to enforce fixed packet limits.
2. **Outer QUIC (Client-to-Proxy):** Set initial/maximum packet size to `1392` bytes.
3. **Inner QUIC (Client-to-Target):** Set initial/maximum packet size to `1352` bytes.

{% hint style="info" %}
The \~40-byte difference supports outer QUIC headers, AEAD encryption tags, DATAGRAM frame headers, HTTP-datagram framing under RFC 9297, and CONNECT-UDP context IDs under RFC 9298.
{% endhint %}

### Response status codes <a href="#response-status-codes" id="response-status-codes"></a>

<table><thead><tr><th width="80">Code</th><th width="260">Status</th><th>Description</th></tr></thead><tbody><tr><td><code>200</code></td><td><code>OK</code></td><td>Tunnel established. UDP datagrams can now flow on the request stream.</td></tr><tr><td><code>400</code></td><td><code>Bad Request</code></td><td>Malformed target URI or invalid request parameters.</td></tr><tr><td><code>407</code></td><td><code>Proxy Authentication Required</code></td><td>Authentication failed or account traffic limit reached.</td></tr></tbody></table>

</details>

## **SOCKS5**

{% hint style="warning" %}

* `SOCKS5` proxy authentication is not supported by Google Chrome. Use Mozilla Firefox or HTTP clients instead.
* Certain target websites can identify proxy traffic using `SOCKS5`. If you encounter connection errors, switch to `HTTP` or `HTTPS`.
* `Google` is a restricted target to use with `UDP` connection.
  {% endhint %}

Oxylabs Residential Proxies support `SOCKS5` connections over `TCP` and `UDP`. For optimal `UDP` tunneling and `HTTP/3` support, we recommend using [MASQUE](/products/proxies/residential-proxies/protocols.md#http-3-masque)).

For a `SOCKS5` connection, use `socks5h://` with your connection string:

```bash
curl -x socks5h://pr.oxylabs.io:7777 -U "customer-USERNAME:PASSWORD" ip.oxylabs.io/location
```

`SOCKS5` does not support country-specific entry point domains. To target a specific location, include the [additional parameters](/products/proxies/residential-proxies/making-requests.md) within your username (e.g., France):

```bash
curl -x socks5h://pr.oxylabs.io:7777 -U "customer-USERNAME-cc-FR:PASSWORD" ip.oxylabs.io/location
```

## Ports of proxies

The default configuration of proxy ports includes `80` and `443`, designed to accommodate standard `HTTP` and `HTTPS` protocols. `HTTP/3 (MASQUE)` operates on UDP port `50000`. To access other ports, it is necessary to undergo compliance verification, please contact our [**support**](mailto:support@oxylabs.io).

| Protocol          | Transport | Port    |
| ----------------- | --------- | ------- |
| `HTTP`            | TCP       | `80`    |
| `HTTPS`           | TCP       | `443`   |
| `HTTP/3 (MASQUE)` | UDP       | `50000` |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/proxies/residential-proxies/protocols.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.