tUpdate pkg/lib doc - tordam - A library for peer discovery inside the Tor network
HTML git clone https://git.parazyd.org/tordam
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
DIR commit 49dd82602b3999181f99ff5b26acb3b77655825a
DIR parent 59ee6cc93167ffe4c259124bca08c81239513cab
HTML Author: parazyd <parazyd@dyne.org>
Date: Sat, 9 Dec 2017 17:35:07 +0100
Update pkg/lib doc
Diffstat:
M pkg/lib/crypto.go | 30 +++++++++++++++++++++++-------
M pkg/lib/helpers.go | 30 +++++++++++++++++++++++++-----
2 files changed, 48 insertions(+), 12 deletions(-)
---
DIR diff --git a/pkg/lib/crypto.go b/pkg/lib/crypto.go
t@@ -19,7 +19,8 @@ import (
"strings"
)
-// GenRsa generates a private RSA keypair of a given bitSize int.
+// GenRsa generates a private RSA keypair of a given bitSize int and returns it
+// as rsa.PrivateKey.
func GenRsa(bitSize int) (*rsa.PrivateKey, error) {
log.Printf("Generating %d-bit RSA keypair...\n", bitSize)
rng := rand.Reader
t@@ -31,6 +32,9 @@ func GenRsa(bitSize int) (*rsa.PrivateKey, error) {
}
// SavePub saves a given RSA public key to a given filename.
+// SavePub takes the filename to write as a string, and the key as
+// rsa.PublicKey. It returns a boolean value and an error, depending on whether
+// it has failed or not.
func SavePub(filename string, pubkey rsa.PublicKey) (bool, error) {
log.Printf("Writing pubkey to %s\n", filename)
// FIXME: worry or not about creating the path if it doesn't exist?
t@@ -59,6 +63,9 @@ func SavePub(filename string, pubkey rsa.PublicKey) (bool, error) {
}
// SavePriv saves a given RSA private key to a given filename.
+// SavePriv takes the filename to write as a string, and the key as
+// *rsa.PrivateKey. It returns a boolean value and an error, depending on whether
+// it has failed or not.
func SavePriv(filename string, privkey *rsa.PrivateKey) (bool, error) {
log.Printf("Writing private key to %s\n", filename)
// FIXME: worry or not about creating the path if it doesn't exist?
t@@ -83,6 +90,9 @@ func SavePriv(filename string, privkey *rsa.PrivateKey) (bool, error) {
}
// LoadKeyFromFile loads a RSA private key from a given filename.
+// LoadKeyFromFile takes a string filename and tries to read from it, parsing
+// the private RSA key. It will return a *rsa.PrivateKey on success, and error
+// on fail.
func LoadKeyFromFile(filename string) (*rsa.PrivateKey, error) {
log.Println("Loading RSA private key from", filename)
dat, err := ioutil.ReadFile(filename)
t@@ -101,6 +111,8 @@ func LoadKeyFromFile(filename string) (*rsa.PrivateKey, error) {
}
// SignMsg signs a given []byte message using a given RSA private key.
+// It will return the signature as a slice of bytes on success, and error on
+// failure.
func SignMsg(message []byte, privkey *rsa.PrivateKey) ([]byte, error) {
log.Println("Signing message...")
rng := rand.Reader
t@@ -113,7 +125,8 @@ func SignMsg(message []byte, privkey *rsa.PrivateKey) ([]byte, error) {
}
// EncryptMsg encrypts a given []byte message using a given RSA public key.
-// Returns the encrypted message in []byte form.
+// Returns the encrypted message as a slice of bytes on success, and error on
+// failure.
func EncryptMsg(message []byte, pubkey *rsa.PublicKey) ([]byte, error) {
log.Println("Encrypting message...")
rng := rand.Reader
t@@ -125,7 +138,8 @@ func EncryptMsg(message []byte, pubkey *rsa.PublicKey) ([]byte, error) {
}
// DecryptMsg decrypts a given []byte message using a given RSA private key.
-// Returns the decrypted message in []byte form.
+// Returns the decrypted message as a slice of bytes on success, and error on
+// failure.
func DecryptMsg(message []byte, privkey *rsa.PrivateKey) ([]byte, error) {
log.Println("Decrypting message...")
rng := rand.Reader
t@@ -136,8 +150,8 @@ func DecryptMsg(message []byte, privkey *rsa.PrivateKey) ([]byte, error) {
return msg, nil
}
-// VerifyMsg verifies a []byte message and []byte signature against a given
-// RSA pubkey.
+// VerifyMsg verifies a message and signature against a given RSA pubkey.
+// Returns a boolean value and error depending on whether it has failed or not.
func VerifyMsg(message []byte, signature []byte, pubkey *rsa.PublicKey) (bool, error) {
log.Println("Verifying message signature")
hashed := sha512.Sum512(message)
t@@ -150,6 +164,8 @@ func VerifyMsg(message []byte, signature []byte, pubkey *rsa.PublicKey) (bool, e
}
// OnionFromPubkey generates a valid onion address from a given RSA pubkey.
+// Returns the onion address as a slice of bytes on success and error on
+// failure.
func OnionFromPubkey(pubkey rsa.PublicKey) ([]byte, error) {
asn1Bytes, err := asn1.Marshal(pubkey)
if err != nil {
t@@ -166,8 +182,8 @@ func OnionFromPubkey(pubkey rsa.PublicKey) ([]byte, error) {
return []byte(encoded), nil
}
-// ParsePubkey parses a []byte form of a RSA public key and returns the proper
-// type.
+// ParsePubkey parses a []byte form of a RSA public key and returns it as
+// *rsa.PublicKey on success. Otherwise, error.
func ParsePubkey(pubkey []byte) (*rsa.PublicKey, error) {
var pub rsa.PublicKey
var ret *rsa.PublicKey
DIR diff --git a/pkg/lib/helpers.go b/pkg/lib/helpers.go
t@@ -20,7 +20,8 @@ import (
// ProxyAddr is the address of our Tor SOCKS port.
const ProxyAddr = "127.0.0.1:9050"
-// CheckError is a handler for errors.
+// CheckError is a handler for errors. It takes an error type as an argument,
+// and issues a log.Fatalln, printing the error and exiting with os.Exit(1).
func CheckError(err error) {
if err != nil {
log.Fatalln(err)
t@@ -28,7 +29,8 @@ func CheckError(err error) {
}
// FetchHSPubkey fetches a hidden service's RSA pubkey by running an external
-// program, giving it an onion address.
+// program, giving it an onion address. It returns the retrieved public key as a
+// string.
func FetchHSPubkey(addr string) string {
var outb, errb bytes.Buffer
t@@ -49,7 +51,22 @@ func FetchHSPubkey(addr string) string {
return outb.String()
}
-// ValidateReq validates our given request against some checks.
+// ValidateReq validates our given request against the logic we are checking.
+// The function takes a request data map, and a public key in the form of a
+// string. If the public key is an empty string, the function will run an
+// external program to fetch the node's public key from a Tor HSDir.
+//
+// ValidateReq will first validate "nodetype", looking whether the announcer
+// is a node or a directory.
+// Then, it will validate the onion address using a regular expression.
+// Now, if pubkey is empty, it will run the external program to fetch it. If a
+// descriptor can't be retrieved, it will retry for 10 times, and fail if those
+// are not successful.
+//
+// Continuing, ValidateReq will verify the RSA signature posted by the
+// announcer.
+// If any of the above are invalid, the function will return nil and false.
+// Otherwise, it will return the pubkey as a slice of bytes, and true.
func ValidateReq(req map[string]string, pubkey string) ([]byte, bool) {
// Validate nodetype.
if req["nodetype"] != "node" {
t@@ -97,8 +114,11 @@ func ValidateReq(req map[string]string, pubkey string) ([]byte, bool) {
return []byte(pubkey), true
}
-// HTTPPost sends an HTTP POST request to the given host. It sends data as
-// application/json.
+// HTTPPost sends an HTTP POST request to the given host.
+// Takes the host to request and the data to post as arguments.
+// If the host ends with ".onion", it will enable the request to be performed
+// over a SOCKS proxy, defined in ProxyAddr.
+// On success, it will return the http.Response. Otherwise, it returns an error.
func HTTPPost(host string, data []byte) (*http.Response, error) {
socksify := false
parsedHost, err := url.Parse(host)