hq

package module
v0.1.40 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 22, 2025 License: BSD-3-Clause Imports: 25 Imported by: 0

README

OVERVIEW

Go Reference Go Report Card Go Build

paepcke.de/hq

  • keys and signatures based on a sphincs-blake3-512
  • no new post-quantum security assumtions needed
  • hash based signatures are well studied for decades (see NIST pq shootout)
  • optional: no private key [export|handling|storage] (password based)
  • default-project-disclaimer: DO NOT USE IN SECURITY CRITIAL PRODUCTION (YET)
  • 100 % pure go, minimal external imports, usable as app or api, see api.go

INSTALL

go install paepcke.de/hq/cmd/hq@latest
DOWNLOAD (prebuild)

github.com/paepckehh/hq/releases

SHOWTIME

generate key pair [hq identity]

hq genrate
# Owner ID      : [email protected]
# Passphrase ONE: **************
# Repeat     ONE: **************
# Passphrase TWO: **************
# Repeat     TWO: **************
# Layer  ############.#########.#######.#######.######.#####.###########.#########.#######.##.#!
# Name TAG      : TIES25-DE-NIIOAS-SO-F42EMA6WOW
# Time needed   : 1.132897239s
  • Public Key will be stored in ~/.hq/NameTAG, current active key will be marked via setting symbolic link 'me' -NameTAG

sign a file

hq sign file.txt
# Owner ID      : [email protected]
# Name TAG      : 6HZVBF-QJ-AFFNEA-JF-JVROQIBRRP
# Passphrase ONE: **************
# Passphrase TWO: **************
# File Name     : text.txt
# Time Stamp    : Sunday, 30-Oct-22 05:25:53 UTC [1667107553]
# Time needed   : 1.16469552ms

verify a file

hq verify file.txt  
# Please unlock your HQ Identity! [pending file sign operation: text.txt]
# Owner ID      : [email protected]
# Name TAG      : 6HZVBF-QJ-AFFNEA-JF-JVROQIBRRP                                             [CONFIRMED]
# File Name     : text.txt.hqs                                                               [CONFIRMED]
# Time Stamp    : Sunday, 30-Oct-22 05:25:53 UTC [1667107553]                                [CONFIRMED]
# Time needed   : 5.833229ms
  • [via pipe: cat ./test.text.hqs | hq] or [run signature: ./text.txt.hqs]

sign an executable

hq sign testscript.sh
[...]

run the executeable

./testscript.hqs
[...]
  • the executable will test its integrity, signatures and will report the state
  • will only exexcute if it finds an trusted hq identiy [public key] in your ~/.hq keystore

sign a directory

hq sign .
# Files FAIL    : 0
# Files OK      : 4
# Files Total   : 4
# Time needed   : 61.891615ms
# Owner ID      : [email protected]
# Name TAG      : 6HZVBF-QJ-AFFNEA-JF-JVROQIBRRP
# File Name     : .hqMAP.1667107763.2022-10-30T05.29.23Z.zst
# Time Stamp    : Sunday, 30-Oct-22 05:29:23 UTC [1667107763]
# Time needed   : 4.331267865s
  • .hqMAP..zst contains the state of every file as [easy-to-use-and-verify-ieverywhere] blake3 checksum
  • .hqMAP..zst.hqs signs the hqMAP

verify a directory

echo "MODIFICATION" >text.txt
hq verify .
# File Name     : text.txt
# Error Code    : FILE MODIFIED [FILE HASH MISSMATCH]
# File Expected : ac169ead597dac88b2d7223edd85c9895392532cfc7a3c5c29a3fbe3ccba37f2
# File Found    : 5eeef57bc6267c9804f8de7f75f0fac4af3b159f04b4a8a302c28f67450ed6b3
# Files FAIL    : 1
# Files OK      : 3
# Files Total   : 4
# Time needed   : 58.889271ms
# Owner ID      : [email protected]
# Name TAG      : 6HZVBF-QJ-AFFNEA-JF-JVROQIBRRP                                             [CONFIRMED]
# File Name     : .hqMAP.1667107836.2022-10-30T05.30.36Z.zst.hqs                             [CONFIRMED]
# Time Stamp    : Sunday, 30-Oct-22 05:30:36 UTC [1667107836]                                [CONFIRMED]
# Time needed   : 877.292µs

SHOWTIME ADVANCED

generate additional [legacy] OpenBSD signify keys and signatures

export HQ_ADD_SIGNIFY=true
hq generate
hq sign
[...]

sign a directory, generate additional codereview hash [filters the noise/signal of source code changes]

hq c .
  • The additional code review hash will only change if compiler/codegeneration relevant changes where performed.
  • Changes on comments, formating, re-order of arguments, functions, renames, will not lead to a executable code & hash change.

Unlock and lock the hq identity private key for subsequent sign operations

hq unlock
[...]
hq lock

every sub-command has a one-letter-short-form

hq s .  [equals: hq sign .]
hq v .  [equals: hq verify .]
[...]

what else ?

hq help
 usage: hq <action<opt:target<opt:timestamp|exec-parameter>

 action:
 [s]ign      sign mode for <target>
 [c]ode      sign mode for <target>, include additional code-review hashes
 [v]erify    verify mode for <target>
 [r]un       run .hqx exec container
 [g]enerate  generate new hq id [or: re-produce public key]
 [u]nlock    unlock id [raw sphincs key]
 [l]ock      lock [remove] cached raw sphincs key
 [p]wd       generate hq id and <targetspecific password
 [x]pwd      generate hq id and <targetspecific legacy password
 [t]est      verify crypto functions via hard-wired test vector suite
 [b]ench     benchmark
 [h]elp      show help

<hqx>|<hqs>|<dir>|<pipe>|<exec- object typ will pick the action

ENV
 FORCE_COLOR=true          color terminal output
 HQ_ADD_SIGNIFY=true       generate additional OpenBSD signify compatible .sig signatures
 HQ_SIG_ONLY=true          to sign executeables as .hqs
 HQ_MAP_ONLY=true          to generate .hqMAP files without signature
 HQ_MAP_CLEAN=true         to remove all existing .hqMAP[s] on <target>
 HQ_OWNER                  set owner for generate operations [batch mode]

EXTERNAL RESOURCES

Special thanks goes to:

DOCS

pkgo.dev/paepcke.de/hq

CONTRIBUTION

Yes, Please! PRs Welcome!

Documentation

Overview

Package hq implements sphincs-blake3-512 hypertree signatures

package hq ...

package hq

Index

Constants

View Source 
const (
	// PublicKeySize
	PublicKeySize = sphincs.PublicKeySize
	// PrivateKeySize
	PrivateKeySize = sphincs.PrivateKeySize
	// SignatureSize
	SignatureSize = sphincs.SignatureSize
	// HashSize
	HashSize = 64
)

const

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

type Config struct {
	Action          string   // Requested Action [sign|verify|generate|bench]
	Target          string   // Requested Target [dir|file]
	TargetTS        string   // Requested Target TimeStamp
	FileName        string   // FileName
	File            *os.File // FileHandle
	Signify         bool     // enable optional OpenBSD signify signatures
	CodeReview      bool     // enable additional code-review hashes for source code files
	Silent          bool     // enable silent mode [eg. for benchmarking]
	IsExec          bool     // true if executeable mode is detected
	IsPipe          bool     // true if exec mode is detected
	MapOnly         bool     // true if exec mode is detected
	RunExec         bool     // true if run mode [not display mode] is requested
	PwdComplex      bool     // true if complex legacy password is requested
	PlainTextScript bool     // run plaintext sh script interpreter
	TokenExec       string   // magic token to determine exec type for execution
	PwdService      string   // the [legacy] password service name [psn]
	ScriptExtL      int      // lengh of extension name
}

Config ...

func NewConfig 

func NewConfig() *Config

NewConfig ...

func (*Config) Bench 

func (c *Config) Bench() bool

Bench ...

func (*Config) CryptoVerify 

func (c *Config) CryptoVerify() bool

CryptoVerify ...

func (*Config) DirSign 

func (c *Config) DirSign() bool

DirSign ...

func (*Config) DirVerify 

func (c *Config) DirVerify() bool

DirVerify ...

func (*Config) FileSign 

func (c *Config) FileSign() bool

FileSign ...

func (*Config) FileSignExecuteable 

func (c *Config) FileSignExecuteable() bool

FileSignExecuteable ...

func (*Config) FileVerify 

func (c *Config) FileVerify() bool

FileVerify ...

func (*Config) FileVerifyExecuteable 

func (c *Config) FileVerifyExecuteable() bool

FileVerifyExecuteable verifies and executes an hq singed hqx container

func (*Config) Generate 

func (c *Config) Generate() bool

Generate sphincs keypair

func (*Config) LegacyPass 

func (c *Config) LegacyPass() bool

LegacyPass is a [k]ey[d]erivation[f]unction for legacy passwords

func (*Config) Lock 

func (c *Config) Lock() bool

Lock cleans the Unlock() exposed raw key

func (*Config) ParseCmd 

func (c *Config) ParseCmd()

ParseCmd ...

func (*Config) RunAction 

func (c *Config) RunAction() bool

RunAction ...

func (*Config) RunExecPlain 

func (c *Config) RunExecPlain() bool

RunExecPlain ...

func (*Config) Unlock 

func (c *Config) Unlock() bool

Unlock unlocks the raw sphincs key for subsequent batch operations

type HQ 

type HQ struct {
	// ID identiy
	ID
	// IO exchange
	IO
}

HQ ...

func NewHQ 

func NewHQ(c *Config) *HQ

NewHQ ...

type ID 

type ID struct {
	OWNER [HashSize]byte      // OWNER ID
	TAG   [30]byte            // NAME TAG
	KEY   [PublicKeySize]byte // SPHINCS Public Key
}

ID identiy

type IO 

type IO struct {
	HashPassONE     [HashSize]byte       // hashed password token
	HashPassTWO     [HashSize]byte       // hashed password token
	MSG             [HashSize]byte       // message[hash] to [sign|verify]
	MSGRAW          []byte               // pointer to raw message
	SCRIPT          []byte               // compressed and base64 encoded exec
	TokenExec       string               // magic token to determine exec type for execution
	ScriptExtL      int                  // lengh of extension name
	DirName         string               // Report DirName
	FileName        string               // Report FileName
	FilesTotal      uint64               // total number of files
	FilesFail       uint64               // total number of files with hash|checksum errors
	FilesNew        uint64               // total number of files with hash|checksum errors
	Signify         bool                 // enable optional OpenBSD signify signatures
	PlainTextScript bool                 // Plain Text Posix script interp mode
	MapClean        bool                 // true if we need to wipe old maps
	Silent          bool                 // silent mode for benchmarking
	UnlockedKey     bool                 // true if /.hq/.unlocked key was found
	IsExec          bool                 // true if exec mode
	ReportID        bool                 // Report Status [summary]
	ReportTime      bool                 // Report Status [summary]
	ReportValid     bool                 // Report Status [summary]
	ColorUI         bool                 // enable CLI ColorUI
	SetMe           bool                 // Set Me Key Symbolic Link
	PwdEnv          bool                 // true if pass creds from env
	CPU             int                  // number of CPU cores
	Start           time.Time            // Time Stamp Start Action
	End             time.Time            // Time Stamp End Action
	TSS             string               // POSIX TS (nanoseconds since 01/01/1970 00:00 UTC)
	SIG             [SignatureSize]byte  // RAW SPHINCS-256 signature
	PRIVKEY         [PrivateKeySize]byte // RAW SPHINCS-256 private key
	SIGNIFYMSG      []byte               // Encoded OpenBSD Signify Message
	SIGNIFYPUB      []byte               // Encoded OpenBSD Signify PublicKey
	SIGNIFYFILE     []byte               // Encoded OpenBSD Signify Signature
}

IO exchange

Source Files

View all Source files

Directories

Path Synopsis
Package blake3 provides an SSE4.1/AVX2 accelerated BLAKE3 implementation.
 Package blake3 provides an SSE4.1/AVX2 accelerated BLAKE3 implementation.
internal/alg
internal/alg/compress
internal/alg/compress/compress_pure
internal/alg/compress/compress_sse41
internal/alg/hash
internal/alg/hash/hash_avx2
internal/alg/hash/hash_pure
internal/consts
internal/utils
cmd
hq
package main
 package main
Package cubetoken provides a complex KDF function
 Package cubetoken provides a complex KDF function
Package scrypt implements the scrypt key derivation function as defined in Colin Percival's paper "Stronger Key Derivation via Sequential Memory-Hard Functions" (https://www.tarsnap.com/scrypt/scrypt.pdf).
 Package scrypt implements the scrypt key derivation function as defined in Colin Percival's paper "Stronger Key Derivation via Sequential Memory-Hard Functions" (https://www.tarsnap.com/scrypt/scrypt.pdf).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
JackTT - Gopher 🇻🇳