From d0a6faa4e66fc12c97be6b0d63440bd51c7686a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Thu, 2 Feb 2023 13:12:47 +0000 Subject: [PATCH] README: rewrite seeds section A user correctly points out that some sentences were confusing, like: It can also make reverse-engineering harder, as an end user could guess what version of Go or garble you're using. Rewrite the whole section. It now also explains what I meant by that sentence with a practical example. I also merged the bits about "provide your own seed" and "rotating the seeds", because they're both talking about the same mechanism. Fixes #666. --- README.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index de76167..16e4a25 100644 --- a/README.md +++ b/README.md @@ -103,18 +103,16 @@ which will change if its build input changes: the version of garble, the version of Go, the package's source code, or any build parameter such as GOOS or -tags. This is a reasonable default since guessing those inputs is very hard. -However, providing your own obfuscation seed via `-seed` brings some advantages. -For example, builds sharing the same seed will produce the same obfuscation, -even if any of the build parameters or versions vary. -It can also make reverse-engineering harder, as an end user could guess what -version of Go or garble you're using. - -Note that extra care should be taken when using custom seeds. -If a seed used to build a binary gets lost, `garble reverse` will not work. -Rotating the seeds can also help against reverse-engineering in the long run, -as otherwise some bits of code may be obfuscated the same way over time. - -An alternative approach is `-seed=random`, where each build is entirely different. +You can use the `-seed` flag to provide your own obfuscation randomness seed. +Reusing the same seed can help produce the same code obfuscation, +which can help when debugging or reproducing problems. +Regularly rotating the seed can also help against reverse-engineering in the long run, +as otherwise one can look at changes in how Go's standard library is obfuscated +to guess when the Go or garble versions were changed across a series of builds. + +To always use a different seed for each build, use `-seed=random`. +Note that extra care should be taken when using custom seeds: +if a `-seed` value used in a build is lost, `garble reverse` will not work. ### Caveats