1nbd_set_tls_psk_file(3)             LIBNBD             nbd_set_tls_psk_file(3)
2
3
4

NAME

6       nbd_set_tls_psk_file - set the TLS Pre-Shared Keys (PSK) filename
7

SYNOPSIS

9        #include <libnbd.h>
10
11        int nbd_set_tls_psk_file (struct nbd_handle *h,
12                                  const char *filename);
13

DESCRIPTION

15       Set the TLS Pre-Shared Keys (PSK) filename.  This is used if trying to
16       authenticate to the server using with a pre-shared key.  There is no
17       default so if this is not set then PSK authentication cannot be used to
18       connect to the server.
19
20       This function may be called regardless of whether TLS is supported, but
21       will have no effect unless nbd_set_tls(3) is also used to request or
22       require TLS.
23

RETURN VALUE

25       If the call is successful the function returns 0.
26

ERRORS

28       On error "-1" is returned.
29
30       Refer to "ERROR HANDLING" in libnbd(3) for how to get further details
31       of the error.
32

HANDLE STATE

34       The handle must be newly created, otherwise this call will return an
35       error.
36

VERSION

38       This function first appeared in libnbd 1.0.
39
40       If you need to test if this function is available at compile time check
41       if the following macro is defined:
42
43        #define LIBNBD_HAVE_NBD_SET_TLS_PSK_FILE 1
44

EXAMPLE

46       This example is also available as examples/encryption.c in the libnbd
47       source code.
48
49        /* An example showing how to connect to a server which is
50         * using TLS encryption.
51         *
52         * This requires nbdkit, and psktool from gnutls.
53         *
54         * Both libnbd and nbdkit support TLS-PSK which is a
55         * simpler-to-deploy form of encryption.  (Of course
56         * certificate-based encryption is also supported, but
57         * it’s harder to make a self-contained example).
58         */
59
60        #include <stdio.h>
61        #include <stdlib.h>
62        #include <string.h>
63        #include <unistd.h>
64
65        #include <libnbd.h>
66
67        #define TMPDIR "/tmp/XXXXXX"
68        #define KEYS "keys.psk"
69        #define USERNAME "alice"
70
71        static char dir[] = TMPDIR;
72        static char keys[] = TMPDIR "/" KEYS;
73        static char cmd[] =
74          "psktool -u " USERNAME " -p " TMPDIR "/" KEYS;
75
76        /* Remove the temporary keys file when the program
77         * exits.
78         */
79        static void
80        cleanup_keys (void)
81        {
82          unlink (keys);
83          rmdir (dir);
84        }
85
86        /* Create the temporary keys file to share with the
87         * server.
88         */
89        static void
90        create_keys (void)
91        {
92          size_t i;
93
94          if (mkdtemp (dir) == NULL) {
95            perror ("mkdtemp");
96            exit (EXIT_FAILURE);
97          }
98          i = strlen (cmd) - strlen (TMPDIR) - strlen (KEYS) - 1;
99          memcpy (&cmd[i], dir, strlen (TMPDIR));
100          memcpy (keys, dir, strlen (TMPDIR));
101
102          if (system (cmd) != 0) {
103            fprintf (stderr, "psktool command failed\n");
104            exit (EXIT_FAILURE);
105          }
106
107          atexit (cleanup_keys);
108        }
109
110        int
111        main (int argc, char *argv[])
112        {
113          struct nbd_handle *nbd;
114          char buf[512];
115
116          create_keys ();
117
118          /* Create the libnbd handle. */
119          nbd = nbd_create ();
120          if (nbd == NULL) {
121            fprintf (stderr, "%s\n", nbd_get_error ());
122            exit (EXIT_FAILURE);
123          }
124
125          /* Enable TLS in the client. */
126          if (nbd_set_tls (nbd, LIBNBD_TLS_REQUIRE) == -1) {
127            fprintf (stderr, "%s\n", nbd_get_error ());
128            exit (EXIT_FAILURE);
129          }
130
131          /* Enable TLS-PSK and pass the keys filename. */
132          if (nbd_set_tls_psk_file (nbd, keys) == -1) {
133            fprintf (stderr, "%s\n", nbd_get_error ());
134            exit (EXIT_FAILURE);
135          }
136
137          /* Set the local username for authentication. */
138          if (nbd_set_tls_username (nbd, USERNAME) == -1) {
139            fprintf (stderr, "%s\n", nbd_get_error ());
140            exit (EXIT_FAILURE);
141          }
142
143          /* Run nbdkit as a subprocess, enabling and requiring
144           * TLS-PSK encryption.
145           */
146          char *args[] = {
147            "nbdkit", "-s", "--exit-with-parent",
148            "--tls", "require", "--tls-psk", keys,
149            "pattern", "size=1M", NULL
150          };
151          if (nbd_connect_command (nbd, args) == -1) {
152            fprintf (stderr, "%s\n", nbd_get_error ());
153            exit (EXIT_FAILURE);
154          }
155
156          /* Read the first sector. */
157          if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
158            fprintf (stderr, "%s\n", nbd_get_error ());
159            exit (EXIT_FAILURE);
160          }
161
162          /* TLS connections must be shut down. */
163          if (nbd_shutdown (nbd, 0) == -1) {
164            fprintf (stderr, "%s\n", nbd_get_error ());
165            exit (EXIT_FAILURE);
166          }
167
168          /* Close the libnbd handle. */
169          nbd_close (nbd);
170
171          exit (EXIT_SUCCESS);
172        }
173

SEE ALSO

175       nbd_create(3), nbd_set_tls(3), libnbd(3).
176

AUTHORS

178       Eric Blake
179
180       Richard W.M. Jones
181
183       Copyright (C) 2019 Red Hat Inc.
184

LICENSE

186       This library is free software; you can redistribute it and/or modify it
187       under the terms of the GNU Lesser General Public License as published
188       by the Free Software Foundation; either version 2 of the License, or
189       (at your option) any later version.
190
191       This library is distributed in the hope that it will be useful, but
192       WITHOUT ANY WARRANTY; without even the implied warranty of
193       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
194       Lesser General Public License for more details.
195
196       You should have received a copy of the GNU Lesser General Public
197       License along with this library; if not, write to the Free Software
198       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
199       02110-1301 USA
200
201
202
203libnbd-1.3.7                      2020-04-23           nbd_set_tls_psk_file(3)
Impressum