libdisco does not provide this functionnality.
8 | 9 |Please refer to the Go-argon2 library for this.
10 | 11 |libdisco uses golang's standard library crypto/rand to generate random numbers.
8 | 9 |It is possible to use Strobe to generate random numbers in userland, but it is not advised at forking or cloning a VM snapshot will end up making different programs produce the same random numbers.
10 | 11 |libdisco provides functions to "spread" a single key into several keys. The input key must be random and larger or equal to 128 bits (16 bytes) for security reasons. The following snippet takes a 16-byte key and derives two 32-byte keys:
8 | 9 |input, _ := hex.DecodeString("2825a87129f065748121cdf6c1dcf8b7")
10 | keys := libdisco.DeriveKeys(input, 64))
11 | key1 := keys[:32]
12 | key2 := keys[32:]Asymmetric cryptographic operations in libdisco are built on top of the Curve25519 primitive. Since Golang has standard libraries implementing both ed25519 (for signing) and X25519 (for key exchanges) this is what we use.
8 | 9 |Please refer to the documentation for x/crypto/ed25519 in order to use it.
10 | 11 |Note that since libdisco already uses these libraries, importing them in your project will not increase the size of the final binaries.
12 | 13 |To encrypt, simply use the Encrypt function with a key of at minimum 128 bits (16 bytes)
key, _ := hex.DecodeString("eda8506c1fb0bbcc3f62626fef074bbf2d09a8c7c608f3fa1482c9a625d00f75")
11 | plaintext := []byte("hello, how are you?")
12 |
13 | ciphertext := libdisco.Encrypt(key, plaintext)To decrypt, use the corresponding Decrypt function with the same key.
key, _ := hex.DecodeString("eda8506c1fb0bbcc3f62626fef074bbf2d09a8c7c608f3fa1482c9a625d00f75")
18 |
19 | decrypted, err := libdisco.Decrypt(key, ciphertext)6 | libdisco is based on the Strobe protocol framework and on Curve25519. In other words, libdisco supports a diverse range of symmetric and asymmetric cryptographic. 7 |
8 |9 | The different cryptographic operations available are documented in the menu on the left. 10 |
11 |12 | More complex symmetric cryptographic primitives can be built on top of Strobe. For this, use the strobe package. Note that it is already imported as part of libdisco, so re-importing it and using it won't increase the size of your applications' binaries. 13 |
14 |The ProtectIntegrity and VerifyIntegrity functions can be used to make sure that a message has not been tampered with. Note that this creates a payload containing your message in clear. This is not encryption!
10 |
11 | to create your payload with a message:
12 | 13 |key, _ := hex.DecodeString("eda8506c1fb0bbcc3f62626fef074bbf2d09a8c7c608f3fa1482c9a625d00f75")
14 |
15 | message := []byte("hoy, how are you?")
16 |
17 | payload := ProtectIntegrity(key, message)to extract your payload use the function VerifyIntegrity. It will return an error if the payload has been modified since its creation, otherwise it will return the original message:
retrievedMessage, err := VerifyIntegrity(key, plaintextAndTag)
22 |
23 | if err != nil {
24 | // the message was tampered with
25 | }General documentation for the protocol parts of libdisco can be found on 
Usages help can be found through-out this website. There are two important parts to libdisco:
9 | 10 |To install the package simply use go get:
18 | go get github.com/mimoo/disco/libdisco
19 | 22 | and import it in your application: 23 |
24 | 25 |package main
26 |
27 | import(
28 | "github.com/mimoo/disco/libdisco"
29 | )Security Consideration
20 |Security Consideration
20 |Security Consideration
20 |libdisco provides a simple hashing primitive that is not compatible with SHA-2 or SHA-3 or other hash functions. This means that the output you will get using libdisco's Hash function will be different. The use case and the security remain equivalent.
8 | 9 |To obtain the 256-bit hash of some input, perform the following:
10 | 11 |input := []byte("hi, how are you?")
12 | digest := libdisco.Hash(input, 32))libdisco's hash function is more than just a hash function, it is actually an eXtendable Output Function (XOF) which provides a flexible output length. The minimum has been set to 32 bytes (256 bits) for security reasons, there is no practical maximum. The following example obtains an output of 1000 bytes:
15 | 16 |input := []byte("a very long output")
17 | digest := libdisco.Hash(input, 1000))If you're planning on running a continuous hash, use NewHash instead:
h := NewHash(32)
22 | h.Write([]byte("hi"))
23 | h.Write([]byte(" how are you?"))
24 | out1 := h.Sum()
25 | h.Write([]byte(" david"))
26 | out2 := h.Sum()The two digests will be equivalent to
29 | 30 |out1 := libdisco.Hash([]byte("hi how are you?"), 32)
31 | out2 := libdisco.Hash([]byte("hi how are you? david"), 32)Warning
36 |Write() function should be used for hashing contiguous chunks of data. If the data is structured (for example age|gender|city) use the WriteTuple() function instead.
39 | 
10 |
11 | Noise_NK is a relevant handshake pattern if your clients already know a server's static public key. This pattern does not authenticate the client nor does it rely on an external root signing key.
14 | 15 |If the client needs to be authenticated, refer to
To understand how to generate the server's static key pair and export its public key part, refer to
You can play with the full example here.
24 | 25 | 26 |serverConfig := libdisco.Config{
29 | HandshakePattern: libdisco.NoiseNK,
30 | KeyPair: serverKeyPair,
31 | }
32 | // listen on port 6666
33 | listener, err := libdisco.Listen("tcp", "127.0.0.1:6666", &serverConfig)
34 | if err != nil {
35 | fmt.Println("cannot setup a listener on localhost:", err)
36 | return
37 | }
38 | addr := listener.Addr().String()
39 | fmt.Println("listening on:", addr)clientConfig := libdisco.Config{
44 | HandshakePattern: libdisco.NoiseNK,
45 | // the server's static public key.
46 | RemoteKey: serverPublicKey,
47 | }
48 | // Dial the port 6666 of localhost
49 | client, err := libdisco.Dial("tcp", "127.0.0.1:6666", &clientConfig)
50 | if err != nil {
51 | fmt.Println("client can't connect to server:", err)
52 | return
53 | }
54 | defer client.Close()
55 | fmt.Println("connected to", client.RemoteAddr())The same security discussed in the Noise specification for the relevant handshake pattern apply.
60 | 61 |
10 |
11 | If you are only dealing with one client and one server, and can manually hardcode a common 32-byte random value on each peer, you probably do not need to deal with public keys and should use this handshake pattern.
14 | 15 |Security Consideration
18 |The shared secret can be generated using a cryptographically random number generator (see
You can play with the full example here.
29 | 30 |// configuring the Disco connection
33 | serverConfig := libdisco.Config{
34 | HandshakePattern: libdisco.NoiseNNpsk2,
35 | // your 32-byte shared secret
36 | PreSharedKey: sharedSecret,
37 | }
38 |
39 | // listen on port 6666
40 | listener, err := libdisco.Listen("tcp", "127.0.0.1:6666", &serverConfig)
41 | if err != nil {
42 | fmt.Println("cannot setup a listener on localhost:", err)
43 | return
44 | }
45 | addr := listener.Addr().String()
46 | fmt.Println("listening on:", addr)// configure the Disco connection
51 | clientConfig := libdisco.Config{
52 | HandshakePattern: libdisco.NoiseNNpsk2,
53 | // your 32-byte shared secret
54 | PreSharedKey: sharedSecret,
55 | }
56 |
57 | // Dial the port 6666 of localhost
58 | client, err := libdisco.Dial("tcp", "127.0.0.1:6666", &clientConfig)
59 | if err != nil {
60 | fmt.Println("client can't connect to server:", err)
61 | return
62 | }
63 | defer client.Close()
64 | fmt.Println("connected to", client.RemoteAddr())The same security discussed in the Noise specification for the relevant handshake pattern apply.
69 | 70 |
10 |
11 | If your protocol involves several peers and both sides of a connection have a way to know the other side's public static key prior to starting the handshake, Noise_KK is a good fit.
14 | 15 |A simple illustration would be a secure messaging application where the peer's public key can be retrieved in advance via a trusted third party (key server). If the third party cannot be trusted, public keys can be further verified out-of-band (usually via a fingerprint mixing both public keys, see Signal's safety numbers).
16 | 17 |If your protocol involves a single client and a single server, refer to
To understand how to generate both peer's key pair, refer to
You can play with the full example here.
24 | 25 |serverConfig := libdisco.Config{
28 | HandshakePattern: libdisco.NoiseKK,
29 | KeyPair: serverKeyPair,
30 | // the public static key of the client
31 | RemoteKey: clientPublicKey
32 | }
33 |
34 | // listen on port 6666
35 | listener, err := libdisco.Listen("tcp", "127.0.0.1:6666", &serverConfig)
36 | if err != nil {
37 | fmt.Println("cannot setup a listener on localhost:", err)
38 | return
39 | }
40 | addr := listener.Addr().String()
41 | fmt.Println("listening on:", addr)clientConfig := libdisco.Config{
46 | HandshakePattern: libdisco.NoiseKK,
47 | KeyPair: clientKeyPair,
48 | // the public static key of the server
49 | RemoteKey: serverPublicKey
50 | }
51 |
52 | // Dial the port 6666 of localhost
53 | client, err := libdisco.Dial("tcp", "127.0.0.1:6666", &clientConfig)
54 | if err != nil {
55 | fmt.Println("client can't connect to server:", err)
56 | return
57 | }
58 | defer client.Close()
59 | fmt.Println("connected to", client.RemoteAddr())The same security discussed in the Noise specification for the relevant handshake pattern apply.
64 | 65 |
10 |
11 | This handshake pattern is useful for clients that always talk to a single server. In addition, since it is a one-way pattern, the server never talks back to them. The server also doesn't require the client to authenticate itself.
14 | 15 |If client authentication is needed, refer to
The client needs to have prior knowledge to the server's public static key. In this example we just pass it as an stdin argument to the client's CLI, but in practice it should be hardcoded.
In addition, every time the server is ran it is generating a new static key pair. In practice this should only be done once, possibly using the
You can play with the full example here.
24 | 25 |// generating the server key pair
28 | serverKeyPair := libdisco.GenerateKeypair(nil)
29 |
30 | // configuring the Disco connection with a Noise_N handshake
31 | // in which the client already knows the server's static public key
32 | serverConfig := libdisco.Config{
33 | HandshakePattern: libdisco.NoiseN,
34 | KeyPair: serverKeyPair,
35 | }
36 | // listen on port 6666
37 | listener, err := libdisco.Listen("tcp", "127.0.0.1:6666", &serverConfig)
38 | if err != nil {
39 | fmt.Println("cannot setup a listener on localhost:", err)
40 | return
41 | }
42 | addr := listener.Addr().String()
43 | fmt.Println("listening on:", addr)
44 | // export public key so that client can retrieve it out of band
45 | fmt.Println("server's public key:", serverKeyPair.ExportPublicKey())// retrieve the server's public key from an argument
50 | serverPubKey := os.Args[1]
51 | serverKey, _ := hex.DecodeString(serverPubKey)
52 |
53 | // configure the Disco connection with Noise_N
54 | // meaning the client knows the server's static public key (retrieved from the CLI)
55 | clientConfig := libdisco.Config{
56 | HandshakePattern: libdisco.NoiseN,
57 | RemoteKey: serverKey,
58 | }
59 | // Dial the port 6666 of localhost
60 | client, err := libdisco.Dial("tcp", "127.0.0.1:6666", &clientConfig)
61 | if err != nil {
62 | fmt.Println("client can't connect to server:", err)
63 | return
64 | }
65 | defer client.Close()
66 | fmt.Println("connected to", client.RemoteAddr())The same security discussed in the Noise specification for the relevant handshake pattern apply.
71 | 72 |
10 |
11 | Like any one-way pattern. If the server never needs to (or cannot) reply to the client, Noise_K might be a good fit. In addition, this handshake authenticates both side of the connection via public-key pinning. This means that both sides need to know in advance each other's static public key.
14 | 15 |If only one side needs to be authenticated, refer to
To configure both the client and the server, they need to have each other's public static key. In this example we just pass these as stdin argument to each CLI, but in practice these should be hardcoded.
In addition, every time the client and server are ran, they are generating new static key pairs. In practice this should only be done once, possibly using the
You can play with the full example here.
24 | 25 |// generating the server key pair
28 | serverKeyPair := libdisco.GenerateKeypair(nil)
29 | fmt.Println("server's public key:", serverKeyPair.ExportPublicKey())
30 |
31 | // configuring the Disco connection
32 | serverConfig := libdisco.Config{
33 | HandshakePattern: libdisco.NoiseK,
34 | KeyPair: serverKeyPair,
35 | }
36 |
37 | // retrieve the client's public key from an argument
38 | fmt.Println("please enter the client's public key in hexadecimal")
39 | scanner := bufio.NewScanner(os.Stdin)
40 | scanner.Scan()
41 | clientKey, _ := hex.DecodeString(scanner.Text())
42 | serverConfig.RemoteKey = clientKey
43 |
44 | // listen on port 6666
45 | listener, err := libdisco.Listen("tcp", "127.0.0.1:6666", &serverConfig)
46 | if err != nil {
47 | fmt.Println("cannot setup a listener on localhost:", err)
48 | return
49 | }
50 | fmt.Println("listening on:", listener.Addr().String())// generating the client key pair
55 | clientKeyPair := libdisco.GenerateKeypair(nil)
56 | fmt.Println("client's public key:", clientKeyPair.ExportPublicKey())
57 |
58 | // configure the Disco connection
59 | clientConfig := libdisco.Config{
60 | HandshakePattern: libdisco.NoiseK,
61 | KeyPair: clientKeyPair,
62 | }
63 |
64 | // retrieve the server's public key from an argument
65 | fmt.Println("please enter the server's public key in hexadecimal")
66 | scanner := bufio.NewScanner(os.Stdin)
67 | scanner.Scan()
68 | serverKey, _ := hex.DecodeString(scanner.Text())
69 | clientConfig.RemoteKey = serverKey
70 |
71 | // Dial the port 6666 of localhost
72 | client, err := libdisco.Dial("tcp", "127.0.0.1:6666", &clientConfig)
73 | if err != nil {
74 | fmt.Println("client can't connect to server:", err)
75 | return
76 | }
77 | defer client.Close()
78 | fmt.Println("connected to", client.RemoteAddr())The same security discussed in the Noise specification for the relevant handshake pattern apply.
84 | 85 |
13 |
Disco makes use of several key pairs:
8 | 9 |
18 | Static keys can be generated via a call to GenerateKeypair(nil). The package also provides some file utility functions:
19 |
KeyPair.ExportPublicKey() retrieves the public part of a static key pair.GenerateAndSaveDiscoKeyPair() creates and saves a static key pair on disk.LoadDiscoKeyPair(discoPrivateKeyPairFile() loads a static key pair from such a file.
26 | Root signing keys can be generated and saved on disk directly via the GenerateAndSaveDiscoRootKeyPair() function. As different peers might need different parts, the private and public parts of the key pair will be saved in different files. To retrieve them you can use the LoadDiscoRootPublicKey() and LoadDiscoRootPrivateKey() functions.
27 |
Storing keys
33 |Imagine a handshake pattern like
1. create the root signing key:
45 | 46 |if err := libdisco.GenerateAndSaveDiscoRootKeyPair("./discoRootPrivateKey", "./discoRootPublicKey"); err != nil {
47 | panic("didn't work")
48 | }Storing root keys
53 |2. sign the server's static public key:
60 | 61 |// we load the private part of the root signing key
62 | rootPrivateKey, err := libdisco.LoadDiscoRootPrivateKey("./discoRootPrivateKey")
63 | if err != nil {
64 | panic("couldn't load the root signing private key")
65 | }
66 | // we compute our proof over the server's public static key
67 | proof := libdisco.CreateStaticPublicKeyProof(rootPrivateKey, serverKeyPair.PublicKey[:])3. configure the server to send its static public key along with its proof:
70 | 71 |serverConfig := libdisco.Config{
72 | HandshakePattern: libdisco.NoiseNX,
73 | KeyPair: serverKeyPair,
74 | StaticPublicKeyProof: proof,
75 | }4. once the discoRootPublicKey file has been passed to the client, we can configure it:
// we load the public part of the root signing key
80 | rootPublicKey, err := LoadDiscoRootPublicKey("./discoRootPublicKey")
81 | if err != nil {
82 | panic("didn't work")
83 | }
84 |
85 | // we create our verifier
86 | someCallbackFunction := CreatePublicKeyVerifier(rootPublicKey)
87 |
88 | // we configure the client
89 | clientConfig := libdisco.Config{
90 | HandshakePattern: libdisco.NoiseNK,
91 | PublicKeyVerifier: someCallbackFunction,
92 | }
93 | 5. And that's it!
96 | 97 |For more example please check each handshake pattern individually on the examples on the source code repository
98 | 99 |Warning
19 |26 | libdisco is a library built by merging the Noise protocol framework and the Strobe protocol framework. This means that it supports a subset of Noise's handshakes while offering the cryptographic primitive Strobe has to offer. In other words, you can use libdisco to securely connect peers together, or to do basic cryptographic operations like hashing or encrypting.
27 | 28 |35 | Want to know more about the technical details? Watch our presentation at Black Hat Europe 2017 and read our whitepaper. 36 |
37 | 38 |To set it up, follow Golang's net/conn standard way of setting up a server with a libdisco config:
41 | 42 |serverConfig := libdisco.Config{
43 | HandshakePattern: libdisco.NoiseNK,
44 | KeyPair: serverKeyPair,
45 | }
46 | listener, err := libdisco.Listen("tcp", "127.0.0.1:6666", &serverConfig)
47 | server, err := listener.Accept()and the standard way of setting up a client with a libdisco config:
50 | 51 |clientConfig := libdisco.Config{
52 | HandshakePattern: libdisco.NoiseNK,
53 | RemoteKey: serverKey,
54 | }
55 | client, err := libdisco.Dial("tcp", "127.0.0.1:6666", &clientConfig)
56 | it's that simple! Check out the
To make use of the 77 | protocol parts, you must first choose how you want to authenticate the connection. For that, it's easy! We have made a small quizz for you bellow, but if you already know what you want you can directly click on your favorite way of doing this in the menu under "protocol" (Noise_NK, Noise_XX, ...) and copy the usage examples.
78 | 79 |To make use of the
82 | cryptographic library, check our
To learn more about it, you can read this blog post or watch our presentation at Black Hat Europe 2017 .
87 | 88 |If you want help, head to the 89 | issues on github.
90 | 91 |If you want to stay tuned on what we're doing, we don't have a mailing list but we have better: a subreddit over at r/discocrypto.
92 |
10 |
11 | This handshake pattern is useful when many different clients want to talk to one server while authenticating both side of the connection. In addition, since it is a one-way pattern, the server never talks back to them.
14 | 15 |If client authentication is not needed, refer to
The client needs to have prior knowledge to the server's public static key in order to authenticate the server during the handshake phase.
20 | 21 |As for the client's authentication:
22 |Both can be done using libdisco's
You can play with the full example here. The root signing key process is illustrated here.
30 | 31 |The authoritative root signing key can be generated using libdisco's GenerateAndSaveDiscoRootKeyPair helper function
// generating the root signing key
36 | if err := libdisco.GenerateAndSaveDiscoRootKeyPair("./privateRoot", "./publicRoot"); err != nil {
37 | panic("cannot generate and save a root key")
38 | }This function (documented here) will create two files, a "privateRoot" (resp. "publicRoot") file containing the private (resp. public) part of the root signing key pair.
41 | 42 |The public part can then be retrieved via the LoadDiscoRootPublicKey function.
// loading the public part
45 | pubkey, err := libdisco.LoadDiscoRootPublicKey("./publicRoot")
46 | if err != nil {
47 | // cannot load the disco root pubkey
48 | }
49 |
50 | // displaying the public part
51 | fmt.Println(hex.EncodeToString(pubkey))To sign a peer's static public key, the CreateStaticPublicKeyProof function can be used.
// load the private root key
56 | privkey, err := libdisco.LoadDiscoRootPrivateKey("./privateRoot")
57 | if err != nil {
58 | // couldn't load the private root key
59 | }
60 |
61 | // create proof where toSign is a peer's static public key
62 | proof := libdisco.CreateStaticPublicKeyProof(privkey, toSign)
63 |
64 | // display the proof
65 | fmt.Println(hex.EncodeToString(proof))// load the server's keypair
70 | serverKeyPair, err := libdisco.LoadDiscoKeyPair("./serverKeyPair")
71 | if err != nil {
72 | fmt.Println("couldn't load the server's key pair")
73 | return
74 | }
75 |
76 | // retrieve the root signing public key
77 | rootPublicKey, err := hex.DecodeString(...)
78 | if err != nil || len(rootPublicKey) != 32 {
79 | fmt.Println("public root key passed is not a 32-byte value in hexadecimal (", len(rootPublicKey), ")")
80 | return
81 | }
82 |
83 | // create a verifier for when we will receive the server's public key
84 | verifier := libdisco.CreatePublicKeyVerifier(rootPublicKey)
85 |
86 | // configuring the Disco connection
87 | // in which the client already knows the server's public key
88 | serverConfig := libdisco.Config{
89 | HandshakePattern: libdisco.NoiseX,
90 | KeyPair: serverKeyPair,
91 | PublicKeyVerifier: verifier,
92 | }
93 |
94 | // listen on port 6666
95 | listener, err := libdisco.Listen("tcp", "127.0.0.1:6666", &serverConfig)
96 | if err != nil {
97 | fmt.Println("cannot setup a listener on localhost:", err)
98 | return
99 | }
100 | addr := listener.Addr().String()
101 | fmt.Println("listening on:", addr)// load the client's keypair
106 | clientKeyPair, err := libdisco.LoadDiscoKeyPair("./clientkeyPair")
107 | if err != nil {
108 | fmt.Println("couldn't load the client's key pair")
109 | return
110 | }
111 |
112 | // retrieve server's static public key
113 | serverPublicKey, err := hex.DecodeString(...)
114 | if err != nil || len(serverPublicKey) != 32 {
115 | fmt.Println("server's static public key passed is not a 32-byte value in hexadecimal (", len(serverPublicKey), ")")
116 | return
117 | }
118 |
119 | // retrieve signature/proof over the client's static public key
120 | proof, err := hex.DecodeString(...)
121 | if err != nil || len(proof) != 64 {
122 | fmt.Println("proof passed is not a 64-byte value in hexadecimal (", len(proof), ")")
123 | return
124 | }
125 |
126 | // configure the Disco connection with Noise_XX
127 | clientConfig := libdisco.Config{
128 | KeyPair: clientKeyPair,
129 | RemoteKey: serverPublicKey,
130 | HandshakePattern: libdisco.NoiseX,
131 | StaticPublicKeyProof: proof,
132 | }
133 |
134 | // Dial the port 6666 of localhost
135 | client, err := libdisco.Dial("tcp", "127.0.0.1:6666", &clientConfig)
136 | if err != nil {
137 | fmt.Println("client can't connect to server:", err)
138 | return
139 | }
140 | defer client.Close()
141 | fmt.Println("connected to", client.RemoteAddr())The same security discussed in the Noise specification for the relevant handshake pattern apply.
146 | 147 |
10 |
11 | Any X pattern where a peer authenticate itself via the signature of an authoritative key (like the Noise_XX pattern) is useful when the other peer doesn't know in advance what peer it will communicate to.
This means that Noise_XX is a good candidate for setups where many clients try to connect to many servers, and none of the clients or servers share the same static key.
Like any X pattern where a static key is sent, the peer needs to also send a proof which is typically a signature over its static public key from an authoritative key (a root key). With Noise_XX, both peers need to provide a proof, and they both need to verify each other's proof. libdisco supplies helpers to achieve both functionalities, the following examples demonstrate how to use them.
In the following example of configuration, libdisco's helper functions are used to create proofs and verify them, as well as to generate the root key which can create these proofs. Notice that the configuration is the same for both peers as we're using a single root key, but two different root keys (one for the servers and one for the clients) could be used if needed.
22 | 23 |Noise_XX requires both side to authenticate themselves as part of the handshake. For this to work:
24 |Both of these requirements can be achieved using libdisco's
You can play with the full example here. The root signing key process is illustrated here.
32 | 33 |The authoritative root signing key can be generated using libdisco's GenerateAndSaveDiscoRootKeyPair helper function
// generating the root signing key
38 | if err := libdisco.GenerateAndSaveDiscoRootKeyPair("./privateRoot", "./publicRoot"); err != nil {
39 | panic("cannot generate and save a root key")
40 | }This function (documented here) will create two files, a "privateRoot" (resp. "publicRoot") file containing the private (resp. public) part of the root signing keypair.
43 | 44 |The public part can then be retrieved via the LoadDiscoRootPublicKey function.
// loading the public part
47 | pubkey, err := libdisco.LoadDiscoRootPublicKey("./publicRoot")
48 | if err != nil {
49 | // cannot load the disco root pubkey
50 | }
51 |
52 | // displaying the public part
53 | fmt.Println(hex.EncodeToString(pubkey))To sign a peer's static public key, the CreateStaticPublicKeyProof function can be used.
// load the private root key
58 | privkey, err := libdisco.LoadDiscoRootPrivateKey("./privateRoot")
59 | if err != nil {
60 | // couldn't load the private root key
61 | }
62 |
63 | // create proof where toSign is a peer's static public key
64 | proof := libdisco.CreateStaticPublicKeyProof(privkey, toSign)
65 |
66 | // display the proof
67 | fmt.Println(hex.EncodeToString(proof))// load the server's keypair
73 | serverKeyPair, err := libdisco.LoadDiscoKeyPair("./serverkeyPair")
74 | if err != nil {
75 | fmt.Println("couldn't load the server's key pair")
76 | return
77 | }
78 |
79 | // create a verifier for when we will receive the server's public key
80 | verifier := libdisco.CreatePublicKeyVerifier(rootPublicKey)
81 |
82 | // configure the Disco connection with Noise_XX
83 | serverConfig := libdisco.Config{
84 | HandshakePattern: libdisco.NoiseXX,
85 | KeyPair: serverKeyPair,
86 | PublicKeyVerifier: verifier,
87 | StaticPublicKeyProof: proof,
88 | }
89 |
90 | // listen on port 6666
91 | listener, err := libdisco.Listen("tcp", "127.0.0.1:6666", &serverConfig)
92 | if err != nil {
93 | fmt.Println("cannot setup a listener on localhost:", err)
94 | return
95 | }
96 | addr := listener.Addr().String()
97 | fmt.Println("listening on:", addr)// load the client's keypair
102 | clientKeyPair, err := libdisco.LoadDiscoKeyPair("./clientkeyPair")
103 | if err != nil {
104 | fmt.Println("couldn't load the client's key pair")
105 | return
106 | }
107 |
108 | // create a verifier for when we will receive the server's public key
109 | verifier := libdisco.CreatePublicKeyVerifier(rootPublicKey)
110 |
111 | // configure the Disco connection with Noise_XX
112 | clientConfig := libdisco.Config{
113 | KeyPair: clientKeyPair,
114 | HandshakePattern: libdisco.NoiseXX,
115 | PublicKeyVerifier: verifier,
116 | StaticPublicKeyProof: proof,
117 | }
118 |
119 | // Dial the port 6666 of localhost
120 | client, err := libdisco.Dial("tcp", "127.0.0.1:6666", &clientConfig)
121 | if err != nil {
122 | fmt.Println("client can't connect to server:", err)
123 | return
124 | }
125 | defer client.Close()
126 | fmt.Println("connected to", client.RemoteAddr())The same security discussed in the Noise specification for the relevant handshake pattern apply.
131 | 132 |This handshake pattern is tricky (like any X-type handshakes) as it requires a Public Key Infrastructure (PKI) where:
10 |
11 | Noise_NX is a fitting handshake pattern if:
14 |if a server's public key is known prior to starting the handshake, refer to
Noise_NX requires the server to authenticate itself as part of the handshake. For this to work:
23 |Both of these requirements can be achieved using libdisco's
You can play with the full example here. The root signing key process is illustrated here.
31 | 32 |The authoritative root signing key can be generated using libdisco's GenerateAndSaveDiscoRootKeyPair helper function
// generating the root signing key
37 | if err := libdisco.GenerateAndSaveDiscoRootKeyPair("./privateRoot", "./publicRoot"); err != nil {
38 | panic("cannot generate and save a root key")
39 | }This function (documented here) will create two files, a "privateRoot" (resp. "publicRoot") file containing the private (resp. public) part of the root signing key pair.
42 | 43 |The public part can then be retrieved via the LoadDiscoRootPublicKey function.
// loading the public part
46 | pubkey, err := libdisco.LoadDiscoRootPublicKey("./publicRoot")
47 | if err != nil {
48 | // cannot load the disco root pubkey
49 | }
50 |
51 | // displaying the public part
52 | fmt.Println(hex.EncodeToString(pubkey))To sign a peer's static public key, the CreateStaticPublicKeyProof function can be used.
// load the private root key
57 | privkey, err := libdisco.LoadDiscoRootPrivateKey("./privateRoot")
58 | if err != nil {
59 | // couldn't load the private root key
60 | }
61 |
62 | // create proof where toSign is a peer's static public key
63 | proof := libdisco.CreateStaticPublicKeyProof(privkey, toSign)
64 |
65 | // display the proof
66 | fmt.Println(hex.EncodeToString(proof))As part of Noise_NX, the server needs to be configured with a static public key, as well as a signature over that key.
71 | 72 |To keep things simple, libdisco provides
// CreateStaticPublicKeyProof helps in creating a signature over the peer's static public key
75 | // for that, it needs the private part of a signing root key pair that is trusted by the client.
76 | proof := CreateStaticPublicKeyProof(rootPrivateKey, peerPublicKey)
77 | Public Key Infrastructure
82 |serverKeyPair as well as a signature of the certificate from a certificate authority's public key. If such a complex public key infrastructure is required, you can construct the PublicKeyVerifier and StaticPublicKeyProof yourself to verify a certificate's signature and accept certificates as proofs. See the Once the proof has been computed, it can be passed to the server which will be able to configure itself for a Noise_NX setup:
89 | 90 |serverConfig := libdisco.Config{
91 | HandshakePattern: libdisco.NoiseNX,
92 | KeyPair: serverKeyPair,
93 | StaticPublicKeyProof: proof,
94 | }
95 |
96 | // listen on port 6666
97 | listener, err := libdisco.Listen("tcp", "127.0.0.1:6666", &serverConfig)
98 | if err != nil {
99 | // cannot setup a listener on localhost
100 | }
101 | addr := listener.Addr().String()
102 | fmt.Println("listening on:", addr)the client needs to be configured with a function capable of acting on the static public key the server will send (as part of the handshake). Without this, there are no guarantees that the static public key the server sends is "legit".
107 | 108 |clientConfig := libdisco.Config{
109 | HandshakePattern: libdisco.NoiseNX,
110 | PublicKeyVerifier: verifier,
111 | }Again, libdisco provides utility functions to create a useful PublicKeyVerifier callback:
// CreatePublicKeyVerifier helps in creating a callback function that will verify a signature
116 | // for this it needs the public part of the signing root public key that we trust.
117 | verifier := CreatePublicKeyVerifier(rootPublicKey)Finally the full example for a client:
120 | 121 |// create a verifier for when we will receive the server's public key
122 | verifier := libdisco.CreatePublicKeyVerifier(rootPublicKey)
123 |
124 | // configure the Disco connection
125 | clientConfig := libdisco.Config{
126 | HandshakePattern: libdisco.NoiseNX,
127 | PublicKeyVerifier: verifier,
128 | }
129 |
130 | // Dial the port 6666 of localhost
131 | client, err := libdisco.Dial("tcp", "127.0.0.1:6666", &clientConfig)
132 | if err != nil {
133 | // client can't connect to server
134 | }
135 | defer client.Close()
136 | fmt.Println("connected to", client.RemoteAddr())The same security discussed in the Noise specification for the relevant handshake pattern apply.
141 | 142 |