Documentation
¶
Overview ¶
Package x25519 provides a ECDH (Elliptic Curve Diffie-Hellman) wrapper for curve X25519.
The main component in the package is the 'KeyPair' instance. Each key pair needs to be securely removed from memory by calling the "Destroy" method.
Key Creation ¶
There are 3 mechanisms to create a new key pair.
// 1. Create a completely random new key
rk, _ := New()
// 2. Key using a given seed material
sk, _ := FromSeed([]byte("material"))
// 3. Load from PEM-encoded content
pk, _ := Unmarshal(pemBinData)
However created, the key pair instance always use a locked memory buffer to securely hold private information. Is mandatory to properly release the memory buffer after using the key by calling the 'Destroy' method.
// Securely release in-memory secrets kp.Destroy()
Key Usage ¶
Diffie-Hellman is a shared key creation mechanism. The main use of a key pair is to generate a shared secret with a provided public key.
// Generate peers
alice, _ := New()
bob, _ := New()
defer alice.Destroy()
defer bob.Destroy()
// Generate shared secret on both sides
s1 := alice.DH(bob.PublicKey())
s2 := bob.DH(alice.PublicKey())
// Test secrets
if !bytes.Equal(s1, s2) {
panic("failed to generate valid secret")
}
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type KeyPair ¶
type KeyPair struct {
// contains filtered or unexported fields
}
KeyPair represents a X25519 (Diffie-Hellman) public/private key.
func FromSeed ¶
FromSeed deterministically generates a keypair instance using the provided seed material. The KP instance needs to be securely removed from memory by calling the "Destroy" method.
func New ¶
New returns a X25519 (Diffie-Hellman) key pair instance. Each KP needs to be securely removed from memory by calling the "Destroy" method.
Example ¶
Generate a shared secret between two key pair instances.
// Generate peers
alice, _ := New()
bob, _ := New()
defer alice.Destroy()
defer bob.Destroy()
// Generate shared secret on both sides
s1 := alice.DH(bob.PublicKey())
s2 := bob.DH(alice.PublicKey())
// Test secrets
if !bytes.Equal(s1, s2) {
panic("failed to generate valid secret")
}
Output:
func Unmarshal ¶
Unmarshal will restore a key pair instance from the provided PEM-encoded private key. The KP instance needs to be securely removed from memory by calling the "Destroy" method.
func (*KeyPair) DH ¶
DH calculates a byte sequence which is the shared secret output from an Elliptic Curve Diffie-Hellman of the provided public key. In case of error the function return 'nil'.
func (*KeyPair) Destroy ¶
func (k *KeyPair) Destroy()
Destroy will safely release the allocated mlock/VirtualLock memory.
func (*KeyPair) MarshalBinary ¶
MarshalBinary returns the PEM-encoded private key.
func (*KeyPair) PrivateKey ¶
PrivateKey returns the private key bytes of the key pair instance. Using this method may unintentionally expose secret material outside the security memory segment managed by the instance. Don't use it unless you really know what you are doing.
func (*KeyPair) UnmarshalBinary ¶
UnmarshalBinary will restore a key pair instance from the provided PEM-encoded private key. The KP instance needs to be securely removed from memory by calling the "Destroy" method.
Source Files