Merge branch 'release/0.1.0'

Author: axllent

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.1.0]
+
+- Add timeout option (#16)
+
+
 ## [0.0.9]
 
 - Add regex support (#13)
@@ -27,7 +32,7 @@
 
 ## [0.0.5]
 
-- Allow for inclusion as a module (see #2)
+- Allow for inclusion as a module (#2)
 
 
 ## [0.0.4]

README.md

@@ -2,7 +2,9 @@
 
 [![Go Report Card](https://goreportcard.com/badge/github.com/axllent/wireguard-vanity-keygen)](https://goreportcard.com/report/github.com/axllent/wireguard-vanity-keygen)
 
-A command-line vanity (public) key generator for [WireGuard](https://www.wireguard.com/). It only matches the prefix of generated public keys, and not whether the search matches anywhere in the public key. The concept is based on [wireguard-vanity-address](https://github.com/warner/wireguard-vanity-address), however I wanted something a little more streamlined.
+A command-line vanity (public) key generator for [WireGuard](https://www.wireguard.com/). By default, it only matches the prefix of generated public keys,
+and not whether the search matches anywhere in the public key. The concept is based on
+[wireguard-vanity-address](https://github.com/warner/wireguard-vanity-address), however I wanted something a little more streamlined.
 
 
 ## Features
@@ -51,10 +53,17 @@ private gJtn0woDChGvyN2eSdc7mTpAFA/nA6jykJeK5bYYfFA=   public Pc7+UEJSHiWsQ9zkO2
 private IMyPmYm/v0SPmB62hC8l6kfxT3/Lfp7dMioo+SM6T2c=   public Pc7/uVfD/ZftxWBHwYbaudEywUS61biBcpj5Tw830Q4=
 ```
 
+
+## Installing
+
+Download the [latest binary release](https://github.com/axllent/wireguard-vanity-keygen/releases/latest) for your system,
+or build from source `go install github.com/axllent/wireguard-vanity-keygen@latest`.
+
+
 ## Timings
 
 To give you a rough idea of how long it will take to generate keys, the following table lists
-estimated timings for each match on a system that reported  "`Calculating speed: 230,000 calculations per second using 19 CPU cores`" when it started:
+estimated timings to find a matching key on a system that reported  "`Calculating speed: 230,000 calculations per second using 19 CPU cores`" when it started:
 
 | Length  | Case-insensitive | Case-sensitive |
 | :------ | :--------------- | :------------- |
@@ -66,14 +75,16 @@ estimated timings for each match on a system that reported  "`Calculating speed:
 | 8 chars | 7 months         | 38 years       |
 | 9 chars | 22 years         | 175 years      |
 
-Note that the above timings are for finding a result for any search term.
-Passing multiple search terms will not substantially increase the time,
-but increasing the limit to two (`--limit 2`) will double the estimated time, three will triple the time, etc.
+Note that the above timings are for finding a matching key for a single search term.
+Passing multiple search terms will not substantially increase the time to find any single term, but the time to find
+all search terms is the sum of all the estimated times.
+Also, increasing the limit to two (`--limit 2`) will double the estimated time, three will triple the time, etc.
 
 If any search term contains numbers, the timings would fall somewhere between the case-insensitive and case-sensitive columns.
 
 Of course, your mileage will differ, depending on the number, and speed, of your CPU cores.
 
+
 ## Regular Expressions
 
 Since each additional letter in a search term increases the search time exponentially, searching using a regular expression may
@@ -87,18 +98,14 @@ reduce the time considerably. Here are some examples:
 
 A good guide on Go's regular expression syntax is at https://pkg.go.dev/regexp/syntax.
 
-To include a `+` in your regular expression, preface it with a backslash, like `\+`.
+To include a literal `+` in your regular expression, preface it with a backslash: `^ex\+`.
 
 NOTE: If your search term contains shell metacharacters, such as `|`, or `^`, you will need to quote it.
 On Windows, you must use double quotes. For example: `"^(a|b)"`.
 
 NOTE: Complex regular expressions, such as those using escape sequences, flags, or character classes, may never match a key.
-To avoid that, consider testing your regex using a tool such as [this one](https://go.dev/play/p/6LJy51Wd08O).
-
-## Installing
-
-Download the [latest binary release](https://github.com/axllent/wireguard-vanity-keygen/releases/latest) for your system, 
-or build from source `go install github.com/axllent/wireguard-vanity-keygen@latest`.
+To avoid that, consider testing your regex using a tool such as [this one](https://go.dev/play/p/6LJy51Wd08O) on The Go Playground,
+ or the same tool on [goplay.tools](https://goplay.tools/snippet/6LJy51Wd08O).
 
 
 ## FAQ
@@ -109,16 +116,20 @@ Valid characters include `A-Z`, `a-z`, `0-9`, `/` and `+`. There are no other ch
 
 You can also use regex expressions to search.
 
+
 ### Why does `test` & `tes1` show different probabilities despite having 4 characters each?
 
 With case-insensitive searches (default), a-z have the chance of matching both uppercase and lowercase. A search for "cat" can match `Cat`, `cAT` etc.
 
 
 ### How accurate are the estimated times?
 
-They are not (and cannot be) accurate. Keys are completely randomly generated, and the estimate is based on a law of averages. For instance, you could find a match for a one in a billion chance on the very first hit, or it could take you 5 billion attempts. It will however give you an indication based on your CPU speed, word count, case sensitivity, and use of numbers or characters.
+They are not (and cannot be) accurate. Keys are completely randomly generated, and the estimate is based on a law of averages.
+For instance, you could find a match for a one in a billion chance on the very first hit, or it could take you 5 billion attempts.
+It will however give you an indication based on your CPU speed, word count, case sensitivity, and use of numbers or characters.
 
 
 ### Why do I need this?
 
-You don't. I wrote it because I run a WireGuard server, which does not provide any reference as to who the key belongs to (`wg` on the server). Using vanity keys, I can at least identify connections. I also wanted to learn more about multi-core processing in Golang.
+You don't. I wrote it because I run a WireGuard server, which does not provide any reference as to who the key belongs to (`wg` on the server).
+Using vanity keys, I can at least identify connections. I also wanted to learn more about multi-core processing in Golang.

keygen/utils.go

@@ -9,8 +9,8 @@ import (
 	"time"
 )
 
-// regexChars contains the list of regex metacharacters, excluding +,
-// which is valid in a key
+// regexChars contains the list of the metacharacters used in regular expressions,
+// but not including the + character, which is valid in a key
 const regexChars = `^$.|?*-[]{}()\`
 
 // regexWillNeverMatch is a shared error message that the regex will never match
@@ -113,21 +113,23 @@ func invalidRegexMsg(s string, errmsg string) string {
 
 // IsValidRegex checks the regex has any chance of matching a key
 func IsValidRegex(s string) string {
-	// A consise guide on golang's regex syntax is at
+	// A concise guide on golang's regex syntax is at
 	// https://pkg.go.dev/regexp/syntax
 
 	stripped := removeMetacharacters(s)
 	if !IsValidSearch(stripped) {
 		return InvalidSearchMsg(s)
 	}
 
-	// Expressions with '^' character
+	// Regexes containing the '^' character:
+
 	re := regexp.MustCompile(`.\^`)
 	if re.MatchString(s) {
 		return invalidRegexMsg(s, "The '^' character must appear at the beginning of the search term")
 	}
 
-	// Expressions with '$' character
+	// Regexes containing the '$' character:
+
 	re = regexp.MustCompile(`\$.`)
 	if re.MatchString(s) {
 		return invalidRegexMsg(s, "The '$' character must appear at the end of the search term")
@@ -141,23 +143,23 @@ func IsValidRegex(s string) string {
 		return invalidRegexMsg(s, "The '=' character can only appear at the end of a key")
 	}
 	// The command:
-	// wireguard-vanity-keygen -l 1000 . | grep private | cut -c 105- | sort -u | tr -d "=" | tr -d "\n"
+	// wireguard-vanity-keygen -l 1000 a | grep private | cut -c 105- | sort -u | tr -d "=" | tr -d "\n"
 	// outputs:
 	// 048AEIMQUYcgkosw
 	re = regexp.MustCompile(`[^048AEIMQUYcgkosw]=\$`)
 	if re.MatchString(s) {
 		return invalidRegexMsg(s, regexWillNeverMatch)
 	}
 
-	// Expressions with backslashes:
+	// Regexes containing backslashes:
 
 	// A regex of just a backslash and a single character will never match
 	re = regexp.MustCompile(`^\\.$`)
 	if re.MatchString(s) {
 		return invalidRegexMsg(s, regexWillNeverMatch)
 	}
 
-	// Control characters and many octal values will meter match, disallow them all
+	// Control characters and most octal values will never match, disallow them all
 	re = regexp.MustCompile(`\\[aftnrxswWpP0-7]`)
 	if re.MatchString(s) {
 		return invalidRegexMsg(s, regexWillNeverMatch)
@@ -169,7 +171,7 @@ func IsValidRegex(s string) string {
 		return invalidRegexMsg(s, regexWillNeverMatch)
 	}
 
-	// Expressions with character classes: [[:alnum:]], etc.
+	// Regexes containing character classes: [[:alnum:]], etc.
 
 	// [[:blank:]], [[:cntrl:]], [[:punct:]] and [[:space:]] will never match
 	re = regexp.MustCompile(`\[\[:(blank|cntrl|punct|space):\]\]`)
@@ -186,7 +188,7 @@ func IsValidRegex(s string) string {
 	return ""
 }
 
-// removeMetacharacters removes regex metacharacters from the string
+// removeMetacharacters removes regex metacharacters (except +) from the string
 func removeMetacharacters(s string) string {
 	// This logic isn't needed anymore, as we don't attempt to calculate the probability of regular expressions
 	// // remove (?i) from beginning of string
@@ -203,7 +205,7 @@ func removeMetacharacters(s string) string {
 	// s = re.ReplaceAllLiteralString(s, "x")
 
 	// strip out remaining regexp metacharacters
-	for _, rune1 := range []rune(regexChars) {
+	for _, rune1 := range regexChars {
 		s = strings.ReplaceAll(s, string(rune1), "")
 	}
 	return s

keygen/worker.go

@@ -1,6 +1,7 @@
 package keygen
 
 import (
+	"fmt"
 	"regexp"
 	"strings"
 	"sync"
@@ -13,6 +14,7 @@ type Options struct {
 	Threads       int
 	CaseSensitive bool
 	Cores         int
+	Timeout       string
 }
 
 // Cruncher struct
@@ -23,6 +25,8 @@ type Cruncher struct {
 	RegexpMap map[*regexp.Regexp]int
 	thread    chan int
 	Abort     bool // set to true to abort processing
+	timeout   time.Duration
+	timedout  bool
 }
 
 // Pair struct
@@ -32,12 +36,13 @@ type Pair struct {
 }
 
 // New returns a Cruncher
-func New(options Options) *Cruncher {
+func New(options Options, timeout time.Duration) *Cruncher {
 	return &Cruncher{
 		Options:   options,
 		WordMap:   make(map[string]int),
 		RegexpMap: make(map[*regexp.Regexp]int),
 		thread:    make(chan int, options.Cores),
+		timeout:   timeout,
 	}
 }
 
@@ -173,14 +178,50 @@ func (c *Cruncher) CollectToSlice() []Pair {
 
 // Find will invoke a callback function for each match to support some interactivity or at least feedback
 func (c *Cruncher) Find(cb func(match Pair)) {
+
+	if c.timeout == time.Duration(0) {
+		// If you change anything in this for block, make the corresponding change in
+		// the timeout-aware for block below this one.
+		for {
+			c.thread <- 1 // will block if there is MAX ints in threads
+			go func() {
+				if c.crunch(cb) {
+					c.Abort = true
+				}
+			}()
+			if c.Abort {
+				return
+			}
+		}
+	}
+
+	t := time.NewTimer(c.timeout)
+
+	// This is same code as immediately above, with only the timeout logic added.
+	// Since the code is simple enough, let's duplicate it, so we don't slow down
+	// the calculations with unnecessary logic, if the user didn't specify a timeout.
 	for {
 		c.thread <- 1 // will block if there is MAX ints in threads
-		go func() {
+		go func(t *time.Timer) {
 			if c.crunch(cb) {
 				c.Abort = true
+				return
 			}
-		}()
+			select {
+			case <-t.C:
+				c.timedout = true
+				c.Abort = true
+			default:
+			}
+		}(t)
 		if c.Abort {
+			if c.timedout {
+				fmt.Printf("Timed out after %v\n", c.timeout)
+			} else {
+				if !t.Stop() {
+					<-t.C
+				}
+			}
 			return
 		}
 	}

main.go

@@ -46,6 +46,7 @@ func main() {
 	flag.BoolVarP(&options.CaseSensitive, "case-sensitive", "c", false, "case sensitive match (default false)")
 	flag.IntVarP(&options.Threads, "threads", "t", options.Cores, "threads")
 	flag.IntVarP(&options.LimitResults, "limit", "l", 1, "limit results to n (exists after)")
+	flag.StringVarP(&options.Timeout, "timeout", "T", "", "quit after n minutes (allowed suffixes: s/m/h) (default \"\")")
 
 	flag.Parse(os.Args[1:])
 	args := flag.Args()
@@ -61,7 +62,13 @@ func main() {
 		options.Cores = options.Threads
 	}
 
-	c := keygen.New(options)
+	timeout, err := parseTimeout(options.Timeout)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Invalid timeout value: %s\n", err)
+		os.Exit(2)
+	}
+
+	c := keygen.New(options, timeout)
 
 	fmt.Printf("Calculating speed: ")
 
@@ -125,6 +132,10 @@ func main() {
 		c.RegexpMap[re] = options.LimitResults
 	}
 
+	if timeout > time.Duration(0) {
+		fmt.Printf("\nQuitting after %v, or sooner if all matching keys are found...\n", timeout)
+	}
+	
 	fmt.Printf("\nPress Ctrl-c to cancel\n\n")
 	if !summary {
 		c.Find(func(match keygen.Pair) {
@@ -136,3 +147,22 @@ func main() {
 		}
 	}
 }
+
+// parseTimeout parses the timeout string to a time.Duration. If the input is
+// solely digits, minutes is assumed
+func parseTimeout(t string) (time.Duration, error) {
+	if t == "" {
+		return time.Duration(0), nil
+	}
+
+	re := regexp.MustCompile(`^[\d\.]+$`)
+	if re.MatchString(t) {
+		t += "m"
+	}
+	complex, err := time.ParseDuration(t)
+	if err != nil {
+		return time.Duration(0), err
+	}
+
+	return complex, nil
+}