Commit ba24193a authored by Nick Mathewson's avatar Nick Mathewson 🎨
Browse files

Make doxygen marginally happier


svn:r5208
parent e53f1ccb
......@@ -776,6 +776,9 @@ get_uname(void)
*/
#if defined(USE_PTHREADS)
/** Wraps a an int (*)(void*) function and its argument so we can
* invoke them in a way pthreads would expect.
*/
typedef struct tor_pthread_data_t {
int (*func)(void *);
void *data;
......@@ -961,6 +964,7 @@ tor_gmtime_r(const time_t *timep, struct tm *result)
#endif
#ifdef USE_WIN32_THREADS
/** A generic lock structure for multithreaded builds. */
struct tor_mutex_t {
HANDLE handle;
};
......@@ -1010,6 +1014,7 @@ tor_get_thread_id(void)
return (unsigned long)GetCurrentThreadId();
}
#elif defined(USE_PTHREADS)
/** A generic lock structure for multithreaded builds. */
struct tor_mutex_t {
pthread_mutex_t mutex;
};
......@@ -1050,6 +1055,7 @@ tor_get_thread_id(void)
return r.id;
}
#else
/** A generic lock structure for multithreaded builds. */
struct tor_mutex_t {
int _unused;
};
......
......@@ -236,6 +236,7 @@ void spawn_exit(void);
/* Because we use threads instead of processes on Windows, we need locking on
* Windows. On Unixy platforms, these functions are no-ops. */
typedef struct tor_mutex_t tor_mutex_t;
#ifdef TOR_IS_MULTITHREADED
tor_mutex_t *tor_mutex_new(void);
......
......@@ -29,8 +29,9 @@ const char container_c_id[] = "$Id$";
#define SMARTLIST_DEFAULT_CAPACITY 32
#ifndef FAST_SMARTLIST
/** A resizeable list of pointers, with associated helpful functionality. */
struct smartlist_t {
/** <b>list</b> has enough capacity to store exactly <b>capacity</b> elements
/* <b>list</b> has enough capacity to store exactly <b>capacity</b> elements
* before it needs to be resized. Only the first <b>num_used</b> (\<=
* capacity) elements point to valid data.
*/
......@@ -484,14 +485,14 @@ smartlist_sort_strings(smartlist_t *sl)
smartlist_sort(sl, _compare_string_ptrs);
}
/** Splay-tree implementation of string-to-void* map
*/
/** A node in a strmap_t string-to-void* map. */
typedef struct strmap_entry_t {
SPLAY_ENTRY(strmap_entry_t) node;
char *key;
void *val;
} strmap_entry_t;
/** Splay-tree implementation of string-to-void* map */
struct strmap_t {
SPLAY_HEAD(strmap_tree, strmap_entry_t) head;
};
......
......@@ -91,18 +91,22 @@ static tor_mutex_t **_openssl_mutexes = NULL;
static int _n_openssl_mutexes = -1;
#endif
/** A public key, or a public/private keypair. */
struct crypto_pk_env_t
{
int refs; /* reference counting so we don't have to copy keys */
RSA *key;
};
/** Key and stream information for a stream cipher. */
struct crypto_cipher_env_t
{
char key[CIPHER_KEY_LEN];
aes_cnt_cipher_t *cipher;
};
/** A structure to hold the first half (x, g^x) of a Diffie-Hellman handshake
* while we're waiting for the second.*/
struct crypto_dh_env_t {
DH *dh;
};
......@@ -1220,6 +1224,7 @@ crypto_digest(char *digest, const char *m, size_t len)
return (SHA1((const unsigned char*)m,len,(unsigned char*)digest) == NULL);
}
/** Intermediate information about the digest of a stream of data. */
struct crypto_digest_env_t {
SHA_CTX d;
};
......
......@@ -24,7 +24,8 @@
/** Length of our DH keys. */
#define DH_BYTES (1024/8)
/* DOCDOC */
/** Length of a message digest when encoded in base64 with trailing = signs
* removed. */
#define BASE64_DIGEST_LEN 27
/** Constants used to indicate no padding for public-key encryption */
......
......@@ -35,15 +35,16 @@ const char tortls_c_id[] = "$Id$";
/** How long do identity certificates live? (sec) */
#define IDENTITY_CERT_LIFETIME (365*24*60*60)
typedef struct tor_tls_context_st {
/* DOCDOC */
typedef struct tor_tls_context_t {
SSL_CTX *ctx;
SSL_CTX *client_only_ctx;
} tor_tls_context;
} tor_tls_context_t;
/** Holds a SSL object and its associated data. Members are only
* accessed from within tortls.c.
*/
struct tor_tls_st {
struct tor_tls_t {
SSL *ssl; /**< An OpenSSL SSL object. */
int socket; /**< The underlying file descriptor for this TLS connection. */
enum {
......@@ -63,7 +64,7 @@ static X509* tor_tls_create_certificate(crypto_pk_env_t *rsa,
/** Global tls context. We keep it here because nobody else needs to
* touch it. */
static tor_tls_context *global_tls_context = NULL;
static tor_tls_context_t *global_tls_context = NULL;
/** True iff tor_tls_init() has been called. */
static int tls_library_is_initialized = 0;
......@@ -111,7 +112,7 @@ tls_log_errors(int severity, const char *doing)
* current action as <b>doing</b>.
*/
static int
tor_tls_get_error(tor_tls *tls, int r, int extra,
tor_tls_get_error(tor_tls_t *tls, int r, int extra,
const char *doing, int severity)
{
int err = SSL_get_error(tls->ssl, r);
......@@ -308,7 +309,7 @@ tor_tls_context_new(crypto_pk_env_t *identity,
crypto_pk_env_t *rsa = NULL;
crypto_dh_env_t *dh = NULL;
EVP_PKEY *pkey = NULL;
tor_tls_context *result = NULL;
tor_tls_context_t *result = NULL;
X509 *cert = NULL, *idcert = NULL;
char nn2[128];
int client_only;
......@@ -337,7 +338,7 @@ tor_tls_context_new(crypto_pk_env_t *identity,
}
}
result = tor_malloc(sizeof(tor_tls_context));
result = tor_malloc(sizeof(tor_tls_context_t));
result->ctx = result->client_only_ctx = NULL;
for (client_only=0; client_only <= 1; ++client_only) {
ctx = client_only ? &result->client_only_ctx : &result->ctx;
......@@ -419,10 +420,10 @@ tor_tls_context_new(crypto_pk_env_t *identity,
/** Create a new TLS object from a file descriptor, and a flag to
* determine whether it is functioning as a server.
*/
tor_tls *
tor_tls_t *
tor_tls_new(int sock, int isServer, int use_no_cert)
{
tor_tls *result = tor_malloc(sizeof(tor_tls));
tor_tls_t *result = tor_malloc(sizeof(tor_tls_t));
SSL_CTX *ctx;
tor_assert(global_tls_context); /* make sure somebody made it first */
ctx = use_no_cert ? global_tls_context->client_only_ctx
......@@ -445,7 +446,7 @@ tor_tls_new(int sock, int isServer, int use_no_cert)
/** Return whether this tls initiated the connect (client) or
* received it (server). */
int
tor_tls_is_server(tor_tls *tls)
tor_tls_is_server(tor_tls_t *tls)
{
tor_assert(tls);
return tls->isServer;
......@@ -455,7 +456,7 @@ tor_tls_is_server(tor_tls *tls)
* underlying file descriptor.
*/
void
tor_tls_free(tor_tls *tls)
tor_tls_free(tor_tls_t *tls)
{
tor_assert(tls && tls->ssl);
SSL_free(tls->ssl);
......@@ -469,7 +470,7 @@ tor_tls_free(tor_tls *tls)
* TOR_TLS_CLOSE, TOR_TLS_WANTREAD, or TOR_TLS_WANTWRITE.
*/
int
tor_tls_read(tor_tls *tls, char *cp, size_t len)
tor_tls_read(tor_tls_t *tls, char *cp, size_t len)
{
int r, err;
tor_assert(tls);
......@@ -496,7 +497,7 @@ tor_tls_read(tor_tls *tls, char *cp, size_t len)
* TOR_TLS_WANTREAD, or TOR_TLS_WANTWRITE.
*/
int
tor_tls_write(tor_tls *tls, char *cp, size_t n)
tor_tls_write(tor_tls_t *tls, char *cp, size_t n)
{
int r, err;
tor_assert(tls);
......@@ -528,7 +529,7 @@ tor_tls_write(tor_tls *tls, char *cp, size_t n)
* or TOR_TLS_WANTWRITE.
*/
int
tor_tls_handshake(tor_tls *tls)
tor_tls_handshake(tor_tls_t *tls)
{
int r;
tor_assert(tls);
......@@ -556,7 +557,7 @@ tor_tls_handshake(tor_tls *tls)
* or TOR_TLS_WANTWRITE.
*/
int
tor_tls_shutdown(tor_tls *tls)
tor_tls_shutdown(tor_tls_t *tls)
{
int r, err;
char buf[128];
......@@ -616,7 +617,7 @@ tor_tls_shutdown(tor_tls *tls)
/** Return true iff this TLS connection is authenticated.
*/
int
tor_tls_peer_has_cert(tor_tls *tls)
tor_tls_peer_has_cert(tor_tls_t *tls)
{
X509 *cert;
cert = SSL_get_peer_certificate(tls->ssl);
......@@ -633,7 +634,7 @@ tor_tls_peer_has_cert(tor_tls *tls)
* NUL-terminate. Return 0 on success, -1 on failure.
*/
int
tor_tls_get_peer_cert_nickname(tor_tls *tls, char *buf, size_t buflen)
tor_tls_get_peer_cert_nickname(tor_tls_t *tls, char *buf, size_t buflen)
{
X509 *cert = NULL;
X509_NAME *name = NULL;
......@@ -726,7 +727,7 @@ log_cert_lifetime(X509 *cert, const char *problem)
* 0. Else, return -1.
*/
int
tor_tls_verify(tor_tls *tls, crypto_pk_env_t **identity_key)
tor_tls_verify(tor_tls_t *tls, crypto_pk_env_t **identity_key)
{
X509 *cert = NULL, *id_cert = NULL;
STACK_OF(X509) *chain = NULL;
......@@ -795,7 +796,7 @@ tor_tls_verify(tor_tls *tls, crypto_pk_env_t **identity_key)
* NOTE: you should call tor_tls_verify before tor_tls_check_lifetime.
*/
int
tor_tls_check_lifetime(tor_tls *tls, int tolerance)
tor_tls_check_lifetime(tor_tls_t *tls, int tolerance)
{
time_t now, t;
X509 *cert;
......@@ -830,7 +831,7 @@ tor_tls_check_lifetime(tor_tls *tls, int tolerance)
/** Return the number of bytes available for reading from <b>tls</b>.
*/
int
tor_tls_get_pending_bytes(tor_tls *tls)
tor_tls_get_pending_bytes(tor_tls_t *tls)
{
tor_assert(tls);
#if OPENSSL_VERSION_NUMBER < 0x0090700fl
......@@ -845,14 +846,14 @@ tor_tls_get_pending_bytes(tor_tls *tls)
/** Return the number of bytes read across the underlying socket. */
unsigned long
tor_tls_get_n_bytes_read(tor_tls *tls)
tor_tls_get_n_bytes_read(tor_tls_t *tls)
{
tor_assert(tls);
return BIO_number_read(SSL_get_rbio(tls->ssl));
}
/** Return the number of bytes written across the underlying socket. */
unsigned long
tor_tls_get_n_bytes_written(tor_tls *tls)
tor_tls_get_n_bytes_written(tor_tls_t *tls)
{
tor_assert(tls);
return BIO_number_written(SSL_get_wbio(tls->ssl));
......
......@@ -16,7 +16,7 @@
#include "../common/compat.h"
/* Opaque structure to hold a TLS connection. */
typedef struct tor_tls_st tor_tls;
typedef struct tor_tls_t tor_tls_t;
/* Possible return values for most tor_tls_* functions. */
#define TOR_TLS_ERROR -4
......@@ -28,21 +28,21 @@ typedef struct tor_tls_st tor_tls;
void tor_tls_free_all(void);
int tor_tls_context_new(crypto_pk_env_t *rsa, int isServer,
const char *nickname, unsigned int key_lifetime);
tor_tls *tor_tls_new(int sock, int is_server, int use_no_cert);
int tor_tls_is_server(tor_tls *tls);
void tor_tls_free(tor_tls *tls);
int tor_tls_peer_has_cert(tor_tls *tls);
int tor_tls_get_peer_cert_nickname(tor_tls *tls, char *buf, size_t buflen);
int tor_tls_verify(tor_tls *tls, crypto_pk_env_t **identity);
int tor_tls_check_lifetime(tor_tls *tls, int tolerance);
int tor_tls_read(tor_tls *tls, char *cp, size_t len);
int tor_tls_write(tor_tls *tls, char *cp, size_t n);
int tor_tls_handshake(tor_tls *tls);
int tor_tls_shutdown(tor_tls *tls);
int tor_tls_get_pending_bytes(tor_tls *tls);
unsigned long tor_tls_get_n_bytes_read(tor_tls *tls);
unsigned long tor_tls_get_n_bytes_written(tor_tls *tls);
tor_tls_t *tor_tls_new(int sock, int is_server, int use_no_cert);
int tor_tls_is_server(tor_tls_t *tls);
void tor_tls_free(tor_tls_t *tls);
int tor_tls_peer_has_cert(tor_tls_t *tls);
int tor_tls_get_peer_cert_nickname(tor_tls_t *tls, char *buf, size_t buflen);
int tor_tls_verify(tor_tls_t *tls, crypto_pk_env_t **identity);
int tor_tls_check_lifetime(tor_tls_t *tls, int tolerance);
int tor_tls_read(tor_tls_t *tls, char *cp, size_t len);
int tor_tls_write(tor_tls_t *tls, char *cp, size_t n);
int tor_tls_handshake(tor_tls_t *tls);
int tor_tls_shutdown(tor_tls_t *tls);
int tor_tls_get_pending_bytes(tor_tls_t *tls);
unsigned long tor_tls_get_n_bytes_read(tor_tls_t *tls);
unsigned long tor_tls_get_n_bytes_written(tor_tls_t *tls);
/* Log and abort if there are unhandled TLS errors in OpenSSL's error stack.
*/
......
......@@ -140,6 +140,8 @@ int check_private_dir(const char *dirname, cpd_check_t check);
int write_str_to_file(const char *fname, const char *str, int bin);
int write_bytes_to_file(const char *fname, const char *str, size_t len,
int bin);
/** An ad-hoc type to hold a string of characters and a count; used by
* write_chunks_to_file. */
typedef struct sized_chunk_t {
const char *bytes;
size_t len;
......
......@@ -49,6 +49,7 @@ const char buffers_c_id[] = "$Id$";
#endif
#define BUFFER_MAGIC 0xB0FFF312u
/** A resizeable buffer, optimized for reading and writing. */
struct buf_t {
uint32_t magic; /**< Magic cookie for debugging: Must be set to BUFFER_MAGIC */
char *mem; /**< Storage for data in the buffer */
......@@ -473,7 +474,7 @@ read_to_buf(int s, size_t at_most, buf_t *buf, int *reached_eof)
* -1 on failure.
*/
static INLINE int
read_to_buf_tls_impl(tor_tls *tls, size_t at_most, buf_t *buf, char *next)
read_to_buf_tls_impl(tor_tls_t *tls, size_t at_most, buf_t *buf, char *next)
{
int r;
......@@ -512,7 +513,7 @@ read_to_buf_tls_impl(tor_tls *tls, size_t at_most, buf_t *buf, char *next)
* ready to write -- or vice versa.
*/
int
read_to_buf_tls(tor_tls *tls, size_t at_most, buf_t *buf)
read_to_buf_tls(tor_tls_t *tls, size_t at_most, buf_t *buf)
{
int r;
char *next;
......@@ -634,7 +635,7 @@ flush_buf(int s, buf_t *buf, size_t *buf_flushlen)
* Return the number of bytes written on success, -1 on failure.
*/
static INLINE int
flush_buf_tls_impl(tor_tls *tls, buf_t *buf, size_t sz, size_t *buf_flushlen)
flush_buf_tls_impl(tor_tls_t *tls, buf_t *buf, size_t sz, size_t *buf_flushlen)
{
int r;
......@@ -652,7 +653,7 @@ flush_buf_tls_impl(tor_tls *tls, buf_t *buf, size_t sz, size_t *buf_flushlen)
/** As flush_buf(), but writes data to a TLS connection.
*/
int
flush_buf_tls(tor_tls *tls, buf_t *buf, size_t *buf_flushlen)
flush_buf_tls(tor_tls_t *tls, buf_t *buf, size_t *buf_flushlen)
{
int r;
size_t flushed=0;
......
......@@ -36,7 +36,7 @@ typedef enum config_type_t {
CONFIG_TYPE_OBSOLETE, /**< Obsolete (ignored) option. */
} config_type_t;
/* An abbreviation for a configuration option allowed on the command line */
/** An abbreviation for a configuration option allowed on the command line */
typedef struct config_abbrev_t {
const char *abbreviated;
const char *full;
......@@ -242,6 +242,9 @@ static config_var_description_t state_description[] = {
typedef int (*validate_fn_t)(void*);
/** Information on the keys, value types, key-to-struct-member mappings,
* variable descriptions, validation functions, and abbreviations for a
* configuration or storage format. */
typedef struct {
size_t size;
uint32_t magic;
......@@ -3087,6 +3090,8 @@ options_save_current(void)
return write_configuration_file(get_default_conf_file(), get_options());
}
/** Mapping from a unit name to a multiplier for converting that unit into a
* base unit. */
struct unit_table_t {
const char *unit;
uint64_t multiplier;
......
......@@ -451,6 +451,7 @@ typedef struct {
int num_resolve_failures;
} addressmap_entry_t;
/** Entry for mapping addresses to which virtual address we mapped them to. */
typedef struct {
char *ipv4_address;
char *hostname_address;
......@@ -1728,7 +1729,7 @@ connection_ap_can_use_exit(connection_t *conn, routerinfo_t *exit)
/** A helper function for socks_policy_permits_address() below.
*
* Parse options->SocksPolicy in the same way that the exit policy
* is parsed, and put the processed version in &socks_policy.
* is parsed, and put the processed version in socks_policy.
* Ignore port specifiers.
*/
void
......@@ -1788,10 +1789,10 @@ set_exit_redirects(smartlist_t *lst)
}
/** If address is of the form "y.onion" with a well-formed handle y:
* Put a \code{'\0'} after y, lower-case it, and return ONION_HOSTNAME.
* Put a NUL after y, lower-case it, and return ONION_HOSTNAME.
*
* If address is of the form "y.exit":
* Put a \code{'\0'} after y and return EXIT_HOSTNAME.
* Put a NUL after y and return EXIT_HOSTNAME.
*
* Otherwise:
* Return NORMAL_HOSTNAME and change nothing.
......
......@@ -379,7 +379,7 @@ connection_tls_start_handshake(connection_t *conn, int receiving)
{
conn->state = OR_CONN_STATE_HANDSHAKING;
conn->tls = tor_tls_new(conn->s, receiving, 0);
if (!conn->tls) {
if (!conn->tls)
log_fn(LOG_WARN,"tor_tls_new failed. Closing.");
return -1;
}
......
......@@ -78,13 +78,19 @@ parse_authdir_policy(void)
}
}
/** A member of fingerprint_list: maps a name to a fingerprint.
**/
typedef struct fingerprint_entry_t {
char *nickname;
char *nickname; /**< The name of a router (if this fingerprint is bound to a
* name); the string "!reject" (if this fingerprint should
* always be rejected); or the string "!invalid" (if this
* fingerprint should be accepted but never marked as
* valid. */
char *fingerprint; /**< Stored as HEX_DIGEST_LEN characters, followed by a NUL */
} fingerprint_entry_t;
/** List of nickname-\>identity fingerprint mappings for all the routers
* that we recognize. Used to prevent Sybil attacks. */
* that we name. Used to prevent router impersonation. */
/* Should be static; exposed for testing */
smartlist_t *fingerprint_list = NULL;
......
......@@ -13,6 +13,8 @@ const char onion_c_id[] = "$Id$";
#include "or.h"
/** Type for a linked list of circuits that are waiting for a free CPU worker
* to process a waiting onion handshake. */
typedef struct onion_queue_t {
circuit_t *circ;
time_t when_added;
......
......@@ -644,7 +644,7 @@ struct connection_t {
char *chosen_exit_name;
/* Used only by OR connections: */
tor_tls *tls; /**< TLS connection state (OR only.) */
tor_tls_t *tls; /**< TLS connection state (OR only.) */
uint16_t next_circ_id; /**< Which circ_id do we try to use next on
* this connection? This is always in the
* range 0..1<<15-1. (OR only.)*/
......@@ -1100,6 +1100,8 @@ typedef struct circuit_t circuit_t;
#define ALLOW_UNVERIFIED_RENDEZVOUS 8
#define ALLOW_UNVERIFIED_INTRODUCTION 16
/** An entry specifying a set of addresses and ports that should be remapped
* to another address and port before exiting this exit node. */
typedef struct exit_redirect_t {
uint32_t addr;
uint32_t mask;
......@@ -1111,6 +1113,7 @@ typedef struct exit_redirect_t {
unsigned is_redirect:1;
} exit_redirect_t;
/** A linked list of lines in a config file. */
typedef struct config_line_t {
char *key;
char *value;
......@@ -1341,10 +1344,10 @@ size_t buf_capacity(const buf_t *buf);
const char *_buf_peek_raw_buffer(const buf_t *buf);
int read_to_buf(int s, size_t at_most, buf_t *buf, int *reached_eof);
int read_to_buf_tls(tor_tls *tls, size_t at_most, buf_t *buf);
int read_to_buf_tls(tor_tls_t *tls, size_t at_most, buf_t *buf);
int flush_buf(int s, buf_t *buf, size_t *buf_flushlen);
int flush_buf_tls(tor_tls *tls, buf_t *buf, size_t *buf_flushlen);
int flush_buf_tls(tor_tls_t *tls, buf_t *buf, size_t *buf_flushlen);
int write_to_buf(const char *string, size_t string_len, buf_t *buf);
int fetch_from_buf(char *string, size_t string_len, buf_t *buf);
......@@ -1965,10 +1968,11 @@ int rend_encode_service_descriptor(rend_service_descriptor_t *desc,
rend_service_descriptor_t *rend_parse_service_descriptor(const char *str, size_t len);
int rend_get_service_id(crypto_pk_env_t *pk, char *out);
/** A cached rendezvous descriptor. */
typedef struct rend_cache_entry_t {
size_t len; /* Length of desc */
time_t received; /* When was the descriptor received? */
char *desc; /* Service descriptor */
size_t len; /** Length of <b>desc</b> */
time_t received; /** When was the descriptor received? */
char *desc; /** Service descriptor */
rend_service_descriptor_t *parsed; /* Parsed value of 'desc' */
} rend_cache_entry_t;
......
......@@ -1175,3 +1175,4 @@ router_free_all(void)
smartlist_free(warned_nonexistent_family);
}
}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment