201d046de3
- Updated Makefile to include generation of documentation for the entire project. - Expanded the documentation in common/DOC.md to include detailed descriptions of signature types and their recommendations for use. - Added new functions for creating sessions from existing subsessions across various modules (datagram, primary, raw, stream) to streamline session management. - Introduced new session creation functions that allow specifying custom signature types and port configurations for enhanced security and compatibility. - Improved examples and usage notes throughout the documentation to clarify session management and options.
41 KiB
sam3
-- import "github.com/go-i2p/go-sam-go"
Package sam3 provides configuration wrapper functions for exposing common package configuration functionality at the root level. This file implements wrapper functions for SAMEmit options and I2PConfig creation that enable applications to configure I2P tunnel parameters and session behaviors through a clean, sam3-compatible API.
Package sam provides a pure-Go implementation of SAMv3.3 (Simple Anonymous Messaging) for I2P networks. This is the root package wrapper that provides sam3-compatible API surface while delegating implementation details to specialized sub-packages.
Package sam provides a pure-Go implementation of SAMv3.3 for I2P networks. This file implements the main wrapper functions that delegate to sub-package implementations while providing the sam3-compatible API surface at the root package level.
Package sam provides type aliases and wrappers for exposing sub-package types at the root level. This file implements the sam3-compatible API surface by creating type aliases that delegate to the appropriate sub-package implementations while maintaining a clean public interface.
Usage
const (
// Sig_NONE is deprecated, use Sig_EdDSA_SHA512_Ed25519 instead for secure signatures.
Sig_NONE = "SIGNATURE_TYPE=EdDSA_SHA512_Ed25519"
// Sig_DSA_SHA1 specifies DSA with SHA1 signature type (legacy, not recommended for new applications).
Sig_DSA_SHA1 = "SIGNATURE_TYPE=DSA_SHA1"
// Sig_ECDSA_SHA256_P256 specifies ECDSA with SHA256 on P256 curve signature type.
Sig_ECDSA_SHA256_P256 = "SIGNATURE_TYPE=ECDSA_SHA256_P256"
// Sig_ECDSA_SHA384_P384 specifies ECDSA with SHA384 on P384 curve signature type.
Sig_ECDSA_SHA384_P384 = "SIGNATURE_TYPE=ECDSA_SHA384_P384"
// Sig_ECDSA_SHA512_P521 specifies ECDSA with SHA512 on P521 curve signature type.
Sig_ECDSA_SHA512_P521 = "SIGNATURE_TYPE=ECDSA_SHA512_P521"
// Sig_EdDSA_SHA512_Ed25519 specifies EdDSA with SHA512 on Ed25519 curve signature type (recommended).
Sig_EdDSA_SHA512_Ed25519 = "SIGNATURE_TYPE=EdDSA_SHA512_Ed25519"
// Sig_DEFAULT points to the recommended secure signature type for new applications.
Sig_DEFAULT = Sig_EdDSA_SHA512_Ed25519
)
Signature type constants for I2P destination key generation. These specify the cryptographic signature algorithm used for I2P destinations. SIG_DEFAULT points to the recommended secure signature type for new applications.
var (
// Options_Humongous provides maximum anonymity and redundancy for extremely high-value traffic.
// Suitable for applications requiring the highest level of anonymity protection with significant
// resource overhead. Uses 3-hop tunnels with high redundancy and parallel connections.
Options_Humongous = []string{
"inbound.length=3", "outbound.length=3",
"inbound.lengthVariance=1", "outbound.lengthVariance=1",
"inbound.backupQuantity=3", "outbound.backupQuantity=3",
"inbound.quantity=6", "outbound.quantity=6",
}
// Options_Large provides strong anonymity for high-traffic applications.
// Suitable for applications shuffling large amounts of traffic with good anonymity protection.
// Balances performance and anonymity with reasonable resource usage.
Options_Large = []string{
"inbound.length=3", "outbound.length=3",
"inbound.lengthVariance=1", "outbound.lengthVariance=1",
"inbound.backupQuantity=1", "outbound.backupQuantity=1",
"inbound.quantity=4", "outbound.quantity=4",
}
// Options_Wide provides minimal anonymity but high performance for traffic requiring low latency.
// Suitable for applications prioritizing speed over anonymity. Uses 1-hop tunnels with
// moderate redundancy for basic privacy protection while maintaining performance.
Options_Wide = []string{
"inbound.length=1", "outbound.length=1",
"inbound.lengthVariance=1", "outbound.lengthVariance=1",
"inbound.backupQuantity=2", "outbound.backupQuantity=2",
"inbound.quantity=3", "outbound.quantity=3",
}
// Options_Medium provides balanced anonymity and performance for moderate traffic loads.
// Suitable for applications with medium traffic requirements that need good anonymity
// without excessive resource overhead. Provides solid baseline protection.
Options_Medium = []string{
"inbound.length=3", "outbound.length=3",
"inbound.lengthVariance=1", "outbound.lengthVariance=1",
"inbound.backupQuantity=0", "outbound.backupQuantity=0",
"inbound.quantity=2", "outbound.quantity=2",
}
// Options_Default provides sensible defaults for most use cases.
// Recommended starting point for most applications. Provides good anonymity
// with reasonable performance characteristics and resource usage.
Options_Default = []string{
"inbound.length=3", "outbound.length=3",
"inbound.lengthVariance=0", "outbound.lengthVariance=0",
"inbound.backupQuantity=1", "outbound.backupQuantity=1",
"inbound.quantity=1", "outbound.quantity=1",
}
// Options_Small provides basic anonymity for low-traffic, short-duration connections.
// Suitable only for applications with minimal traffic requirements and short connection
// lifetimes. Offers basic privacy with minimal resource usage.
Options_Small = []string{
"inbound.length=3", "outbound.length=3",
"inbound.lengthVariance=1", "outbound.lengthVariance=1",
"inbound.backupQuantity=0", "outbound.backupQuantity=0",
"inbound.quantity=1", "outbound.quantity=1",
}
// Options_Warning_ZeroHop disables all anonymization - zero hop configuration.
// WARNING: This configuration provides NO anonymity protection and should only be used
// for testing or debugging purposes. All traffic is directly routed without tunnel protection.
Options_Warning_ZeroHop = []string{
"inbound.length=0", "outbound.length=0",
"inbound.lengthVariance=0", "outbound.lengthVariance=0",
"inbound.backupQuantity=0", "outbound.backupQuantity=0",
"inbound.quantity=2", "outbound.quantity=2",
}
)
Predefined tunnel configuration option sets for different traffic patterns and anonymity requirements. These option sets balance performance, anonymity, and resource usage for common use cases. Each option set specifies tunnel length, variance, backup quantity, and parallel tunnel count.
var (
// SAM_HOST specifies the SAM bridge host address.
// Can be overridden with the 'sam_host' environment variable.
// Defaults to localhost (127.0.0.1) for local I2P router connections.
SAM_HOST = getEnv("sam_host", "127.0.0.1")
// SAM_PORT specifies the SAM bridge port number.
// Can be overridden with the 'sam_port' environment variable.
// Defaults to 7656, the standard SAM bridge port.
SAM_PORT = getEnv("sam_port", "7656")
// PrimarySessionSwitch enables primary session functionality.
// This is used internally to enable multi-session capabilities.
PrimarySessionSwitch = PrimarySessionString()
)
SAM bridge connection variables with environment variable support. These variables can be overridden using sam_host and sam_port environment variables.
func ExtractDest
func ExtractDest(input string) string
ExtractDest extracts the destination address from a SAM protocol response string. This utility function takes the first space-separated token from the input as the destination. It's commonly used for parsing SAM session creation responses and connection messages.
Example:
dest := ExtractDest("ABCD1234...destination_address RESULT=OK")
// Returns: "ABCD1234...destination_address"
func ExtractPairInt
func ExtractPairInt(input, value string) int
ExtractPairInt extracts an integer value from a key=value pair in a space-separated string. This utility function searches for the specified key and converts its value to an integer. Returns 0 if the key is not found or the value cannot be converted to an integer.
Example:
port := ExtractPairInt("HOST=example.org PORT=1234 TYPE=stream", "PORT")
// Returns: 1234
func ExtractPairString
func ExtractPairString(input, value string) string
ExtractPairString extracts a string value from a key=value pair in a space-separated string. This utility function searches for the specified key and returns its associated value. Returns empty string if the key is not found or has no value.
Example:
host := ExtractPairString("HOST=example.org PORT=1234 TYPE=stream", "HOST")
// Returns: "example.org"
func GenerateOptionString
func GenerateOptionString(opts []string) string
GenerateOptionString converts a slice of tunnel options into a single space-separated string. This utility function takes an array of I2P tunnel configuration options and formats them for use in SAM protocol commands. Each option should be in "key=value" format.
Example:
opts := []string{"inbound.length=3", "outbound.length=3"}
result := GenerateOptionString(opts)
// Returns: "inbound.length=3 outbound.length=3"
func GetSAM3Logger
func GetSAM3Logger() *logrus.Logger
GetSAM3Logger returns the initialized logger instance used by the SAM library. This function provides access to the structured logger for applications that want to integrate with the library's logging system or adjust log levels.
The logger is configured with appropriate fields for I2P and SAM operations, supporting debug, info, warn, and error levels with structured output.
func IgnorePortError
func IgnorePortError(err error) error
IgnorePortError filters out "missing port in address" errors for convenience when parsing addresses. This utility function is used when working with addresses that may not include port numbers. Returns nil if the error is about a missing port, otherwise returns the original error unchanged.
This is particularly useful when parsing I2P destination addresses that don't always include port specifications, allowing graceful handling of address parsing operations.
Example:
_, _, err := net.SplitHostPort("example.i2p") // This would error
err = IgnorePortError(err) // This returns nil
func InitializeSAM3Logger
func InitializeSAM3Logger()
InitializeSAM3Logger configures the logging system for the SAM library. This function sets up the logger with appropriate configuration for I2P operations, including proper log levels and formatting for SAM protocol debugging.
The logger respects environment variables for configuration: - DEBUG_I2P: Controls log level (debug, info, warn, error) Applications should call this once during initialization if they want to enable structured logging for SAM operations.
func PrimarySessionString
func PrimarySessionString() string
PrimarySessionString returns the primary session configuration identifier. This function provides compatibility with the sam3 library's primary session switch mechanism for enabling advanced session management features.
func RandString
func RandString() string
RandString generates a random string suitable for use as session identifiers or tunnel names. This utility function creates cryptographically secure random strings using I2P's random number generator. The generated strings are URL-safe and suitable for use in SAM protocol commands and session identification.
Returns a random string that can be used for session IDs, tunnel names, or other identifiers that require uniqueness and unpredictability in I2P operations.
func SAMDefaultAddr
func SAMDefaultAddr(fallforward string) string
SAMDefaultAddr constructs the default SAM bridge address with fallback support. This utility function provides a standardized way to determine the SAM bridge address, using the provided fallback if the standard environment variables are not set.
The function checks SAM_HOST and SAM_PORT variables first, then falls back to the provided fallforward parameter if those are not available. This enables flexible configuration while providing sensible defaults for most I2P installations.
Example:
addr := SAMDefaultAddr("127.0.0.1:7656")
// Returns: "127.0.0.1:7656" (or values from SAM_HOST/SAM_PORT if set)
func SetAccessList
func SetAccessList(s []string) func(*SAMEmit) error
SetAccessList sets the list of destinations for access control. The behavior depends on the access list type: whitelist allows only these destinations, blacklist denies these destinations.
Example usage:
destinations := []string{"dest1.b32.i2p", "dest2.b32.i2p"}
emit, err := NewEmit(SetAccessList(destinations))
func SetAccessListType
func SetAccessListType(s string) func(*SAMEmit) error
SetAccessListType sets the type of access control to apply. Valid values are "whitelist" (allow only listed destinations), "blacklist" (deny listed destinations), or "none" (no filtering).
Example usage:
emit, err := NewEmit(SetAccessListType("whitelist"))
func SetAllowZeroIn
func SetAllowZeroIn(b bool) func(*SAMEmit) error
SetAllowZeroIn enables or disables acceptance of zero-hop inbound tunnels. Zero-hop tunnels provide no anonymity but offer better performance for applications that don't require anonymity protection.
Example usage:
emit, err := NewEmit(SetAllowZeroIn(false))
func SetAllowZeroOut
func SetAllowZeroOut(b bool) func(*SAMEmit) error
SetAllowZeroOut enables or disables acceptance of zero-hop outbound tunnels. Zero-hop tunnels provide no anonymity but offer better performance for applications that don't require anonymity protection.
Example usage:
emit, err := NewEmit(SetAllowZeroOut(false))
func SetCloseIdle
func SetCloseIdle(b bool) func(*SAMEmit) error
SetCloseIdle enables or disables complete tunnel closure during extended idle periods. When enabled, closes all tunnels after the specified idle time to completely conserve router resources.
Example usage:
emit, err := NewEmit(SetCloseIdle(true))
func SetCloseIdleTime
func SetCloseIdleTime(u int) func(*SAMEmit) error
SetCloseIdleTime sets the time in minutes to wait before closing all tunnels. After this period of inactivity, all tunnels will be closed to conserve router resources.
Example usage:
emit, err := NewEmit(SetCloseIdleTime(30)) // 30 minutes
func SetCloseIdleTimeMs
func SetCloseIdleTimeMs(u int) func(*SAMEmit) error
SetCloseIdleTimeMs sets the time in milliseconds to wait before closing all tunnels. After this period of inactivity, all tunnels will be closed to conserve router resources.
Example usage:
emit, err := NewEmit(SetCloseIdleTimeMs(1800000)) // 30 minutes
func SetCompress
func SetCompress(b bool) func(*SAMEmit) error
SetCompress enables or disables data compression for tunnel traffic. Compression can reduce bandwidth usage but may impact performance and could potentially affect anonymity through traffic analysis.
Example usage:
emit, err := NewEmit(SetCompress(true))
func SetEncrypt
func SetEncrypt(b bool) func(*SAMEmit) error
SetEncrypt enables or disables encrypted lease sets for enhanced security. Encrypted lease sets provide additional protection against traffic analysis but may slightly impact performance and compatibility.
Example usage:
emit, err := NewEmit(SetEncrypt(true))
func SetFastRecieve
func SetFastRecieve(b bool) func(*SAMEmit) error
SetFastRecieve enables or disables fast receive mode for improved performance. When enabled, bypasses some protocol overhead for faster data transmission at the potential cost of some reliability guarantees.
Example usage:
emit, err := NewEmit(SetFastRecieve(true))
func SetInBackups
func SetInBackups(u int) func(*SAMEmit) error
SetInBackups sets the number of backup inbound tunnels (0-5). Backup tunnels are pre-built spare tunnels that can quickly replace failed primary tunnels, improving connection reliability.
Example usage:
emit, err := NewEmit(SetInBackups(1))
func SetInLength
func SetInLength(u int) func(*SAMEmit) error
SetInLength sets the number of hops for inbound tunnels (0-6). Higher values provide better anonymity but increase latency and resource usage. Most applications use 3 hops as a balance between security and performance.
Example usage:
emit, err := NewEmit(SetInLength(3))
func SetInQuantity
func SetInQuantity(u int) func(*SAMEmit) error
SetInQuantity sets the number of inbound tunnels to maintain (1-16). More tunnels provide better load distribution and redundancy but consume more router resources. Most applications use 1-4 tunnels.
Example usage:
emit, err := NewEmit(SetInQuantity(2))
func SetInVariance
func SetInVariance(i int) func(*SAMEmit) error
SetInVariance sets the variance for inbound tunnel hop counts (-6 to 6). This adds randomness to tunnel lengths to prevent traffic analysis. Positive values increase maximum hops, negative values allow shorter tunnels.
Example usage:
emit, err := NewEmit(SetInVariance(1))
func SetLeaseSetKey
func SetLeaseSetKey(s string) func(*SAMEmit) error
SetLeaseSetKey sets the public key for lease set encryption. This key is used to encrypt the lease set information, providing additional security for the destination's routing information.
Example usage:
emit, err := NewEmit(SetLeaseSetKey("base64-encoded-key"))
func SetLeaseSetPrivateKey
func SetLeaseSetPrivateKey(s string) func(*SAMEmit) error
SetLeaseSetPrivateKey sets the private key for lease set decryption. This key is used to decrypt lease set information when encrypted lease sets are enabled for enhanced security.
Example usage:
emit, err := NewEmit(SetLeaseSetPrivateKey("base64-encoded-private-key"))
func SetLeaseSetPrivateSigningKey
func SetLeaseSetPrivateSigningKey(s string) func(*SAMEmit) error
SetLeaseSetPrivateSigningKey sets the private signing key for lease set authentication. This key is used to sign lease set information to ensure authenticity and prevent tampering with routing information.
Example usage:
emit, err := NewEmit(SetLeaseSetPrivateSigningKey("base64-encoded-signing-key"))
func SetMessageReliability
func SetMessageReliability(s string) func(*SAMEmit) error
SetMessageReliability sets the reliability level for message delivery. Options include "none", "BestEffort", or "Guaranteed" depending on the application's reliability requirements and performance trade-offs.
Example usage:
emit, err := NewEmit(SetMessageReliability("BestEffort"))
func SetName
func SetName(s string) func(*SAMEmit) error
SetName sets the tunnel name for identification and debugging purposes. This name appears in I2P router logs and management interfaces to help identify and manage specific tunnels created by your application.
Example usage:
emit, err := NewEmit(SetName("my-app-tunnel"))
func SetOutBackups
func SetOutBackups(u int) func(*SAMEmit) error
SetOutBackups sets the number of backup outbound tunnels (0-5). Backup tunnels are pre-built spare tunnels that can quickly replace failed primary tunnels, improving connection reliability.
Example usage:
emit, err := NewEmit(SetOutBackups(1))
func SetOutLength
func SetOutLength(u int) func(*SAMEmit) error
SetOutLength sets the number of hops for outbound tunnels (0-6). Higher values provide better anonymity but increase latency and resource usage. Most applications use 3 hops as a balance between security and performance.
Example usage:
emit, err := NewEmit(SetOutLength(3))
func SetOutQuantity
func SetOutQuantity(u int) func(*SAMEmit) error
SetOutQuantity sets the number of outbound tunnels to maintain (1-16). More tunnels provide better load distribution and redundancy but consume more router resources. Most applications use 1-4 tunnels.
Example usage:
emit, err := NewEmit(SetOutQuantity(2))
func SetOutVariance
func SetOutVariance(i int) func(*SAMEmit) error
SetOutVariance sets the variance for outbound tunnel hop counts (-6 to 6). This adds randomness to tunnel lengths to prevent traffic analysis. Positive values increase maximum hops, negative values allow shorter tunnels.
Example usage:
emit, err := NewEmit(SetOutVariance(1))
func SetReduceIdle
func SetReduceIdle(b bool) func(*SAMEmit) error
SetReduceIdle enables or disables tunnel reduction during extended idle periods. When enabled, reduces the number of active tunnels during idle time to conserve router resources while maintaining minimal connectivity.
Example usage:
emit, err := NewEmit(SetReduceIdle(true))
func SetReduceIdleQuantity
func SetReduceIdleQuantity(u int) func(*SAMEmit) error
SetReduceIdleQuantity sets the minimum number of tunnels during idle periods. When idle reduction is enabled, this is the number of tunnels that will be maintained during periods of low activity.
Example usage:
emit, err := NewEmit(SetReduceIdleQuantity(1))
func SetReduceIdleTime
func SetReduceIdleTime(u int) func(*SAMEmit) error
SetReduceIdleTime sets the time in minutes to wait before reducing tunnels. After this period of inactivity, the number of tunnels will be reduced to the quantity specified by SetReduceIdleQuantity.
Example usage:
emit, err := NewEmit(SetReduceIdleTime(10)) // 10 minutes
func SetReduceIdleTimeMs
func SetReduceIdleTimeMs(u int) func(*SAMEmit) error
SetReduceIdleTimeMs sets the time in milliseconds to wait before reducing tunnels. After this period of inactivity, the number of tunnels will be reduced to the quantity specified by SetReduceIdleQuantity.
Example usage:
emit, err := NewEmit(SetReduceIdleTimeMs(600000)) // 10 minutes
func SetSAMAddress
func SetSAMAddress(s string) func(*SAMEmit) error
SetSAMAddress sets the SAM bridge address all-at-once using "host:port" format. This convenience function parses the address string and sets both host and port simultaneously for simplified SAM bridge configuration.
Example usage:
emit, err := NewEmit(SetSAMAddress("127.0.0.1:7656"))
func SetSAMHost
func SetSAMHost(s string) func(*SAMEmit) error
SetSAMHost sets the hostname or IP address of the SAM bridge. The SAM bridge is the interface that allows applications to communicate with the I2P router for creating sessions and managing connections.
Example usage:
emit, err := NewEmit(SetSAMHost("127.0.0.1"))
func SetSAMPort
func SetSAMPort(s string) func(*SAMEmit) error
SetSAMPort sets the port number of the SAM bridge using a string value. The port must be a valid TCP port number (0-65535) where the I2P router's SAM bridge is listening for incoming connections.
Example usage:
emit, err := NewEmit(SetSAMPort("7656"))
func SetType
func SetType(s string) func(*SAMEmit) error
SetType sets the session type for the forwarder server. Valid values are "STREAM", "DATAGRAM", or "RAW" corresponding to different communication patterns available in the I2P network protocol.
Example usage:
emit, err := NewEmit(SetType("STREAM"))
func SplitHostPort
func SplitHostPort(hostport string) (string, string, error)
SplitHostPort separates host and port from a combined address string with I2P-aware handling. Unlike net.SplitHostPort, this function handles I2P addresses gracefully, including those without explicit port specifications. Returns host, port as strings, and error.
This function is I2P-aware and handles the common case where I2P destination addresses don't include port numbers. Port defaults to "0" if not specified, and the function uses IgnorePortError internally to handle missing port situations gracefully.
Example:
host, port, err := SplitHostPort("example.i2p")
// Returns: "example.i2p", "0", nil
type BaseSession
type BaseSession = common.BaseSession
BaseSession represents the underlying session functionality that all session types extend. It provides common operations like connection management, key access, and standard net.Conn interface implementation for I2P session operations.
type DatagramSession
type DatagramSession = datagram.DatagramSession
DatagramSession provides UDP-like messaging capabilities with message reliability and ordering guarantees over I2P networks. It handles signed, authenticated messaging with replay protection for secure datagram communication patterns.
type I2PConfig
type I2PConfig = common.I2PConfig
I2PConfig manages I2P tunnel configuration options including tunnel length, backup quantities, variance settings, and other I2P-specific parameters. Applications use this to customize their anonymity and performance characteristics.
func NewConfig
func NewConfig(opts ...func(*I2PConfig) error) (*I2PConfig, error)
NewConfig creates a new I2PConfig instance with default values and applies functional options. Returns a configured instance ready for use in session creation or an error if any option fails. This delegates to common.NewConfig while providing the sam3 API surface.
Example usage:
config, err := NewConfig(SetInLength(4), SetOutLength(4))
if err != nil {
log.Fatal("Failed to create config:", err)
}
type Option
type Option = common.Option
Option represents a functional option for configuring SAMEmit instances. This follows the functional options pattern to provide type-safe configuration with clear error handling and composable session parameter management.
type Options
type Options = common.Options
Options represents a map of configuration options that can be applied to sessions. This provides a flexible way to specify tunnel parameters and session behaviors using key-value pairs that are converted to SAM protocol commands.
type PrimarySession
type PrimarySession = primary.PrimarySession
PrimarySession provides master session capabilities that can create and manage multiple sub-sessions of different types (stream, datagram, raw) within a single I2P session context. This enables complex applications with multiple communication patterns while sharing the same I2P identity and tunnel infrastructure.
type RawSession
type RawSession = raw.RawSession
RawSession provides unrepliable datagram communication over I2P networks. Messages are encrypted end-to-end but senders cannot be identified or replied to, providing the highest level of sender anonymity for one-way communication.
type SAM
type SAM struct {
*common.SAM
}
SAM represents the core SAM bridge connection and provides methods for session creation and I2P address resolution. It embeds common.SAM to enable method extension while exposing the sam3-compatible interface at the root package level.
func NewSAM
func NewSAM(address string) (*SAM, error)
NewSAM creates a new SAM connection to the specified address and performs the initial handshake. This is the main entry point for establishing connections to the I2P SAM bridge. Address should be in the format "host:port", typically "127.0.0.1:7656" for local I2P routers.
The function connects to the SAM bridge, performs the protocol handshake, and initializes the resolver for I2P name lookups. It returns a ready-to-use SAM instance or an error if any step of the initialization process fails.
Example:
sam, err := NewSAM("127.0.0.1:7656")
if err != nil {
log.Fatal(err)
}
defer sam.Close()
func (*SAM) NewDatagramSession
func (sam *SAM) NewDatagramSession(id string, keys i2pkeys.I2PKeys, options []string, udpPort int) (*DatagramSession, error)
NewDatagramSession creates a new datagram session for UDP-like authenticated messaging over I2P. Datagram sessions provide connectionless communication with message authentication and replay protection, suitable for applications that need fast, lightweight messaging without the overhead of connection establishment.
Unlike raw sessions, datagram sessions provide sender authentication and message integrity verification, making them suitable for applications where message authenticity is important. Each message includes cryptographic signatures that allow recipients to verify the sender's identity and detect tampering.
Returns a DatagramSession ready for sending and receiving authenticated datagrams, or an error if the session creation fails.
The udpPort parameter specifies the local UDP port for the session's datagram interface. If set to 0, the I2P router will use the standard SAM UDP port (typically 7655). This port is used for the local UDP socket that communicates with the I2P datagram subsystem for message forwarding and reception.
Example usage:
sam, err := NewSAM("127.0.0.1:7656")
keys, _ := i2pkeys.NewKeys(i2pkeys.KT_ECDSA_SHA256_P256)
session, err := sam.NewDatagramSession("chat-app", keys, Options_Medium, 0)
func (*SAM) NewPrimarySession
func (sam *SAM) NewPrimarySession(id string, keys i2pkeys.I2PKeys, options []string) (*PrimarySession, error)
NewPrimarySession creates a new primary session that can manage multiple sub-sessions of different types (stream, datagram, raw) within a single I2P session context. The primary session enables complex applications with multiple communication patterns while sharing the same I2P identity and tunnel infrastructure for enhanced efficiency.
The session ID must be unique and will be used to identify this session in the SAM protocol. The I2P keys define the cryptographic identity that will be shared across all sub-sessions created from this primary session. Configuration options control tunnel parameters such as length, backup quantity, and other I2P-specific settings.
Returns a PrimarySession that can create and manage sub-sessions, or an error if the session creation fails due to SAM protocol errors, network issues, or invalid configuration parameters.
Example usage:
sam, err := NewSAM("127.0.0.1:7656")
keys, _ := i2pkeys.NewKeys(i2pkeys.KT_ECDSA_SHA256_P256)
primary, err := sam.NewPrimarySession("app-primary", keys, Options_Default)
streamSub, err := primary.NewStreamSubSession("tcp-handler", []string{})
datagramSub, err := primary.NewDatagramSubSession("udp-handler", []string{})
func (*SAM) NewPrimarySessionWithSignature
func (sam *SAM) NewPrimarySessionWithSignature(id string, keys i2pkeys.I2PKeys, options []string, sigType string) (*PrimarySession, error)
NewPrimarySessionWithSignature creates a new primary session with a specific signature type. This method provides the same functionality as NewPrimarySession but allows explicit control over the cryptographic signature algorithm used for the session's I2P identity.
The signature type must be one of the supported I2P signature algorithms (use the Sig_* constants defined in this package). Different signature types offer different security levels and performance characteristics - EdDSA_SHA512_Ed25519 is recommended for most applications as it provides strong security with good performance.
Returns a PrimarySession configured with the specified signature type, or an error if the session creation fails or the signature type is not supported by the I2P router.
Example usage:
sam, err := NewSAM("127.0.0.1:7656")
keys, _ := i2pkeys.NewKeys(i2pkeys.KT_EdDSA_SHA512_Ed25519)
primary, err := sam.NewPrimarySessionWithSignature("secure-primary", keys,
Options_Default, Sig_EdDSA_SHA512_Ed25519)
func (*SAM) NewRawSession
func (sam *SAM) NewRawSession(id string, keys i2pkeys.I2PKeys, options []string, udpPort int) (*RawSession, error)
NewRawSession creates a new raw session for unrepliable datagram communication over I2P. Raw sessions provide the most lightweight form of I2P communication, where messages are encrypted end-to-end but do not include sender authentication or guarantee delivery. Recipients cannot identify the sender or send replies directly.
Raw sessions are suitable for applications that need maximum anonymity and minimal overhead, such as anonymous publishing, voting systems, or situations where sender identity must remain completely hidden. The lack of sender authentication provides stronger anonymity but eliminates the ability to verify message authenticity.
The udpPort parameter specifies the local UDP port for the session's datagram interface. This port is used for the local UDP socket that communicates with the I2P raw datagram subsystem.
Returns a RawSession ready for sending anonymous unrepliable datagrams, or an error if the session creation fails.
Example usage:
sam, err := NewSAM("127.0.0.1:7656")
keys, _ := i2pkeys.NewKeys(i2pkeys.KT_ECDSA_SHA256_P256)
session, err := sam.NewRawSession("anonymous-publisher", keys, Options_Small, 0)
writer := session.NewWriter()
reader := session.NewReader()
func (*SAM) NewStreamSession
func (sam *SAM) NewStreamSession(id string, keys i2pkeys.I2PKeys, options []string) (*StreamSession, error)
NewStreamSession creates a new stream session for TCP-like reliable connections over I2P. Stream sessions provide connection-oriented communication with guarantees for message ordering, delivery, and flow control, similar to TCP but routed through I2P tunnels.
The session can be used to create listeners for accepting incoming connections or to establish outbound connections to other I2P destinations. All connections share the same I2P identity defined by the provided keys and benefit from the tunnel configuration specified in the options.
Returns a StreamSession ready for creating connections, or an error if the session creation fails due to SAM protocol errors, network issues, or invalid configuration.
Example usage:
sam, err := NewSAM("127.0.0.1:7656")
keys, _ := i2pkeys.NewKeys(i2pkeys.KT_ECDSA_SHA256_P256)
session, err := sam.NewStreamSession("web-server", keys, Options_Default)
listener, err := session.Listen()
conn, err := session.Dial("destination.b32.i2p")
func (*SAM) NewStreamSessionWithSignature
func (sam *SAM) NewStreamSessionWithSignature(id string, keys i2pkeys.I2PKeys, options []string, sigType string) (*StreamSession, error)
NewStreamSessionWithSignature creates a new stream session with a specific signature type. This method provides the same functionality as NewStreamSession but allows explicit control over the cryptographic signature algorithm used for the session's I2P identity.
The signature type determines the cryptographic strength and performance characteristics of the session. EdDSA_SHA512_Ed25519 is recommended for most applications, while ECDSA variants may be preferred for compatibility with older I2P routers or specific security requirements.
Returns a StreamSession configured with the specified signature type, or an error if the session creation fails or the signature type is not supported.
Example usage:
sam, err := NewSAM("127.0.0.1:7656")
keys, _ := i2pkeys.NewKeys(i2pkeys.KT_EdDSA_SHA512_Ed25519)
session, err := sam.NewStreamSessionWithSignature("secure-stream", keys,
Options_Large, Sig_EdDSA_SHA512_Ed25519)
func (*SAM) NewStreamSessionWithSignatureAndPorts
func (sam *SAM) NewStreamSessionWithSignatureAndPorts(id, from, to string, keys i2pkeys.I2PKeys, options []string, sigType string) (*StreamSession, error)
NewStreamSessionWithSignatureAndPorts creates a new stream session with signature type and specific port configuration. This method enables advanced port mapping scenarios where the session should bind to specific local ports or forward to specific remote ports.
The 'from' parameter specifies the local port or port range that the session should use for incoming connections. The 'to' parameter specifies the target port or port range for outbound connections. Port specifications can be single ports ("80") or ranges ("8080-8090").
This method is particularly useful for applications that need to maintain consistent port mappings or integrate with existing network infrastructure that expects specific port configurations.
Returns a StreamSession with the specified port configuration, or an error if the session creation fails or the port configuration is invalid.
Example usage:
sam, err := NewSAM("127.0.0.1:7656")
keys, _ := i2pkeys.NewKeys(i2pkeys.KT_ECDSA_SHA256_P256)
session, err := sam.NewStreamSessionWithSignatureAndPorts("http-proxy",
"8080", "80", keys, Options_Default, Sig_ECDSA_SHA256_P256)
type SAMConn
type SAMConn = stream.StreamConn
SAMConn implements net.Conn for I2P streaming connections, providing a standard Go networking interface for TCP-like reliable communication over I2P networks. This alias maintains sam3 API compatibility while delegating to stream.StreamConn.
type SAMEmit
type SAMEmit = common.SAMEmit
SAMEmit handles SAM protocol message generation and configuration management. It embeds I2PConfig to provide comprehensive session configuration capabilities while managing the underlying SAM protocol communication requirements.
func NewEmit
func NewEmit(opts ...func(*SAMEmit) error) (*SAMEmit, error)
NewEmit creates a new SAMEmit instance with the specified configuration options. Applies functional options to configure the emitter with custom settings. Returns an error if any option fails to apply correctly.
Example usage:
emit, err := NewEmit(SetSAMHost("localhost"), SetSAMPort("7656"))
if err != nil {
log.Fatal("Failed to create emitter:", err)
}
type SAMResolver
type SAMResolver = common.SAMResolver
SAMResolver provides I2P address resolution services through the SAM protocol. It wraps the common.SAMResolver to provide name-to-address lookup functionality that applications need for connecting to I2P destinations by name.
func NewFullSAMResolver
func NewFullSAMResolver(address string) (*SAMResolver, error)
NewFullSAMResolver creates a new complete SAM resolver by establishing its own connection. This convenience function creates both a SAM connection and resolver in a single operation. It's useful when you only need name resolution and don't require a persistent SAM connection for session management or other operations.
The resolver will establish its own connection to the specified address and be ready for immediate use. The caller is responsible for closing the resolver when done.
Example:
resolver, err := NewFullSAMResolver("127.0.0.1:7656")
if err != nil {
return err
}
defer resolver.Close()
func NewSAMResolver
func NewSAMResolver(parent *SAM) (*SAMResolver, error)
NewSAMResolver creates a new SAM resolver instance for I2P name lookups. This function creates a resolver that can translate I2P names (like "example.i2p") into Base32 destination addresses for use in connections and messaging.
The resolver uses the provided SAM connection for performing lookups through the I2P network's address book and naming services. It's essential for applications that want to connect to I2P services using human-readable names.
Example:
resolver, err := NewSAMResolver(sam)
if err != nil {
return err
}
addr, err := resolver.Resolve("example.i2p")
type StreamListener
type StreamListener = stream.StreamListener
StreamListener implements net.Listener for I2P streaming connections. It manages incoming connection acceptance and provides thread-safe operations for accepting connections from remote I2P destinations in server applications.
type StreamSession
type StreamSession = stream.StreamSession
StreamSession provides TCP-like reliable connection capabilities over I2P networks. It supports both client and server operations with connection multiplexing, listener management, and standard Go networking interfaces for streaming data.
type TestListener
type TestListener struct {
}
TestListener manages a local I2P listener for testing purposes. It provides a stable, local destination that can replace external sites in tests.
func SetupTestListener
func SetupTestListener(t *testing.T, config *TestListenerConfig) *TestListener
SetupTestListener creates and starts a local I2P listener that can serve as a test destination. This replaces the need for external sites like i2p-projekt.i2p or idk.i2p in tests. The listener will respond to HTTP GET requests with basic HTML content.
func SetupTestListenerWithHTTP
func SetupTestListenerWithHTTP(t *testing.T, sessionID string) *TestListener
SetupTestListenerWithHTTP creates a test listener that provides HTTP-like responses suitable for replacing external web sites in tests.
func (*TestListener) Addr
func (tl *TestListener) Addr() i2pkeys.I2PAddr
Addr returns the I2P address of the test listener.
func (*TestListener) AddrString
func (tl *TestListener) AddrString() string
AddrString returns the Base32 address string of the test listener.
func (*TestListener) Close
func (tl *TestListener) Close() error
Close shuts down the test listener and cleans up resources.
type TestListenerConfig
type TestListenerConfig struct {
SessionID string
HTTPResponse string // Optional custom HTTP response content
Timeout time.Duration
}
TestListenerConfig holds configuration for creating test listeners.
func DefaultTestListenerConfig
func DefaultTestListenerConfig(sessionID string) *TestListenerConfig
DefaultTestListenerConfig returns a default configuration for test listeners.