"Fossies" - the Fresh Open Source Software Archive

Member "rgdbm-2.1.42/rgdbm.3" (21 Jun 2007, 8332 Bytes) of package /linux/privat/old/rgdbm-2.1.42.tgz:


Caution: As a special service "Fossies" has tried to format the requested manual source page into HTML format but links to other man pages may be missing or even erroneous. Alternatively you can here view or download the uninterpreted manual source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

RGDBM

NAME
SYNOPSIS
DESCRIPTION
LINKING
FILES
BUGS
SEE ALSO
AUTHOR
REPORTING BUGS

NAME

RGDBM - The Remote GNU database manager.

SYNOPSIS

#include <gdbm.h>
#include <rgdbm.h>

rgdbm_error
rgdbm_errno()

char
*rgdbm_version()

RGDBM_FILE
rgdbm_open (name, block_size, read_write, mode, fatal_func)
char * name;
int block_size, read_write, mode;
void (*fatal_func) ();

void
rgdbm_close (dbf)
RGDBM_FILE dbf;

int
rgdbm_store (dbf, key, content, flag)
RGDBM_FILE dbf;
datum key, content;
int flag;

datum
rgdbm_fetch (dbf, key)
RGDBM_FILE dbf;
datum key;

int
gdbm_delete (dbf, key)
RGDBM_FILE dbf;
datum key;

datum
rgdbm_firstkey (dbf)
RGDBM_FILE dbf;

datum
rgdbm_nextkey (dbf, key)
RGDBM_FILE dbf;
datum key;

int
rgdbm_reorganize (dbf)
RGDBM_FILE dbf;

void
rgdbm_sync (dbf)
RGDBM_FILE dbf;

int
rgdbm_exists (dbf, key)
RGDBM_FILE dbf;
datum key;

char *
rgdbm_strerror (errno)
rgdbm_error errno;

int
rgdbm_setopt (dbf, option, value, size)
RGDBM_FILE dbf;
int option;
int *value;
int size;

int
rgdbm_fdesc (dbf)
RGDBM_FILE dbf;

int
rgdbm_connect(hostname, dirname, username, flags)
char *hostname, *dirname, *username;
unsigned long flags;

void
rgdbm_disconnect(void)

DESCRIPTION

These are drop-in replacements for the GDBM(3) suite of functions, starting with rgdbm_* instead of gdbm_*. See GDBM(3) for semantics.

The only additional functions over the set listed in GDBM(3) are rgdbm_connect and rgdbm_disconnect.

Each process currently admits only one connection through this library. The connection must be initiated with rgdbm_connect and terminated with rgdbm_disconnect before another connection can be started to the same or a different server.

Each connection supports up to (in the default compilation) 128 open gdbm databases ("tables") at one time. A disconnect does close all the open tables by virtue of killing the server thread which had them open, but they should be closed explicitly otherwise.

The procedure for opening a rgdbm connection is:

int err = rgdbm_connect (hostname, dirname, username, flags);

Hostname is the name of the server. It can contain a ’:port’ suffix, which, if present, will determine the server port to connect to.

dirname is the name of the subdir of the server’s work area in which the gdbm databases will live (it will be made if it doesn’t exist yet).

Username is the user to log in as with the server daemon. It can contain a ’/passwd’ suffix, which, if present, will authenticate the user. The server daemon usually authenticates through its own passwd file, not the system’s. If no password is given the user must be able to login without a password on the server daemon.

Flags specifies the transport encryption type. It may be any of

RGDBM_CRYPTO_SSL_OR_NONE

RGDBM_CRYPTO_SSL

RGDBM_CRYPTO_NONE

RGDBM_CRYPTO_ANY

ANY is currently the same as SSL_OR_NONE. NONE means plain TCP(7). SSL(3) is a secure encrypted protocol requiring server/client certificate interchange. The client will not offer a certification, but the server will, and the client will check it.

The value 0 will be silently mapped to RGDBM_CRYPTO_ANY.

Only the encrypted password (not the plaintext) will ever be sent across the net in any case, and that is sent in encrypted form too. The server only asks the client to prove that it knows the password, not to show it the unencrypted password. It asks for a code phrase to be md5-summed using as input (1) the client’s own encryption of the password to match that stored on the server, and (2) some randomly generated data that the server sends out in the clear. Only server and client have the shared secret knowledge (of the encrypted password) required to make this interchange work. The random data from the server helps avoid replay attacks (with the cycle length of the random data). A man-in-the-middle attack can’t stop the server from requiring a different encryption each time, so the m-i-t-m must pass on the request as-is to the client, and pass the answer back unaltered, and hence m-i-t-m attacks fail against the password. Data is vulnerable, however, unless SSL is used as the transport.

The username can also contain a ’.group’ suffix, before the password if both appear, which denotes which of the groups to which the user belongs should be taken as the user’s group for the session. If the group is not known or the user is not a member of that group as far as the server knows, it is ignored.

It is important that every connection opened is also closed. This is done by:

rgdbm_disconnect ();

See GDBM(3) for details of the other routines. Things to note include:

The typename of the database file handles used is formally RGDBM_FILE, not GDBM_FILE. In fact these names are interchangable, but RGDBM_FILE is guaranteed to be defined even when the gdbm.h header file is not available.

The typename of the rgdbm_errno return is rgdbm_error, not gdbm_error. Again, these typenames are interchangable, but rgdbm_error is guaranteed to be defined even without gdbm.h being available.

The flags supplied to the rgdbm_open routine are formally RGDBM_READER, RGDBM_WRITER, and so on, not GDBM_READER, GDBM_WRITER, etc. The difference is only cosmetic, but the RGDBM_* names are guaranteed to be defined even when gdbm.h is not available.

The rgdbm_setopt options are formally RGDBM_CACHESIZE, RGDBM_FASTMODE, and so on, not GDBM_CACHESIZE, GDBM_FASTMODE, etc. The difference is only cosmetic, but the RGDBM_* names are guaranteed to be defined even when gdbm.h is not available.

The connection is set up under SSL if the compilation supported SSL. If SSL was not available at compile time then the connection is done under TCP and not SSL. The net result is that an SSL-compiled client will not talk to a non-SSL-compiled server, but a non-SSL-compiled client will talk to a SSL-compiled server.

LINKING

This library is accessed by specifying -lrgdbm in the compile line, e.g.:

gcc −o prog prog.c −lrgdbm

If SSL is compiled into the library, it is likely that

−lssl

will also be needed.

FILES

If the server agrees to do SSL, we had better have the Certificate Authority who issued the server’s certificate in

/etc/ssl/certs

If the certificate was self-signed, that means having the server certifcate itself in there, preferably unencrypted (i.e. no key needed to access it). Check on the internet for the

selfsign.html

page for details on how to create a self-signed certificate using openssl.

BUGS

Probably.

SEE ALSO

gdbm(3)

AUTHOR

by Peter T. Breuer. Copyright (C) 2007.

RGDBM is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version.

RGDBM is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with RGDBM; see the file LICENCE. If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

In addition, permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is also granted to process this manual through TeX or other type-setters such as troff and print the results, provided the resulting printed document carries copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual).

REPORTING BUGS

You may contact the original author by:
e-mail: ptb@inv.it.uc3m.es