Documentation ¶
Index ¶
- Variables
- func AuthTimestamp(additionalData []byte, latestTimestamp int64) (ok bool, ts int64, err error)
- func CurrentTimestamp() int64
- func CurrentTimestampBytes() []byte
- func CurrentTimestampString() string
- type AEAD
- type AEADStore
- type AESGCM
- type ChaCha20Poly1305
- type HKDF
- func (k *HKDF) DeriveKey(sharedSecret string, hash func() hash.Hash, nonce []byte, ...) (b []byte, err error)
- func (k *HKDF) Next(r io.Reader) (b []byte, err error)
- func (k *HKDF) Nonce() []byte
- func (k *HKDF) Reader(sharedSecret string, hash func() hash.Hash, nonce []byte, ...) (r io.Reader, err error)
- type HPKEAEADStore
- type HPKEStore
- func NewHPKE(curve ecdh.Curve, hash func() hash.Hash, kdfSender KDF, kdfRecipient KDF, ...) (s *HPKEStore, err error)
- func NewHPKEWithPrivateKey(curve ecdh.Curve, hash func() hash.Hash, kdfSender KDF, kdfRecipient KDF, ...) (s *HPKEStore, err error)
- func NewHPKE_Curve25519_SHA256_HKDF_AESGCM() (s *HPKEStore, err error)
- func NewHPKE_Curve25519_SHA256_HKDF_AESGCM_WithPrivateKey(privateKey string) (s *HPKEStore, err error)
- func (s *HPKEStore) Decrypt(ciphertext []byte, aeadNonce []byte, additionalData []byte) (plaintext []byte, err error)
- func (s *HPKEStore) DecryptAEADStore(v *AEADStore) (plaintext []byte, err error)
- func (s *HPKEStore) EncodeJSONAndEncryptToJSON(value interface{}, additionalData []byte) (jsonData []byte, err error)
- func (s *HPKEStore) EncodeJSONAndEncryptToJSONWithNonce(value interface{}, aeadNonce []byte, additionalData []byte) (jsonData []byte, err error)
- func (s *HPKEStore) Encrypt(plaintext []byte, additionalData []byte) (v *AEADStore, err error)
- func (s *HPKEStore) EncryptWithNonce(plaintext []byte, aeadNonce []byte, additionalData []byte) (v *AEADStore, err error)
- func (s *HPKEStore) ExternalPublicKey() string
- func (s *HPKEStore) PrivateKey() string
- func (s *HPKEStore) PublicKey() string
- func (s *HPKEStore) SetExternalPublicKeyAndStartKDFs(externalPublicKey string, senderKDFNonce []byte, recipientKDFNonce []byte, ...) (err error)
- func (s *HPKEStore) SharedSecret() string
- func (s *HPKEStore) UnmarshalJSONAndDecryptFromJSON(jsonData []byte, v any) (err error)
- func (s *HPKEStore) UnmarshalJSONAndDecryptFromJSONWithADCheck(jsonData []byte, v any, authFunc func(additionalData []byte) (bool, error)) (err error)
- func (s *HPKEStore) X963RepresentationPrivateKey() []byte
- func (s *HPKEStore) X963RepresentationPublicKey() []byte
- type KDF
- type KDFStore
- type Store
- func New(curve ecdh.Curve, hash func() hash.Hash, kdf KDF, aead AEAD, ...) (s *Store, err error)
- func NewWithPrivateKey(curve ecdh.Curve, hash func() hash.Hash, kdf KDF, aead AEAD, privateKey string, ...) (s *Store, err error)
- func New_Curve25519_SHA256_HKDF_AESGCM(externalPublicKey string) (s *Store, err error)
- func New_Curve25519_SHA256_HKDF_AESGCM_WithPrivateKey(privateKey string, externalPublicKey string) (s *Store, err error)
- func (s *Store) Decrypt(symmetricKeyNonce []byte, ciphertext []byte, aeadNonce []byte, ...) (plaintext []byte, err error)
- func (s *Store) DecryptAEADStore(v *AEADStore) (plaintext []byte, err error)
- func (s *Store) EncodeJSONAndEncryptToJSON(value interface{}, additionalData []byte) (jsonData []byte, err error)
- func (s *Store) EncodeJSONAndEncryptToJSONWithNonces(symmetricKeyNonce []byte, value interface{}, aeadNonce []byte, ...) (jsonData []byte, err error)
- func (s *Store) Encrypt(plaintext []byte, additionalData []byte) (v *AEADStore, err error)
- func (s *Store) EncryptWithNonces(symmetricKeyNonce []byte, plaintext []byte, aeadNonce []byte, ...) (v *AEADStore, err error)
- func (s *Store) ExternalPublicKey() string
- func (s *Store) PrivateKey() string
- func (s *Store) PrivateKeyPEM() (string, error)
- func (s *Store) PublicKey() string
- func (s *Store) PublicKeyPEM() (string, error)
- func (s *Store) SetExternalPublicKey(externalPublicKey string) error
- func (s *Store) SharedSecret() string
- func (s *Store) UnmarshalJSONAndDecryptFromJSON(jsonData []byte, v any) (err error)
- func (s *Store) UnmarshalJSONAndDecryptFromJSONWithADCheck(jsonData []byte, v any, authFunc func(additionalData []byte) (bool, error)) (err error)
- func (s *Store) X963RepresentationPrivateKey() []byte
- func (s *Store) X963RepresentationPublicKey() []byte
Constants ¶
This section is empty.
Variables ¶
var ErrAdditionalData = errors.New("additional data authentication error")
var ErrDecrypt = errors.New("decrypt error")
var ErrDeriveKey = errors.New("derive key error")
var ErrEncrypt = errors.New("encrypt error")
var ErrMarsal = errors.New("marshal error")
var ErrPublicKeyNotSet = errors.New("external public key not set")
var ErrUnmarsal = errors.New("unmarshal error")
var ErrUnmarsalAEADStore = errors.New("AEADStore unmarshal error")
Functions ¶
func AuthTimestamp ¶ added in v0.0.3
AuthTimestamp converts additionalData ([]byte) into an int64 timestamp, ensures that this timestamp is after the latestTimestamp, and ensures the timestamp is within the last 10 milliseconds
func CurrentTimestamp ¶ added in v0.0.3
func CurrentTimestamp() int64
CurrentTimestamp is the current time since 1970 in milliseconds as an int64.
func CurrentTimestampBytes ¶ added in v0.0.3
func CurrentTimestampBytes() []byte
CurrentTimestampBytes is the current time since 1970 in milliseconds as a bytes.
func CurrentTimestampString ¶ added in v0.0.3
func CurrentTimestampString() string
CurrentTimestampString is the current time since 1970 in milliseconds as a string.
Types ¶
type AEAD ¶
type AEAD interface { Encrypt(symmetricKey, symmetricKeyNonce, plaintext, aeadNonce, additionalData []byte) (*AEADStore, error) Decrypt(symmetricKey, ciphertext, aeadNonce, additionalData []byte) (plaintext []byte, err error) }
AEAD is the interface for authenticated encryption with associated data (AEAD) ciphers.
type AESGCM ¶
type AESGCM struct {
AEAD
}
AESGCM is the Advanced Encryption Standard (AES) Galois/Counter Mode (GCM) struct. AESGCM conforms with the AEAD interface.
type ChaCha20Poly1305 ¶
type ChaCha20Poly1305 struct {
AEAD
}
ChaCha20Poly1305 combines the ChaCha20 stream cipher with the Poly1305 message authentication code. haCha20Poly1305 conforms with the AEAD interface.
func NewChaCha20Poly1305 ¶
func NewChaCha20Poly1305() *ChaCha20Poly1305
NewChaCha20Poly1305 creates a new ChaCha20Poly1305 struct.
type HKDF ¶
HKDF is a key derivation function (KDF) based on the HMAC message authentication code. HKDF conforms with the KDF interface.
func (*HKDF) DeriveKey ¶
func (k *HKDF) DeriveKey( sharedSecret string, hash func() hash.Hash, nonce []byte, additionalData []byte, ) (b []byte, err error)
Derivekey creates a single HKDF key from a sharedSecret. Use Reader() and Next() to create multiple derived keys from a single sharedSecret.
type HPKEAEADStore ¶ added in v0.0.3
HPKEAEADStore stores authenticated encryption with associated data (AEAD) variables.
type HPKEStore ¶ added in v0.0.3
type HPKEStore struct {
// contains filtered or unexported fields
}
HPKEStore stores key exchange variables.
func NewHPKE ¶ added in v0.0.3
func NewHPKE( curve ecdh.Curve, hash func() hash.Hash, kdfSender KDF, kdfRecipient KDF, aead AEAD, ) (s *HPKEStore, err error)
NewHPKE creates a new Store with a random private key. If we do not know the externalPublicKey when we create the Store, the externalPublicKey can be set as an empty string and updated later using SetExternalPublicKey().
func NewHPKEWithPrivateKey ¶ added in v0.0.3
func NewHPKEWithPrivateKey( curve ecdh.Curve, hash func() hash.Hash, kdfSender KDF, kdfRecipient KDF, aead AEAD, privateKey string, ) (s *HPKEStore, err error)
NewHPKEWithPrivateKey creates a new Store with the specified private key. Only use a specified (i.e. non-random) private key for testing. If we do not know the externalPublicKey when we create the Store, the externalPublicKey can be set as an empty string and updated later using SetExternalPublicKey().
func NewHPKE_Curve25519_SHA256_HKDF_AESGCM ¶ added in v0.0.3
NewHPKE_Curve25519_SHA256_HKDF_AESGCM creates a new Store using the Curve25519 curve, SHA256 as the hash, HKDF as the key derivation function, and AESGCM as the authenticated encryption with associated data (AEAD) cipher. This is a commonly used Store combination as at September 2023. If we do not know the externalPublicKey when we create the Store, the externalPublicKey can be set as an empty string here and updated later using SetExternalPublicKey().
func NewHPKE_Curve25519_SHA256_HKDF_AESGCM_WithPrivateKey ¶ added in v0.0.3
func NewHPKE_Curve25519_SHA256_HKDF_AESGCM_WithPrivateKey( privateKey string, ) (s *HPKEStore, err error)
NewHPKE_Curve25519_SHA256_HKDF_AESGCM_WithPrivateKey is New_Curve25519_SHA256_HKDF_AESGCM() using the specified private key. Only use specified (i.e. non-random) nonces for testing. If we do not know the externalPublicKey when we create the Store, the externalPublicKey can be set as an empty string here and updated later using SetExternalPublicKey().
func (*HPKEStore) Decrypt ¶ added in v0.0.3
func (s *HPKEStore) Decrypt( ciphertext []byte, aeadNonce []byte, additionalData []byte, ) (plaintext []byte, err error)
Decrypt decrypts (i.e. performs the opposite of the Encrypt() function) the ciphertext using the provided aeadNonce and additionalData. All of this information is included in AEADStore structs.
func (*HPKEStore) DecryptAEADStore ¶ added in v0.0.3
DecryptAEADStore performs Decrypt() using the provided AEADStore struct.
func (*HPKEStore) EncodeJSONAndEncryptToJSON ¶ added in v0.0.3
func (s *HPKEStore) EncodeJSONAndEncryptToJSON( value interface{}, additionalData []byte, ) (jsonData []byte, err error)
EncodeJSONAndEncryptToJSON JSON is a convenience function that encodes the value to JSON (using the provided additionalData), performs Encrypt(), then encodes the AEADStore as JSON bytes.
func (*HPKEStore) EncodeJSONAndEncryptToJSONWithNonce ¶ added in v0.0.3
func (s *HPKEStore) EncodeJSONAndEncryptToJSONWithNonce( value interface{}, aeadNonce []byte, additionalData []byte, ) (jsonData []byte, err error)
EncodeJSONAndEncryptToJSONWithNonce is the same as EncodeJSONAndEncryptToJSON but with user specified aeadNonce. Set these nonce as nil to create a random nonce. Only use specified (i.e. non-random) nonces for testing.
func (*HPKEStore) Encrypt ¶ added in v0.0.3
Encrypt creates a random nonce (the symmetricKeyNonce), uses the key derivation function with this symmetricKeyNonceto to create a derived key for our SharedSecret, creates a second random nonce (the aeadNonce), and then encrypts the plaintext with the aeadNonce. The additionalData bytes (which do not need to be secret) are used with both the key derivation function and when encrypting (using encryption with associated data (AEAD) encryption). Encrypt() returns an AEADStore struct containing both nonces, the ciphertext, and the additionalData.
func (*HPKEStore) EncryptWithNonce ¶ added in v0.0.3
func (s *HPKEStore) EncryptWithNonce( plaintext []byte, aeadNonce []byte, additionalData []byte, ) (v *AEADStore, err error)
EncryptWithNonce is the same as Encrypt() but with a user specified aeadNonce. Set this nonce as nil to create a random nonce. Only use specified (i.e. non-random) nonces for testing.
func (*HPKEStore) ExternalPublicKey ¶ added in v0.0.3
ExternalPublicKey prints the external Elliptic-curve Diffie–Hellman (ECDH) public key for the Store. We use the ECDH private key and this ECDH ExternalPublicKey to create the SharedSecret for the Store.
func (*HPKEStore) PrivateKey ¶ added in v0.0.3
PrivateKey prints the Elliptic-curve Diffie–Hellman (ECDH) private key for the Store.
func (*HPKEStore) PublicKey ¶ added in v0.0.3
PublicKey prints the Elliptic-curve Diffie–Hellman (ECDH) public key for the Store.
func (*HPKEStore) SetExternalPublicKeyAndStartKDFs ¶ added in v0.0.3
func (s *HPKEStore) SetExternalPublicKeyAndStartKDFs( externalPublicKey string, senderKDFNonce []byte, recipientKDFNonce []byte, additionalData []byte, ) (err error)
SetExternalPublicKeyAndKDF sets the externalPublicKey, uses the ECDH private key and the ECDH ExternalPublicKey to create the SharedSecret for the Store, and starts the key derivation functions. We only need to call this function if we set the externalPublicKey as an empty string when we created the Store.
func (*HPKEStore) SharedSecret ¶ added in v0.0.3
SharedSecret is the Elliptic-curve Diffie–Hellman (ECDH) sharded secret for the Store. We use the ECDH private key and the ECDH ExternalPublicKey to create this SharedSecret for the Store.
func (*HPKEStore) UnmarshalJSONAndDecryptFromJSON ¶ added in v0.0.3
UnmarshalJSONAndDecryptFromJSON is a convenience function that performs the opposite of EncodeJSONAndEncryptToJSON(). This function unmarshals JSON AEADStore bytes, decrypts, and then unmarshals the resulting JSON plaintext.
func (*HPKEStore) UnmarshalJSONAndDecryptFromJSONWithADCheck ¶ added in v0.0.3
func (s *HPKEStore) UnmarshalJSONAndDecryptFromJSONWithADCheck( jsonData []byte, v any, authFunc func(additionalData []byte) (bool, error), ) (err error)
UnmarshalJSONAndDecryptFromJSONWithAdditionalData is a convenience function that performs the opposite of EncodeJSONAndEncryptToJSON(). This function unmarshals JSON AEADStore bytes, decrypts, and then unmarshals the resulting JSON plaintext. This function also checks whether the provided additionalData matches with the AEADStore additionalData.
func (*HPKEStore) X963RepresentationPrivateKey ¶ added in v0.0.3
X963RepresentationPrivateKey prints the Store Elliptic-curve Diffie–Hellman (ECDH) public key and private key as bytes. This produces the same result as calling X963RepresentationPrivateKey in the Apple CryptoKit library.
func (*HPKEStore) X963RepresentationPublicKey ¶ added in v0.0.3
X963RepresentationPublicKey prints the Store Elliptic-curve Diffie–Hellman (ECDH) public key as bytes. This produces the same result as calling X963RepresentationPublicKey in the Apple CryptoKit library.
type KDF ¶
type KDF interface { Nonce() []byte DeriveKey(sharedSecret string, hash func() hash.Hash, nonce []byte, additionalData []byte) (b []byte, err error) Reader(sharedSecret string, hash func() hash.Hash, nonce []byte, additionalData []byte) (io.Reader, error) Next(r io.Reader) (b []byte, err error) }
KDF is the interface for key derivation functions (KDFs).
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store stores key exchange variables.
func New ¶
func New( curve ecdh.Curve, hash func() hash.Hash, kdf KDF, aead AEAD, externalPublicKey string, ) (s *Store, err error)
New creates a new Store with a random private key. If we do not know the externalPublicKey when we create the Store, the externalPublicKey can be set as an empty string and updated later using SetExternalPublicKey().
func NewWithPrivateKey ¶
func NewWithPrivateKey( curve ecdh.Curve, hash func() hash.Hash, kdf KDF, aead AEAD, privateKey string, externalPublicKey string, ) (s *Store, err error)
New creates a new Store with the specified private key. Only use a specified (i.e. non-random) private key for testing. If we do not know the externalPublicKey when we create the Store, the externalPublicKey can be set as an empty string and updated later using SetExternalPublicKey().
func New_Curve25519_SHA256_HKDF_AESGCM ¶
New_Curve25519_SHA256_HKDF_AESGCM creates a new Store using the Curve25519 curve, SHA256 as the hash, HKDF as the key derivation function, and AESGCM as the authenticated encryption with associated data (AEAD) cipher. This is a commonly used Store combination as at September 2023. If we do not know the externalPublicKey when we create the Store, the externalPublicKey can be set as an empty string here and updated later using SetExternalPublicKey().
func New_Curve25519_SHA256_HKDF_AESGCM_WithPrivateKey ¶
func New_Curve25519_SHA256_HKDF_AESGCM_WithPrivateKey( privateKey string, externalPublicKey string, ) (s *Store, err error)
New_Curve25519_SHA256_HKDF_AESGCM_WithPrivateKey is New_Curve25519_SHA256_HKDF_AESGCM() using the specified private key. Only use specified (i.e. non-random) nonces for testing. If we do not know the externalPublicKey when we create the Store, the externalPublicKey can be set as an empty string here and updated later using SetExternalPublicKey().
func (*Store) Decrypt ¶
func (s *Store) Decrypt( symmetricKeyNonce []byte, ciphertext []byte, aeadNonce []byte, additionalData []byte, ) (plaintext []byte, err error)
Decrypt decrypts (i.e. performs the opposite of the Encrypt() function) the ciphertext using the provided symmetricKeyNonce, aeadNonce, and additionalData. All of this information is included in AEADStore structs.
func (*Store) DecryptAEADStore ¶
DecryptAEADStore performs Decrypt() using the provided AEADStore struct.
func (*Store) EncodeJSONAndEncryptToJSON ¶
func (s *Store) EncodeJSONAndEncryptToJSON( value interface{}, additionalData []byte, ) (jsonData []byte, err error)
EncodeJSONAndEncryptToJSON JSON is a convenience function that encodes the value to JSON (using the provided additionalData), performs Encrypt(), then encodes the AEADStore as JSON bytes.
func (*Store) EncodeJSONAndEncryptToJSONWithNonces ¶
func (s *Store) EncodeJSONAndEncryptToJSONWithNonces( symmetricKeyNonce []byte, value interface{}, aeadNonce []byte, additionalData []byte, ) (jsonData []byte, err error)
EncodeJSONAndEncryptToJSONWithNonce is the same as EncodeJSONAndEncryptToJSON but with user specified nonces (i.e. the symmetricKeyNonce and aeadNonce). Set these nonces as nil to create random nonces. Only use specified (i.e. non-random) nonces for testing.
func (*Store) Encrypt ¶
Encrypt creates a random nonce (the symmetricKeyNonce), uses the key derivation function with this symmetricKeyNonceto to create a derived key for our SharedSecret, creates a second random nonce (the aeadNonce), and then encrypts the plaintext with the aeadNonce. The additionalData bytes (which do not need to be secret) are used with both the key derivation function and when encrypting (using encryption with associated data (AEAD) encryption). Encrypt() returns an AEADStore struct containing both nonces, the ciphertext, and the additionalData.
func (*Store) EncryptWithNonces ¶
func (s *Store) EncryptWithNonces( symmetricKeyNonce []byte, plaintext []byte, aeadNonce []byte, additionalData []byte, ) (v *AEADStore, err error)
EncryptWithNonces is the same as Encrypt() but with user specified nonces (i.e. the symmetricKeyNonce and aeadNonce). Set these nonces as nil to create random nonces. Only use specified (i.e. non-random) nonces for testing.
func (*Store) ExternalPublicKey ¶
ExternalPublicKey prints the external Elliptic-curve Diffie–Hellman (ECDH) public key for the Store. We use the ECDH private key and this ECDH ExternalPublicKey to create the SharedSecret for the Store.
func (*Store) PrivateKey ¶
PrivateKey prints the Elliptic-curve Diffie–Hellman (ECDH) private key for the Store.
func (*Store) PrivateKeyPEM ¶
PrivateKeyPEM returns the private key in the Privacy-Enhanced Mail (PEM) format.
func (*Store) PublicKey ¶
PublicKey prints the Elliptic-curve Diffie–Hellman (ECDH) public key for the Store.
func (*Store) PublicKeyPEM ¶
PrivateKeyPEM returns the public key in the Privacy-Enhanced Mail (PEM) format.
func (*Store) SetExternalPublicKey ¶
SetExternalPublicKey sets the externalPublicKey, and uses the ECDH private key and the ECDH ExternalPublicKey to create the SharedSecret for the Store. We only need to call this function if we set the externalPublicKey as an empty string when we created the Store.
func (*Store) SharedSecret ¶
SharedSecret is the Elliptic-curve Diffie–Hellman (ECDH) sharded secret for the Store. We use the ECDH private key and the ECDH ExternalPublicKey to create this SharedSecret for the Store.
func (*Store) UnmarshalJSONAndDecryptFromJSON ¶
UnmarshalJSONAndDecryptFromJSON is a convenience function that performs the opposite of EncodeJSONAndEncryptToJSON(). This function unmarshals JSON AEADStore bytes, decrypts, and then unmarshals the resulting JSON plaintext.
func (*Store) UnmarshalJSONAndDecryptFromJSONWithADCheck ¶
func (s *Store) UnmarshalJSONAndDecryptFromJSONWithADCheck( jsonData []byte, v any, authFunc func(additionalData []byte) (bool, error), ) (err error)
UnmarshalJSONAndDecryptFromJSONWithAdditionalData is a convenience function that performs the opposite of EncodeJSONAndEncryptToJSON(). This function unmarshals JSON AEADStore bytes, decrypts, and then unmarshals the resulting JSON plaintext. This function also checks whether the provided additionalData matches with the AEADStore additionalData.
func (*Store) X963RepresentationPrivateKey ¶
X963RepresentationPrivateKey prints the Store Elliptic-curve Diffie–Hellman (ECDH) public key and private key as bytes. This produces the same result as calling X963RepresentationPrivateKey in the Apple CryptoKit library.
func (*Store) X963RepresentationPublicKey ¶
X963RepresentationPublicKey prints the Store Elliptic-curve Diffie–Hellman (ECDH) public key as bytes. This produces the same result as calling X963RepresentationPublicKey in the Apple CryptoKit library.