Documentation ¶
Index ¶
- Constants
- Variables
- func CalculateLeaves(dataSize uint64) uint64
- func DecryptWithNonce(ciphertext []byte, aead cipher.AEAD) ([]byte, error)
- func DeriveSharedSecret(xsk X25519SecretKey, xpk X25519PublicKey) (secret [32]byte)
- func EncryptWithNonce(plaintext []byte, aead cipher.AEAD) []byte
- func GenerateKeyPair() (sk SecretKey, pk PublicKey)
- func GenerateKeyPairDeterministic(entropy [EntropySize]byte) (sk SecretKey, pk PublicKey)
- func GenerateX25519KeyPair() (xsk X25519SecretKey, xpk X25519PublicKey)
- func IsValidCipherType(ct CipherType) bool
- func NewHash() hash.Hash
- func ReadSignedObject(r io.Reader, obj interface{}, maxLen uint64, pk PublicKey) error
- func SecureWipe(data []byte)
- func VerifyDiffProof(ranges []ProofRange, numLeaves uint64, proofHashes, leafHashes []Hash, ...) bool
- func VerifyHash(data Hash, pk PublicKey, sig Signature) error
- func VerifyMixedRangeProof(segmentData []byte, proof []Hash, root Hash, start, end int) bool
- func VerifyRangeProof(segments []byte, proof []Hash, start, end int, root Hash) bool
- func VerifySectorRangeProof(roots []Hash, proof []Hash, start, end int, root Hash) bool
- func VerifySegment(base []byte, hashSet []Hash, numSegments, proofIndex uint64, root Hash) bool
- func WriteSignedObject(w io.Writer, obj interface{}, sk SecretKey) error
- type CachedMerkleTree
- type CipherKey
- type CipherType
- type Ciphertext
- type Hash
- func HashAll(objs ...interface{}) (hash Hash)
- func HashBytes(data []byte) Hash
- func HashObject(obj interface{}) (hash Hash)
- func MerkleDiffProof(ranges []ProofRange, numLeaves uint64, updatedSectors [][]byte, ...) []Hash
- func MerkleMixedRangeProof(sectorRoots []Hash, segmentData []byte, sectorSize int, start, end int) []Hash
- func MerkleProof(b []byte, proofIndex uint64) (base []byte, hashSet []Hash)
- func MerkleRangeProof(b []byte, start, end int) []Hash
- func MerkleRoot(b []byte) Hash
- func MerkleSectorRangeProof(roots []Hash, start, end int) []Hash
- type HashSlice
- type MerkleTree
- type ProofRange
- type PublicKey
- type SecretKey
- type Signature
- type X25519PublicKey
- type X25519SecretKey
Constants ¶
const ( // EntropySize defines the amount of entropy necessary to do secure // cryptographic operations, in bytes. EntropySize = 32 // PublicKeySize defines the size of public keys in bytes. PublicKeySize = ed25519.PublicKeySize // SecretKeySize defines the size of secret keys in bytes. SecretKeySize = ed25519.PrivateKeySize // SignatureSize defines the size of signatures in bytes. SignatureSize = ed25519.SignatureSize )
const (
// HashSize is the length of a Hash in bytes.
HashSize = 32
)
const ( // SegmentSize is the chunk size that is used when taking the Merkle root // of a file. 64 is chosen because bandwidth is scarce and it optimizes for // the smallest possible storage proofs. Using a larger base, even 256 // bytes, would result in substantially faster hashing, but the bandwidth // tradeoff was deemed to be more important, as blockchain space is scarce. SegmentSize = 64 )
Variables ¶
var ( // TypeDefaultRenter is the default CipherType that is used for // encrypting pieces of uploaded data. TypeDefaultRenter = TypeThreefish // TypeDefaultWallet is the default CipherType that is used for // wallet operations like encrypting the wallet files. TypeDefaultWallet = TypeTwofish // TypeInvalid represents an invalid type which cannot be used for any // meaningful purpose. TypeInvalid = CipherType{0, 0, 0, 0, 0, 0, 0, 0} // TypePlain means no encryption is used. TypePlain = CipherType{0, 0, 0, 0, 0, 0, 0, 1} // TypeTwofish is the type for the Twofish-GCM encryption. TypeTwofish = CipherType{0, 0, 0, 0, 0, 0, 0, 2} // TypeThreefish is the type for the Threefish encryption. TypeThreefish = CipherType{0, 0, 0, 0, 0, 0, 0, 3} // TypeXChaCha20 is the type for the XChaCha20 encryption. TypeXChaCha20 = CipherType{0, 0, 0, 0, 0, 0, 0, 4} )
var ( // ErrHashWrongLen is the error when encoded value has the wrong // length to be a hash. ErrHashWrongLen = errors.New("encoded value has the wrong length to be a hash") )
var ( // ErrInsufficientLen is an error when supplied ciphertext is not // long enough to contain a nonce. ErrInsufficientLen = errors.New("supplied ciphertext is not long enough to contain a nonce") )
var ( // ErrInvalidCipherType is returned upon encountering an unknown cipher // type. ErrInvalidCipherType = errors.New("provided cipher type is invalid") )
var ( // ErrInvalidSignature is returned if a signature is provided that does not // match the data and public key. ErrInvalidSignature = errors.New("invalid signature") )
Functions ¶
func CalculateLeaves ¶ added in v0.3.3
CalculateLeaves calculates the number of leaves that would be pushed from data of size 'dataSize'.
func DecryptWithNonce ¶ added in v1.4.0
DecryptWithNonce decrypts ciphertext with aead, using a prepended nonce.
func DeriveSharedSecret ¶ added in v1.4.0
func DeriveSharedSecret(xsk X25519SecretKey, xpk X25519PublicKey) (secret [32]byte)
DeriveSharedSecret derives 32 bytes of entropy from a secret key and public key. Derivation is via ScalarMult of the private and public keys, followed by a 256-bit unkeyed blake2b hash.
func EncryptWithNonce ¶ added in v1.4.0
EncryptWithNonce encrypts plaintext with aead and prepends a random nonce.
func GenerateKeyPair ¶ added in v1.0.0
GenerateKeyPair creates a public-secret keypair that can be used to sign and verify messages.
func GenerateKeyPairDeterministic ¶ added in v1.0.0
func GenerateKeyPairDeterministic(entropy [EntropySize]byte) (sk SecretKey, pk PublicKey)
GenerateKeyPairDeterministic generates keys deterministically using the input entropy. The input entropy must be 32 bytes in length.
func GenerateX25519KeyPair ¶ added in v1.4.0
func GenerateX25519KeyPair() (xsk X25519SecretKey, xpk X25519PublicKey)
GenerateX25519KeyPair generates an ephemeral key pair for use in ECDH.
func IsValidCipherType ¶ added in v1.4.0
func IsValidCipherType(ct CipherType) bool
IsValidCipherType returns true if ct is a known CipherType and false otherwise.
func ReadSignedObject ¶ added in v1.0.0
ReadSignedObject reads a length-prefixed object prefixed by its signature, and verifies the signature.
func SecureWipe ¶ added in v1.0.0
func SecureWipe(data []byte)
SecureWipe destroys the data contained within a byte slice. There are no strong guarantees that all copies of the memory have been eliminated. If the OS was doing context switching or using swap space the keys may still be elsewhere in memory.
func VerifyDiffProof ¶ added in v1.4.0
func VerifyDiffProof(ranges []ProofRange, numLeaves uint64, proofHashes, leafHashes []Hash, root Hash) bool
VerifyDiffProof verifies a proof produced by MerkleDiffProof.
func VerifyHash ¶ added in v0.3.0
VerifyHash uses a public key and input data to verify a signature.
func VerifyMixedRangeProof ¶ added in v1.5.7
VerifyMixedRangeProof verifies a mixed proof given the node hashes, downloaded segments, the proof, contract root, number of segments in the contract, sectorSize, a start and an end for the downloaded range.
func VerifyRangeProof ¶ added in v1.4.0
VerifyRangeProof verifies a proof produced by MerkleRangeProof.
VerifyRangeProof for a single segment is NOT equivalent to VerifySegment.
func VerifySectorRangeProof ¶ added in v1.4.0
VerifySectorRangeProof verifies a proof produced by MerkleSectorRangeProof.
func VerifySegment ¶ added in v0.3.0
VerifySegment will verify that a segment, given the proof, is a part of a Merkle root.
VerifySegment is NOT equivalent to VerifyRangeProof for a single segment.
Types ¶
type CachedMerkleTree ¶ added in v1.0.0
type CachedMerkleTree struct {
merkletree.CachedTree
}
CachedMerkleTree wraps merkletree.CachedTree, changing some of the function definitions to assume sia-specific constants and return sia-specific types.
func NewCachedTree ¶ added in v1.0.0
func NewCachedTree(height uint64) *CachedMerkleTree
NewCachedTree returns a CachedMerkleTree, which can be used for getting Merkle roots and proofs from data that has cached subroots. See merkletree.CachedTree for more details.
func (*CachedMerkleTree) Prove ¶ added in v1.0.0
func (ct *CachedMerkleTree) Prove(base []byte, cachedHashSet []Hash) []Hash
Prove is a redefinition of merkletree.CachedTree.Prove, so that Sia-specific types are used instead of the generic types used by the parent package. The base is not a return value because the base is used as input.
func (*CachedMerkleTree) Push ¶ added in v1.0.0
func (ct *CachedMerkleTree) Push(h Hash)
Push is shorthand for PushSubTree(0, h).
func (*CachedMerkleTree) PushSubTree ¶ added in v1.3.3
func (ct *CachedMerkleTree) PushSubTree(height int, h Hash) error
PushSubTree is a redefinition of merkletree.CachedTree.PushSubTree, with the added type safety of only accepting a hash.
func (*CachedMerkleTree) Root ¶ added in v1.0.0
func (ct *CachedMerkleTree) Root() (h Hash)
Root is a redefinition of merkletree.CachedTree.Root, returning a Hash instead of a []byte.
type CipherKey ¶ added in v1.4.0
type CipherKey interface { // Key returns the underlying key. Key() []byte // Type returns the type of the key. Type() CipherType // EncryptBytes encrypts the given plaintext and returns the // ciphertext. EncryptBytes([]byte) Ciphertext // DecryptBytes decrypts the given ciphertext and returns the // plaintext. DecryptBytes(Ciphertext) ([]byte, error) // DecryptBytesInPlace decrypts the given ciphertext and returns the // plaintext. It will reuse the memory of the ciphertext which means // that it's not safe to use it after calling DecryptBytesInPlace. The // uint64 is the blockIndex at which the ciphertext is supposed to // start. e.g. if the ciphertext starts at offset 64 and Threefish is // used which has a BlockSize of 64 bytes, then the index would be 1. DecryptBytesInPlace(Ciphertext, uint64) ([]byte, error) // Derive derives a child cipherkey given a provided chunk index and // piece index. Derive(chunkIndex, pieceIndex uint64) CipherKey }
CipherKey is a key with Sia specific encryption/decryption methods.
func GenerateSiaKey ¶ added in v1.4.0
func GenerateSiaKey(ct CipherType) CipherKey
GenerateSiaKey creates a new SiaKey from the provided type.
func NewSiaKey ¶ added in v1.4.0
func NewSiaKey(ct CipherType, entropy []byte) (CipherKey, error)
NewSiaKey creates a new SiaKey from the provided type and entropy.
func NewWalletKey ¶ added in v1.4.0
NewWalletKey is a helper method which is meant to be used only if the type and entropy are guaranteed to be valid. In the wallet this is always the case since we always use hashes as the entropy and we don't read the key from file.
type CipherType ¶ added in v1.4.0
type CipherType [8]byte
CipherType is an identifier for the individual ciphers provided by this package.
func RandomCipherType ¶ added in v1.4.0
func RandomCipherType() CipherType
RandomCipherType is a helper function for testing. It's located in the crypto package to centralize all the types within one file to make future changes to them easy.
func (*CipherType) FromString ¶ added in v1.4.0
func (ct *CipherType) FromString(s string) error
FromString reads a CipherType from a string.
func (CipherType) Overhead ¶ added in v1.4.0
func (ct CipherType) Overhead() uint64
Overhead reports the overhead produced by a CipherType in bytes.
func (CipherType) String ¶ added in v1.4.0
func (ct CipherType) String() string
String creates a string representation of a CipherType that can be converted into a type with FromString.
type Hash ¶ added in v0.3.0
Hash is a BLAKE2b 256-bit digest.
func HashAll ¶ added in v0.3.0
func HashAll(objs ...interface{}) (hash Hash)
HashAll takes a set of objects as input, encodes them all using the encoding package, and then hashes the result.
func HashObject ¶ added in v0.3.0
func HashObject(obj interface{}) (hash Hash)
HashObject takes an object as input, encodes it using the encoding package, and then hashes the result.
func MerkleDiffProof ¶ added in v1.4.0
func MerkleDiffProof(ranges []ProofRange, numLeaves uint64, updatedSectors [][]byte, sectorRoots []Hash) []Hash
MerkleDiffProof builds a Merkle proof for multiple segment ranges.
func MerkleMixedRangeProof ¶ added in v1.5.7
func MerkleMixedRangeProof(sectorRoots []Hash, segmentData []byte, sectorSize int, start, end int) []Hash
MerkleMixedRangeProof creates a merkle range proof using both sector hashes and segments.
func MerkleProof ¶ added in v1.0.0
MerkleProof builds a Merkle proof that the data at segment 'proofIndex' is a part of the Merkle root formed by 'b'.
MerkleProof is NOT equivalent to MerkleRangeProof for a single segment.
func MerkleRangeProof ¶ added in v1.4.0
MerkleRangeProof builds a Merkle proof for the segment range [start,end).
MerkleRangeProof for a single segment is NOT equivalent to MerkleProof.
func MerkleRoot ¶ added in v0.3.0
MerkleRoot returns the Merkle root of the input data.
func MerkleSectorRangeProof ¶ added in v1.4.0
MerkleSectorRangeProof builds a Merkle proof for the sector range [start,end).
func (*Hash) LoadString ¶ added in v1.0.1
LoadString takes a string, parses the hash value of the string, and sets the value of the hash equal to the hash value of the string.
func (Hash) MarshalJSON ¶ added in v1.0.0
MarshalJSON marshals a hash as a hex string.
func (*Hash) UnmarshalJSON ¶ added in v1.0.0
UnmarshalJSON decodes the json hex string of the hash.
type HashSlice ¶ added in v0.3.0
type HashSlice []Hash
HashSlice is used for sorting
type MerkleTree ¶ added in v1.0.0
type MerkleTree struct {
merkletree.Tree
}
MerkleTree wraps merkletree.Tree, changing some of the function definitions to assume sia-specific constants and return sia-specific types.
func NewTree ¶ added in v0.3.0
func NewTree() *MerkleTree
NewTree returns a MerkleTree, which can be used for getting Merkle roots and Merkle proofs on data. See merkletree.Tree for more details.
func (*MerkleTree) PushObject ¶ added in v1.0.0
func (t *MerkleTree) PushObject(obj interface{})
PushObject encodes and adds the hash of the encoded object to the tree as a leaf.
func (*MerkleTree) Root ¶ added in v1.0.0
func (t *MerkleTree) Root() (h Hash)
Root is a redefinition of merkletree.Tree.Root, returning a Hash instead of a []byte.
type ProofRange ¶ added in v1.4.0
type ProofRange = merkletree.LeafRange
A ProofRange is a contiguous range of segments or sectors.
type PublicKey ¶
type PublicKey [PublicKeySize]byte
PublicKey is an object that can be used to verify signatures.
type SecretKey ¶
type SecretKey [SecretKeySize]byte
SecretKey can be used to sign data for the corresponding public key.
type Signature ¶
type Signature [SignatureSize]byte
Signature proves that data was signed by the owner of a particular public key's corresponding secret key.
type X25519PublicKey ¶ added in v1.4.0
type X25519PublicKey [32]byte
An X25519PublicKey is the public half of an X25519 key pair.
type X25519SecretKey ¶ added in v1.4.0
type X25519SecretKey [32]byte
An X25519SecretKey is the secret half of an X25519 key pair.