sodium

package module
v1.0.13 Latest Latest
Warning

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

 Go to latest Published: Jan 1, 2022 License: MIT Imports: 5 Imported by: 27

README

sodium

A wrapper for libsodium in golang

See documents GoDoc.

Currently this is build against libsodium 1.0.13.

Following functions included:

  • crypto_auth crypto_auth_verify
  • crypto_sign_keypair crypto_sign_seed_keypair crypto_sign_ed25519_sk_to_seed crypto_sign_ed25519_sk_to_pk
  • crypto_sign crypto_sign_open crypto_sign_detached crypto_sign_verify_detached
  • crypto_sign_init crypto_sign_update crypto_sign_final_create crypto_sign_final_verify
  • crypto_sign_ed25519_sk_to_curve25519 crypto_sign_ed25519_pk_to_curve25519
  • crypto_scalarmult_base crypto_scalarmult
  • crypto_box_keypair crypto_box_seed_keypair
  • crypto_box_seal crypto_box_seal_open
  • crypto_box_easy crypto_box_open_easy crypto_box_detached crypto_box_open_detached
  • crypto_secretbox_easy crypto_secretbox_open_easy crypto_secretbox_detached crypto_secretbox_open_detached
  • crypto_pwhash crypto_pwhash_str crypto_pwhash_str_verify
  • crypto_pwhash_opslimit_interactive crypto_pwhash_memlimit_interactive
  • crypto_pwhash_opslimit_moderate crypto_pwhash_memlimit_moderate
  • crypto_pwhash_opslimit_sensitive crypto_pwhash_memlimit_sensitive
  • crypto_shorthash crypto_generichash_init crypto_generichash_update crypto_generichash_final
  • crypto_kdf_keygen crypto_kdf_derive_from_key
  • crypto_kx_keypair crypto_kx_seed_keypair crypto_kx_server_session_keys crypto_kx_client_session_keys
  • crypto_aead_chacha20poly1305_ietf_encrypt crypto_aead_chacha20poly1305_ietf_decrypt crypto_aead_chacha20poly1305_ietf_encrypt_detached crypto_aead_chacha20poly1305_ietf_decrypt_detached
  • sodium_memzero sodium_memcmp sodium_increment

NOTE: This is a modified and enhanced version based on github.com/GoKillers/libsodium-go. Because there're a lot of package reformat and interface changes, I'd like to launch a new project. Thankfully, the original author permits reuse its code as long as the original LICENSE remains. You can find the LICENSE.original and README.original.md stating the original license. And this version is released under MIT License.

Documentation

Overview

Package sodium is a wrapper for https://github.com/jedisct1/libsodium

Most of the functions is a method to the "Bytes" type. They are grouped below:

Signature

Sender sign a message with its SecretKey and the receiver can verify the Signature by sender's PublicKey 

type SignKP struct {
    PublicKey SignPublicKey
    SecretKey SignSecretKey
}
func MakeSignKP() SignKP
func SeedSignKP(seed SignSeed) SignKP
func (k SignSecretKey) PublicKey() SignPublicKey
func (k SignSecretKey) Seed() SignSeed

//SignKP can be converted to BoxKP
//It is recommended to use separate keys for signing and encrytion.
func (p SignKP) ToBox() BoxKP
func (k SignSecretKey) ToBox() BoxSecretKey
func (k SignPublicKey) ToBox() BoxPublicKey

//Message + Signature
func (b Bytes) Sign(key SignSecretKey) (sm Bytes)
func (b Bytes) SignOpen(key SignPublicKey) (m Bytes, err error)

//Detached Signature
func (b Bytes) SignDetached(key SignSecretKey) (sig Signature)
func (b Bytes) SignVerifyDetached(sig Signature, key SignPublicKey) (err error)

(Ed25519) 

//for multi-part messages that can't fit in memory
func MakeSignState() SignState
func (s SignState) Update(b []byte)
func (s SignState) Sign(key SignSecretKey) Signature
func (s SignState) Verify(sig Signature, key SignPublicKey) (err error)

(Ed25519ph)

Anonymous Public Key Encryption

An anonymous can encrypt a message with an ephemeral key pair and reveiver's PublicKey. The receiver can decrypt the message with its SecretKey. Only the receiver is authenticated. 

type BoxKP struct {
    PublicKey BoxPublicKey
    SecretKey BoxSecretKey
}
func MakeBoxKP() BoxKP
func SeedBoxKP(seed BoxSeed) BoxKP

func (b Bytes) SealedBox(pk BoxPublicKey) (cm Bytes)
func (b Bytes) SealedBoxOpen(kp BoxKP) (m Bytes, err error)

(X25519-XSalsa20-Poly1305)

Authenticated Public Key Encryption

Authenticated Box can be used to pass encrypt message from a known sender to a known receiver. The sender and the receiver are both authenticated to each other.

A one-time shared nonce is also generated and passed to protect the key pairs and messages. 

type BoxKP struct {
    PublicKey BoxPublicKey
    SecretKey BoxSecretKey
}
func MakeBoxKP() BoxKP
func SeedBoxKP(seed BoxSeed) BoxKP

func (b *BoxNonce) Next()

//All-in-one box
func (b Bytes) Box(n BoxNonce, pk BoxPublicKey, sk BoxSecretKey) (c Bytes)
func (b Bytes) BoxOpen(n BoxNonce, pk BoxPublicKey, sk BoxSecretKey) (m Bytes, err error)

//Detached MAC
func (b Bytes) BoxDetached(n BoxNonce, pk BoxPublicKey, sk BoxSecretKey) (mac BoxMAC, c Bytes)
func (b Bytes) BoxOpenDetached(mac BoxMAC, n BoxNonce, pk BoxPublicKey, sk BoxSecretKey) (c Bytes, err error)

(X25519-XSalsa20-Poly1305)

Key Exchanging

Server and Client exchange their public key and calculates a common session key with their own secret key. 

type KXKP struct {
    PublicKey KXPublicKey
    SecretKey KXSecretKey
}
func MakeKXKP() KXKP
func SeedKXKP(seed KXSeed) KXKP

type KXSessionKeys struct {
    Rx KXSessionKey
    Tx KXSessionKey
}

// session keys for client
func (kp KXKP) ClientSessionKeys(server_pk KXPublicKey) (*KXSessionKeys, error)

// session keys for server
func (kp KXKP) ServerSessionKeys(client_pk KXPublicKey) (*KXSessionKeys, error) {
// client's rx == server's tx
// client's tx == server's rx

(rx || tx = BLAKE2B-512(p.n || client_pk || server_pk))

Secret Key Authentication

One holder of a secret key authenticates the message with MAC. 

//Holders of the key can generate a MAC for the message.
func (b Bytes) Auth(key MACKey) (mac MAC)
//Holders of the key can verify the message's authenticity.
func (b Bytes) AuthVerify(mac MAC, key MACKey) (err error)

(HMAC-SHA512256)

Secret Key Encryption

Use a secret key and a nonce to protect the key, messages could be encrypted into a SecretBox. The encrypted data's intergrity is checked when decryption. 

func (n *SecretBoxNonce) Next()

//encrypted message + MAC.
func (b Bytes) SecretBox(n SecretBoxNonce, k SecretBoxKey) (c Bytes)
func (b Bytes) SecretBoxOpen(n SecretBoxNonce, k SecretBoxKey) (m Bytes, err error)

//Detached version has a separate MAC.
func (b Bytes) SecretBoxDetached(n SecretBoxNonce, k SecretBoxKey) (c Bytes, mac SecretBoxMAC)
func (b Bytes) SecretBoxOpenDetached(mac SecretBoxMAC, n SecretBoxNonce, k SecretBoxKey) (m Bytes, err error)

(XSalsa20-Poly1305)

Authenticated Encryption with Additional Data

Use a secret key and a nonce to protect the key, messages could be encrypted. Optional additional data and the message is authenticited with an authentication tag. Both intergrity and authenticity is checked when decryption. The decryption would not be performed unless the authentication tag is verified. 

func (n *AEADCPNonce) Next()

//encrypted message + MAC.
func (b Bytes) AEADCPEncrypt(ad Bytes, n AEADCPNonce, k AEADCPKey) (c Bytes)
func (b Bytes) AEADCPDecrypt(ad Bytes, n AEADCPNonce, k AEADCPKey) (m Bytes, err error)
func (b Bytes) AEADCPVerify(ad Bytes, n AEADCPNonce, k AEADCPKey) (err error)

//Detached version has a separate MAC.
func (b Bytes) AEADCPEncryptDetached(ad Bytes, n AEADCPNonce, k AEADCPKey) (c Bytes, mac AEADCPMAC)
func (b Bytes) AEADCPDecryptDetached(mac AEADCPMAC, ad Bytes, n AEADCPNonce, k AEADCPKey) (m Bytes, err error)
func (b Bytes) AEADCPVerifyDetached(mac AEADCPMAC, ad Bytes, n AEADCPNonce, k AEADCPKey) (err error)

AEADCP* (ChaCha20-Poly1305_IETF)

Key Derivation

Deriving subkeys from a single high-entropy key 

func MakeMasterKey() MasterKey
func MakeKeyContext(s string) KeyContext
func (m MasterKey) Derive(length int, id uint64, context KeyContext) SubKey

KDF (BLAKE2B)

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	CryptoKDFBytesMin     = int(C.crypto_kdf_bytes_min())
	CryptoKDFBytesMax     = int(C.crypto_kdf_bytes_max())
	CryptoKDFContextBytes = int(C.crypto_kdf_contextbytes())
)
View Source 
var (
	CryptoPWHashOpsLimitInteractive = int(C.crypto_pwhash_opslimit_interactive())
	CryptoPWHashMemLimitInteractive = int(C.crypto_pwhash_memlimit_interactive())
	CryptoPWHashOpsLimitModerate    = int(C.crypto_pwhash_opslimit_moderate())
	CryptoPWHashMemLimitModerate    = int(C.crypto_pwhash_memlimit_moderate())
	CryptoPWHashOpsLimitSensitive   = int(C.crypto_pwhash_opslimit_sensitive())
	CryptoPWHashMemLimitSensitive   = int(C.crypto_pwhash_memlimit_sensitive())
)
View Source 
var (
	RuntimeHasNeon = bool(C.sodium_runtime_has_neon() != 0)
	RuntimeHasSse2 = bool(C.sodium_runtime_has_sse2() != 0)
	RuntimeHasSse3 = bool(C.sodium_runtime_has_sse3() != 0)
)
View Source 
var (
	ErrAuth        = errors.New("sodium: Message forged")
	ErrOpenBox     = errors.New("sodium: Can't open box")
	ErrOpenSign    = errors.New("sodium: Signature forged")
	ErrDecryptAEAD = errors.New("sodium: Can't decrypt message")
	ErrPassword    = errors.New("sodium: Password not matched")
	ErrInvalidKey  = errors.New("sodium: Invalid key")
)

Functions

func MemCmp 

func MemCmp(buff1, buff2 Bytes, length int) int

MemCmp compare to buffer without leaking timing infomation

func MemZero 

func MemZero(buff1 Bytes)

MemZero sets the buffer to zero

func Randomize 

func Randomize(k Typed)

Randomize fill the Typed with random bytes.

Types

type AEADCPKey 

type AEADCPKey struct {
	Bytes
}

func (AEADCPKey) Size 

func (AEADCPKey) Size() int

type AEADCPMAC 

type AEADCPMAC struct {
	Bytes
}

func (AEADCPMAC) Size 

func (AEADCPMAC) Size() int

type AEADCPNonce 

type AEADCPNonce struct {
	Bytes
}

func (*AEADCPNonce) Next 

func (n *AEADCPNonce) Next()

func (AEADCPNonce) Size 

func (AEADCPNonce) Size() int

type BoxKP 

type BoxKP struct {
	PublicKey BoxPublicKey
	SecretKey BoxSecretKey
}

func MakeBoxKP 

func MakeBoxKP() BoxKP

MakeBoxKP generates a keypair for Box

func SeedBoxKP 

func SeedBoxKP(seed BoxSeed) BoxKP

SeedBoxKP generates a keypair for signing from a BoxSeed.

The same pair of keys will be generated with the same 'seed'

Example 
seed := BoxSeed{}
Randomize(&seed)
kp1 := SeedBoxKP(seed)
kp2 := SeedBoxKP(seed)
s1 := kp1.SecretKey
s2 := kp2.SecretKey

fmt.Println(MemCmp(s1.Bytes, s2.Bytes, s1.Length()) == 0)

Output:

true

type BoxMAC 

type BoxMAC struct {
	Bytes
}

func (BoxMAC) Size 

func (b BoxMAC) Size() int

type BoxNonce 

type BoxNonce struct {
	Bytes
}

func (*BoxNonce) Next 

func (b *BoxNonce) Next()

func (BoxNonce) Size 

func (n BoxNonce) Size() int

type BoxPublicKey 

type BoxPublicKey struct {
	Bytes
}

func (BoxPublicKey) Size 

func (k BoxPublicKey) Size() int

type BoxSecretKey 

type BoxSecretKey struct {
	Bytes
}

func (BoxSecretKey) PublicKey 

func (k BoxSecretKey) PublicKey() BoxPublicKey

PublicKey calculates public key from BoxSecretKey.

Example 
kp := MakeBoxKP()
pk := kp.SecretKey.PublicKey()

fmt.Println(MemCmp(kp.PublicKey.Bytes, pk.Bytes, pk.Length()) == 0)

Output:

true

func (BoxSecretKey) Size 

func (k BoxSecretKey) Size() int

type BoxSeed 

type BoxSeed struct {
	Bytes
}

func (BoxSeed) Size 

func (b BoxSeed) Size() int

type Bytes 

type Bytes []byte

Bytes warppers around []byte.

func (Bytes) AEADCPDecrypt 

func (b Bytes) AEADCPDecrypt(ad Bytes, n AEADCPNonce, k AEADCPKey) (m Bytes, err error)

AEADCPDecrypt decrypts message with AEADCPKey, and AEADCPNonce. The appended authenticated tag is verified with additional data 'ad' before decryption.

It returns an error if decryption failed.

func (Bytes) AEADCPDecryptDetached 

func (b Bytes) AEADCPDecryptDetached(mac AEADCPMAC, ad Bytes, n AEADCPNonce, k AEADCPKey) (m Bytes, err error)

AEADCPDecryptDetached decrypts message with AEADCPKey, and AEADCPNonce. The separated authenticated tag is verified with additional data 'ad' before decryption.

It returns an error if decryption failed.

func (Bytes) AEADCPEncrypt 

func (b Bytes) AEADCPEncrypt(ad Bytes, n AEADCPNonce, k AEADCPKey) (c Bytes)

AEADCPEncrypt encrypts message with AEADCPKey, and AEADCPNonce. Message then authenticated with additional data 'ad'. Authentication tag is append to the encrypted data.

Example 
key := AEADCPKey{}
Randomize(&key)

n := AEADCPNonce{}
Randomize(&n)

ad := Bytes(`addtional data`)

e := m.AEADCPEncrypt(ad, n, key)

md, err := e.AEADCPDecrypt(ad, n, key)
fmt.Println(err)
fmt.Println(MemCmp(md, m, m.Length()) == 0)

Output:

<nil>
true

func (Bytes) AEADCPEncryptDetached 

func (b Bytes) AEADCPEncryptDetached(ad Bytes, n AEADCPNonce, k AEADCPKey) (c Bytes, mac AEADCPMAC)

AEADCPEncryptDetached encrypts message with AEADCPKey, and AEADCPNonce. Message then authenticated with additional data 'ad'. Authentication tag is separated saved as 'mac'.

Example 
key := AEADCPKey{}
Randomize(&key)

n := AEADCPNonce{}
Randomize(&n)

ad := Bytes(`addtional data`)

e, mac := m.AEADCPEncryptDetached(ad, n, key)

md, err := e.AEADCPDecryptDetached(mac, ad, n, key)
fmt.Println(err)
fmt.Println(MemCmp(md, m, m.Length()) == 0)

Output:

<nil>
true

func (Bytes) AEADCPVerify 

func (b Bytes) AEADCPVerify(ad Bytes, n AEADCPNonce, k AEADCPKey) (err error)

AEADCPVerify decrypts message with AEADCPKey, and AEADCPNonce without writing decrypted data. The appended authenticated tag is verified with additional data 'ad' before decryption.

It returns an error if decryption failed.

Example 
key := AEADCPKey{}
Randomize(&key)

n := AEADCPNonce{}
Randomize(&n)

ad := Bytes(`addtional data`)

e := m.AEADCPEncrypt(ad, n, key)

err := e.AEADCPVerify(ad, n, key)
fmt.Println(err)

Output:

<nil>

func (Bytes) AEADCPVerifyDetached 

func (b Bytes) AEADCPVerifyDetached(mac AEADCPMAC, ad Bytes, n AEADCPNonce, k AEADCPKey) (err error)

AEADCPVerifyDetached decrypts message with AEADCPKey, and AEADCPNonce without writing decrypted data. The separated authenticated tag is verified with additional data 'ad' before decryption.

It returns an error if decryption failed.

Example 
key := AEADCPKey{}
Randomize(&key)

n := AEADCPNonce{}
Randomize(&n)

ad := Bytes(`addtional data`)

e, mac := m.AEADCPEncryptDetached(ad, n, key)

err := e.AEADCPVerifyDetached(mac, ad, n, key)
fmt.Println(err)

Output:

<nil>

func (Bytes) Auth 

func (b Bytes) Auth(key MACKey) (mac MAC)

Auth generates a MAC for the message with the secret 'key'.

Example 
key := MACKey{}
Randomize(&key)
mac := m.Auth(key)

err := m.AuthVerify(mac, key)
fmt.Println(err)

Output:

<nil>

func (Bytes) AuthVerify 

func (b Bytes) AuthVerify(mac MAC, key MACKey) (err error)

AuthVerify verifies a messagee with MAC and the secret 'key'.

It returns an error if verification failed.

func (Bytes) Box 

func (b Bytes) Box(n BoxNonce, pk BoxPublicKey, sk BoxSecretKey) (c Bytes)

Box puts message into an authenticated encrypted box using sender's SecretKey and receiver's PublicKey, with a shared one-time nonce is used for each message.

Example 
rkp := MakeBoxKP()
skp := MakeBoxKP()

n := BoxNonce{}
Randomize(&n)

bc := m.Box(n, rkp.PublicKey, skp.SecretKey)
bom, err := bc.BoxOpen(n, skp.PublicKey, rkp.SecretKey)

fmt.Println(err)
fmt.Println(MemCmp(bom, m, m.Length()) == 0)

Output:

<nil>
true

func (Bytes) BoxDetached 

func (b Bytes) BoxDetached(n BoxNonce, pk BoxPublicKey, sk BoxSecretKey) (mac BoxMAC, c Bytes)

BoxDetached encodes message into an encrypted message using sender's SecretKey and receiver's PublicKey, with a shared one-time nonce is used for each message.

Detached MAC is return along with encrypted message for authentication.

Example 
rkp := MakeBoxKP()
skp := MakeBoxKP()

n := BoxNonce{}
Randomize(&n)

mac, bcd := m.BoxDetached(n, rkp.PublicKey, skp.SecretKey)
bomd, err := bcd.BoxOpenDetached(mac, n, skp.PublicKey, rkp.SecretKey)

fmt.Println(err)
fmt.Println(MemCmp(bomd, m, m.Length()) == 0)

Output:

<nil>
true

func (Bytes) BoxOpen 

func (b Bytes) BoxOpen(n BoxNonce, pk BoxPublicKey, sk BoxSecretKey) (m Bytes, err error)

BoxOpen reads message from an authenticated encrypted box using receiver's SecretKey and sender's PublicKey with a shared one-time nonce

It returns an error if opening failed.

func (Bytes) BoxOpenDetached 

func (b Bytes) BoxOpenDetached(mac BoxMAC, n BoxNonce, pk BoxPublicKey, sk BoxSecretKey) (m Bytes, err error)

BoxOpenDetached decodes message from an encrypted message along with a MAC for authentication, and using receiver's SecretKey and sender's PublicKey with a shared one-time nonce.

It returns an error if opening failed.

func (Bytes) Length 

func (b Bytes) Length() int

Length returns the byte length.

func (Bytes) SealedBox 

func (b Bytes) SealedBox(pk BoxPublicKey) (cm Bytes)

SealedBox puts message into a sealed box using receiver's PublicKey and an ephemeral key pair of which the SecretKey is destroyed on sender's side right after encryption, and the PublicKey is packed with the Box to the receiver.

The receiver can open the box but can not verify the identity of the sender.

Example 
kp := MakeBoxKP()

n := BoxNonce{}
Randomize(&n)

c := m.SealedBox(kp.PublicKey)
om, err := c.SealedBoxOpen(kp)

fmt.Println(err)
fmt.Println(MemCmp(om, m, m.Length()) == 0)

Output:

<nil>
true

func (Bytes) SealedBoxOpen 

func (b Bytes) SealedBoxOpen(kp BoxKP) (m Bytes, err error)

SealedBoxOpen reads message from a sealed box using its key pair and ephemeral public packed in the Box.

It returns an error if opening failed.

func (Bytes) SecretBox 

func (b Bytes) SecretBox(n SecretBoxNonce, k SecretBoxKey) (c Bytes)

SecretBox use a SecretBoxNonce and a SecretBoxKey to encrypt a message.

Example 
key := SecretBoxKey{}
Randomize(&key)
n := SecretBoxNonce{}
Randomize(&n)

c := m.SecretBox(n, key)
md, err := c.SecretBoxOpen(n, key)
fmt.Println(err)
fmt.Println(MemCmp(md, m, m.Length()) == 0)

Output:

<nil>
true

func (Bytes) SecretBoxDetached 

func (b Bytes) SecretBoxDetached(n SecretBoxNonce, k SecretBoxKey) (c Bytes, mac SecretBoxMAC)

SecretBoxDetached use a SecretBoxNonce and a SecretBoxKey to encrypt a message. A separate MAC is returned.

Example 
key := SecretBoxKey{}
Randomize(&key)
n := SecretBoxNonce{}
Randomize(&n)

c, mac := m.SecretBoxDetached(n, key)
md, err := c.SecretBoxOpenDetached(mac, n, key)
fmt.Println(err)
fmt.Println(MemCmp(md, m, m.Length()) == 0)

Output:

<nil>
true

func (Bytes) SecretBoxOpen 

func (b Bytes) SecretBoxOpen(n SecretBoxNonce, k SecretBoxKey) (m Bytes, err error)

SecretBoxOpen opens a SecretBox using SecretBoxKey and SecretBoxNonce.

It returns an error if opening failed.

func (Bytes) SecretBoxOpenDetached 

func (b Bytes) SecretBoxOpenDetached(mac SecretBoxMAC, n SecretBoxNonce, k SecretBoxKey) (m Bytes, err error)

SecretBoxOpenDetached opens a SecretBox using SecretBoxKey and SecretBoxNonce. with a separate MAC.

It returns an error if opening failed.

func (Bytes) Shorthash 

func (b Bytes) Shorthash(key ShortHashKey) (out Bytes)

Shorthash use a secret key and input to produce a ShortHash. It is protective to short input. And it's output is also too short to be collision-resistent, however it can be used in hash table, Bloom filter or generate MAC for interactive protocol.

Example 
key := ShortHashKey{}
Randomize(&key)

m := Bytes(`short message`)
hash := m.Shorthash(key)
fmt.Println(hash.Length())

Output:

8

func (Bytes) Sign 

func (b Bytes) Sign(key SignSecretKey) (sm Bytes)

Sign returns 'sm': signature+message

func (Bytes) SignDetached 

func (b Bytes) SignDetached(key SignSecretKey) (sig Signature)

SignDetached signs the message with 'key' and returns only the signature.

Example 
kp := MakeSignKP()
sm := m.Sign(kp.SecretKey)

om, err := sm.SignOpen(kp.PublicKey)
sig := m.SignDetached(kp.SecretKey)

fmt.Println(err)
fmt.Println(MemCmp(om, m, m.Length()) == 0)
fmt.Println(MemCmp(sig.Bytes, sm, sig.Length()) == 0)

err = m.SignVerifyDetached(sig, kp.PublicKey)
fmt.Println(err)

Output:

<nil>
true
true
<nil>

func (Bytes) SignOpen 

func (b Bytes) SignOpen(key SignPublicKey) (m Bytes, err error)

SignOpen returns message 'm' from signature+message, verified by 'key'.

It returns an error if verification failed.

func (Bytes) SignVerifyDetached 

func (b Bytes) SignVerifyDetached(sig Signature, key SignPublicKey) (err error)

SignVerifyDetached verifies the message and its detached 'sig' with 'key'.

It returns an error if verification failed.

type GenericHash 

type GenericHash struct {
	// contains filtered or unexported fields
}

GenericHash provides a BLAKE2b (RFC7693) hash, in interface of hash.Hash.

The Hash's and key's size can be any between 16 bytes (128 bits) to 64 bytes (512 bits) based on different application.

func NewGenericHash 

func NewGenericHash(outlen int) GenericHash

Unkeyed version, output length should between 16 (128-bit) to 64 (512-bit).

func NewGenericHashDefault 

func NewGenericHashDefault() GenericHash

Unkeyed version with default output length.

func NewGenericHashDefaultKeyed 

func NewGenericHashDefaultKeyed(key GenericHashKey) GenericHash

Keyed version with default output length.

func NewGenericHashKeyed 

func NewGenericHashKeyed(outlen int, key GenericHashKey) GenericHash

Keyed version, output length in bytes should between 16 (128-bit) to 64 (512-bit).

Example 
kp := MakeBoxKP()
key := GenericHashKey{kp.SecretKey.Bytes}

h := NewGenericHashKeyed(48, key)
h.Write(m)
sh := h.Sum(nil)

he := NewGenericHash(48)
he.Write(m)
she := he.Sum(nil)

fmt.Println(len(sh))
fmt.Println(len(she))
fmt.Println((MemCmp(sh, she, len(sh))) == 0)

Output:

48
48
false

func (GenericHash) BlockSize 

func (g GenericHash) BlockSize() int

Implements hash.Hash

func (*GenericHash) Reset 

func (g *GenericHash) Reset()

Implements hash.Hash

func (GenericHash) Size 

func (g GenericHash) Size() int

Output length in bytes.

Implements hash.Hash

func (*GenericHash) Sum 

func (g *GenericHash) Sum(b []byte) []byte

Return appended the Sum after b.

Implements hash.Hash.

NOTE: Repeated call is allowed. But can't call Write() after Sum(). The underlying state is freed. It MUST be Reset() to use it again after calling Sum(). This behaviour is inconsistent with the definition of hash.Hash.

func (*GenericHash) Write 

func (g *GenericHash) Write(p []byte) (n int, err error)

Use GenericHash.Write([]byte) to hash chunks of message.

Implements hash.Hash

type GenericHashKey 

type GenericHashKey struct {
	Bytes
}

func (GenericHashKey) Size 

func (GenericHashKey) Size() int

type KXKP 

type KXKP struct {
	PublicKey KXPublicKey
	SecretKey KXSecretKey
}

func MakeKXKP 

func MakeKXKP() KXKP

MakeKXKP generates a keypair for signing

Example 
skp := MakeKXKP()
ckp := MakeKXKP()

sss, _ := skp.ServerSessionKeys(ckp.PublicKey)
css, _ := ckp.ClientSessionKeys(skp.PublicKey)

fmt.Println(MemCmp(sss.Tx.Bytes, css.Rx.Bytes, sss.Tx.Size()) == 0)
fmt.Println(MemCmp(sss.Rx.Bytes, css.Tx.Bytes, sss.Rx.Size()) == 0)

fmt.Println(MemCmp(sss.Tx.Bytes, sss.Rx.Bytes, sss.Tx.Size()) == 0)
fmt.Println(MemCmp(css.Tx.Bytes, css.Rx.Bytes, css.Tx.Size()) == 0)

Output:

true
true
false
false

func SeedKXKP 

func SeedKXKP(seed KXSeed) KXKP

SeedKXKP generates a keypair for exchanging from a KXSeed.

The same pair of keys will be generated with the same 'seed'

func (KXKP) ClientSessionKeys 

func (kp KXKP) ClientSessionKeys(server_pk KXPublicKey) (*KXSessionKeys, error)

ClientSessionKeys calculates Rx (for receving) and Tx (for sending) session keys with server's public key. return error when server_pk is not acceptable.

func (KXKP) ServerSessionKeys 

func (kp KXKP) ServerSessionKeys(client_pk KXPublicKey) (*KXSessionKeys, error)

ServerSessionKeys calculates Rx (for receving) and Tx (for sending) session keys with client's public key. return error when client_pk is not acceptable.

type KXPublicKey 

type KXPublicKey struct {
	Bytes
}

func (KXPublicKey) Size 

func (k KXPublicKey) Size() int

type KXSecretKey 

type KXSecretKey struct {
	Bytes
}

func (KXSecretKey) Size 

func (k KXSecretKey) Size() int

type KXSeed 

type KXSeed struct {
	Bytes
}

func (KXSeed) Size 

func (k KXSeed) Size() int

type KXSessionKey 

type KXSessionKey struct {
	Bytes
}

func (KXSessionKey) Size 

func (k KXSessionKey) Size() int

type KXSessionKeys 

type KXSessionKeys struct {
	Rx KXSessionKey
	Tx KXSessionKey
}

type KeyContext 

type KeyContext string

KeyContext is a CryptoKDFContextBytes length string indicating the context for the key. e.g. "username"

func MakeKeyContext 

func MakeKeyContext(s string) KeyContext

func (KeyContext) Length 

func (k KeyContext) Length() int

func (KeyContext) Size 

func (KeyContext) Size() int

type MAC 

type MAC struct {
	Bytes
}

MAC stores Message Authentication Code produced by HMAC-SHA512256.

func (MAC) Size 

func (b MAC) Size() int

type MACKey 

type MACKey struct {
	Bytes
}

func (MACKey) Size 

func (b MACKey) Size() int

type MasterKey 

type MasterKey struct {
	Bytes
}

MasterKey for deriving SubKeys

func MakeMasterKey 

func MakeMasterKey() MasterKey

MakeMasterKey generates a new MasterKey

func (MasterKey) Derive 

func (m MasterKey) Derive(length int, id uint64, context KeyContext) SubKey

Derive SubKey from the MasterKey length should be between CryptoKDFBytesMin and CryptoKDFBytesMax

Example 
mk := MakeMasterKey()
context := MakeKeyContext("testblablabla") // only first CryptoKDFContextBytes is used
fmt.Println(context)
sk := mk.Derive(CryptoKDFBytesMin, 0, context)

fmt.Println(sk.Length() == CryptoKDFBytesMin)

Output:

testblab
true

func (MasterKey) Length 

func (m MasterKey) Length() int

func (MasterKey) Size 

func (MasterKey) Size() int

type Nonce 

type Nonce interface {
	Typed
	Next() //Next unused nonce
}

Nonce is used to protect secret key. It is important to not use the same nonce for a given key.

type PWHashSalt 

type PWHashSalt struct {
	Bytes
}

PWHashSalt implements the Typed interface

func (PWHashSalt) Size 

func (s PWHashSalt) Size() int

type PWHashStr 

type PWHashStr struct {
	// contains filtered or unexported fields
}

PWHashStr implements the Typed interface

func LoadPWHashStr 

func LoadPWHashStr(b Bytes) PWHashStr

func PWHashStore 

func PWHashStore(pw string) PWHashStr

PWHashStore use moderate profile to pack hashed password into PWHashStr.

Example 
s := PWHashStore("test")
str := s.Value()        // str for store
t := LoadPWHashStr(str) // load from storage
err := t.PWHashVerify("test")

fmt.Println(err)

Output:

<nil>

func PWHashStoreInteractive 

func PWHashStoreInteractive(pw string) PWHashStr

PWHashStoreInteractive use interactive profile to pack hashed password into PWHashStr.

func PWHashStoreSensitive 

func PWHashStoreSensitive(pw string) PWHashStr

PWHashStoreSensitive use sensitive profile to pack hashed password into PWHashStr.

func (PWHashStr) Length 

func (s PWHashStr) Length() int

func (PWHashStr) PWHashVerify 

func (s PWHashStr) PWHashVerify(pw string) (err error)

PWHashVerify verifies password.

func (PWHashStr) Size 

func (s PWHashStr) Size() int

func (PWHashStr) Value 

func (s PWHashStr) Value() Bytes

Value returns the underlying bytes for PWHashStr

type Scalar 

type Scalar struct {
	Bytes
}

func CryptoScalarmultBase 

func CryptoScalarmultBase(n Scalar) (q Scalar)

CryptoScalarmultBase calculates BoxPublicKey 'q' from BoxSecertKey 'n'.

func (Scalar) Size 

func (s Scalar) Size() int

type ScalarMult 

type ScalarMult struct {
	Bytes
}

ScalarMult is the mulitiplication of two Scalar, used to calculate shared key from BoxSecertKey and other end's BoxPublicKey.

func CryptoScalarmult 

func CryptoScalarmult(n, p Scalar) (q ScalarMult)

CryptoScalarmult calculates common key 'q' from private key 'n' and other's public key 'p'

func (ScalarMult) Size 

func (s ScalarMult) Size() int

type SecretBoxKey 

type SecretBoxKey struct {
	Bytes
}

func (SecretBoxKey) Size 

func (s SecretBoxKey) Size() int

type SecretBoxMAC 

type SecretBoxMAC struct {
	Bytes
}

func (SecretBoxMAC) Size 

func (s SecretBoxMAC) Size() int

type SecretBoxNonce 

type SecretBoxNonce struct {
	Bytes
}

func (*SecretBoxNonce) Next 

func (n *SecretBoxNonce) Next()

func (SecretBoxNonce) Size 

func (n SecretBoxNonce) Size() int

type ShortHash 

type ShortHash struct {
	Bytes
}

func (ShortHash) Size 

func (s ShortHash) Size() int

type ShortHashKey 

type ShortHashKey struct {
	Bytes
}

func (ShortHashKey) Size 

func (s ShortHashKey) Size() int

type SignKP 

type SignKP struct {
	PublicKey SignPublicKey
	SecretKey SignSecretKey
}

func MakeSignKP 

func MakeSignKP() SignKP

MakeSignKP generates a keypair for signing

func SeedSignKP 

func SeedSignKP(seed SignSeed) SignKP

SeedSignKP generates a keypair for signing from a SignSeed.

The same pair of keys will be generated with the same 'seed'

Example 
seed := SignSeed{}
Randomize(&seed)
kp1 := SeedSignKP(seed)
kp2 := SeedSignKP(seed)
s1 := kp1.SecretKey
s2 := kp2.SecretKey

s := s1.Seed()
pk1 := s1.PublicKey()

fmt.Println(MemCmp(s1.Bytes, s2.Bytes, s1.Length()) == 0)
fmt.Println(MemCmp(s.Bytes, seed.Bytes, seed.Length()) == 0)
fmt.Println(MemCmp(pk1.Bytes, kp1.PublicKey.Bytes, pk1.Length()) == 0)

Output:

true
true
true

func (SignKP) ToBox 

func (p SignKP) ToBox() BoxKP

ToBox converts a pair of signing key into a pair of box key - ed25519 to curve25519 - returns BoxKP.

Example 
skp := MakeSignKP()
bkp := skp.ToBox()
rkp := MakeBoxKP()

sb := skp.SecretKey.ToBox()
pb := skp.PublicKey.ToBox()

fmt.Println(MemCmp(bkp.SecretKey.Bytes, sb.Bytes, bkp.SecretKey.Length()) == 0)
fmt.Println(MemCmp(bkp.PublicKey.Bytes, pb.Bytes, bkp.PublicKey.Length()) == 0)

n := BoxNonce{}
Randomize(&n)

bc := m.Box(n, rkp.PublicKey, bkp.SecretKey)
bom, err := bc.BoxOpen(n, bkp.PublicKey, rkp.SecretKey)

fmt.Println(err)
fmt.Println(MemCmp(bom, m, m.Length()) == 0)

Output:

true
true
<nil>
true

type SignPublicKey 

type SignPublicKey struct {
	Bytes
}

func (SignPublicKey) Size 

func (k SignPublicKey) Size() int

func (SignPublicKey) ToBox 

func (k SignPublicKey) ToBox() BoxPublicKey

ToBox converts a signing public key into a box public key - ed25519 to curve25519 - returns BoxPublicKey.

type SignSecretKey 

type SignSecretKey struct {
	Bytes
}

func (SignSecretKey) PublicKey 

func (k SignSecretKey) PublicKey() SignPublicKey

PublicKey extracts the SignPublicKey from the SignSecretKey.

func (SignSecretKey) Seed 

func (k SignSecretKey) Seed() SignSeed

Seed extracts the seed used when generating the key pair.

func (SignSecretKey) Size 

func (k SignSecretKey) Size() int

func (SignSecretKey) ToBox 

func (k SignSecretKey) ToBox() BoxSecretKey

ToBox converts a signing secret key into a box secret key - ed25519 to curve25519 - returns BoxSecretKey.

type SignSeed 

type SignSeed struct {
	Bytes
}

func (SignSeed) Size 

func (k SignSeed) Size() int

type SignState 

type SignState struct {
	// contains filtered or unexported fields
}

func MakeSignState 

func MakeSignState() SignState

MakeSignState creates an empty state for multi-part messages that can't fit in memory.

Example 
kp := MakeSignKP()

s_a := MakeSignState()
s_a.Update(m)

siga := s_a.Sign(kp.SecretKey)

s_b := MakeSignState()
s_b.Update(m)

err := s_b.Verify(siga, kp.PublicKey)
fmt.Println(err)

Output:

<nil>

func (SignState) Sign 

func (s SignState) Sign(key SignSecretKey) Signature

Sign a signature for the current state.

The underlying state is freed after this call.

func (SignState) Update 

func (s SignState) Update(b []byte)

Update the state by add more data.

func (SignState) Verify 

func (s SignState) Verify(sig Signature, key SignPublicKey) (err error)

Verify the signature with the current state and public key.

It returns an error if verification failed.

type Signature 

type Signature struct {
	Bytes
}

func (Signature) Size 

func (b Signature) Size() int

type SubKey 

type SubKey struct {
	Bytes
}

SubKey derived from a MasterKey

func (SubKey) Size 

func (SubKey) Size() int

type Typed 

type Typed interface {
	Size() int // Size returns the pre-defined size of the object.
	Length() int
	// contains filtered or unexported methods
}

Typed has pre-defined size.

Source Files

View all Source files

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.