Skip to content

Commit

Permalink
improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@BarraRoffe
BarraRoffe committed Jul 7, 2015
1 parent 58c636c commit a24b938
Show file tree
Hide file tree
Showing 8 changed files with 137 additions and 136 deletions.
13 changes: 7 additions & 6 deletions hashcash/hashcash.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ import (
"encoding/binary"
)

// Version of this release
// Version of this release.
const Version = "0.0.1 very alpha"

// NonceSize is the size of a hashcash nonce
// NonceSize is the size of a hashcash nonce.
const NonceSize = 8

// BitCount counts leading zero bits in d and returns them
// BitCount counts leading zero bits in d and returns them.
func BitCount(d [32]byte) byte {
var ret byte
for _, x := range d {
Expand Down Expand Up @@ -55,7 +55,7 @@ func BitCount(d [32]byte) byte {
return ret
}

// TestNonce verifies that a given nonce generates bits zero bits on d when hashed
// TestNonce verifies that a given nonce generates bits zero bits on d when hashed.
func TestNonce(d, nonce []byte, bits byte) (bool, byte) {
bits--
x := make([]byte, len(d)+len(nonce))
Expand All @@ -73,8 +73,9 @@ func NonceToUInt64(nonce []byte) uint64 {
return binary.LittleEndian.Uint64(nonce)
}

// ComputeNonce is the hashcash algorithm
// c is the start value for calculation, stop is the end value. Both can be 0 to ignore segemented calculations
// ComputeNonce is the hashcash algorithm.
// c is the start value for calculation, stop is the end value.
// Both can be 0 to ignore segemented calculations.
func ComputeNonce(d []byte, bits byte, c, stop uint64) (nonce []byte, ok bool) {
bits--
x := make([]byte, len(d)+NonceSize)
Expand Down
10 changes: 5 additions & 5 deletions hashcash/parallel.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ import (
)

var (
// Steps is the number of steps per thread per cycle
// Steps is the number of steps per thread per cycle.
Steps = uint64(4194304)
// SingleThreadBits Number of bits required for parallel computing
// SingleThreadBits Number of bits required for parallel computing.
SingleThreadBits = byte(20)
)

Expand All @@ -17,7 +17,7 @@ type computeResult struct {
nonce []byte
}

// ComputeNonceParallel parallel compute hashcash
// ComputeNonceParallel computes hashcash in parallel.
func ComputeNonceParallel(d []byte, bits byte, start, stop uint64) (nonce []byte, ok bool) {
ncpus := runtime.NumCPU()
if ncpus > 1 {
Expand Down Expand Up @@ -45,7 +45,7 @@ func ComputeNonceParallel(d []byte, bits byte, start, stop uint64) (nonce []byte
}
}

// computeNonceThread computes a nonce
// computeNonceThread computes a nonce.
func computeNonceThread(d []byte, bits byte, c, stop uint64, res chan<- computeResult) {
nonce, ok := ComputeNonce(d, bits, c, stop)
res <- computeResult{
Expand All @@ -54,7 +54,7 @@ func computeNonceThread(d []byte, bits byte, c, stop uint64, res chan<- computeR
}
}

// ComputeNonceSelect calls parallel or single compute depending on bits
// ComputeNonceSelect calls parallel or single compute depending on bits.
func ComputeNonceSelect(d []byte, bits byte, start, stop uint64) (nonce []byte, ok bool) {
if bits > SingleThreadBits {
return ComputeNonceParallel(d, bits, start, stop)
Expand Down
10 changes: 5 additions & 5 deletions message/envelope.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,14 @@ const (
)

var (
// ErrEnvelopeShort is returned if the envelope is too short to even contain a signature header
// ErrEnvelopeShort is returned if the envelope is too short to even contain a signature header.
ErrEnvelopeShort = errors.New("message: Envelope too short")
)

// Base64Message is a message encoded in Base64
// Base64Message is a message encoded in Base64.
type Base64Message []byte

// GetSignHeader returns the signature header from an message
// GetSignHeader returns the signature header from an message.
func (bm Base64Message) GetSignHeader() (*[SignHeaderSize]byte, error) {
var ret [SignHeaderSize]byte
if len(bm) < signHeaderMaxBase64 {
Expand All @@ -35,7 +35,7 @@ func (bm Base64Message) GetSignHeader() (*[SignHeaderSize]byte, error) {
return &ret, nil
}

// Decode a base64 encoded message
// Decode a base64 encoded message.
func (bm Base64Message) Decode() ([]byte, error) {
dst := make([]byte, base64.StdEncoding.DecodedLen(len(bm)))
n, err := base64.StdEncoding.Decode(dst, bm)
Expand All @@ -45,7 +45,7 @@ func (bm Base64Message) Decode() ([]byte, error) {
return dst[:n], nil
}

// EncodeBase64 encodes a message to base64
// EncodeBase64 encodes a message to base64.
func EncodeBase64(message []byte) Base64Message {
dst := make([]byte, base64.StdEncoding.EncodedLen(len(message)))
base64.StdEncoding.Encode(dst, message)
Expand Down
66 changes: 33 additions & 33 deletions message/integration.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,67 +32,67 @@ Receive Output:
error
*/

// VersionID of this release
// VersionID of this release.
const VersionID = "0.0.1 very alpha"

var (
//ErrNoKeys is returned if no method for private key discovery is available
// ErrNoKeys is returned if no method for private key discovery is available.
ErrNoKeys = errors.New("message: No private keys available")
// ErrBadMessageID is returned when the message ID signed is different from the one calculated
// ErrBadMessageID is returned when the message ID signed is different from the one calculated.
ErrBadMessageID = errors.New("message: Unexpected message ID")
// ErrBadSender is returned when another sender was expected
// ErrBadSender is returned when another sender was expected.
ErrBadSender = errors.New("message: Unexpected sender")
)

const (
// DefaultTotalLength is the size of the message.
DefaultTotalLength = BodyMaxLength + SignHeaderSize + KeyHeaderSize
// DefaultPadToLength is the size of the body including random padding
// DefaultPadToLength is the size of the body including random padding.
DefaultPadToLength = 4096
// DefaultHashCashBits is the minimum number of hashcash bits requried
// DefaultHashCashBits is the minimum number of hashcash bits requried.
DefaultHashCashBits = byte(23)
)

// CalcMaxEmbedded returns the maximum size of data that can be included in a message of TotalLength size
// CalcMaxEmbedded returns the maximum size of data that can be included in a message of TotalLength size.
func CalcMaxEmbedded(TotalLength int) int {
return TotalLength - SignHeaderSize - KeyHeaderSize
}

// Encrypt encrypts a message
// Encrypt encrypts a message.
func (sender Sender) Encrypt(messageType byte, message []byte) (encMessage []byte, meta *MetaDataSend, err error) {
return sender.encrypt(messageType, message, false)
}

// EncryptRepost encrypts a message for reposting, meaning that the deterministic padding is thrown away and there is no encoding
// EncryptRepost encrypts a message for reposting, meaning that the deterministic padding is thrown away and there is no encoding.
func (sender Sender) EncryptRepost(messageType byte, message []byte) (rewrapMessage []byte, meta *MetaDataSend, err error) {
return sender.encrypt(messageType, message, true)
}

// Sender defines sender behavior
type Sender struct {
Signer *SignKeyPair // Optional, autogenerated when missing
SenderPrivateKey *Curve25519Key // Optional. Use ephemeral key if missing
ReceiveConstantPublicKey *Curve25519Key // Optional. Constant public key of receiver, ephemeral keys will be used if missing
ReceiveTemporaryPublicKey *Curve25519Key // MUST be set IF ReceiveConstantPublicKey is set
Signer *SignKeyPair // Optional, autogenerated when missing.
SenderPrivateKey *Curve25519Key // Optional. Use ephemeral key if missing.
ReceiveConstantPublicKey *Curve25519Key // Optional. Constant public key of receiver, ephemeral keys will be used if missing.
ReceiveTemporaryPublicKey *Curve25519Key // MUST be set IF ReceiveConstantPublicKey is set.
// TotalLength is the total size of body including padding.
// Set to default if missing if 0
// Set to default if missing if 0.
TotalLength int
// PadToLength will pad the body to PadToLength size of random padding before adding deterministic padding, if any.
// Set to default if missing if 0
// Set to default if missing if 0.
PadToLength int
// HashCashBits is the minimum number of hashcash bits required. Will be set to default if missing
// HashCashBits is the minimum number of hashcash bits required. Will be set to default if missing.
HashCashBits byte
}

// MetaDataSend contains metadata for the message
// MetaDataSend contains metadata for the message.
type MetaDataSend struct {
MessageID [MessageIDSize]byte // MessageID of the message (calculated from header+body)
PadKey *[PadKeySize]byte // Will be set if deterministic padding is appended and meaningful
MessageKey *Curve25519Key // Will be set if ephemeral recipient keys are used
MessageID [MessageIDSize]byte // MessageID of the message (calculated from header+body).
PadKey *[PadKeySize]byte // Will be set if deterministic padding is appended and meaningful.
MessageKey *Curve25519Key // Will be set if ephemeral recipient keys are used.
ReceiverConstantPubKey *Curve25519Key
}

// encrypt message
// encrypt message.
func (sender *Sender) encrypt(messageType byte, message []byte, repost bool) (encMessage []byte, meta *MetaDataSend, err error) {
var Signer *SignKeyPair
meta = new(MetaDataSend)
Expand Down Expand Up @@ -182,27 +182,27 @@ func (sender *Sender) encrypt(messageType byte, message []byte, repost bool) (en
return EncodeBase64(myMessage.Bytes()), meta, nil
}

// Receiver defines receiver functionality
// Receiver defines receiver functionality.
type Receiver struct {
SenderPublicKey *Curve25519Key // Optional. If set, verify for message
ReceiveConstantPrivateKey *Curve25519Key // Optional. Will use callback if not set
ReceiveTemporaryPrivateKey *Curve25519Key // Optional. Will try to generate from ReceiveConstantPrivateKey, then Callback
// KeyCallBack is an optional function to get private keys. It takes a public key as parameter and expects the private key or nil as return
SenderPublicKey *Curve25519Key // Optional. If set, verify for message.
ReceiveConstantPrivateKey *Curve25519Key // Optional. Will use callback if not set.
ReceiveTemporaryPrivateKey *Curve25519Key // Optional. Will try to generate from ReceiveConstantPrivateKey, then Callback.
// KeyCallBack is an optional function to get private keys. It takes a public key as parameter and expects the private key or nil as return.
KeyCallBack func(*Curve25519Key) *Curve25519Key
// HashCashBits is the minimum number of hashcash bits required. Will be set to default if missing
// HashCashBits is the minimum number of hashcash bits required. Will be set to default if missing.
HashCashBits byte
}

// MetaDataRecieve contains data from decryption
type MetaDataRecieve struct {
SenderConstantPublicKey *Curve25519Key // Public key used by sender
ReceiveConstantPublicKey *Curve25519Key // Constant public key of recipient
ReceiveTemporaryPublicKey *Curve25519Key // Temporary public key of recipient
MessageID [MessageIDSize]byte // MessageID as calculated
MessageType byte // MessageType of message
SenderConstantPublicKey *Curve25519Key // Public key used by sender.
ReceiveConstantPublicKey *Curve25519Key // Constant public key of recipient.
ReceiveTemporaryPublicKey *Curve25519Key // Temporary public key of recipient.
MessageID [MessageIDSize]byte // MessageID as calculated.
MessageType byte // MessageType of message.
}

// Decrypt applies decryption & verification to a messsage
// Decrypt applies decryption & verification to a messsage.
func (receiver Receiver) Decrypt(encMessage []byte) (message []byte, meta *MetaDataRecieve, err error) {
// Set defaults
if receiver.HashCashBits <= 0 {
Expand Down
Loading

0 comments on commit a24b938

Please sign in to comment.