contrib/unbound/daemon/remote.h

   1 /*
   2  * daemon/remote.h - remote control for the unbound daemon.
   3  *
   4  * Copyright (c) 2008, NLnet Labs. All rights reserved.
   5  *
   6  * This software is open source.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  *
  12  * Redistributions of source code must retain the above copyright notice,
  13  * this list of conditions and the following disclaimer.
  14  *
  15  * Redistributions in binary form must reproduce the above copyright notice,
  16  * this list of conditions and the following disclaimer in the documentation
  17  * and/or other materials provided with the distribution.
  18  *
  19  * Neither the name of the NLNET LABS nor the names of its contributors may
  20  * be used to endorse or promote products derived from this software without
  21  * specific prior written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  26  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  27  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  28  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  29  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  30  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  31  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  32  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  */
  35
  36 /**
  37  * \file
  38  *
  39  * This file contains the remote control functionality for the daemon.
  40  * The remote control can be performed using either the commandline
  41  * unbound-control tool, or a SSLv3/TLS capable web browser.
  42  * The channel is secured using SSLv3 or TLSv1, and certificates.
  43  * Both the server and the client(control tool) have their own keys.
  44  */
  45
  46 #ifndef DAEMON_REMOTE_H
  47 #define DAEMON_REMOTE_H
  48 #ifdef HAVE_OPENSSL_SSL_H
  49 #include "openssl/ssl.h"
  50 #endif
  51 struct config_file;
  52 struct listen_list;
  53 struct listen_port;
  54 struct worker;
  55 struct comm_reply;
  56 struct comm_point;
  57 struct daemon_remote;
  58
  59 /** number of milliseconds timeout on incoming remote control handshake */
  60 #define REMOTE_CONTROL_TCP_TIMEOUT 120000
  61
  62 /**
  63  * a busy control command connection, SSL state
  64  */
  65 struct rc_state {
  66         /** the next item in list */
  67         struct rc_state* next;
  68         /** the commpoint */
  69         struct comm_point* c;
  70         /** in the handshake part */
  71         enum { rc_none, rc_hs_read, rc_hs_write } shake_state;
  72 #ifdef HAVE_SSL
  73         /** the ssl state */
  74         SSL* ssl;
  75 #endif
  76         /** file descriptor */
  77         int fd;
  78         /** the rc this is part of */
  79         struct daemon_remote* rc;
  80 };
  81
  82 /**
  83  * The remote control tool state.
  84  * The state is only created for the first thread, other threads
  85  * are called from this thread.  Only the first threads listens to
  86  * the control port.  The other threads do not, but are called on the
  87  * command channel(pipe) from the first thread.
  88  */
  89 struct daemon_remote {
  90         /** the worker for this remote control */
  91         struct worker* worker;
  92         /** commpoints for accepting remote control connections */
  93         struct listen_list* accept_list;
  94         /* if certificates are used */
  95         int use_cert;
  96         /** number of active commpoints that are handling remote control */
  97         int active;
  98         /** max active commpoints */
  99         int max_active;
 100         /** current commpoints busy; should be a short list, malloced */
 101         struct rc_state* busy_list;
 102 #ifdef HAVE_SSL
 103         /** the SSL context for creating new SSL streams */
 104         SSL_CTX* ctx;
 105 #endif
 106 };
 107
 108 /**
 109  * Connection to print to, either SSL or plain over fd
 110  */
 111 struct remote_stream {
 112 #ifdef HAVE_SSL
 113         /** SSL structure, nonNULL if using SSL */
 114         SSL* ssl;
 115 #endif
 116         /** file descriptor for plain transfer */
 117         int fd;
 118 };
 119 typedef struct remote_stream RES;
 120
 121 /**
 122  * Create new remote control state for the daemon.
 123  * @param cfg: config file with key file settings.
 124  * @return new state, or NULL on failure.
 125  */
 126 struct daemon_remote* daemon_remote_create(struct config_file* cfg);
 127
 128 /**
 129  * remote control state to delete.
 130  * @param rc: state to delete.
 131  */
 132 void daemon_remote_delete(struct daemon_remote* rc);
 133
 134 /**
 135  * remote control state to clear up. Busy and accept points are closed.
 136  * Does not delete the rc itself, or the ssl context (with its keys).
 137  * @param rc: state to clear.
 138  */
 139 void daemon_remote_clear(struct daemon_remote* rc);
 140
 141 /**
 142  * Open and create listening ports for remote control.
 143  * @param cfg: config options.
 144  * @return list of ports or NULL on failure.
 145  *      can be freed with listening_ports_free().
 146  */
 147 struct listen_port* daemon_remote_open_ports(struct config_file* cfg);
 148
 149 /**
 150  * Setup comm points for accepting remote control connections.
 151  * @param rc: state
 152  * @param ports: already opened ports.
 153  * @param worker: worker with communication base. and links to command channels.
 154  * @return false on error.
 155  */
 156 int daemon_remote_open_accept(struct daemon_remote* rc,
 157         struct listen_port* ports, struct worker* worker);
 158
 159 /**
 160  * Stop accept handlers for TCP (until enabled again)
 161  * @param rc: state
 162  */
 163 void daemon_remote_stop_accept(struct daemon_remote* rc);
 164
 165 /**
 166  * Stop accept handlers for TCP (until enabled again)
 167  * @param rc: state
 168  */
 169 void daemon_remote_start_accept(struct daemon_remote* rc);
 170
 171 /**
 172  * Handle nonthreaded remote cmd execution.
 173  * @param worker: this worker (the remote worker).
 174  */
 175 void daemon_remote_exec(struct worker* worker);
 176
 177 #ifdef HAVE_SSL
 178 /**
 179  * Print fixed line of text over ssl connection in blocking mode
 180  * @param ssl: print to
 181  * @param text: the text.
 182  * @return false on connection failure.
 183  */
 184 int ssl_print_text(RES* ssl, const char* text);
 185
 186 /**
 187  * printf style printing to the ssl connection
 188  * @param ssl: the RES connection to print to. Blocking.
 189  * @param format: printf style format string.
 190  * @return success or false on a network failure.
 191  */
 192 int ssl_printf(RES* ssl, const char* format, ...)
 193         ATTR_FORMAT(printf, 2, 3);
 194
 195 /**
 196  * Read until \n is encountered
 197  * If stream signals EOF, the string up to then is returned (without \n).
 198  * @param ssl: the RES connection to read from. blocking.
 199  * @param buf: buffer to read to.
 200  * @param max: size of buffer.
 201  * @return false on connection failure.
 202  */
 203 int ssl_read_line(RES* ssl, char* buf, size_t max);
 204 #endif /* HAVE_SSL */
 205
 206 #endif /* DAEMON_REMOTE_H */