Secret Hygiene

The secure, salt, password, and subtle/random helpers — zeroization, salt management, password policy, and randomness, with an honest account of what each actually guarantees.

Four small packages that surround the cryptography rather than performing it: wiping key material after use, generating and tracking salts, enforcing a password policy at signup, and getting random bytes. None of them is load-bearing for confidentiality — a correct aead call with a correctly derived key is secure whether or not you zeroize afterwards — but they are the difference between a key living for microseconds and living until the process exits into a core dump.

They are also the least polished corner of this library. Several helpers are duplicated across packages, one guarantee is weaker than its name suggests, and one type is not safe for concurrent use. Everything below states what the code does.

secure — zeroization and wrapped secrets

github.com/sonr-io/crypto/secure provides free functions for wiping and comparing byte slices, plus three container types that wipe themselves.

The guarantee, precisely

Free functions

SecureRandom is the randomness call to prefer in this library: it reports failure instead of panicking, unlike subtle/random.

SecureBytes

A mutex-guarded byte buffer with a runtime.SetFinalizer that wipes it if you forget to. Grounded in secure/memory_test.go (TestSecureBytes):

package main

import (
	"fmt"

	"github.com/sonr-io/crypto/secure"
)

func main() {
	// Allocate a zeroed 32-byte secret holder.
	sb := secure.NewSecureBytes(32)
	defer sb.Clear() // idempotent; also removes the finalizer

	// Bytes() hands back a copy, so writes must go through CopyTo.
	scratch := make([]byte, sb.Size())
	if err := secure.SecureRandom(scratch); err != nil {
		panic(err)
	}
	if err := sb.CopyTo(scratch); err != nil {
		panic(err)
	}
	secure.Zeroize(scratch) // wipe the intermediate immediately

	fmt.Println(sb.Size(), sb.IsEmpty()) // 32 false

	// Wrapping existing material copies it — the source stays independent.
	raw := []byte{1, 2, 3, 4, 5}
	wrapped := secure.FromBytes(raw)
	secure.Zeroize(raw) // wiping the original does not affect `wrapped`

	out := wrapped.Bytes() // a fresh copy: your responsibility now
	fmt.Println(out)       // [1 2 3 4 5]
	secure.Zeroize(out)
	wrapped.Clear()
}

SecureString

NewSecureString(s string) wraps a string; String() returns the value (or "" once cleared), IsEmpty() reports finalized-or-empty, and Clear() calls ZeroizeString and marks it finalized. Given the ZeroizeString limitation above, this type buys you a “cleared” flag and a mutex, not erasure. Prefer SecureBytes.

SecureBuffer

A fixed-capacity append-only buffer for assembling sensitive data.

salt

github.com/sonr-io/crypto/salt wraps salt bytes in a type that redacts itself in logs, compares in constant time, and can wipe itself — plus an in-memory keyed store.

Generate(size) errors outside [16, 1024]; GenerateDefault() is Generate(32); FromBytes(data) applies the same bounds and copies the input so later mutation of your slice cannot change the salt.

package main

import (
	"fmt"

	"github.com/sonr-io/crypto/argon2"
	"github.com/sonr-io/crypto/salt"
)

func main() {
	s, err := salt.GenerateDefault() // 32 bytes
	if err != nil {
		panic(err)
	}
	defer s.Clear()

	fmt.Println(s.Size())      // 32
	fmt.Println(s.String())    // Salt{size=32} — value is never printed
	fmt.Println(s.IsEmpty())   // false

	key := argon2.New(argon2.DefaultConfig()).DeriveKey([]byte("pw"), s.Bytes())
	fmt.Println(len(key))      // 32

	// Round-tripping a persisted salt.
	restored, err := salt.FromBytes(s.Bytes())
	if err != nil {
		panic(err)
	}
	fmt.Println(s.Equal(restored)) // true, compared in constant time
}

Every *Salt method is nil-receiver safe, which is unusual and worth knowing: a nil salt reports Size() == 0 and IsEmpty() == true rather than panicking.

SaltStore

NewSaltStore() returns a keyed collection with Store(id, salt), Retrieve(id), GenerateAndStore(id, size), Remove(id), List(), Size(), and Clear(). Store and Retrieve both copy, so the store never shares a backing array with your code, and Remove/Clear zeroize before deleting. An empty id is an error, as is storing a nil-or-empty salt or retrieving/removing an unknown id.

password

github.com/sonr-io/crypto/password is a policy checker, not a hasher — it never touches Argon2. Feed a candidate password through Validate at signup or change-password time, then hand it to argon2.

Those are the literal values in DefaultPasswordConfig(). NewValidator(nil) uses them.

package main

import (
	"fmt"

	"github.com/sonr-io/crypto/password"
)

func main() {
	v := password.NewValidator(nil) // DefaultPasswordConfig()

	// Rejected: 7 bytes < MinLength 12.
	fmt.Println(v.Validate([]byte("Short1!")))
	// password must be at least 12 characters

	// Rejected: no uppercase.
	fmt.Println(v.Validate([]byte("longenoughpassword123!")))
	// password must contain at least one uppercase letter

	// Accepted.
	fmt.Println(v.Validate([]byte("ValidPassword123!"))) // <nil>

	// Loosen the policy explicitly rather than editing the default.
	relaxed := password.NewValidator(&password.PasswordConfig{
		MinLength:        8,
		MaxLength:        64,
		RequireUppercase: false,
		RequireLowercase: true,
		RequireDigits:    true,
		RequireSpecial:   false,
		MinEntropy:       30.0,
	})
	fmt.Println(relaxed.Validate([]byte("simple123"))) // <nil>
}

Validate returns the first violated rule as a fmt.Errorf string, checked in order: min length, max length, uppercase, lowercase, digit, special, entropy. There is no aggregated result, so a UI that wants to show every failure must call it repeatedly with narrowed configs.

The three loose helpers are unrelated to validation: GenerateSalt(size) returns size random bytes and errors below 16; SecureCompare(a, b) is the same XOR loop as secure.SecureCompare; ZeroBytes(b) is the same wipe loop as secure.Zeroize minus the runtime.KeepAlive.

subtle random

github.com/sonr-io/crypto/subtle/random is nine lines of code with two functions:

Inside this repository, random is used by test code (for example the AES-SIV tests) rather than by production paths — which is roughly the right scope for a panicking API.

Duplicated helpers

The same two primitives are implemented three and four times over. They are not identical, and it matters which you call.

For salt generation, salt.Generate is the strictest: it enforces the 16-byte floor and a 1024-byte ceiling. password.GenerateSalt enforces only the 16-byte floor, and (*KDF).GenerateSalt enforces nothing beyond using the configured SaltLength.

Related