About Jargyle

Introduction

Jargyle is a Java SOCKS5 server and API designed to be both flexible and powerful. It allows you to create SOCKS5 proxies, integrate SOCKS5 functionality into your Java applications, and manage network traffic with fine-grained control. Inspired by projects like JSocks, SocksLib, Esocks, and Dante, Jargyle aims to provide a modern and robust solution for SOCKS5 in Java.

Project Status

Jargyle is still a work in progress and is not yet production-ready. Here’s why:

• Testing: Comprehensive unit and integration tests are still under development. This means that while the project is functional, it is not yet fully tested for all use cases and edge cases.

• Documentation: The Javadocs and reference documentation are incomplete. The user guide provides basic usage examples, but some advanced features may lack detailed explanations.

Warning: Breaking changes may occur as the project evolves. However, any existing documentation will be updated to reflect these changes.

Key Concepts

Before diving into the features and examples, it's important to understand the core concepts behind Jargyle:

• SOCKS5: A network protocol that allows clients to connect to servers through a proxy server. SOCKS5 provides advantages like firewall traversal and anonymity.

• SOCKS Server: Accepts connections from clients, forwards their requests to the destination server, and relays the responses back.

• SOCKS Client API: Allows Java applications to act as SOCKS clients, routing their network traffic through a SOCKS server.

• Proxy Chaining: Routes traffic through multiple SOCKS servers, creating a chain of proxies.

• SSL/TLS and DTLS: Encrypts traffic between clients and the SOCKS server (SSL/TLS for TCP, DTLS for UDP) for enhanced security.

• Authentication Methods: SOCKS5 supports different authentication methods, including no authentication, username/password, and GSS-API.

Features

Uses

• Enhancing SOCKS Support: Use Jargyle to provide advanced SOCKS features (e.g., authentication, proxy chaining) to applications that only have basic SOCKS support.

• Secure Tunneling: Encrypt your network traffic using SSL/TLS or DTLS.

• Circumventing Restrictions: Bypass firewalls and geo-restrictions.

• Testing and Development: Simulate different network conditions and test SOCKS5 client/server implementations.

• Adding SOCKS5 Support to Applications: Integrate the SOCKS client API into your Java applications to route traffic through a SOCKS server.

Examples

The following examples demonstrate how to use Jargyle's command-line interface and APIs.

# Start a SOCKS server on port 8080 with username/password authentication
jargyle start-server \
    --setting=port=8080 \
    --setting=socks5.methods=USERNAME_PASSWORD \
    --setting=socks5.userpassmethod.userRepository=StringSourceUserRepository:Aladdin:opensesame

# Start a SOCKS server that chains to another SOCKS server
jargyle start-server \
    --setting=chaining.socksServerUri=socks5://upstream-proxy.example.com:1080

// Example: Start a basic SOCKS server programmatically

package com.example;

import com.github.jh3nd3rs0n.jargyle.server.Configuration;
import com.github.jh3nd3rs0n.jargyle.server.Setting;
import com.github.jh3nd3rs0n.jargyle.server.Settings;
import com.github.jh3nd3rs0n.jargyle.server.SocksServer;

import java.io.IOException;

public class ServerApp {
    public static void main(String[] args) throws IOException {
        SocksServer server = new SocksServer(Configuration.newUnmodifiableInstance(Settings.of(
                Setting.newInstanceWithParsedValue("port", "1080")
        ))).start();
    }
}

// Example: Configure a SOCKS client to connect to a SOCKS server

package com.example;

import com.github.jh3nd3rs0n.jargyle.client.NetObjectFactory;

import java.io.IOException;

import java.net.Socket;

public class ClientApp {
    public static void main(String[] args) throws IOException {
        System.setProperty("socksClient.socksServerUri", "socks5://127.0.0.1:1080");
        NetObjectFactory netObjectFactory = NetObjectFactory.newInstance();
        Socket socket = netObjectFactory.newSocket("google.com", 80);
        // ...
    }
}

Get Started

1. Download: Download the latest release of Jargyle from Releases.

2. Explore:

   • User Guide: Learn how to use Jargyle with the user guide.

   • API Reference (Incomplete): Explore the API documentation in the reference documentation. (Note: This documentation is currently incomplete.)

   • JavaDocs (Incomplete): Browse the JavaDocs here. (Note: These JavaDocs are currently incomplete.)

3. Feedback Welcome!: If you encounter any issues or have suggestions, please open an issue on GitHub. Your feedback will help improve Jargyle!

License

Jargyle is licensed under the MIT license. You are free to use, modify, and distribute Jargyle in accordance with the terms of this license. See the full license text here.