This file is indexed.

/usr/include/avis/keys.h is in libavis-dev 1.2.4-8.

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
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
/*
 *  Avis Elvin client library for C.
 *
 *  Copyright (C) 2008 Matthew Phillips <avis@mattp.name>
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of version 3 of the GNU Lesser General
 *  Public License as published by the Free Software Foundation.
 *
 *  This program 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 this program. If not, see <http://www.gnu.org/licenses/>.
 */
/** \file
 * Secure messaging keys.
 */
#ifndef ELVIN_KEYS_H
#define ELVIN_KEYS_H

#include <string.h>

#include <avis/defs.h>
#include <avis/stdtypes.h>
#include <avis/arrays.h>

/**
 * A pointer to an immutable empty Keys collection.
 */
#define EMPTY_KEYS (&_empty_keys)

/**
 * A key value used to secure notifications. A key is simply an
 * immutable block of bytes.
 * <p>
 * Elvin defines two types of key, <em>private</em> (or <em>raw</em>)
 * keys, and <em>public</em> (or <em>prime</em>) keys. A public
 * key is a one-way hash (e.g. using SHA-1) of a private key. A
 * private key may be any random data, or simply a password. A private
 * key is defined to match a public key if the corresponding hash of
 * its data matches the public key's data, e.g. if
 * <code>sha1 (privateKey.data) == publicKey.data</code>.
 * <p>
 * Note that this is not a public key system in the RSA sense but
 * that, like RSA, public keys can be shared in the open without loss
 * of security.
 */
typedef struct
{
  uint8_t * data;
  uint32_t  length;
} Key;

/**
 * A key collection used to secure notifications. A key collection
 * contains zero or more mappings from a KeyScheme to the Keys registered
 * for that scheme.
 * <p>
 * See also section 7.4 of the client protocol spec.
 * <p>
 * <h3>Ownership</h3>
 *
 * Once added to a Keys collection, a Key's data is considered to be
 * owned by the key set and will be freed when elvin_keys_free() is
 * invoked. Thus, if you wish to add the same key more than once you
 * should elvin_key_copy() it first.
 * <p>
 * Similarly, once a Keys instance has been used in a successful call
 * to an Elvin client connection (e.g. elvin_open_with_keys() or
 * elvin_subscribe_with_keys()), the connection will take ownership of
 * that key collection and free it when appropriate.
 * <p>
 * Once in use, key collections should be treated as immutable
 * and never be modified directly.
 */
typedef struct
{
  ArrayList keys [3];
} Keys;

struct KeyScheme_t;

/**
 * Defines an Elvin security scheme. A key scheme
 * defines a mode of sending or receiving notifications securely.
 *
 * <h3>The Producer Scheme</h3>
 *
 * In the producer scheme, consumers of notifications ensure that a
 * notification producer is known to them. The producer uses the
 * private key, and consumers use the public key. If the producer
 * keeps its private key secure, consumers can be assured they are
 * receiving notifications from a trusted producer.
 *
 * <h3>The Consumer Scheme</h3>
 *
 * In the consumer scheme, producers of notifications ensure that a
 * notification consumer is known to them, i.e. the producer controls
 * who can receive its notifications. In this scheme -- the reverse of
 * the producer scheme -- the consumer uses the private key, and
 * producers use the public key. If the consumer keeps its private key
 * secure, then the producer can be assured that only the trusted
 * consumer can receive its notifications.
 *
 * <h3>The Dual Scheme</h3>
 *
 * The dual scheme combines both the producer and consumer schemes, so
 * that both ends can send and receive securely. Typically both ends
 * exchange public keys, and each end then emits notifications with
 * both its private key and the public key(s) of its intended
 * consumer(s) attached. Similarly, each end would subscribe using its
 * private key and the public key(s) of its intended producer(s).
 *
 * <h3>Supported Schemes</h3>
 *
 * Avis currently supports just the SHA-1 secure hash as defined in
 * version 4.0 of the Elvin protocol. As such, three schemes are
 * available: KEY_SCHEME_SHA1_DUAL, KEY_SCHEME_SHA1_CONSUMER and
 * KEY_SCHEME_SHA1_PRODUCER.
 */
typedef struct KeyScheme_t * KeyScheme;

AVIS_PUBLIC_DATA struct KeyScheme_t _KEY_SCHEME_SHA1_DUAL;
AVIS_PUBLIC_DATA struct KeyScheme_t _KEY_SCHEME_SHA1_PRODUCER;
AVIS_PUBLIC_DATA struct KeyScheme_t _KEY_SCHEME_SHA1_CONSUMER;

/**
 * The SHA-1 dual key scheme.
 *
 * @see KeyScheme
 */
#define KEY_SCHEME_SHA1_DUAL (&_KEY_SCHEME_SHA1_DUAL)

/**
 * The SHA-1 producer key scheme.
 *
 * @see KeyScheme
 */
#define KEY_SCHEME_SHA1_PRODUCER (&_KEY_SCHEME_SHA1_PRODUCER)

/**
 * The SHA-1 consumer key scheme.
 *
 * @see KeyScheme
 */
#define KEY_SCHEME_SHA1_CONSUMER (&_KEY_SCHEME_SHA1_CONSUMER)

AVIS_PUBLIC_DATA Keys _empty_keys;

/**
 * Create an empty keys collection.
 *
 * @see elvin_keys_free()
 * @see elvin_keys_destroy()
 */
#define elvin_keys_create() \
  (elvin_keys_init ((Keys *)avis_emalloc (sizeof (Keys))))

/**
 * Macro to destroy and NULL a keys collection. Handles NULL and EMPTY_KEYS
 * values.
 *
 * @see elvin_keys_free()
 */
#define elvin_keys_destroy(keys) \
  if ((keys) != EMPTY_KEYS && (keys) != NULL) \
  {\
    elvin_keys_free (keys); free (keys); \
  }\
  keys = NULL;\

/**
 * Initialise a keys collection to empty.
 *
 * @see elvin_keys_create()
 */
AVIS_PUBLIC
Keys *elvin_keys_init (Keys *keys);

/**
 * Copy a key collection.
 *
 * @param keys The keys to copy.
 *
 * @return An independent copy of the source key collection.
 *
 * @see elvin_keys_free()
 * @see elvin_key_copy()
 */
AVIS_PUBLIC
Keys *elvin_keys_copy (Keys *keys);

/**
 * Free any resources held by key collection. This includes any key data
 * blocks referenced.
 *
 * @see Keys
 * @see elvin_keys_init()
 */
AVIS_PUBLIC
void elvin_keys_free (Keys *keys);

/**
 * Test if two key collections are logically equal.
 */
AVIS_PUBLIC
bool elvin_keys_equal (Keys *keys1, Keys *keys2);

/**
 * Add a key to the collection in a given security scheme.
 *
 * @param keys The keys to add to.
 * @param scheme the security scheme to associate the key with.
 * @param key The key to add. The key becomes owned by the collection and
 * will be freed when the collection is.
 * @return True if the key was added, false if the collection was not modified
 * (the key was already in the collection).
 *
 * @see elvin_keys_add_dual_consumer()
 * @see elvin_keys_add_dual_producer()
 */
AVIS_PUBLIC
bool elvin_keys_add (Keys *keys, KeyScheme scheme, Key key);

/**
 * Add a key to the collection as a consumer key in a given dual key security
 * scheme.
 *
 * @param keys The keys to add to.
 * @param scheme the security scheme to associate the key with. This must
 * be a dual scheme (e.g. KEY_SCHEME_SHA1_DUAL).
 * @param key The key to add. The key becomes owned by the collection and
 * will be freed when the collection is.
 * @return True if the key was added, false if the collection was not modified
 * (the key was already in the collection, or the scheme is not a dual key
 * scheme).
 *
 * @see elvin_keys_add()
 * @see elvin_keys_add_dual_producer()
 */
AVIS_PUBLIC
bool elvin_keys_add_dual_consumer (Keys *keys, KeyScheme scheme, Key key);

/**
 * Add a key to the collection as a producer key in a given dual key security
 * scheme.
 *
 * @param keys The keys to add to.
 * @param scheme the security scheme to associate the key with. This must
 * be a dual scheme (e.g. KEY_SCHEME_SHA1_DUAL).
 * @param key The key to add. The key becomes owned by the collection and
 * will be freed when the collection is.
 * @return True if the key was added, false if the collection was not modified
 * (the key was already in the collection, or the scheme is not a dual key
 * scheme).
 *
 * @see elvin_keys_add()
 * @see elvin_keys_add_dual_consumer()
 */
AVIS_PUBLIC
bool elvin_keys_add_dual_producer (Keys *keys, KeyScheme scheme, Key key);

/**
 * Free the data block associated with a key.
 *
 * @see elvin_key_create_from_string()
 * @see elvin_key_create_from_data()
 */
AVIS_PUBLIC
void elvin_key_free (Key key);

/**
 * Copy a key.
 *
 * @see elvin_key_create_from_data()
 */
#define elvin_key_copy(key) \
  (elvin_key_create_from_data ((key).data, (key).length))

/**
 * Create a key from a character string.
 *
 * @param str The string to use as the data block.
 *
 * @see elvin_key_create_from_data()
 * @see elvin_key_free()
 */
AVIS_PUBLIC
Key elvin_key_create_from_string (const char *str);

/**
 * Create a key from a block of data.
 *
 * @param data The data block.
 * @param length The length of the data block.
 *
 * @see elvin_key_create_from_string()
 * @see elvin_key_create_public()
 * @see elvin_key_free()
 */
AVIS_PUBLIC
Key elvin_key_create_from_data (const uint8_t *data, size_t length);

/**
 * Create a public key from a private key using a given scheme's hash.
 *
 * @param private_key The private key block.
 * @param scheme The security scheme to use.
 *
 * @return The public key. public_key.data = hash (private_key.data)
 *
 * @see elvin_key_create_from_data()
 * @see elvin_key_free()
 */
AVIS_PUBLIC
Key elvin_key_create_public (Key private_key, KeyScheme scheme);

/**
 * Test if two keys are equal.
 */
AVIS_PUBLIC
bool elvin_key_equal (Key key1, Key key2);

#endif /* ELVIN_KEYS_H */