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`
```rust
usehyper_custom_cert::{HttpClient,ClientError};
## 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
When running in browser environments, WASM operates under significant security restrictions:
**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
**Browser Development Guidance:**
```rust,ignore
#[cfg(target_arch = "wasm32")]
{
// For browser WASM, rely on browser's built-in certificate validation
let client = HttpClient::builder()
.with_timeout(Duration::from_secs(10))
.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.
### Environment Detection
To handle both edge runtime and browser environments gracefully:
```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));
#[cfg(feature = "rustls")]
{
// Try to use custom CA - this will work in edge runtimes
eprintln!("Custom CA configuration not supported in this WASM environment");
}
}
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);
}
let client = builder.build();
}
```
### Production Considerations
## Security Best Practices
**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
### Production Recommendations
**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
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
## Security Notes
### Development vs Production
- 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.
```rust
// ✅ GOOD: Production configuration
#[cfg(not(debug_assertions))]
letclient=HttpClient::new();// Uses OS trust store
// ✅ GOOD: Development configuration
#[cfg(debug_assertions)]
letclient=HttpClient::builder()
.insecure_accept_invalid_certs(true)// Only in debug builds
.build();
```
## Examples
See the `examples/` directory for complete working examples:
-`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
## Testing
```bash
# Test with default features
cargo test
# 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
```
## Contributing
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
## License
This project is licensed under either of:
- 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.
//! - A production-grade path to trust a custom Root CA by providing PEM bytes
//! - Clear security boundaries and feature flags
//!
//! This crate is derived from a reference implementation located under
//! `reference-implementation/hyper-custom-cert` in this repository. The reference
//! implementation remains unchanged and serves as inspiration and verification.
//!
//! Note: Networking internals are intentionally abstracted for now; this crate
//! focuses on a robust and secure configuration API surfaced via a builder.
//!
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.
