README
¶
onramp
High-level, easy-to-use listeners and clients for I2P and onion URL's from Go. Provides only the most widely-used functions in a basic way. It expects nothing from the users, an otherwise empty instance of the structs will listen and dial I2P Streaming and Tor TCP sessions successfully.
In all cases, it assumes that keys are "persistent" in that they are managed
maintained between usages of the same application in the same configuration.
This means that hidden services will maintain their identities, and that clients
will always have the same return addresses. If you don't want this behavior,
make sure to delete the "keystore" when your app closes or when your application
needs to cycle keys by calling the Garlic.DeleteKeys() or Onion.DeleteKeys()
function. For more information, check out the godoc.
STATUS: This project is maintained. I will respond to issues, pull requests, and feature requests within a few days.
Usage
Basic usage is designed to be very simple, import the package and instantiate a struct and you're ready to go.
For more extensive examples, see: EXAMPLE
I2P(Garlic) Usage:
When using it to manage an I2P session, set up an onramp.Garlic
struct.
package main
import (
"log"
"github.com/go-i2p/onramp"
)
func main() {
garlic := &onramp.Garlic{}
defer garlic.Close()
listener, err := garlic.Listen()
if err != nil {
log.Fatal(err)
}
defer listener.Close()
}
Tor(Onion) Usage:
When using it to manage a Tor session, set up an onramp.Onion
struct.
package main
import (
"log"
"github.com/go-i2p/onramp"
)
func main() {
onion := &onramp.Onion{}
defer garlic.Close()
listener, err := onion.Listen()
if err != nil {
log.Fatal(err)
}
defer listener.Close()
}
Verbosity
Logging can be enabled and configured using the DEBUG_I2P environment variable. By default, logging is disabled.
There are three available log levels:
- Debug
export DEBUG_I2P=debug
- Warn
export DEBUG_I2P=warn
- Error
export DEBUG_I2P=error
If DEBUG_I2P is set to an unrecognized variable, it will fall back to "debug".
Contributing
See CONTRIBUTING.md for more information.
License
This project is licensed under the MIT license, see LICENSE for more information.
Documentation
¶
Index ¶
- Constants
- Variables
- func CloseAllGarlic()
- func CloseAllOnion()
- func CloseGarlic(tunName string)
- func CloseOnion(tunName string)
- func CreateTLSCertificate(tlsHost string) error
- func DeleteGarlicKeys(tunName string) error
- func DeleteI2PKeyStore() error
- func DeleteOnionKeys(tunName string) error
- func DeleteTLSKeyStore() error
- func DeleteTorKeyStore() error
- func Dial(network, addr string) (net.Conn, error)
- func DialGarlic(network, addr string) (net.Conn, error)
- func DialOnion(network, addr string) (net.Conn, error)
- func GetJoinedWD(dir string) (string, error)
- func GetOnrampLogger() *logrus.Logger
- func I2PKeys(tunName, samAddr string) (i2pkeys.I2PKeys, error)
- func I2PKeystorePath() (string, error)
- func InitializeOnrampLogger()
- func Listen(network, keys string) (net.Listener, error)
- func ListenGarlic(network, keys string) (net.Listener, error)
- func ListenOnion(network, keys string) (net.Listener, error)
- func NewTLSCertificate(host string, priv *ecdsa.PrivateKey) ([]byte, error)
- func NewTLSCertificateAltNames(priv *ecdsa.PrivateKey, hosts ...string) ([]byte, error)
- func Proxy(list net.Listener, raddr string) error
- func TLSKeys(tlsHost string) (tls.Certificate, error)
- func TLSKeystorePath() (string, error)
- func TorKeys(keyName string) (ed25519.KeyPair, error)
- func TorKeystorePath() (string, error)
- type Garlic
- func (g *Garlic) Close() error
- func (g *Garlic) DeleteKeys() error
- func (g *Garlic) Dial(net, addr string) (net.Conn, error)
- func (g *Garlic) DialContext(ctx context.Context, net, addr string) (net.Conn, error)
- func (g *Garlic) Keys() (*i2pkeys.I2PKeys, error)
- func (g *Garlic) Listen(args ...string) (net.Listener, error)
- func (g *Garlic) ListenPacket() (net.PacketConn, error)
- func (g *Garlic) ListenStream() (net.Listener, error)
- func (g *Garlic) ListenTLS(args ...string) (net.Listener, error)
- func (g *Garlic) Network() string
- func (g *Garlic) NewListener(n, addr string) (net.Listener, error)
- func (g *Garlic) OldListen(args ...string) (net.Listener, error)
- func (g *Garlic) String() string
- func (g *Garlic) TLSKeys() (tls.Certificate, error)
- type NullConn
- func (nc *NullConn) Close() error
- func (nc *NullConn) LocalAddr() net.Addr
- func (nc *NullConn) Read(b []byte) (n int, err error)
- func (nc *NullConn) RemoteAddr() net.Addr
- func (nc *NullConn) SetDeadline(t time.Time) error
- func (nc *NullConn) SetReadDeadline(t time.Time) error
- func (nc *NullConn) SetWriteDeadline(t time.Time) error
- func (nc *NullConn) Write(b []byte) (n int, err error)
- type Onion
- func (o *Onion) Close() error
- func (g *Onion) DeleteKeys() error
- func (o *Onion) Dial(net, addr string) (net.Conn, error)
- func (o *Onion) Keys() (ed25519.KeyPair, error)
- func (o *Onion) Listen(args ...string) (net.Listener, error)
- func (o *Onion) ListenTLS(args ...string) (net.Listener, error)
- func (o *Onion) NewListener(n, addr string) (net.Listener, error)
- func (o *Onion) OldListen(args ...string) (net.Listener, error)
- func (o *Onion) TLSKeys() (tls.Certificate, error)
- type OnrampProxy
Constants ¶
const ( DEST_BASE32 = 0 DEST_HASH = 1 DEST_HASH_BYTES = 2 DEST_BASE32_TRUNCATED = 3 DEST_BASE64 = 4 DEST_BASE64_BYTES = 5 )
Variables ¶
var ( OPT_DEFAULTS = sam3.Options_Default OPT_WIDE = sam3.Options_Wide )
var ( OPT_HUGE = sam3.Options_Humongous OPT_LARGE = sam3.Options_Large OPT_MEDIUM = sam3.Options_Medium OPT_SMALL = sam3.Options_Small )
var I2P_KEYSTORE_PATH = i2pdefault
I2P_KEYSTORE_PATH is the place where I2P Keys will be saved. it defaults to the directory "i2pkeys" current working directory. reference it by calling I2PKeystorePath() to check for errors
var ONION_KEYSTORE_PATH = tordefault
ONION_KEYSTORE_PATH is the place where Onion Keys will be saved. it defaults to the directory "onionkeys" current working directory. reference it by calling OnionKeystorePath() to check for errors
var SAM_ADDR = "127.0.0.1:7656"
SAM_ADDR is the default I2P SAM address. It can be overridden by the struct or by changing this variable.
var TLS_KEYSTORE_PATH = tlsdefault
TLS_KEYSTORE_PATH is the place where TLS Keys will be saved. it defaults to the directory "tlskeys" current working directory. reference it by calling TLSKeystorePath() to check for errors
Functions ¶
func CloseAllGarlic ¶
func CloseAllGarlic()
CloseAllGarlic closes all garlics managed by the onramp package. It does not affect objects instantiated by an app.
func CloseAllOnion ¶
func CloseAllOnion()
CloseAllOnion closes all onions managed by the onramp package. It does not affect objects instantiated by an app.
func CloseGarlic ¶
func CloseGarlic(tunName string)
CloseGarlic closes the Garlic at the given index. It does not affect Garlic objects instantiated by an app.
func CloseOnion ¶
func CloseOnion(tunName string)
CloseOnion closes the Onion at the given index. It does not affect Onion objects instantiated by an app.
func CreateTLSCertificate ¶
CreateTLSCertificate generates a TLS certificate for the given hostname, and stores it in the TLS keystore for the application. If the keys already exist, generation is skipped.
func DeleteGarlicKeys ¶
DeleteGarlicKeys deletes the key file at the given path as determined by keystore + tunName. This is permanent and irreversible, and will change the onion service address.
func DeleteOnionKeys ¶
DeleteOnionKeys deletes the key file at the given path as determined by keystore + tunName.
func DeleteTorKeyStore ¶
func DeleteTorKeyStore() error
DeleteTorKeyStore deletes the Onion Keystore.
func Dial ¶
Dial returns a connection for the given network and address. network is ignored. If the address ends in i2p, it returns an I2P connection. if the address ends in anything else, it returns a Tor connection.
func DialGarlic ¶
DialGarlic returns a net.Conn for a garlic structure's keys corresponding to a structure managed by the onramp library and not instantiated by an app.
func DialOnion ¶
DialOnion returns a net.Conn for a onion structure's keys corresponding to a structure managed by the onramp library and not instantiated by an app.
func GetJoinedWD ¶
GetJoinedWD returns the working directory joined with the given path.
func GetOnrampLogger ¶
GetI2PKeysLogger returns the initialized logger
func I2PKeys ¶
I2PKeys returns the I2PKeys at the keystore directory for the given tunnel name. If none exist, they are created and stored.
func I2PKeystorePath ¶
I2PKeystorePath returns the path to the I2P Keystore. If the path is not set, it returns the default path. If the path does not exist, it creates it.
func InitializeOnrampLogger ¶
func InitializeOnrampLogger()
func Listen ¶
Listen returns a listener for the given network and address. if network is i2p or garlic, it returns an I2P listener. if network is tor or onion, it returns an Onion listener. if keys ends with ".i2p", it returns an I2P listener.
func ListenGarlic ¶
ListenGarlic returns a net.Listener for a garlic structure's keys corresponding to a structure managed by the onramp library and not instantiated by an app.
func ListenOnion ¶
ListenOnion returns a net.Listener for a onion structure's keys corresponding to a structure managed by the onramp library and not instantiated by an app.
func NewTLSCertificate ¶
func NewTLSCertificate(host string, priv *ecdsa.PrivateKey) ([]byte, error)
NewTLSCertificate generates a new TLS certificate for the given hostname, returning it as bytes.
func NewTLSCertificateAltNames ¶
func NewTLSCertificateAltNames(priv *ecdsa.PrivateKey, hosts ...string) ([]byte, error)
NewTLSCertificateAltNames generates a new TLS certificate for the given hostname, and a list of alternate names, returning it as bytes.
func TLSKeys ¶
func TLSKeys(tlsHost string) (tls.Certificate, error)
TLSKeys returns the TLS certificate and key for the given hostname.
func TLSKeystorePath ¶
TLSKeystorePath returns the path to the TLS Keystore. If the path is not set, it returns the default path. If the path does not exist, it creates it.
func TorKeys ¶
TorKeys returns a key pair which will be stored at the given key name in the key store. If the key already exists, it will be returned. If it does not exist, it will be generated.
func TorKeystorePath ¶
TorKeystorePath returns the path to the Onion Keystore. If the path is not set, it returns the default path. If the path does not exist, it creates it.
Types ¶
type Garlic ¶
type Garlic struct {
*sam3.StreamListener
*sam3.StreamSession
*sam3.DatagramSession
ServiceKeys *i2pkeys.I2PKeys
*sam3.SAM
AddrMode int
TorrentMode bool
// contains filtered or unexported fields
}
Garlic is a ready-made I2P streaming manager. Once initialized it always has a valid I2PKeys and StreamSession.
func NewGarlic ¶
NewGarlic returns a new Garlic struct. It is immediately ready to use with I2P streaming.
func (*Garlic) DeleteKeys ¶
func (*Garlic) DialContext ¶
DialContext returns a net.Conn for the Garlic structure's I2P keys.
func (*Garlic) Keys ¶
Keys returns the I2PKeys for the Garlic structure. If none exist, they are created and stored.
func (*Garlic) Listen ¶
Listen returns a net.Listener for the Garlic structure's I2P keys. accepts a variable list of arguments, arguments after the first one are ignored.
func (*Garlic) ListenPacket ¶
func (g *Garlic) ListenPacket() (net.PacketConn, error)
ListenPacket returns a net.PacketConn for the Garlic structure's I2P keys.
func (*Garlic) ListenStream ¶
Listen returns a net.Listener for the Garlic structure's I2P keys.
func (*Garlic) ListenTLS ¶
ListenTLS returns a net.Listener for the Garlic structure's I2P keys, which also uses TLS either for additional encryption, authentication, or browser-compatibility.
func (*Garlic) NewListener ¶
NewListener returns a net.Listener for the Garlic structure's I2P keys. accepts a variable list of arguments, arguments after the first one are ignored.
type NullConn ¶
func (*NullConn) RemoteAddr ¶
type Onion ¶
type Onion struct {
*tor.StartConf
*tor.ListenConf
*tor.DialConf
context.Context
// contains filtered or unexported fields
}
Onion represents a structure which manages an onion service and a Tor client. The onion service will automatically have persistent keys.
func (*Onion) DeleteKeys ¶
DeleteKeys deletes the keys at the given key name in the key store. This is permanent and irreversible, and will change the onion service address.
func (*Onion) Listen ¶
Listen returns a net.Listener which will listen on an onion address, and will automatically generate a keypair and store it. the args are always ignored
func (*Onion) ListenTLS ¶
ListenTLS returns a net.Listener which will apply TLS encryption to the onion listener, which will not be decrypted until it reaches the browser
func (*Onion) NewListener ¶
NewListener returns a net.Listener which will listen on an onion address, and will automatically generate a keypair and store it. the args are always ignored
type OnrampProxy ¶
func (*OnrampProxy) Proxy ¶
func (p *OnrampProxy) Proxy(list net.Listener, raddr string) error
Proxy passes requests from a net.Listener to a remote server without touching them in any way. It can be used as a shortcut, set up a Garlic or Onion Listener and pass it, along with the address of a locally running service and the hidden service listener will expose the local service. Pass it a regular net.Listener(or a TLS listener if you like), and an I2P or Onion address, and it will act as a tunnel to a listening hidden service somewhere.
Source Files