idk/go-sam-go
1
0
Fork 0
mirror of https://github.com/go-i2p/go-sam-go.git synced 2025-07-03 09:57:43 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
a53acecb87b62c941a7e1470d0f7335a84feddba
go-sam-go/common/DOC.md
eyedeekay a53acecb87 godoc
2025-05-29 19:44:45 -04:00

945 lines
19 KiB
Markdown
Raw Blame History

# common
--
import "github.com/go-i2p/go-sam-go/common"
## Usage
```go
const (
DEFAULT_SAM_MIN = "3.1"
DEFAULT_SAM_MAX = "3.3"
)
```
```go
const (
SESSION_OK = "SESSION STATUS RESULT=OK DESTINATION="
SESSION_DUPLICATE_ID = "SESSION STATUS RESULT=DUPLICATED_ID\n"
SESSION_DUPLICATE_DEST = "SESSION STATUS RESULT=DUPLICATED_DEST\n"
SESSION_INVALID_KEY = "SESSION STATUS RESULT=INVALID_KEY\n"
SESSION_I2P_ERROR = "SESSION STATUS RESULT=I2P_ERROR MESSAGE="
)
```
```go
const (
SIG_NONE = "SIGNATURE_TYPE=EdDSA_SHA512_Ed25519"
SIG_DSA_SHA1 = "SIGNATURE_TYPE=DSA_SHA1"
SIG_ECDSA_SHA256_P256 = "SIGNATURE_TYPE=ECDSA_SHA256_P256"
SIG_ECDSA_SHA384_P384 = "SIGNATURE_TYPE=ECDSA_SHA384_P384"
SIG_ECDSA_SHA512_P521 = "SIGNATURE_TYPE=ECDSA_SHA512_P521"
SIG_EdDSA_SHA512_Ed25519 = "SIGNATURE_TYPE=EdDSA_SHA512_Ed25519"
// Add a default constant that points to the recommended secure signature type
SIG_DEFAULT = SIG_EdDSA_SHA512_Ed25519
)
```
```go
const (
SAM_RESULT_OK = "RESULT=OK"
SAM_RESULT_INVALID_KEY = "RESULT=INVALID_KEY"
SAM_RESULT_KEY_NOT_FOUND = "RESULT=KEY_NOT_FOUND"
)
```
```go
const (
HELLO_REPLY_OK = "HELLO REPLY RESULT=OK"
HELLO_REPLY_NOVERSION = "HELLO REPLY RESULT=NOVERSION\n"
)
```
```go
const (
SESSION_STYLE_STREAM = "STREAM"
SESSION_STYLE_DATAGRAM = "DATAGRAM"
SESSION_STYLE_RAW = "RAW"
)
```
```go
const (
ACCESS_TYPE_WHITELIST = "whitelist"
ACCESS_TYPE_BLACKLIST = "blacklist"
ACCESS_TYPE_NONE = "none"
)
```
#### func ExtractDest
```go
func ExtractDest(input string) string
```
#### func ExtractPairInt
```go
func ExtractPairInt(input, value string) int
```
#### func ExtractPairString
```go
func ExtractPairString(input, value string) string
```
#### func IgnorePortError
```go
func IgnorePortError(err error) error
```
#### func RandPort
```go
func RandPort() (portNumber string, err error)
```
#### func SetAccessList
```go
func SetAccessList(s []string) func(*SAMEmit) error
```
SetAccessList tells the system to treat the AccessList as a whitelist
#### func SetAccessListType
```go
func SetAccessListType(s string) func(*SAMEmit) error
```
SetAccessListType tells the system to treat the AccessList as a whitelist
#### func SetAllowZeroIn
```go
func SetAllowZeroIn(b bool) func(*SAMEmit) error
```
SetAllowZeroIn tells the tunnel to accept zero-hop peers
#### func SetAllowZeroOut
```go
func SetAllowZeroOut(b bool) func(*SAMEmit) error
```
SetAllowZeroOut tells the tunnel to accept zero-hop peers
#### func SetCloseIdle
```go
func SetCloseIdle(b bool) func(*SAMEmit) error
```
SetCloseIdle tells the connection to close it's tunnels during extended idle
time.
#### func SetCloseIdleTime
```go
func SetCloseIdleTime(u int) func(*SAMEmit) error
```
SetCloseIdleTime sets the time to wait before closing tunnels to idle levels
#### func SetCloseIdleTimeMs
```go
func SetCloseIdleTimeMs(u int) func(*SAMEmit) error
```
SetCloseIdleTimeMs sets the time to wait before closing tunnels to idle levels
in milliseconds
#### func SetCompress
```go
func SetCompress(b bool) func(*SAMEmit) error
```
SetCompress tells clients to use compression
#### func SetEncrypt
```go
func SetEncrypt(b bool) func(*SAMEmit) error
```
SetEncrypt tells the router to use an encrypted leaseset
#### func SetFastRecieve
```go
func SetFastRecieve(b bool) func(*SAMEmit) error
```
SetFastRecieve tells clients to use compression
#### func SetInBackups
```go
func SetInBackups(u int) func(*SAMEmit) error
```
SetInBackups sets the inbound tunnel backups
#### func SetInLength
```go
func SetInLength(u int) func(*SAMEmit) error
```
SetInLength sets the number of hops inbound
#### func SetInQuantity
```go
func SetInQuantity(u int) func(*SAMEmit) error
```
SetInQuantity sets the inbound tunnel quantity
#### func SetInVariance
```go
func SetInVariance(i int) func(*SAMEmit) error
```
SetInVariance sets the variance of a number of hops inbound
#### func SetLeaseSetKey
```go
func SetLeaseSetKey(s string) func(*SAMEmit) error
```
SetLeaseSetKey sets the host of the SAMEmit's SAM bridge
#### func SetLeaseSetPrivateKey
```go
func SetLeaseSetPrivateKey(s string) func(*SAMEmit) error
```
SetLeaseSetPrivateKey sets the host of the SAMEmit's SAM bridge
#### func SetLeaseSetPrivateSigningKey
```go
func SetLeaseSetPrivateSigningKey(s string) func(*SAMEmit) error
```
SetLeaseSetPrivateSigningKey sets the host of the SAMEmit's SAM bridge
#### func SetMessageReliability
```go
func SetMessageReliability(s string) func(*SAMEmit) error
```
SetMessageReliability sets the host of the SAMEmit's SAM bridge
#### func SetName
```go
func SetName(s string) func(*SAMEmit) error
```
SetName sets the host of the SAMEmit's SAM bridge
#### func SetOutBackups
```go
func SetOutBackups(u int) func(*SAMEmit) error
```
SetOutBackups sets the inbound tunnel backups
#### func SetOutLength
```go
func SetOutLength(u int) func(*SAMEmit) error
```
SetOutLength sets the number of hops outbound
#### func SetOutQuantity
```go
func SetOutQuantity(u int) func(*SAMEmit) error
```
SetOutQuantity sets the outbound tunnel quantity
#### func SetOutVariance
```go
func SetOutVariance(i int) func(*SAMEmit) error
```
SetOutVariance sets the variance of a number of hops outbound
#### func SetReduceIdle
```go
func SetReduceIdle(b bool) func(*SAMEmit) error
```
SetReduceIdle tells the connection to reduce it's tunnels during extended idle
time.
#### func SetReduceIdleQuantity
```go
func SetReduceIdleQuantity(u int) func(*SAMEmit) error
```
SetReduceIdleQuantity sets minimum number of tunnels to reduce to during idle
time
#### func SetReduceIdleTime
```go
func SetReduceIdleTime(u int) func(*SAMEmit) error
```
SetReduceIdleTime sets the time to wait before reducing tunnels to idle levels
#### func SetReduceIdleTimeMs
```go
func SetReduceIdleTimeMs(u int) func(*SAMEmit) error
```
SetReduceIdleTimeMs sets the time to wait before reducing tunnels to idle levels
in milliseconds
#### func SetSAMAddress
```go
func SetSAMAddress(s string) func(*SAMEmit) error
```
SetSAMAddress sets the SAM address all-at-once
#### func SetSAMHost
```go
func SetSAMHost(s string) func(*SAMEmit) error
```
SetSAMHost sets the host of the SAMEmit's SAM bridge
#### func SetSAMPort
```go
func SetSAMPort(s string) func(*SAMEmit) error
```
SetSAMPort sets the port of the SAMEmit's SAM bridge using a string
#### func SetType
```go
func SetType(s string) func(*SAMEmit) error
```
SetType sets the type of the forwarder server
#### func SplitHostPort
```go
func SplitHostPort(hostport string) (string, string, error)
```
#### type BaseSession
```go
type BaseSession struct {
SAM SAM
}
```
#### func (*BaseSession) Close
```go
func (bs *BaseSession) Close() error
```
#### func (*BaseSession) From
```go
func (bs *BaseSession) From() string
```
#### func (*BaseSession) ID
```go
func (bs *BaseSession) ID() string
```
#### func (*BaseSession) Keys
```go
func (bs *BaseSession) Keys() i2pkeys.I2PKeys
```
#### func (*BaseSession) LocalAddr
```go
func (bs *BaseSession) LocalAddr() net.Addr
```
#### func (*BaseSession) Read
```go
func (bs *BaseSession) Read(b []byte) (int, error)
```
#### func (*BaseSession) RemoteAddr
```go
func (bs *BaseSession) RemoteAddr() net.Addr
```
#### func (*BaseSession) SetDeadline
```go
func (bs *BaseSession) SetDeadline(t time.Time) error
```
#### func (*BaseSession) SetReadDeadline
```go
func (bs *BaseSession) SetReadDeadline(t time.Time) error
```
#### func (*BaseSession) SetWriteDeadline
```go
func (bs *BaseSession) SetWriteDeadline(t time.Time) error
```
#### func (*BaseSession) To
```go
func (bs *BaseSession) To() string
```
#### func (*BaseSession) Write
```go
func (bs *BaseSession) Write(b []byte) (int, error)
```
#### type I2PConfig
```go
type I2PConfig struct {
SamHost string
SamPort int
TunName string
SamMin string
SamMax string
Fromport string
Toport string
Style string
TunType string
DestinationKeys *i2pkeys.I2PKeys
SigType string
EncryptLeaseSet bool
LeaseSetKey string
LeaseSetPrivateKey string
LeaseSetPrivateSigningKey string
LeaseSetKeys i2pkeys.I2PKeys
InAllowZeroHop bool
OutAllowZeroHop bool
InLength int
OutLength int
InQuantity int
OutQuantity int
InVariance int
OutVariance int
InBackupQuantity int
OutBackupQuantity int
FastRecieve bool
UseCompression bool
MessageReliability string
CloseIdle bool
CloseIdleTime int
ReduceIdle bool
ReduceIdleTime int
ReduceIdleQuantity int
LeaseSetEncryption string
// Streaming Library options
AccessListType string
AccessList []string
}
```
I2PConfig is a struct which manages I2P configuration options.
#### func NewConfig
```go
func NewConfig(opts ...func(*I2PConfig) error) (*I2PConfig, error)
```
#### func (*I2PConfig) Accesslist
```go
func (f *I2PConfig) Accesslist() string
```
Accesslist generates the I2CP access list configuration string based on the
configured access list
#### func (*I2PConfig) Accesslisttype
```go
func (f *I2PConfig) Accesslisttype() string
```
Accesslisttype returns the I2CP access list configuration string based on the
AccessListType setting
#### func (*I2PConfig) Close
```go
func (f *I2PConfig) Close() string
```
Close returns I2CP close-on-idle configuration settings as a string if enabled
#### func (*I2PConfig) DestinationKey
```go
func (f *I2PConfig) DestinationKey() string
```
DestinationKey returns the DESTINATION configuration string for the SAM bridge
If destination keys are set, returns them as a string, otherwise returns
"TRANSIENT"
#### func (*I2PConfig) DoZero
```go
func (f *I2PConfig) DoZero() string
```
DoZero returns the zero hop and fast receive configuration string settings
#### func (*I2PConfig) EncryptLease
```go
func (f *I2PConfig) EncryptLease() string
```
EncryptLease returns the lease set encryption configuration string Returns
"i2cp.encryptLeaseSet=true" if encryption is enabled, empty string otherwise
#### func (*I2PConfig) FromPort
```go
func (f *I2PConfig) FromPort() string
```
FromPort returns the FROM_PORT configuration string for SAM bridges >= 3.1
Returns an empty string if SAM version < 3.1 or if fromport is "0"
#### func (*I2PConfig) ID
```go
func (f *I2PConfig) ID() string
```
ID returns the tunnel name as a formatted string. If no tunnel name is set,
generates a random 12-character name using lowercase letters.
#### func (*I2PConfig) InboundBackupQuantity
```go
func (f *I2PConfig) InboundBackupQuantity() string
```
#### func (*I2PConfig) InboundLength
```go
func (f *I2PConfig) InboundLength() string
```
#### func (*I2PConfig) InboundLengthVariance
```go
func (f *I2PConfig) InboundLengthVariance() string
```
#### func (*I2PConfig) InboundQuantity
```go
func (f *I2PConfig) InboundQuantity() string
```
#### func (*I2PConfig) LeaseSetEncryptionType
```go
func (f *I2PConfig) LeaseSetEncryptionType() string
```
LeaseSetEncryptionType returns the I2CP lease set encryption type configuration
string. If no encryption type is set, returns default value "4,0". Validates
that all encryption types are valid integers.
#### func (*I2PConfig) LeaseSetSettings
```go
func (f *I2PConfig) LeaseSetSettings() (string, string, string)
```
Leasesetsettings returns the lease set configuration strings for I2P Returns
three strings: lease set key, private key, and private signing key settings
#### func (*I2PConfig) MaxSAM
```go
func (f *I2PConfig) MaxSAM() string
```
MaxSAM returns the maximum SAM version supported as a string If no maximum
version is set, returns default value "3.1"
#### func (*I2PConfig) MinSAM
```go
func (f *I2PConfig) MinSAM() string
```
MinSAM returns the minimum SAM version supported as a string If no minimum
version is set, returns default value "3.0"
#### func (*I2PConfig) OutboundBackupQuantity
```go
func (f *I2PConfig) OutboundBackupQuantity() string
```
#### func (*I2PConfig) OutboundLength
```go
func (f *I2PConfig) OutboundLength() string
```
#### func (*I2PConfig) OutboundLengthVariance
```go
func (f *I2PConfig) OutboundLengthVariance() string
```
#### func (*I2PConfig) OutboundQuantity
```go
func (f *I2PConfig) OutboundQuantity() string
```
#### func (*I2PConfig) Print
```go
func (f *I2PConfig) Print() []string
```
Print returns a slice of strings containing all the I2P configuration settings
#### func (*I2PConfig) Reduce
```go
func (f *I2PConfig) Reduce() string
```
Reduce returns I2CP reduce-on-idle configuration settings as a string if enabled
#### func (*I2PConfig) Reliability
```go
func (f *I2PConfig) Reliability() string
```
Reliability returns the message reliability configuration string for the SAM
bridge If a reliability setting is specified, returns formatted
i2cp.messageReliability setting
#### func (*I2PConfig) SAMAddress
```go
func (f *I2PConfig) SAMAddress() string
```
SAMAddress returns the SAM bridge address in the format "host:port" This is a
convenience method that uses the Sam() function to get the address. It is used
to provide a consistent interface for retrieving the SAM address.
#### func (*I2PConfig) Sam
```go
func (f *I2PConfig) Sam() string
```
Sam returns the SAM bridge address as a string in the format "host:port"
#### func (*I2PConfig) SessionStyle
```go
func (f *I2PConfig) SessionStyle() string
```
SessionStyle returns the SAM session style configuration string If no style is
set, defaults to "STREAM"
#### func (*I2PConfig) SetSAMAddress
```go
func (f *I2PConfig) SetSAMAddress(addr string)
```
SetSAMAddress sets the SAM bridge host and port from a combined address string.
If no address is provided, it sets default values for the host and port.
#### func (*I2PConfig) SignatureType
```go
func (f *I2PConfig) SignatureType() string
```
SignatureType returns the SIGNATURE_TYPE configuration string for SAM bridges >=
3.1 Returns empty string if SAM version < 3.1 or if no signature type is set
#### func (*I2PConfig) ToPort
```go
func (f *I2PConfig) ToPort() string
```
ToPort returns the TO_PORT configuration string for SAM bridges >= 3.1 Returns
an empty string if SAM version < 3.1 or if toport is "0"
#### func (*I2PConfig) UsingCompression
```go
func (f *I2PConfig) UsingCompression() string
```
#### type Option
```go
type Option func(*SAMEmit) error
```
Option is a SAMEmit Option
#### type Options
```go
type Options map[string]string
```
options map
#### func (Options) AsList
```go
func (opts Options) AsList() (ls []string)
```
obtain sam options as list of strings
#### type SAM
```go
type SAM struct {
SAMEmit
SAMResolver
net.Conn
// Timeout for SAM connections
Timeout time.Duration
// Context for control of lifecycle
Context context.Context
}
```
Used for controlling I2Ps SAMv3.
#### func NewSAM
```go
func NewSAM(address string) (*SAM, error)
```
NewSAM creates a new SAM instance by connecting to the specified address,
performing the hello handshake, and initializing the SAM resolver. It returns a
pointer to the SAM instance or an error if any step fails. This function
combines connection establishment and hello handshake into a single step,
eliminating the need for separate helper functions. It also initializes the SAM
resolver directly after the connection is established. The SAM instance is ready
to use for further operations like session creation or name resolution.
#### func (*SAM) Close
```go
func (sam *SAM) Close() error
```
close this sam session
#### func (*SAM) EnsureKeyfile
```go
func (sam *SAM) EnsureKeyfile(fname string) (keys i2pkeys.I2PKeys, err error)
```
if keyfile fname does not exist
#### func (*SAM) Keys
```go
func (sam *SAM) Keys() (k *i2pkeys.I2PKeys)
```
#### func (*SAM) Lookup
```go
func (sam *SAM) Lookup(name string) (i2pkeys.I2PAddr, error)
```
Performs a lookup, probably this order: 1) routers known addresses, cached
addresses, 3) by asking peers in the I2P network.
#### func (SAM) NewGenericSession
```go
func (sam SAM) NewGenericSession(style, id string, keys i2pkeys.I2PKeys, extras []string) (Session, error)
```
Creates a new session with the style of either "STREAM", "DATAGRAM" or "RAW",
for a new I2P tunnel with name id, using the cypher keys specified, with the
I2CP/streaminglib-options as specified. Extra arguments can be specified by
setting extra to something else than []string{}. This sam3 instance is now a
session
#### func (SAM) NewGenericSessionWithSignature
```go
func (sam SAM) NewGenericSessionWithSignature(style, id string, keys i2pkeys.I2PKeys, sigType string, extras []string) (Session, error)
```
#### func (SAM) NewGenericSessionWithSignatureAndPorts
```go
func (sam SAM) NewGenericSessionWithSignatureAndPorts(style, id, from, to string, keys i2pkeys.I2PKeys, sigType string, extras []string) (Session, error)
```
Creates a new session with the style of either "STREAM", "DATAGRAM" or "RAW",
for a new I2P tunnel with name id, using the cypher keys specified, with the
I2CP/streaminglib-options as specified. Extra arguments can be specified by
setting extra to something else than []string{}. This sam3 instance is now a
session
#### func (*SAM) NewKeys
```go
func (sam *SAM) NewKeys(sigType ...string) (i2pkeys.I2PKeys, error)
```
Creates the I2P-equivalent of an IP address, that is unique and only the one who
has the private keys can send messages from. The public keys are the I2P
desination (the address) that anyone can send messages to.
#### func (*SAM) ReadKeys
```go
func (sam *SAM) ReadKeys(r io.Reader) (err error)
```
read public/private keys from an io.Reader
#### type SAMEmit
```go
type SAMEmit struct {
I2PConfig
}
```
#### func NewEmit
```go
func NewEmit(opts ...func(*SAMEmit) error) (*SAMEmit, error)
```
#### func (*SAMEmit) Accept
```go
func (e *SAMEmit) Accept() string
```
#### func (*SAMEmit) AcceptBytes
```go
func (e *SAMEmit) AcceptBytes() []byte
```
#### func (*SAMEmit) Connect
```go
func (e *SAMEmit) Connect(dest string) string
```
#### func (*SAMEmit) ConnectBytes
```go
func (e *SAMEmit) ConnectBytes(dest string) []byte
```
#### func (*SAMEmit) Create
```go
func (e *SAMEmit) Create() string
```
#### func (*SAMEmit) CreateBytes
```go
func (e *SAMEmit) CreateBytes() []byte
```
#### func (*SAMEmit) GenerateDestination
```go
func (e *SAMEmit) GenerateDestination() string
```
#### func (*SAMEmit) GenerateDestinationBytes
```go
func (e *SAMEmit) GenerateDestinationBytes() []byte
```
#### func (*SAMEmit) Hello
```go
func (e *SAMEmit) Hello() string
```
#### func (*SAMEmit) HelloBytes
```go
func (e *SAMEmit) HelloBytes() []byte
```
#### func (*SAMEmit) Lookup
```go
func (e *SAMEmit) Lookup(name string) string
```
#### func (*SAMEmit) LookupBytes
```go
func (e *SAMEmit) LookupBytes(name string) []byte
```
#### func (*SAMEmit) SamOptionsString
```go
func (e *SAMEmit) SamOptionsString() string
```
#### type SAMResolver
```go
type SAMResolver struct {
*SAM
}
```
#### func NewFullSAMResolver
```go
func NewFullSAMResolver(address string) (*SAMResolver, error)
```
#### func NewSAMResolver
```go
func NewSAMResolver(parent *SAM) (*SAMResolver, error)
```
#### func (*SAMResolver) Resolve
```go
func (sam *SAMResolver) Resolve(name string) (i2pkeys.I2PAddr, error)
```
Performs a lookup, probably this order: 1) routers known addresses, cached
addresses, 3) by asking peers in the I2P network.
#### type Session
```go
type Session interface {
net.Conn
ID() string
Keys() i2pkeys.I2PKeys
Close() error
}
```
Reference in New Issue View Git Blame Copy Permalink