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."
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`
## Quick Start
- Uses the operating system trust store via `hyper-tls`/`native-tls`.
- Secure default for connecting to standard, publicly trusted endpoints.
- Optional: `rustls`
`cargo add hyper-custom-cert`
- 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).
- Optional: `insecure-dangerous`
### Basic Usage (Secure Default)
- 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.
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
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:**
```rust
- **No Custom Root CA Support:** Methods like `with_root_ca_pem()` and `with_root_ca_file()` may return `WasmNotImplemented` errors
usehyper_custom_cert::{HttpClient,ClientError};
- **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:**
matchclient.request("https://example.com").await{
```rust,ignore
Ok(_)=>println!("Request successful"),
#[cfg(target_arch = "wasm32")]
Err(ClientError::WasmNotImplemented)=>{
{
println!("This operation isn't supported in WASM");
// For browser WASM, rely on browser's built-in certificate validation
}
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()
letclient=HttpClient::builder()
.with_timeout(Duration::from_secs(10))
.insecure_accept_invalid_certs(true)// Only in debug builds
.build();
.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
## Testing
#[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")]
```bash
{
# Test with default features
// Try to use custom CA - this will work in edge runtimes
eprintln!("Custom CA configuration not supported in this WASM environment");
}
}
}
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:**
1. Fork the repository
- Leverage full TLS configuration capabilities available in your edge platform
2. Create a feature branch
- Use custom CAs and certificate pinning for enhanced security
3. Make your changes
- Test certificate handling across different edge runtime providers
4. Add tests for new functionality
- Consider platform-specific TLS optimizations
5. Ensure all tests pass: `cargo test --all-features`
6. Submit a pull request
**For Browser Applications:**
## License
- 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
## Security Notes
This project is licensed under either of:
- Prefer the default `native-tls` or the `rustls` feature for production.
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- The `insecure-dangerous` feature must never be enabled in production; it bypasses certificate validation and exposes you to active MITM risk.
- MIT License ([LICENSE-MIT](LICENSE-MIT))
- 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.
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
//! - A production-grade path to trust a custom Root CA by providing PEM bytes
//! - Clear security boundaries and feature flags
//! - 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
//! Note: Networking internals are intentionally abstracted for now; this crate
//! focuses on a robust and secure configuration API surfaced via a builder.
//! 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.
