gosodium

README

Note from RedragonX

This is a complete rework of jasonmccampbell's GoSodium fork. The original coder seems to be MIA. I've changed a lot already like the folder management, better testing, and building environment scripts. This fork will one day hopefully replace his fork to be the official GoSodium library.

Introduction

GoSodium is a (work-in-progress) Go language binding for the LibSodium cryptography library. LibSodium is a cross-platform port of the NaCL library published by Dan Bernstein and company implementing the 25519 elliptic curve. These cryptographic methods, and these libraries, are highly regarded as fast, secure, and free of governmental influences.

This package is primarily for personal use as an excuse to learn Go and get more familiar with cryptography and is very much a work-in-progress. If it is useful to others, please feel free to use it, copy it, or contribute to it. If this is a duplicate of other work, please let me know as I am happy to contribute to other projects to avoid redundant efforts.

Status

I am (slowly) wrapping parts of the library as I have time / need so many parts are yet-unwrapped. This table provides a summary of the functionality in each module of the LibSodium library and whether they are included.

Module	Wrap status	Test coverage	Function
cryptoauth	Not wrapped	N/A	Generates a MAC for a given message and secret key using SHA-series hashes (key may be used across multiple messages)
cryptobox	Wrapped	Yes	Encrypts and authenticates a message using a key pair and nonce
cryptocore	Not wrapped	N/A	Core encryption algorithms used by other modules
cryptogenerichash	Partially	N/A	Cryptographically secure generic hash function
cryptohash	Not wrapped	N/A	Hash function based on SHA512 algorithm
cryptoonetimeauth	Wrapped	Yes	Generates a MAC for a given message and shared key using Poly1305 algorithm (key may NOT be reused across messages)
cryptoscalarmult	Partially	N/A	Compute the public key given a secret key previously generated with crypto_box_keypair
cryptosecret_box	Wrapped	Partial	Encrypts and authenticates a message using a shared key and nonce
cryptosign	Wrapped	N/A	Seals and verifies a message using a key pair
cryptostreaming	Not wrapped	N/A	Generates a randomized stream of bits to be XOR'd with a message
randombytes	Wrapped	Yes	Fills a byte array with cryptographic-quality random values
sodium	Partially	Partial	Initialization and utility methods

Definitions:

• Key Pair: A pair of keys comprised of one public key and one secret key. For example, the sender's secret key and the recipient's public key, or the sender's public key and the recipient's private key.
• Shared key: A single key which is known to both the sender and recipient(s). In LibSodium it is common to generate a shared key from a key pair above. The keys have the property that the symmetric key can be generated from each half of a key pair. That is, Alice's public key plus Bob's secret key can be combined to generate the same key as Bob's public key and Alice's private key.

Building and testing GoSodium

Once you have a working golang environment, go to your Go 'src' directory and run the following commands:

./test.sh

If all works as expected, the tests should pass for all packages in the sodium folder and everything should be ready for use.

To build into your main pkg folder, run this command:

./build.sh

The scripts use a custom libsodium location, currently works on Arch Linux. Please change the locations if needed.

Contact

Questions? Comments? Requests? Complaints? Feel free to contact me here or Twitter @RedragonX

Documentation

Overview

GoSodium is a higher level, go-ideomatic wrapper on top of the LibSodium library. The functions provided here handle much of the memory allocation and error checking, raising panic calls in cases where a function fails. For low-level access to the full libsodium library use GoSodium.sodium, which attempts to faithfully reproduce the libsodium interface.

Index

• func NewKeyPair() (PublicKey, SecretKey)
• type Nonce
  • func NewBoxNonce() Nonce
• type PublicKey
  • func AllocPublicKey() PublicKey
• type SecretKey
  • func AllocSecretKey() SecretKey
• type SymmetricKey
  • func AllocSymmetricKey() SymmetricKey

Functions

func NewKeyPair

func NewKeyPair() (PublicKey, SecretKey)

Types

type Nonce

type Nonce []byte

func NewBoxNonce

func NewBoxNonce() Nonce

type PublicKey

type PublicKey []byte

func AllocPublicKey

func AllocPublicKey() PublicKey

type SecretKey

type SecretKey []byte

func AllocSecretKey

func AllocSecretKey() SecretKey

type SymmetricKey

type SymmetricKey []byte

func AllocSymmetricKey

func AllocSymmetricKey() SymmetricKey