1 /* tlspool/starttls.h -- Library functions to invoke from clients/servers */
3 #ifndef TLSPOOL_STARTTLS_H
4 #define TLSPOOL_STARTTLS_H
11 #include <tlspool/commands.h>
17 #endif /* WINDOWS_PORT */
21 * These functions are used by application software to turn an existing
22 * connection into one that runs over TLS or DTLS. These functions are
23 * not just used after an acknowledged STARTTLS exchange, but can also
24 * be used immediately on a newly opened connection running an xxxs:
25 * secure variation of a standard protocol xxx: -- usually, the two
26 * versions each have their own default port.
28 * The starttls_ operations can consume a fair amount of time to finish,
29 * so future versions may provide asynchronous variations. At present,
30 * the calls are not re-entrant. TODO: asynchronicity & request pooling.
35 #define TLSPOOL_DEFAULT_CONFIG_PATH "/etc/tlspool.conf.windows"
36 #define TLSPOOL_DEFAULT_SOCKET_PATH "\\\\.\\pipe\\tlspool"
37 #define TLSPOOL_DEFAULT_PIDFILE_PATH "/var/run/tlspool.pid"
39 #define TLSPOOL_DEFAULT_CONFIG_PATH "/etc/tlspool.conf"
40 #define TLSPOOL_DEFAULT_SOCKET_PATH "/var/run/tlspool.sock"
41 #define TLSPOOL_DEFAULT_PIDFILE_PATH "/var/run/tlspool.pid"
42 #endif /* WINDOWS_PORT */
44 /* Retrieve the process identity of the TLS Pool from the named file, or fall
45 * back on the default file if the name is set to NULL. Returns -1 on failure.
47 int tlspool_pid (char *opt_pidfile);
49 /* OS independent pool handle
55 struct tlspool_command chRequest;
59 } PIPEINST, *LPPIPEINST;
60 typedef LPPIPEINST pool_handle_t;
61 #define INVALID_POOL_HANDLE NULL
62 #else /* WINDOWS_PORT */
63 typedef int pool_handle_t;
64 #define INVALID_POOL_HANDLE -1
65 #endif /* WINDOWS_PORT */
67 /* Setup the TLS pool socket to use, if it is not the default path name
68 * /var/run/tlspool.sock. The return value is the file descriptor for the
69 * pool. This function can be called again, in which case the argument is
70 * ignored and the previously set socket is returned. The function can also
71 * be called with NULL in the first call, in which case the default location
74 pool_handle_t tlspool_open_poolhandle (char *path);
76 /* Close a pool handle
79 static inline void tlspool_close_poolhandle (pool_handle_t poolh) {
82 #else /* WINDOWS_PORT */
83 static inline void tlspool_close_poolhandle (pool_handle_t poolh) {
86 #endif /* WINDOWS_PORT */
89 /* The library function for ping, which is called to establish the API
90 * version and a list of facilities supported by the TLS Pool. The data
91 * supplied to the TLS Pool should represent the environment of the
92 * application, which is why no defaults are provided by this function
93 * but the application should supply all ping data.
95 * The pioc_ping structure will be copied into the command structure,
96 * and upon completion it will be copied back. Normally, the application
97 * would set YYYYMMDD_producer to TLSPOOL_IDENTITY_V2, and facilities
98 * to PIOF_FACILITY_ALL_CURRENT. The TLS Pool overwrites the former and
99 * resets unsupported bits in the latter. Note that facilities may be
100 * unsupported due to the compile-time environment of the TLS Pool or
101 * because it was configured without the requested support.
103 * This function returns zero on success, and -1 on failure. In case of
104 * failure, errno will be set.
106 int tlspool_ping (pingpool_t *pingdata);
109 /* The library function for starttls, which is normally called through one
110 * of the two inline variations below, which start client and server sides.
112 * The cryptfd handle supplies the TLS connection that is assumed to have
113 * been setup. When the function ends, either in success or failure, this
114 * handle will no longer be available to the caller; the responsibility of
115 * closing it is passed on to the function and/or the TLS Pool.
117 * The tlsdata structure will be copied into the command structure,
118 * and upon completion it will be copied back. You can use it to
119 * communicate flags, protocols and other parameters, including the
120 * most important settings -- local and remote identifiers. See
121 * the socket protocol document for details.
123 * The privdata handle is used in conjunction with the namedconnect() call;
124 * it is passed on to connect the latter to the context from which it was
125 * called and is not further acted upon by this function.
127 * The namedconnect() function is called when the identities have been
128 * exchanged, and established, in the TLS handshake. This is the point
129 * at which a connection to the plaintext side is needed, and a callback
130 * to namedconnect() is made to find a handle for it. The function is
131 * called with a version of the tlsdata that has been updated by the
132 * TLS Pool to hold the local and remote identities. The return value
133 * should be -1 on error, with errno set, or it should be a valid file
134 * handle that can be passed back to the TLS Pool to connect to.
136 * When the namedconnect argument passed is NULL, default behaviour is
137 * triggered. This interprets the privdata handle as an (int *) holding
138 * a file descriptor. If its value is valid, that is, >= 0, it will be
139 * returned directly; otherwise, a socketpair is constructed, one of the
140 * sockets is stored in privdata for use by the caller and the other is
141 * returned as the connected file descriptor for use by the TLS Pool.
142 * This means that the privdata must be properly initialised for this
143 * use, with either -1 (to create a socketpair) or the TLS Pool's
144 * plaintext file descriptor endpoint. The file handle returned in
145 * privdata, if it is >= 0, should be closed by the caller, both in case
146 * of success and failure.
148 * This function returns zero on success, and -1 on failure. In case of
149 * failure, errno will be set.
151 int tlspool_starttls (int cryptfd, starttls_t *tlsdata,
153 int namedconnect (starttls_t *tlsdata, void *privdata));
156 /* The library function to send a control connection command, notably
157 * TLSPOOL_CONTROL_DETACH and TLSPOOL_CONTROL_REATTACH.
159 * This function returns zero on success, and -1 on failure. In case of
160 * failure, errno will be set.
162 int _tlspool_control_command (int cmd, uint8_t *ctlkey);
165 /* Explicitly detach a TLS session from the controlling connection to the
166 * TLS Pool. This means that the control connection (and so, this program)
167 * can be taken down without affecting the TLS session as it is setup. It
168 * also means that any control connection (including ones from other processes
169 * and other programs) can reattach, using the ctlkey for the TLS session.
171 * The return value is 0 for success, -1 for failure. In case of failure,
172 * errno will also be set.
174 static inline int tlspool_control_detach (uint8_t *ctlkey) {
175 return _tlspool_control_command (PIOC_CONTROL_DETACH_V2, ctlkey);
179 /* Explicitly reattach a control connection to a TLS session. This may be
180 * called on a TLS session that is detached, by any process or program that
181 * presents the proper control key.
183 * The return value is 0 for success, -1 for failure. In case of failure,
184 * errno will also be set.
186 static inline int tlspool_control_reattach (uint8_t *ctlkey) {
187 return _tlspool_control_command (PIOC_CONTROL_REATTACH_V2, ctlkey);
191 /* Register a callback function for local identity selection with the
192 * LIDENTRY API of the TLS Pool. This will invoke the callback with zero
193 * or more database entries (marked with flag PIOF_LIDENTRY_DBENTRY) and an
194 * inquiry (without that flag) to enter a local identity. The callback is
195 * expected to save the database entries in some sort of a menu structure
196 * (or ignore it if it is not interested in them) and use them in the
197 * selection process. What it does precisely is up to the registered
200 * The callback behaviour of the API can be influenced in various ways;
201 * see the PIOF_LIDENTRY_xxx flags in <tlspool/commands.h> for details.
202 * Some flags are used during registration and supplied in regflags,
203 * some are used during callback and exchanged in the tlspool_command.
205 * The registration for callback terminates in the following situations:
206 * - the TLS Pool file handle is closed
207 * - the callback returns a wrong type of command, including PIOC_ERROR_xx
208 * - the callback does not respond fast enough (other apps may overtake)
210 * The responsetimeout is set to the number of seconds that a callback
211 * may at most take to respond. The claim on the registration will expire
212 * after this time has passed.
214 * Note that the service function does not return until the callback
215 * registration is terminated. This is why it is called xxx_service and
216 * not xxx_callback. You may want to use a thread if your intention is
217 * to do other things as well. Note however, that it is usually a good
218 * idea to keep localid handling separate, as a GUI function, from the
219 * other components that interact with the TLS Pool for other purposes,
220 * such as wrapping an application protocol.
222 * This function returns 0 on success, meaning it has gotten to a stage
223 * where it was registered with the TLS Pool. Otherwise, it returns -1
226 int tlspool_localid_service (char *path, uint32_t regflags, int responsetimeout, char * (*cb) (struct pioc_lidentry *entry, void *data), void *data);
229 /* The library function to service PIN entry callbacks. It registers
230 * with the TLS Pool and will service callback requests until it is no
231 * longer welcomed. Of course, if another process already has a claim on
232 * this functionality, the service offering will not be welcome from the
235 * This function differs from most other TLS Pool library functions in
236 * setting up a private socket. This helps to avoid the overhead in the
237 * foreseeable applications that only do this; it also helps to close
238 * down the exclusive claim on local identity resolution when (part of)
239 * the program is torn down. The function has been built to cleanup
240 * properly when it is subjected to pthread_cancel().
242 * The path parameter offers a mechanism to specify the socket path. When
243 * set to NULL, the library's compiled-in default path will be used.
245 * In terms of linking, this routine is a separate archive object. This
246 * minimizes the amount of code carried around in statically linked binaries.
248 * This function returns -1 on error, or 0 on success.
250 int tlspool_pin_service (char *path, uint32_t regflags, int responsetimeout_usec, void (*cb) (pinentry_t *entry, void *data), void *data);
253 /* Generate a pseudo-random sequence based on session cryptographic keys.
255 * In the case of TLS, this adheres to RFC 5705; other protocols may or
256 * may not support a similar mechanism, in which case an error is returned.
258 * This leans on access privileges to an existing connection at a meta-level,
259 * for which we use the customary ctlkey verification mechanism introduced with
260 * tlspool_starttls (). Note that random material may be used for security
261 * purposes, such as finding the same session key for both sides deriving from
262 * prior key negotiation; the protection of a ctlkey for such applications is
265 * The inputs to this function must adhere to the following restrictions:
266 * - label must not be a NULL pointer, but opt_ctxvalue may be set to NULL
267 * to bypass the use of a context value. Note that passing an empty string
268 * in opt_ctxvalue is different from not providing the string at all by
269 * setting it to NULL.
270 * - label and opt_ctxvalue (if non-NULL) refer to ASCII strings with
271 * printable characters, terminated with a NUL character. The maximum
272 * string length of each is 254 bytes.
273 * - prng_len holds the requested number of pseudo-random bytes
274 * - prng_buf points is a non-NULL pointer to a buffer that can hold
277 * If the operation succeeds, then prng_buf holds prng_len bytes of random
278 * material, and zero is returned. If the operation fails, then prng_buf
279 * is filled with zero bytes (to make it stand out as a rather rare case of
280 * a random byte string) and -1 is returned.
282 * Note a few restrictions to the generality of this function, as a result of
283 * the underlying packet format for the communication with the TLS Pool; but
284 * the dimensions have been choosen such that these restrictions would not
285 * typically be a problem in practice:
286 * - it constrains the string lengths of label and opt_ctxvalue
287 * - it constrains prng_len to a maximum value of TLSPOOL_PRNGBUFLEN
289 * The TLS Pool may limit certain TLS PRNG labels, in adherence to the
290 * IANA-maintained TLS Exporter Label Registry. It additionally supports
291 * the EXPERIMENTAL label prefix specified in RFC 5705.
293 * Be advised that the maximum size of buffer may increase in future releases.
294 * So, be sure to use TLSPOOL_PRNGBUFLEN which holds the header-file defined
297 int tlspool_prng (char *label, char *opt_ctxvalue,
298 uint16_t prng_len, uint8_t *prng_buf,
302 /* Fetch a configuration variable value from the configuration file. This is not
303 * an efficient procedure, at best suited for startup of tools or daemons; it
304 * will iterate over the config file until it reads the desired value. The value
305 * returned is allocated and should be freed by the caller using free().
307 * When cfgfile is NULL, the environment variable TLSPOOL_CONFIGFILE is
308 * tried first, followed by the default setting from the macro
309 * TLSPOOL_DEFAULT_SOCKET_PATH as defined in <tlspool/starttls.h>.
311 * The value returned is NULL when the variable is not found, including when this
312 * is due to errors such as not being able to open the file.
314 char *tlspool_configvar (char *cfgfile, char *varname);
322 #endif // TLSPOOL_STARTTLS_H