description="A small, ergonomic HTTP client wrapper around hyper with optional support for custom Root CAs and a dev-only insecure mode for self-signed certificates."
A reusable HTTP client builder API with clear, security‑focused feature flags for selecting your TLS backend and security posture.
A small, ergonomic HTTP client wrapper around hyper with optional support for custom Root CAs and a dev-only insecure mode for self-signed certificates.
This crate is derived from a reference implementation in this repository (under `reference-implementation/`), but is designed as a reusable library with a more robust and explicit configuration surface. Networking internals are intentionally abstracted for now; the focus is on a secure, ergonomic API.
## Features
## Features and TLS strategy
- **Secure by Default**: Uses the operating system's native trust store via `native-tls`
- **Custom CA Support**: Optional `rustls` feature for connecting to services with custom Certificate Authorities
- **Development Mode**: Optional `insecure-dangerous` feature for testing with self-signed certificates (⚠️ **NEVER use in production**)
- **WebAssembly Compatible**: Proper WASM support with appropriate security constraints
- **Certificate Pinning**: Advanced security feature for production environments
- **Builder Pattern**: Ergonomic configuration with sensible defaults
- Default: `native-tls`
- Uses the operating system trust store via `hyper-tls`/`native-tls`.
- Secure default for connecting to standard, publicly trusted endpoints.
## Quick Start
- Optional: `rustls`
- Uses `hyper-rustls`.
- Activates the `with_root_ca_pem` method on the builder, allowing you to trust a custom Root CA (recommended approach for custom/private CAs).
`cargo add hyper-custom-cert`
- Optional: `insecure-dangerous`
- Unlocks `insecure_accept_invalid_certs(true)` and `HttpClient::with_self_signed_certs()`.
- IMPORTANT: This is for local development/testing only and must NEVER be used in production.
### Basic Usage (Secure Default)
See SECURITY.md for a thorough discussion of these modes and when to use them.
- With native TLS: `cargo build --features insecure-dangerous`
- With rustls: `cargo build --no-default-features --features rustls,insecure-dangerous`
## WASM Support
This library's WASM build is **primarily intended for edge runtime environments** such as Cloudflare Workers, Deno Deploy, Vercel Edge Functions, and similar serverless edge computing platforms.
### Edge Runtime Usage (Primary Use Case)
Edge runtimes provide a more capable WASM environment compared to browsers, often supporting custom certificate configuration and advanced TLS features:
**Capabilities in Edge Runtimes:**
- **Custom Root CA Support:** Methods like `with_root_ca_pem()` and `with_root_ca_file()` are typically supported
- **Certificate Pinning:** The `with_pinned_cert_sha256()` method may be available depending on the runtime
- **Flexible TLS Configuration:** Full control over certificate validation and TLS settings
- **No Same-Origin Policy:** Direct network access without browser security restrictions
**Recommended Approach for Edge Runtimes:**
```rust,ignore
#[cfg(target_arch = "wasm32")]
{
// For edge runtimes, full custom CA support is typically available
- Custom Root CA installation requires browser/OS-level certificate management
- Some TLS configuration options may not be available
- Certificate pinning may be limited by browser security policies
### Browser Usage (Limited Support)
**Browser Certificate Installation:**
1. Download your organization's Root CA certificate
2. Install it in your browser's certificate store
3. Mark it as trusted for websites
4. Your WASM application will then trust endpoints signed by that CA
When running in browser environments, WASM operates under significant security restrictions:
## Error Handling
**Browser Limitations:**
- **No Custom Root CA Support:** Methods like `with_root_ca_pem()` and `with_root_ca_file()` may return `WasmNotImplemented` errors
- **No Certificate Pinning:** The `with_pinned_cert_sha256()` method is not available in browser environments
- **Browser-Controlled Trust:** All certificate validation is handled by the browser's built-in certificate store
- **Same-Origin Policy:** Cross-origin requests are subject to CORS policies and browser security models
```rust
usehyper_custom_cert::{HttpClient,ClientError};
**Browser Development Guidance:**
```rust,ignore
#[cfg(target_arch = "wasm32")]
{
// For browser WASM, rely on browser's built-in certificate validation
matchclient.request("https://example.com").await{
Ok(_)=>println!("Request successful"),
Err(ClientError::WasmNotImplemented)=>{
println!("This operation isn't supported in WASM");
}
Err(e)=>{
println!("Request failed: {}",e);
}
}
```
## Security Best Practices
### Production Recommendations
1.**Use Default Mode**: Stick with `native-tls` for public endpoints
2.**Custom CA Only When Needed**: Only use `rustls` feature when connecting to private CAs
3.**Never Use `insecure-dangerous`**: This feature should never be enabled in production
4.**Keep Dependencies Updated**: Monitor for security advisories
5.**Certificate Pinning**: Consider pinning for high-security applications
### Development vs Production
```rust
// ✅ GOOD: Production configuration
#[cfg(not(debug_assertions))]
letclient=HttpClient::new();// Uses OS trust store
// ✅ GOOD: Development configuration
#[cfg(debug_assertions)]
letclient=HttpClient::builder()
.with_timeout(Duration::from_secs(10))
.insecure_accept_invalid_certs(true)// Only in debug builds
.build();
}
```
For development with self-signed certificates in browsers, you'll need to install certificates in the browser's certificate store rather than configuring them programmatically.
## Examples
### Environment Detection
See the `examples/` directory for complete working examples:
To handle both edge runtime and browser environments gracefully:
-`examples/self-signed-certs/` - Comprehensive examples for all modes
- Example of connecting to public endpoints (default mode)
- Example of using custom Root CA for private services
- Example of development mode with self-signed certificates
```rust,ignore
#[cfg(target_arch = "wasm32")]
{
// Attempt edge runtime configuration, fall back to basic setup
let mut builder = HttpClient::builder()
.with_timeout(Duration::from_secs(10));
## Testing
#[cfg(feature = "rustls")]
{
// Try to use custom CA - this will work in edge runtimes
eprintln!("Custom CA configuration not supported in this WASM environment");
}
}
}
```bash
# Test with default features
cargo test
let client = builder.build();
}
# Test with rustls features
cargo test --features rustls
# Test with all features (for development)
cargo test --features rustls,insecure-dangerous
# Test WASM compatibility
cargo test --target wasm32-unknown-unknown
```
### Production Considerations
## Contributing
**For Edge Runtimes:**
- Leverage full TLS configuration capabilities available in your edge platform
- Use custom CAs and certificate pinning for enhanced security
- Test certificate handling across different edge runtime providers
- Consider platform-specific TLS optimizations
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass: `cargo test --all-features`
6. Submit a pull request
**For Browser Applications:**
- Always use proper SSL/TLS certificates from trusted CAs
- Consider using Let's Encrypt or other automated certificate management solutions
- Document any certificate requirements clearly for end users
- Plan for browser security policy limitations
## License
## Security Notes
This project is licensed under either of:
- Prefer the default `native-tls` or the `rustls` feature for production.
- The `insecure-dangerous` feature must never be enabled in production; it bypasses certificate validation and exposes you to active MITM risk.
- On WASM platforms, certificate handling varies by environment: edge runtimes typically support full custom CA configuration, while browser environments manage certificate validation through built-in certificate stores.
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT License ([LICENSE-MIT](LICENSE-MIT))
at your option.
## Security Policy
For security vulnerabilities, please see [SECURITY.md](SECURITY.md) for our responsible disclosure policy.
---
**Remember**: This library prioritizes security by default. The `insecure-dangerous` feature exists solely for development convenience and should never be used in production environments.
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
