/usr/share/doc/refdb/refdb-manual/ch23s02.html is in refdb-doc 1.0.2-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Basic principles</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="RefDB handbook" /><link rel="up" href="ch23.html" title="Chapter 23. The RefDB client/server communication protocol" /><link rel="prev" href="ch23.html" title="Chapter 23. The RefDB client/server communication protocol" /><link rel="next" href="ch23s03.html" title="Commented abstract representation of the client/server protocol" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Basic principles</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch23.html">Prev</a> </td><th width="60%" align="center">Chapter 23. The RefDB client/server communication protocol</th><td width="20%" align="right"> <a accesskey="n" href="ch23s03.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp71235488"></a>Basic principles</h2></div></div></div><p>refdbd is implemented as a forking server. The parent process waits to accept connections from the clients. If a valid connection request is detected, the server forks. The parent closes the connection and is ready to respond to further requests. The child processes the client request and terminates when done.</p><p>The communication between the client and the server is at least a two-stage process. In the first stage, the validity of the client request is checked, the protocol version is checked and the password encryption is initiated. In the second stage, the command proper is executed and the results are sent back to the client. The second stage may use several iterations of client/server messages in order to transfer larger amounts of data.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp71232848"></a>Message format</h3></div></div></div><p>All data, that is client commands as well as the server-generated results, are sent as plain text. We have to distinguish between three types of messages:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Status messages</span></dt><dd><p>Status messages are unterminated three-byte sequences which encode the client or server status. They may precede terminated messages, but they can also appear alone. The three bytes are a text representation of the client or server status. E.g. the sequence "000" (that is, three times the ASCII character 48 representing the digit 'zero') denotes an OK status. A listing of the status messages used by RefDB is shown in the section <a class="link" href="ch23s03.html#sect-statusmessages" title="Status messages">Status Messages</a>.</p></dd><dt><span class="term">Terminated messages</span></dt><dd><p>Most of the data transfer between client and server uses terminated messages. Due to the support of multibyte character sets the string termination character is not a single '\0' character as in a C string, but a sequence of four consecutive '\0' bytes (sequences of up to three '\0' bytes may occur as part of multibyte Unicode characters). It is best to think of the messages as binary strings. A custom client has to terminate its messages to the server appropriately, and it has to scan the data sent back by the server for the terminating sequence.</p></dd><dt><span class="term">Messages of a specified length</span></dt><dd><p>In a few cases, the client asks the server to provide a buffer of a certain size, and will subsequently transfer exactly the requested number of bytes. These messages are unterminated.</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp75600480"></a>First stage</h3></div></div></div><p>The purpose of the first stage is to check whether the client request makes sense at all, and if so, to initiate the exchange of the password encryption information.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idp75598800"></a>Sanity and permission check</h4></div></div></div><p>Unless told otherwise, refdbd accepts only local connections. If the client request stems from a computer with a different IP address than the computer that runs refdbd, the connection request is refused without any further attempt to talk to the client. From the client side the connection will simply time out. This "unfriendly" behaviour minimizes the risk of remote exploits.</p><p>If the client is allowed to connect, refdbd tries to read a terminated string from the client. If this string is too short or too long to represent the protocol number which the client is supposed to send, the connection request is refused by sending back an appropriate status message. The same occurs if the protocol version of the client is not supported by the server.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idp75781200"></a>Password encryption</h4></div></div></div><p>The RefDB clients may have to transmit the database username and password in order to authenticate the user with the database server. In order to avoid sending the password across the network as plain text, the clients send encrypted versions, which the refdbd server decrypts again. Database engine client libraries usually employ their own means to encrypt the passwords when they are sent from refdbd to the database engine.</p><p>RefDB uses a fairly simple password encryption. It is still too cumbersome to decrypt for bored script kiddies so it should serve it's purpose. The encryption is somewhat modeled after the (in)famous ENIGMA boxes used by the bad guys in WWII. The basic idea is that refdbd sends a string to the client which encodes the (randomly generated) rotor sequence and positions for this particular connection. The client uses this information to encode the password. The server can decrypt the password using the sequence and position information that it previously generated.</p><p>The rotor wirings are hardcoded. Any client or library has to use the same wirings as in <code class="filename">src/filename.c</code>. The encoding string has the format "ABC-DE-FG-HI", which stands for:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">ABC</span></dt><dd><p>This three-digit string denotes the sequence of the wheels. ABC denote the wheels in slots 0, 1, and 2, respectively. The wheels are also numbered 0 through 2, and each wheel can be used only once. That is, all valid combinations are "012", "021", "102", "120", "210", "201". For example, the string "120" means that wheel 1 is inserted in slot 0, wheel 2 in slot 1, and wheel 0 in slot 2.</p></dd><dt><span class="term">DE</span></dt><dd><p>The position of the wheel in slot 0. A two-digit integer equal to or larger than 0 and smaller than 94. For example, the string "05" means the wheel in slot 0 has to advance 5 positions.</p></dd><dt><span class="term">FG</span></dt><dd><p>Same as DE, but for slot 1.</p></dd><dt><span class="term">HI</span></dt><dd><p>Same as DE, but for slot 2.</p></dd></dl></div><p>The encryption and decryption itself is described in sufficient detail in the source file <code class="filename">src/enigma.c</code> or in the <code class="filename">Client.pm</code> file of the RefDBClient Perl module. If you cannot implement this mechanism in your favourite programming language, there is also an external program <a class="link" href="re30.html" title="eenc">eenc</a> as part of the RefDB distribution which performs the encryption/decryption and sends the result to <code class="filename">stdout</code>. Use it like this:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>eenc -p <em class="replaceable"><code>ABC-DE-FG-HI</code></em> <em class="replaceable"><code>password</code></em></code></strong>
</pre><p>Most programming languages allow to read the results from <code class="filename">stdout</code> into a variable and use it as the encrypted or decrypted string.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>There is no switch for encryption or decryption as the ENIGMA mechanism is symmetrical.</p></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp75583296"></a>Second stage</h3></div></div></div><p>As the first step of the second stage the client sends the command string proper. These strings are commands as you know them from your shell. They are roughly equivalent to the command strings that you type into the C clients. refdbd parses the command string internally with the getopt library, just as your shell does. After the command string is parsed, refdbd executes the command. The result is returned in at least two steps. With one exception, refdbd first sends back the command result, followed by a command summary. For example, the <a class="link" href="re11.html#app-c-command-listdb" title="listdb">listdb</a> command first sends back a newline-separated list of database names (the command result proper), followed by the number of available databases (the command summary). These steps are explained in more detail in the following sections. First we'll have a look at the internal command syntax.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idp75585888"></a>Command syntax</h4></div></div></div><p>Each command consists of the command word proper, optionally followed by switches, options, and arguments. As the string is parsed by the getopt library, the sequence of options, commands, and arguments does not matter. The following synopsis shows all possible switches and options.</p><div class="cmdsynopsis"><p><code class="command">command</code> [-a] [-A <em class="replaceable"><code>in_format</code></em>] [-b <em class="replaceable"><code>listname</code></em>] [-d <em class="replaceable"><code>database</code></em>] [-E <em class="replaceable"><code>encoding</code></em>] [-G <em class="replaceable"><code>URL</code></em>] [-H <em class="replaceable"><code>host</code></em>] [-k] [-n] [-N <em class="replaceable"><code>limit[:offset]</code></em>] [-o <em class="replaceable"><code>number</code></em>] [-p] [-P] [-r] [-R <em class="replaceable"><code>pdfroot</code></em>] [-s <em class="replaceable"><code>format_string</code></em>] [-S <em class="replaceable"><code>sort_string</code></em>] [-t <em class="replaceable"><code>ref_format</code></em>] [-u <em class="replaceable"><code>username</code></em>] [-U <em class="replaceable"><code>name</code></em>] [-w <em class="replaceable"><code>password</code></em>] [-W <em class="replaceable"><code>newuser_password</code></em>]</p></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">-a</span></dt><dd><p>The commands <a class="link" href="re11.html#app-c-command-getjo" title="getjo, getjf, getj1, getj2">getjo</a>, <a class="link" href="re11.html#app-c-command-getjf">getjf</a>, <a class="link" href="re11.html#app-c-command-getj1">getj1</a>, and <a class="link" href="re11.html#app-c-command-getj2">getj2</a> use this switch to request all journal names (short, full, user abbrev1, and user abbrev2) instead of only the one used to match the query.</p></dd><dt><span class="term">-A <em class="replaceable"><code>in_format</code></em></span></dt><dd><p>The input data format for <a class="link" href="re11.html#app-c-command-addref" title="addref">addref</a>, <a class="link" href="re11.html#app-c-command-updateref" title="updateref">updateref</a>, and <a class="link" href="re11.html#app-c-command-checkref" title="checkref">checkref</a>. Currently supported values are "ris" and "risx".</p></dd><dt><span class="term">-b <em class="replaceable"><code>listname</code></em></span></dt><dd><p>Specifies the name of a personal reference list.</p></dd><dt><span class="term">-d <em class="replaceable"><code>database</code></em></span></dt><dd><p>This option sets the name of the database to be used with the current command.</p></dd><dt><span class="term">-E <em class="replaceable"><code>encoding</code></em></span></dt><dd><p>This option sets the character encoding for the current command.</p></dd><dt><span class="term">-G <em class="replaceable"><code>URL</code></em></span></dt><dd><p>The <a class="link" href="re11.html#app-c-command-getref" title="getref">getref</a> command uses this option to pass the URL of a CSS stylesheet to the server.</p></dd><dt><span class="term">-H <em class="replaceable"><code>host</code></em></span></dt><dd><p>The <a class="link" href="re06.html#app-a-command-adduser" title="adduser">adduser</a> command uses this option to set the hostname or IP address of the user to be added.</p></dd><dt><span class="term">-k</span></dt><dd><p>This switch tells the <a class="link" href="re11.html#app-c-command-addref" title="addref">addref</a> command to preserve the numerical ID of the datasets in the U5 field.</p></dd><dt><span class="term">-n <em class="replaceable"><code>namespace</code></em></span></dt><dd><p>This option passes a namespace prefix to the getref and getnote commands (applies only to XML output)</p></dd><dt><span class="term">-N <em class="replaceable"><code>limit[:offset]</code></em></span></dt><dd><p>The <a class="link" href="re11.html#app-c-command-getref" title="getref">getref</a> command and all other get* commands use this option to limit the range of datasets to return. <em class="replaceable"><code>limit</code></em> denotes the number of references to return, and <em class="replaceable"><code>offset</code></em> is an optional number of references to skip at the beginning.
</p></dd><dt><span class="term">-o <em class="replaceable"><code>number</code></em></span></dt><dd><p>This option is used to set a custom starting number for numeric bibliographies.</p></dd><dt><span class="term">-p</span></dt><dd><p>This option is used with the addref and updateref commands. If set, refdbd will update personal info only.</p></dd><dt><span class="term">-P</span></dt><dd><p>If used with the getref command, only references in the personal interest list will be returned.</p></dd><dt><span class="term">-r</span></dt><dd><p>This switch is used with several commands to turn an "add" operation into a "remove" operation.</p></dd><dt><span class="term">-R <em class="replaceable"><code>pdfroot</code></em></span></dt><dd><p>This option tells the getref command the variant part of the link to an electronic offprint.</p></dd><dt><span class="term">-s <em class="replaceable"><code>format_string</code></em></span></dt><dd><p>getbib uses this option to pass the bibliography style. Checkref uses this option to request additional fields in the xhtml output.</p></dd><dt><span class="term">-S <em class="replaceable"><code>sort_string</code></em></span></dt><dd><p>The name of the bibliography style to be used with the getbib command.</p></dd><dt><span class="term">-t <em class="replaceable"><code>ref_format</code></em></span></dt><dd><p>The output format of the references retrieved with the getref and getbib commands.</p></dd><dt><span class="term">-u <em class="replaceable"><code>username</code></em></span></dt><dd><p>The username to be used to authenticate with the database engine.</p></dd><dt><span class="term">-U <em class="replaceable"><code>name</code></em></span></dt><dd><p>The name of the user to be associated with a query.</p></dd><dt><span class="term">-w <em class="replaceable"><code>password</code></em></span></dt><dd><p>The password to be used to authenticate with the database engine.</p></dd><dt><span class="term">-W <em class="replaceable"><code>newuser_password</code></em></span></dt><dd><p>The <a class="link" href="re06.html#app-a-command-adduser" title="adduser">adduser</a> command uses this option to set the password of the new user.</p></dd></dl></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch23.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch23.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch23s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 23. The RefDB client/server communication protocol </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Commented abstract representation of the client/server protocol</td></tr></table></div></body></html>
|