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 LIMITED
  25  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  26  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
  27  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  28  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  29  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  30  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  31  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  33  * 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 seconds timeout on incoming remote control handshake */
  60 #define REMOTE_CONTROL_TCP_TIMEOUT 120
  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         /** the rc this is part of */
  77         struct daemon_remote* rc;
  78 };
  79
  80 /**
  81  * The remote control tool state.
  82  * The state is only created for the first thread, other threads
  83  * are called from this thread.  Only the first threads listens to
  84  * the control port.  The other threads do not, but are called on the
  85  * command channel(pipe) from the first thread.
  86  */
  87 struct daemon_remote {
  88         /** the worker for this remote control */
  89         struct worker* worker;
  90         /** commpoints for accepting remote control connections */
  91         struct listen_list* accept_list;
  92         /** number of active commpoints that are handling remote control */
  93         int active;
  94         /** max active commpoints */
  95         int max_active;
  96         /** current commpoints busy; should be a short list, malloced */
  97         struct rc_state* busy_list;
  98 #ifdef HAVE_SSL
  99         /** the SSL context for creating new SSL streams */
 100         SSL_CTX* ctx;
 101 #endif
 102 };
 103
 104 /**
 105  * Create new remote control state for the daemon.
 106  * @param cfg: config file with key file settings.
 107  * @return new state, or NULL on failure.
 108  */
 109 struct daemon_remote* daemon_remote_create(struct config_file* cfg);
 110
 111 /**
 112  * remote control state to delete.
 113  * @param rc: state to delete.
 114  */
 115 void daemon_remote_delete(struct daemon_remote* rc);
 116
 117 /**
 118  * remote control state to clear up. Busy and accept points are closed.
 119  * Does not delete the rc itself, or the ssl context (with its keys).
 120  * @param rc: state to clear.
 121  */
 122 void daemon_remote_clear(struct daemon_remote* rc);
 123
 124 /**
 125  * Open and create listening ports for remote control.
 126  * @param cfg: config options.
 127  * @return list of ports or NULL on failure.
 128  *      can be freed with listening_ports_free().
 129  */
 130 struct listen_port* daemon_remote_open_ports(struct config_file* cfg);
 131
 132 /**
 133  * Setup comm points for accepting remote control connections.
 134  * @param rc: state
 135  * @param ports: already opened ports.
 136  * @param worker: worker with communication base. and links to command channels.
 137  * @return false on error.
 138  */
 139 int daemon_remote_open_accept(struct daemon_remote* rc,
 140         struct listen_port* ports, struct worker* worker);
 141
 142 /**
 143  * Stop accept handlers for TCP (until enabled again)
 144  * @param rc: state
 145  */
 146 void daemon_remote_stop_accept(struct daemon_remote* rc);
 147
 148 /**
 149  * Stop accept handlers for TCP (until enabled again)
 150  * @param rc: state
 151  */
 152 void daemon_remote_start_accept(struct daemon_remote* rc);
 153
 154 /**
 155  * Handle nonthreaded remote cmd execution.
 156  * @param worker: this worker (the remote worker).
 157  */
 158 void daemon_remote_exec(struct worker* worker);
 159
 160 #ifdef HAVE_SSL
 161 /**
 162  * Print fixed line of text over ssl connection in blocking mode
 163  * @param ssl: print to
 164  * @param text: the text.
 165  * @return false on connection failure.
 166  */
 167 int ssl_print_text(SSL* ssl, const char* text);
 168
 169 /**
 170  * printf style printing to the ssl connection
 171  * @param ssl: the SSL connection to print to. Blocking.
 172  * @param format: printf style format string.
 173  * @return success or false on a network failure.
 174  */
 175 int ssl_printf(SSL* ssl, const char* format, ...)
 176         ATTR_FORMAT(printf, 2, 3);
 177
 178 /**
 179  * Read until \n is encountered
 180  * If SSL signals EOF, the string up to then is returned (without \n).
 181  * @param ssl: the SSL connection to read from. blocking.
 182  * @param buf: buffer to read to.
 183  * @param max: size of buffer.
 184  * @return false on connection failure.
 185  */
 186 int ssl_read_line(SSL* ssl, char* buf, size_t max);
 187 #endif /* HAVE_SSL */
 188
 189 #endif /* DAEMON_REMOTE_H */