blob: 6b0443c8b27e9c48d44b055a9ed0f7f31eba5bf8 [file] [log] [blame]
Alexander Afanasyev6b997c52011-08-08 12:55:25 -07001/* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */
2/*
3 * Copyright (c) 2011 University of California, Los Angeles
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License version 2 as
7 * published by the Free Software Foundation;
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 *
18 * Author: Ilya Moiseenko <iliamo@cs.ucla.edu>
19 */
20
Ilya Moiseenkoc115fba2011-08-01 10:53:18 -070021/*
22 * ccn_ccn.h
23 * Abstraction
24 *
25 * Created by Ilya on 7/29/11.
26 * Copyright 2011 __MyCompanyName__. All rights reserved.
27 *
28 */
29
30#ifndef CCN_CCN_DEFINED
31#define CCN_CCN_DEFINED
32
33#include <stdint.h>
34#include "ccn_coding.h"
35#include "ccn_charbuf.h"
36#include "ccn_indexbuf.h"
37
Ilya Moiseenko7e254b72011-08-04 19:06:10 -070038/***********************************
39 * Writing Names
40 * Names for interests are constructed in charbufs using
41 * the following routines.
42 */
43
44/*
45 * ccn_name_init: reset charbuf to represent an empty Name in binary format
46 * Return value is 0, or -1 for error.
47 */
48int ccn_name_init(struct ccn_charbuf *c);
49
50/*
51 * ccn_name_append: add a Component to a Name
52 * The component is an arbitrary string of n octets, no escaping required.
53 * Return value is 0, or -1 for error.
54 */
55int ccn_name_append(struct ccn_charbuf *c, const void *component, size_t n);
56
57/*
58 * ccn_name_append_str: add a Component that is a \0 terminated string.
59 * The component added is the bytes of the string without the \0.
60 * This function is convenient for those applications that construct
61 * component names from simple strings.
62 * Return value is 0, or -1 for error
63 */
64int ccn_name_append_str(struct ccn_charbuf *c, const char *s);
65
66/*
67 * ccn_name_append_components: add sequence of ccnb-encoded Components
68 * to a ccnb-encoded Name
69 * start and stop are offsets from ccnb
70 * Return value is 0, or -1 for obvious error
71 */
72int ccn_name_append_components(struct ccn_charbuf *c,
73 const unsigned char *ccnb,
74 size_t start, size_t stop);
75
Ilya Moiseenkoc115fba2011-08-01 10:53:18 -070076enum ccn_marker {
Ilya Moiseenko7e254b72011-08-04 19:06:10 -070077 CCN_MARKER_NONE = -1,
78 CCN_MARKER_SEQNUM = 0x00, /**< consecutive block sequence numbers */
79 CCN_MARKER_CONTROL = 0xC1, /**< commands, etc. */
80 CCN_MARKER_OSEQNUM = 0xF8, /**< deprecated */
81 CCN_MARKER_BLKID = 0xFB, /**< nonconsecutive block ids */
82 CCN_MARKER_VERSION = 0xFD /**< timestamp-based versioning */
Ilya Moiseenkoc115fba2011-08-01 10:53:18 -070083};
84
Ilya Moiseenko7e254b72011-08-04 19:06:10 -070085/*
86 * ccn_name_append_numeric: add binary Component to ccnb-encoded Name
87 * These are special components used for marking versions, fragments, etc.
88 * Return value is 0, or -1 for error
89 * see doc/technical/NameConventions.html
90 */
91int ccn_name_append_numeric(struct ccn_charbuf *c,
92 enum ccn_marker tag, uintmax_t value);
93
94/*
95 * ccn_name_append_nonce: add nonce Component to ccnb-encoded Name
96 * Uses %C1.N.n marker.
97 * see doc/technical/NameConventions.html
98 */
99int ccn_name_append_nonce(struct ccn_charbuf *c);
100
101/*
102 * ccn_name_split: find Component boundaries in a ccnb-encoded Name
103 * Thin veneer over ccn_parse_Name().
104 * returns -1 for error, otherwise the number of Components
105 * components arg may be NULL to just do a validity check
106 */
107int ccn_name_split(const struct ccn_charbuf *c,
108 struct ccn_indexbuf* components);
109
110/*
111 * ccn_name_chop: Chop the name down to n components.
112 * returns -1 for error, otherwise the new number of Components
113 * components arg may be NULL; if provided it must be consistent with
114 * some prefix of the name, and is updated accordingly.
115 * n may be negative to say how many components to remove instead of how
116 * many to leave, e.g. -1 will remove just the last component.
117 */
118int ccn_name_chop(struct ccn_charbuf *c,
119 struct ccn_indexbuf* components, int n);
120
121
122
Ilya Moiseenkoc115fba2011-08-01 10:53:18 -0700123
124/*********** Interest parsing ***********/
125
126/*
127 * The parse of an interest results in an array of offsets into the
128 * wire representation, with the start and end of each major element and
129 * a few of the inportant sub-elements. The following enum allows those
130 * array items to be referred to symbolically. The *_B_* indices correspond
131 * to beginning offsets and the *_E_* indices correspond to ending offsets.
132 * An omitted element has its beginning and ending offset equal to each other.
133 * Normally these offsets will end up in non-decreasing order.
134 * Some aliasing tricks may be played here, e.g. since
135 * offset[CCN_PI_E_ComponentLast] is always equal to
136 * offset[CCN_PI_E_LastPrefixComponent],
137 * we may define CCN_PI_E_ComponentLast = CCN_PI_E_LastPrefixComponent.
138 * However, code should not rely on that,
139 * since it may change from time to time as the
140 * interest schema evolves.
141 */
142enum ccn_parsed_interest_offsetid {
143 CCN_PI_B_Name,
144 CCN_PI_B_Component0,
145 CCN_PI_B_LastPrefixComponent,
146 CCN_PI_E_LastPrefixComponent,
147 CCN_PI_E_ComponentLast = CCN_PI_E_LastPrefixComponent,
148 CCN_PI_E_Name,
149 CCN_PI_B_MinSuffixComponents,
150 CCN_PI_E_MinSuffixComponents,
151 CCN_PI_B_MaxSuffixComponents,
152 CCN_PI_E_MaxSuffixComponents,
153 CCN_PI_B_PublisherID, // XXX - rename
154 CCN_PI_B_PublisherIDKeyDigest,
155 CCN_PI_E_PublisherIDKeyDigest,
156 CCN_PI_E_PublisherID,
157 CCN_PI_B_Exclude,
158 CCN_PI_E_Exclude,
159 CCN_PI_B_ChildSelector,
160 CCN_PI_E_ChildSelector,
161 CCN_PI_B_AnswerOriginKind,
162 CCN_PI_E_AnswerOriginKind,
163 CCN_PI_B_Scope,
164 CCN_PI_E_Scope,
165 CCN_PI_B_InterestLifetime,
166 CCN_PI_E_InterestLifetime,
167 CCN_PI_B_Nonce,
168 CCN_PI_E_Nonce,
169 CCN_PI_B_OTHER,
170 CCN_PI_E_OTHER,
171 CCN_PI_E
172};
173
174
175struct ccn_parsed_interest {
176 int magic;
177 int prefix_comps;
178 int min_suffix_comps;
179 int max_suffix_comps;
180 int orderpref;
181 int answerfrom;
182 int scope;
183 unsigned short offset[CCN_PI_E+1];
184};
185
186/*
187 * Bitmasks for AnswerOriginKind
188 */
189#define CCN_AOK_CS 0x1 /* Answer from content store */
190#define CCN_AOK_NEW 0x2 /* OK to produce new content */
191#define CCN_AOK_DEFAULT (CCN_AOK_CS | CCN_AOK_NEW)
192#define CCN_AOK_STALE 0x4 /* OK to answer with stale data */
193#define CCN_AOK_EXPIRE 0x10 /* Mark as stale (must have Scope 0) */
194
195/***********************************
196 * Low-level binary formatting
197 */
198
199/*
200 * Append a ccnb start marker
201 *
202 * This forms the basic building block of ccnb-encoded data.
203 * c is the buffer to append to.
204 * Return value is 0, or -1 for error.
205 */
206int ccn_charbuf_append_tt(struct ccn_charbuf *c, size_t val, enum ccn_tt tt);
207
208/**
209 * Append a CCN_CLOSE
210 *
211 * Use this to close off an element in ccnb-encoded data.
212 * @param c is the buffer to append to.
213 * @returns 0 for success or -1 for error.
214 */
215int ccn_charbuf_append_closer(struct ccn_charbuf *c);
216
217/***********************************
218 * Slightly higher level binary formatting
219 */
220
221/*
222 * Append a non-negative integer as a UDATA.
223 */
224int ccnb_append_number(struct ccn_charbuf *c, int nni);
225
226/*
227 * Append a binary timestamp
228 * as a BLOB using the ccn binary Timestamp representation (12-bit fraction).
229 */
230int ccnb_append_timestamp_blob(struct ccn_charbuf *c,
231 enum ccn_marker marker,
232 long long secs, int nsecs);
233
234/*
235 * Append a binary timestamp, using the current time.
236 */
237int ccnb_append_now_blob(struct ccn_charbuf *c, enum ccn_marker marker);
238
239/*
240 * Append a start-of-element marker.
241 */
242int ccnb_element_begin(struct ccn_charbuf *c, enum ccn_dtag dtag);
243
244/*
245 * Append an end-of-element marker.
246 * This is the same as ccn_charbuf_append_closer()
247 */
248int ccnb_element_end(struct ccn_charbuf *c);
249
250/*
251 * Append a tagged BLOB
252 */
253int ccnb_append_tagged_blob(struct ccn_charbuf *c, enum ccn_dtag dtag,
254 const void *data, size_t size);
255
256/*
257 * Append a tagged UDATA string, with printf-style formatting
258 */
259int ccnb_tagged_putf(struct ccn_charbuf *c, enum ccn_dtag dtag,
260 const char *fmt, ...);
261
262
263
264/***********************************
265 * Binary decoding
266 * These routines require that the whole binary object be buffered.
267 */
268
269struct ccn_buf_decoder {
270 struct ccn_skeleton_decoder decoder;
271 const unsigned char *buf;
272 size_t size;
273};
274
275struct ccn_buf_decoder *ccn_buf_decoder_start(struct ccn_buf_decoder *d,
276 const unsigned char *buf, size_t size);
277
278void ccn_buf_advance(struct ccn_buf_decoder *d);
279int ccn_buf_advance_past_element(struct ccn_buf_decoder *d);
280
281/* The match routines return a boolean - true for match */
282int ccn_buf_match_dtag(struct ccn_buf_decoder *d, enum ccn_dtag dtag);
283
284int ccn_buf_match_some_dtag(struct ccn_buf_decoder *d);
285
286int ccn_buf_match_some_blob(struct ccn_buf_decoder *d);
287int ccn_buf_match_blob(struct ccn_buf_decoder *d,
288 const unsigned char **bufp, size_t *sizep);
289
290int ccn_buf_match_udata(struct ccn_buf_decoder *d, const char *s);
291
292int ccn_buf_match_attr(struct ccn_buf_decoder *d, const char *s);
293
294/* On error, the parse routines enter an error state and return a negative value. */
295/*int ccn_parse_required_tagged_BLOB(struct ccn_buf_decoder *d,
296 enum ccn_dtag dtag,
297 int minlen, int maxlen);
298int ccn_parse_optional_tagged_BLOB(struct ccn_buf_decoder *d,
299 enum ccn_dtag dtag,
300 int minlen, int maxlen);
301int ccn_parse_nonNegativeInteger(struct ccn_buf_decoder *d);
302int ccn_parse_optional_tagged_nonNegativeInteger(struct ccn_buf_decoder *d,
303 enum ccn_dtag dtag);
304int ccn_parse_uintmax(struct ccn_buf_decoder *d, uintmax_t *result);
305int ccn_parse_tagged_string(struct ccn_buf_decoder *d,
306 enum ccn_dtag dtag, struct ccn_charbuf *store);*/
307/* check the decoder error state for these two - result can't be negative */
308/*uintmax_t ccn_parse_required_tagged_binary_number(struct ccn_buf_decoder *d,
309 enum ccn_dtag dtag,
310 int minlen, int maxlen);
311uintmax_t ccn_parse_optional_tagged_binary_number(struct ccn_buf_decoder *d,
312 enum ccn_dtag dtag,
313 int minlen, int maxlen,
314 uintmax_t default_value);*/
315
316/**
317 * Enter an error state if element closer not found.
318 */
319void ccn_buf_check_close(struct ccn_buf_decoder *d);
320
321/*
322 * ccn_ref_tagged_BLOB: Get address & size associated with blob-valued element
323 * Returns 0 for success, negative value for error.
324 */
325int ccn_ref_tagged_BLOB(enum ccn_dtag tt,
326 const unsigned char *buf,
327 size_t start, size_t stop,
328 const unsigned char **presult, size_t *psize);
329
330/*
331 * ccn_parse_Name: Parses a ccnb-encoded name
332 * components may be NULL, otherwise is filled in with Component boundary offsets
333 * Returns the number of Components in the Name, or -1 if there is an error.
334 */
335int ccn_parse_Name(struct ccn_buf_decoder *d, struct ccn_indexbuf *components);
336
337/***********************************
338 * Authenticators and signatures for content are constructed in charbufs
339 * using the following routines.
340 */
341
342enum ccn_content_type {
343 CCN_CONTENT_DATA = 0x0C04C0,
344 CCN_CONTENT_ENCR = 0x10D091,
345 CCN_CONTENT_GONE = 0x18E344,
346 CCN_CONTENT_KEY = 0x28463F,
347 CCN_CONTENT_LINK = 0x2C834A,
348 CCN_CONTENT_NACK = 0x34008A
349};
350
351
352/*********** ContentObject parsing ***********/
353/* Analogous to enum ccn_parsed_interest_offsetid, but for content */
354enum ccn_parsed_content_object_offsetid {
355 CCN_PCO_B_Signature,
356 CCN_PCO_B_DigestAlgorithm,
357 CCN_PCO_E_DigestAlgorithm,
358 CCN_PCO_B_Witness,
359 CCN_PCO_E_Witness,
360 CCN_PCO_B_SignatureBits,
361 CCN_PCO_E_SignatureBits,
362 CCN_PCO_E_Signature,
363 CCN_PCO_B_Name,
364 CCN_PCO_B_Component0,
365 CCN_PCO_E_ComponentN,
366 CCN_PCO_E_ComponentLast = CCN_PCO_E_ComponentN,
367 CCN_PCO_E_Name,
368 CCN_PCO_B_SignedInfo,
369 CCN_PCO_B_PublisherPublicKeyDigest,
370 CCN_PCO_E_PublisherPublicKeyDigest,
371 CCN_PCO_B_Timestamp,
372 CCN_PCO_E_Timestamp,
373 CCN_PCO_B_Type,
374 CCN_PCO_E_Type,
375 CCN_PCO_B_FreshnessSeconds,
376 CCN_PCO_E_FreshnessSeconds,
377 CCN_PCO_B_FinalBlockID,
378 CCN_PCO_E_FinalBlockID,
379 CCN_PCO_B_KeyLocator,
380 /* Exactly one of Key, Certificate, or KeyName will be present */
381 CCN_PCO_B_Key_Certificate_KeyName,
382 CCN_PCO_B_KeyName_Name,
383 CCN_PCO_E_KeyName_Name,
384 CCN_PCO_B_KeyName_Pub,
385 CCN_PCO_E_KeyName_Pub,
386 CCN_PCO_E_Key_Certificate_KeyName,
387 CCN_PCO_E_KeyLocator,
388 CCN_PCO_E_SignedInfo,
389 CCN_PCO_B_Content,
390 CCN_PCO_E_Content,
391 CCN_PCO_E
392};
393
394struct ccn_parsed_ContentObject {
395 int magic;
396 enum ccn_content_type type;
397 int name_ncomps;
398 unsigned short offset[CCN_PCO_E+1];
399 unsigned char digest[32]; /* Computed only when needed */
400 int digest_bytes;
401};
Ilya Moiseenko7e254b72011-08-04 19:06:10 -0700402
403int ccn_encode_ContentObject(struct ccn_charbuf *buf,
404 const struct ccn_charbuf *Name,
405 const void *data,
406 size_t size);
Ilya Moiseenkoc115fba2011-08-01 10:53:18 -0700407#endif