Tor  0.4.5.0-alpha-dev
hs_cache.h
Go to the documentation of this file.
1 /* Copyright (c) 2016-2020, The Tor Project, Inc. */
2 /* See LICENSE for licensing information */
3 
4 /**
5  * \file hs_cache.h
6  * \brief Header file for hs_cache.c
7  **/
8 
9 #ifndef TOR_HS_CACHE_H
10 #define TOR_HS_CACHE_H
11 
12 #include <stdint.h>
13 
14 #include "feature/hs/hs_common.h"
18 
20 
21 /** This is the maximum time an introduction point state object can stay in the
22  * client cache in seconds (2 mins or 120 seconds). */
23 #define HS_CACHE_CLIENT_INTRO_STATE_MAX_AGE (2 * 60)
24 
25 /** Introduction point state. */
26 typedef struct hs_cache_intro_state_t {
27  /** When this entry was created and put in the cache. */
28  time_t created_ts;
29 
30  /** Did it suffered a generic error? */
31  unsigned int error : 1;
32 
33  /** Did it timed out? */
34  unsigned int timed_out : 1;
35 
36  /** How many times we tried to reached it and it was unreachable. */
39 
41  /** Contains hs_cache_intro_state_t object indexed by introduction point
42  * authentication key. */
43  digest256map_t *intro_points;
45 
46 /** Descriptor representation on the directory side which is a subset of
47  * information that the HSDir can decode and serve it. */
48 typedef struct hs_cache_dir_descriptor_t {
49  /** This object is indexed using the blinded pubkey located in the plaintext
50  * data which is populated only once the descriptor has been successfully
51  * decoded and validated. This simply points to that pubkey. */
52  const uint8_t *key;
53 
54  /** When does this entry has been created. Used to expire entries. */
55  time_t created_ts;
56 
57  /** Descriptor plaintext information. Obviously, we can't decrypt the
58  * encrypted part of the descriptor. */
60 
61  /** Encoded descriptor which is basically in text form. It's a NUL terminated
62  * string thus safe to strlen(). */
63  char *encoded_desc;
65 
66 /* Public API */
67 
68 void hs_cache_init(void);
69 void hs_cache_free_all(void);
70 void hs_cache_clean_as_dir(time_t now);
71 size_t hs_cache_handle_oom(time_t now, size_t min_remove_bytes);
72 
73 unsigned int hs_cache_get_max_descriptor_size(void);
74 
75 /* Store and Lookup function. They are version agnostic that is depending on
76  * the requested version of the descriptor, it will be re-routed to the
77  * right function. */
78 int hs_cache_store_as_dir(const char *desc);
79 int hs_cache_lookup_as_dir(uint32_t version, const char *query,
80  const char **desc_out);
81 
82 const hs_descriptor_t *
84 const char *
87  const struct ed25519_public_key_t *identity_pk);
88 void hs_cache_remove_as_client(const struct ed25519_public_key_t *key);
89 void hs_cache_clean_as_client(time_t now);
90 void hs_cache_purge_as_client(void);
91 
92 /* Client failure cache. */
94  const struct ed25519_public_key_t *service_pk,
95  const struct ed25519_public_key_t *auth_key,
96  rend_intro_point_failure_t failure);
98  const struct ed25519_public_key_t *service_pk,
99  const struct ed25519_public_key_t *auth_key);
100 void hs_cache_client_intro_state_clean(time_t now);
102 
103 bool hs_cache_client_new_auth_parse(const ed25519_public_key_t *service_pk);
104 
105 #ifdef HS_CACHE_PRIVATE
107 
108 /** Represents a locally cached HS descriptor on a hidden service client. */
109 typedef struct hs_cache_client_descriptor_t {
110  /** This object is indexed using the service identity public key */
111  struct ed25519_public_key_t key;
112 
113  /** When will this entry expire? We expire cached client descriptors in the
114  * start of the next time period, since that's when clients need to start
115  * using the next blinded key of the service. */
116  time_t expiration_ts;
117 
118  /** The cached decoded descriptor, this object is the owner. This can be
119  * NULL if the descriptor couldn't be decoded due to missing or bad client
120  * authorization. It can be decoded later from the encoded_desc object if
121  * the proper client authorization is given tor. */
122  hs_descriptor_t *desc;
123 
124  /** Encoded descriptor in string form. Can't be NULL. */
125  char *encoded_desc;
126 } hs_cache_client_descriptor_t;
127 
128 STATIC size_t cache_clean_v3_as_dir(time_t now, time_t global_cutoff);
129 
130 STATIC hs_cache_client_descriptor_t *
131 lookup_v3_desc_as_client(const uint8_t *key);
132 
133 #endif /* defined(HS_CACHE_PRIVATE) */
134 
135 #endif /* !defined(TOR_HS_CACHE_H) */
hs_cache_client_intro_state_purge
void hs_cache_client_intro_state_purge(void)
Definition: hs_cache.c:1009
hs_cache_dir_descriptor_t::key
const uint8_t * key
Definition: hs_cache.h:52
hs_cache_store_as_client
hs_desc_decode_status_t hs_cache_store_as_client(const char *desc_str, const ed25519_public_key_t *identity_pk)
Definition: hs_cache.c:860
hs_cache_client_intro_state_note
void hs_cache_client_intro_state_note(const ed25519_public_key_t *service_pk, const ed25519_public_key_t *auth_key, rend_intro_point_failure_t failure)
Definition: hs_cache.c:957
hs_desc_decode_status_t
hs_desc_decode_status_t
Definition: hs_descriptor.h:74
hs_cache_get_max_descriptor_size
unsigned int hs_cache_get_max_descriptor_size(void)
Definition: hs_cache.c:1111
hs_cache_intro_state_t
Definition: hs_cache.h:26
hs_cache_client_intro_state_clean
void hs_cache_client_intro_state_clean(time_t now)
Definition: hs_cache.c:989
hs_cache_clean_as_client
void hs_cache_clean_as_client(time_t now)
Definition: hs_cache.c:928
hs_cache_dir_descriptor_t::plaintext_data
hs_desc_plaintext_data_t * plaintext_data
Definition: hs_cache.h:59
hs_cache_handle_oom
size_t hs_cache_handle_oom(time_t now, size_t min_remove_bytes)
Definition: hs_cache.c:1060
torcert.h
Header for torcert.c.
hs_cache_lookup_as_dir
int hs_cache_lookup_as_dir(uint32_t version, const char *query, const char **desc_out)
Definition: hs_cache.c:311
hs_cache_client_intro_state_t::intro_points
digest256map_t * intro_points
Definition: hs_cache.h:43
ed25519_public_key_t
Definition: crypto_ed25519.h:23
hs_cache_lookup_as_client
const hs_descriptor_t * hs_cache_lookup_as_client(const ed25519_public_key_t *key)
Definition: hs_cache.c:829
hs_cache_remove_as_client
void hs_cache_remove_as_client(const ed25519_public_key_t *key)
Definition: hs_cache.c:896
hs_desc_plaintext_data_t
Definition: hs_descriptor.h:193
hs_cache_dir_descriptor_t
Definition: hs_cache.h:48
hs_descriptor_t
Definition: hs_descriptor.h:226
cache_clean_v3_as_dir
STATIC size_t cache_clean_v3_as_dir(time_t now, time_t global_cutoff)
Definition: hs_cache.c:225
hs_cache_intro_state_t::timed_out
unsigned int timed_out
Definition: hs_cache.h:34
hs_cache_intro_state_t::error
unsigned int error
Definition: hs_cache.h:31
hs_cache_purge_as_client
void hs_cache_purge_as_client(void)
Definition: hs_cache.c:939
hs_cache_init
void hs_cache_init(void)
Definition: hs_cache.c:1120
hs_common.h
Header file containing common data for the whole HS subsytem.
lookup_v3_desc_as_client
STATIC hs_cache_client_descriptor_t * lookup_v3_desc_as_client(const uint8_t *key)
Definition: hs_cache.c:400
hs_cache_store_as_dir
int hs_cache_store_as_dir(const char *desc)
Definition: hs_cache.c:274
hs_cache_dir_descriptor_t::encoded_desc
char * encoded_desc
Definition: hs_cache.h:63
hs_cache_client_intro_state_find
const hs_cache_intro_state_t * hs_cache_client_intro_state_find(const ed25519_public_key_t *service_pk, const ed25519_public_key_t *auth_key)
Definition: hs_cache.c:979
hs_cache_intro_state_t::unreachable_count
uint32_t unreachable_count
Definition: hs_cache.h:37
hs_cache_client_intro_state_t
Definition: hs_cache.h:40
hs_cache_clean_as_dir
void hs_cache_clean_as_dir(time_t now)
Definition: hs_cache.c:332
STATIC
#define STATIC
Definition: testsupport.h:32
crypto_ed25519.h
Header for crypto_ed25519.c.
hs_descriptor.h
Header file for hs_descriptor.c.
rendcommon.h
Header file for rendcommon.c.
hs_cache_dir_descriptor_t::created_ts
time_t created_ts
Definition: hs_cache.h:55
hs_cache_lookup_encoded_as_client
const char * hs_cache_lookup_encoded_as_client(const ed25519_public_key_t *key)
Definition: hs_cache.c:809
hs_cache_free_all
void hs_cache_free_all(void)
Definition: hs_cache.c:1135
hs_cache_intro_state_t::created_ts
time_t created_ts
Definition: hs_cache.h:28