NCBI C++ ToolKit
ncbi_comm.h
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CONNECT___NCBI_COMM__H
2 #define CONNECT___NCBI_COMM__H
3 
4 /* $Id: ncbi_comm.h 92698 2021-02-07 16:50:04Z lavr $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Author: Anton Lavrentiev
30  *
31  * File Description:
32  * Common part of internal communication protocol used by both sides
33  * (client and server) of firewall daemon and service dispatchers.
34  *
35  */
36 
37 #define NCBID_WEBPATH "/Service/ncbid.cgi"
38 #define NCBI_DISP_VERSION "1.2"
39 #define HTTP_CONNECTION_INFO "Connection-Info:"
40 #define HTTP_DISP_FAILURES "Dispatcher-Failures:"
41 #define HTTP_DISP_MESSAGES "Dispatcher-Messages:"
42 #define HTTP_NCBI_MESSAGE "NCBI-Message:"
43 #define HTTP_NCBI_SID "NCBI-SID:"
44 #define HTTP_NCBI_PHID "NCBI-PHID:"
45 #define LBSM_DEFAULT_TIME 30 /* Default expiration time, seconds */
46 #define LBSM_DEFAULT_RATE 1000.0 /* For SLBSM_Service::info::rate */
47 #define LBSM_STANDBY_THRESHOLD 0.01
48 #define DISPATCHER_CFGPATH "/etc/lbsmd/"
49 #define DISPATCHER_CFGFILE "servrc.cfg"
50 #define DISPATCHER_MSGFILE ".dispd.msg"
51 #define CONN_FWD_PORT_MIN 5860
52 #define CONN_FWD_PORT_MAX 5870
53 #define CONN_FWD_BASE \
54  "https://www.ncbi.nlm.nih.gov/IEB/ToolBox/NETWORK"
55 #define CONN_FWD_LINK CONN_FWD_BASE "/dispatcher.html#Firewalling"
56 #define CONN_FWD_URL CONN_FWD_BASE "/firewall.html#Settings"
57 #define NCBI_EXTERNAL "NCBI-External"
58 #define SERVNSD_TXT_RR_PORT "_PORT="
59 
60 
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64 
65 
66 typedef unsigned int ticket_t;
67 
68 
69 /** FWDaemon request / reply.
70  * Assumed packed, all intergal fields are in network byte order.
71  *
72  * A client (identified by its IP in the "origin" field, or "0" for current
73  * host, or "-1" for unknown host) requests to connect to "host:port", and to
74  * send an optional (when non-zero) "ticket" as the very first data in that
75  * connection.
76  * The client may also (optionally) identify the connection with a variable
77  * size "text" (like a service name) that must be '\0'-terminated unless it
78  * extends to the maximal request size, FWD_RR_MAX_SIZE. In case if no such
79  * information can or should be provided, the request may skip transmitting
80  * the "text" field altogether, or can put a single '\0' in that field.
81  * @note that in order to be processed correctly, if the "text" field is to be
82  * sent, it _must_ be sent in a single transaction (syscall) with the rest of
83  * the request.
84  * Bit 0 (FWD_RR_FIREWALL, if set) of the FWDaemon control ("flag") is used to
85  * indicate that the client is a true firewall client. If the bit is clear,
86  * it means that the client is a relay client (and hence, should use a
87  * secondary, _not an official firewall_, port of the daemon, if available).
88  *
89  * In a successful reply, FWDaemon sends back a "host:port" pair for the
90  * client to re-connect to, and to send a new (non-zero) "ticket" as the very
91  * first data of that connection, so that the client can reach the endpoint
92  * requested. If FWD_RR_KEEPALIVE was requested in "flag", then "ticket" can
93  * be returned as 0 to indicate that the client _must_ keep reusing the
94  * existing connection to this FWDaemon in order to talk to the endpoint.
95  * FWDaemon identifies itself in the "origin" field.
96  * Non-zero bit 0 in "flag" of a successful reply indicates that the true
97  * firewall mode (via DMZ) is available (acknowledged when requested), and is
98  * being used by FWDaemon. The "text" field contains no useful information
99  * (it may not be present at all if the "ticket" returned non-zero, i.e. the
100  * re-connect is required; otherwise, it is always '\0'-terminated unless it
101  * extends to the maximal reply size, FWD_RR_MAX_SIZE).
102  *
103  * An error is signified by either a short reply (shorter than up to "text" --
104  * have to be discarded, and not considered to have any valid fields), or by
105  * "port" returned 0, or by the "flag" field testing non-zero with the
106  * FWD_RR_ERRORMASK mask. In the latter two cases of a full (i.e. not
107  * short) failure reply received:
108  * 1. If "flag" does not have any bits set within FWD_RR_ERRORMASK, then:
109  * if "flag" has some bits set in FWD_RR_REJECTMASK, then the client was
110  * "rejected"; otherwise, the error is "unknown" (the "text" field, if
111  * received and non-empty, may contain an optional error message in either
112  * of these cases);
113  * 2. If "flag" has some bits set within FWD_RR_ERRORMASK, then:
114  * if first 4 bytes of the reply contain "NCBI", then the entire reply is
115  * an error message (up to FWD_RR_MAX_SIZE or '\0', whichever comes first)
116  * and all the remaining fields of the reply should be considered invalid;
117  * else if the "text" field is present and non-empty, then it contains an
118  * error message; otherwise, the error is "unspecified".
119  *
120  * @sa
121  * FWDaemon_Request
122  */
123 
124 /** FWdaemon request / reply codes (the "flag" field, see above) */
125 #define FWD_RR_FIREWALL 1 /**< FIREWALL mode client, else RELAY */
126 #define FWD_RR_KEEPALIVE 2 /**< Try to reuse the connection */
127 
128 /** FWDaemon FWD_RR_REJECTMASK codes (the "flag" field, see above) */
129 #define FWD_RR_BADREQUEST 1 /**< Bad request (e.g. port 0 and no svc) */
130 #define FWD_RR_USEDIRECT 2 /**< Use directly (e.g. via direct connect) */
131 #define FWD_RR_NOFORWARD 3 /**< Bad forwarding (e.g. non-local endpoint) */
132 #define FWD_RR_NOTFOUND 4 /**< Service not found */
133 #define FWD_RR_CANTCONN 5 /**< Cannot connect to server */
134 #define FWD_RR_REFUSED 6 /**< Refused (e.g. due to abuse) */
135 
136 #define FWD_RR_ERRORMASK 0xF0F0
137 #define FWD_RR_REJECTMASK 0x0F0F
138 
139 typedef struct {
140  unsigned int host; /**< Host to connect to */
141  unsigned short port; /**< Port to connect to (if 0, use service) */
142  unsigned short flag; /**< FWDaemon control flag */
143  ticket_t ticket; /**< Connection ticket */
144  unsigned int origin; /**< Host requesting / replying */
145  char text[1]; /**< Service name / error message / status */
147 
148 
149 /** Maximal accepted request/reply size */
150 #define FWD_RR_MAX_SIZE 128
151 #define FWD_MAX_RR_SIZE FWD_RR_MAX_SIZE
152 
153 
154 #ifdef __cplusplus
155 } /* extern "C" */
156 #endif
157 
158 #endif /* CONNECT___NCBI_COMM__H */
static void text(MDB_val *v)
Definition: mdb_dump.c:62
unsigned int ticket_t
Definition: ncbi_comm.h:66
ticket_t ticket
Connection ticket.
Definition: ncbi_comm.h:143
unsigned short flag
FWDaemon control flag.
Definition: ncbi_comm.h:142
unsigned short port
Port to connect to (if 0, use service)
Definition: ncbi_comm.h:141
unsigned int origin
Host requesting / replying.
Definition: ncbi_comm.h:144
unsigned int host
Host to connect to.
Definition: ncbi_comm.h:140
Modified on Wed Feb 28 07:13:30 2024 by modify_doxy.py rev. 669887