ccn.h

Go to the documentation of this file.
00001 /**
00002  * @file ccn/ccn.h
00003  *
00004  * This is the low-level interface for CCNx clients.
00005  *
00006  * Part of the CCNx C Library.
00007  *
00008  * Copyright (C) 2008-2012 Palo Alto Research Center, Inc.
00009  *
00010  * This library is free software; you can redistribute it and/or modify it
00011  * under the terms of the GNU Lesser General Public License version 2.1
00012  * as published by the Free Software Foundation.
00013  * This library is distributed in the hope that it will be useful,
00014  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00015  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
00016  * Lesser General Public License for more details. You should have received
00017  * a copy of the GNU Lesser General Public License along with this library;
00018  * if not, write to the Free Software Foundation, Inc., 51 Franklin Street,
00019  * Fifth Floor, Boston, MA 02110-1301 USA.
00020  */
00021 
00022 #ifndef CCN_CCN_DEFINED
00023 #define CCN_CCN_DEFINED
00024 
00025 #include <stdint.h>
00026 #include <ccn/coding.h>
00027 #include <ccn/charbuf.h>
00028 #include <ccn/indexbuf.h>
00029 
00030 /**
00031  * A macro that clients may use to cope with an evolving API.
00032  *
00033  * The decimal digits of this use the pattern MMVVXXX, where MM is the
00034  * major release number and VV is the minor version level.
00035  * XXX will be bumped when an API change is made, but it will not be
00036  * directly tied to the patch level in a release number.
00037  * Thus CCN_API_VERSION=1000 would have corresponded to the first public
00038  * release (0.1.0), but that version did not have this macro defined.
00039  */
00040 #define CCN_API_VERSION 6003
00041 
00042 /**
00043  * Interest lifetime default.
00044  *
00045  * If the interest lifetime is not explicit, this is the default value.
00046  */
00047 #define CCN_INTEREST_LIFETIME_SEC 4
00048 #define CCN_INTEREST_LIFETIME_MICROSEC (CCN_INTEREST_LIFETIME_SEC * 1000000)
00049 
00050 /* opaque declarations */
00051 struct ccn;
00052 struct ccn_pkey;
00053 
00054 /* forward declarations */
00055 struct ccn_closure;
00056 struct ccn_upcall_info;
00057 struct ccn_parsed_interest;
00058 struct ccn_parsed_ContentObject;
00059 struct ccn_parsed_Link;
00060 
00061 /*
00062  * Types for implementing upcalls
00063  * To receive notifications of incoming interests and content, the
00064  * client creates closures (using client-managed memory).
00065  */
00066 
00067 /**
00068  * This tells what kind of event the upcall is handling.
00069  *
00070  * The KEYMISSING and RAW codes are used only if deferred verification has been
00071  * requested.
00072  */
00073 enum ccn_upcall_kind {
00074     CCN_UPCALL_FINAL,             /**< handler is about to be deregistered */
00075     CCN_UPCALL_INTEREST,          /**< incoming interest */
00076     CCN_UPCALL_CONSUMED_INTEREST, /**< incoming interest, someone has answered */
00077     CCN_UPCALL_CONTENT,           /**< incoming verified content */
00078     CCN_UPCALL_INTEREST_TIMED_OUT,/**< interest timed out */
00079     CCN_UPCALL_CONTENT_UNVERIFIED,/**< content that has not been verified */
00080     CCN_UPCALL_CONTENT_BAD,       /**< verification failed */
00081     CCN_UPCALL_CONTENT_KEYMISSING,/**< key has not been fetched */
00082     CCN_UPCALL_CONTENT_RAW        /**< verification has not been attempted */
00083 };
00084 
00085 /**
00086  * Upcalls return one of these values.
00087  */
00088 enum ccn_upcall_res {
00089     CCN_UPCALL_RESULT_ERR = -1, /**< upcall detected an error */
00090     CCN_UPCALL_RESULT_OK = 0,   /**< normal upcall return */
00091     CCN_UPCALL_RESULT_REEXPRESS = 1, /**< reexpress the same interest again */
00092     CCN_UPCALL_RESULT_INTEREST_CONSUMED = 2,/**< upcall claims to consume interest */
00093     CCN_UPCALL_RESULT_VERIFY = 3, /**< force an unverified result to be verified */
00094     CCN_UPCALL_RESULT_FETCHKEY = 4 /**< request fetching of an unfetched key */
00095 };
00096 
00097 /**
00098  * @type ccn_handler
00099  * This is the procedure type for the closure's implementation.
00100  */
00101 typedef enum ccn_upcall_res (*ccn_handler)(
00102     struct ccn_closure *selfp,
00103     enum ccn_upcall_kind kind,
00104     struct ccn_upcall_info *info  /**< details about the event */
00105 );
00106 
00107 /**
00108  * Handle for upcalls that allow clients receive notifications of
00109  * incoming interests and content.
00110  *
00111  * The client is responsible for managing this piece of memory and the
00112  * data therein. The refcount should be initially zero, and is used by the
00113  * library to keep to track of multiple registrations of the same closure.
00114  * When the count drops back to 0, the closure will be called with
00115  * kind = CCN_UPCALL_FINAL so that it has an opportunity to clean up.
00116  */
00117 struct ccn_closure {
00118     ccn_handler p;      /**< client-supplied handler */
00119     void *data;         /**< for client use */
00120     intptr_t intdata;   /**< for client use */
00121     int refcount;       /**< client should not update this directly */
00122 };
00123 
00124 /**
00125  * Additional information provided in the upcall.
00126  *
00127  * The client is responsible for managing this piece of memory and the
00128  * data therein. The refcount should be initially zero, and is used by the
00129  * library to keep to track of multiple registrations of the same closure.
00130  * When the count drops back to 0, the closure will be called with
00131  * kind = CCN_UPCALL_FINAL so that it has an opportunity to clean up.
00132  */
00133 struct ccn_upcall_info {
00134     struct ccn *h;              /**< The ccn library handle */
00135     /* Interest (incoming or matched) */
00136     const unsigned char *interest_ccnb;
00137     struct ccn_parsed_interest *pi;
00138     struct ccn_indexbuf *interest_comps;
00139     int matched_comps;
00140     /* Incoming content for CCN_UPCALL_CONTENT* - otherwise NULL */
00141     const unsigned char *content_ccnb;
00142     struct ccn_parsed_ContentObject *pco;
00143     struct ccn_indexbuf *content_comps;
00144 };
00145 
00146 /*
00147  * ccn_create: create a client handle
00148  * Creates and initializes a client handle, not yet connected.
00149  * On error, returns NULL and sets errno.
00150  * Errors: ENOMEM
00151  */ 
00152 struct ccn *ccn_create(void);
00153 
00154 /*
00155  * ccn_connect: connect to local ccnd
00156  * Use NULL for name to get the default.
00157  * Normal return value is the fd for the connection.
00158  * On error, returns -1.
00159  */ 
00160 int ccn_connect(struct ccn *h, const char *name);
00161 
00162 /*
00163  * ccn_get_connection_fd: get connection socket fd
00164  * This is in case the client needs to know the associated
00165  * file descriptor, e.g. for use in select/poll.
00166  * The client should not use this fd for actual I/O.
00167  * Normal return value is the fd for the connection.
00168  * Returns -1 if the handle is not connected.
00169  */ 
00170 int ccn_get_connection_fd(struct ccn *h);
00171 
00172 /*
00173  * ccn_disconnect: disconnect from local ccnd
00174  * This breaks the connection and discards buffered I/O,
00175  * but leaves other state intact.
00176  */ 
00177 int ccn_disconnect(struct ccn *h);
00178 
00179 /*
00180  * ccn_destroy: destroy handle
00181  * Releases all resources associated with *hp and sets it to NULL.
00182  */ 
00183 void ccn_destroy(struct ccn **hp);
00184 
00185 /* Control where verification happens */
00186 int ccn_defer_verification(struct ccn *h, int defer);
00187 
00188 /***********************************
00189  * Writing Names
00190  * Names for interests are constructed in charbufs using 
00191  * the following routines.
00192  */
00193 
00194 /*
00195  * ccn_name_init: reset charbuf to represent an empty Name in binary format
00196  * Return value is 0, or -1 for error.
00197  */
00198 int ccn_name_init(struct ccn_charbuf *c);
00199 
00200 /*
00201  * ccn_name_append: add a Component to a Name
00202  * The component is an arbitrary string of n octets, no escaping required.
00203  * Return value is 0, or -1 for error.
00204  */
00205 int ccn_name_append(struct ccn_charbuf *c, const void *component, size_t n);
00206 
00207 /*
00208  * ccn_name_append_str: add a Component that is a \0 terminated string.
00209  * The component added is the bytes of the string without the \0.
00210  * This function is convenient for those applications that construct 
00211  * component names from simple strings.
00212  * Return value is 0, or -1 for error
00213  */
00214 int ccn_name_append_str(struct ccn_charbuf *c, const char *s);
00215 
00216 /*
00217  * ccn_name_append_components: add sequence of ccnb-encoded Components
00218  *    to a ccnb-encoded Name
00219  * start and stop are offsets from ccnb
00220  * Return value is 0, or -1 for obvious error
00221  */
00222 int ccn_name_append_components(struct ccn_charbuf *c,
00223                                const unsigned char *ccnb,
00224                                size_t start, size_t stop);
00225 
00226 enum ccn_marker {
00227     CCN_MARKER_NONE = -1,
00228     CCN_MARKER_SEQNUM  = 0x00, /**< consecutive block sequence numbers */
00229     CCN_MARKER_CONTROL = 0xC1, /**< commands, etc. */ 
00230     CCN_MARKER_OSEQNUM = 0xF8, /**< deprecated */
00231     CCN_MARKER_BLKID   = 0xFB, /**< nonconsecutive block ids */
00232     CCN_MARKER_VERSION = 0xFD  /**< timestamp-based versioning */
00233 };
00234 
00235 /*
00236  * ccn_name_append_numeric: add binary Component to ccnb-encoded Name
00237  * These are special components used for marking versions, fragments, etc.
00238  * Return value is 0, or -1 for error
00239  * see doc/technical/NameConventions.html
00240  */
00241 int ccn_name_append_numeric(struct ccn_charbuf *c,
00242                             enum ccn_marker tag, uintmax_t value);
00243 
00244 /*
00245  * ccn_name_append_nonce: add nonce Component to ccnb-encoded Name
00246  * Uses %C1.N.n marker.
00247  * see doc/technical/NameConventions.html
00248  */
00249 int ccn_name_append_nonce(struct ccn_charbuf *c);
00250 
00251 /*
00252  * ccn_name_split: find Component boundaries in a ccnb-encoded Name
00253  * Thin veneer over ccn_parse_Name().
00254  * returns -1 for error, otherwise the number of Components
00255  * components arg may be NULL to just do a validity check
00256  */
00257 int ccn_name_split(const struct ccn_charbuf *c,
00258                    struct ccn_indexbuf* components);
00259 
00260 /*
00261  * ccn_name_chop: Chop the name down to n components.
00262  * returns -1 for error, otherwise the new number of Components
00263  * components arg may be NULL; if provided it must be consistent with
00264  * some prefix of the name, and is updated accordingly.
00265  * n may be negative to say how many components to remove instead of how
00266  * many to leave, e.g. -1 will remove just the last component.
00267  */
00268 int ccn_name_chop(struct ccn_charbuf *c,
00269                   struct ccn_indexbuf* components, int n);
00270 
00271 
00272 /***********************************
00273  * Authenticators and signatures for content are constructed in charbufs
00274  * using the following routines.
00275  */
00276 
00277 enum ccn_content_type {
00278     CCN_CONTENT_DATA = 0x0C04C0,
00279     CCN_CONTENT_ENCR = 0x10D091,
00280     CCN_CONTENT_GONE = 0x18E344,
00281     CCN_CONTENT_KEY  = 0x28463F,
00282     CCN_CONTENT_LINK = 0x2C834A,
00283     CCN_CONTENT_NACK = 0x34008A
00284 };
00285 
00286 /***********************************
00287  * ccn_express_interest: 
00288  * Use the above routines to set up namebuf.
00289  * Matching occurs only on the first prefix_comps components of
00290  * the name, or on all components if prefix_comps is -1.
00291  * Any remaining components serve to establish the starting point for
00292  * the search for matching content.
00293  * The namebuf may be reused or destroyed after the call.
00294  * If action is not NULL, it is invoked when matching data comes back.
00295  * If interest_template is supplied, it should contain a ccnb formatted
00296  * interest message to provide the other portions of the interest.
00297  * It may also be reused or destroyed after the call.
00298  * When an interest times out, the upcall may return
00299  * CCN_UPCALL_RESULT_REEXPRESS to simply re-express the interest.
00300  * The default is to unregister the handler.  The common use will be for
00301  * the upcall to register again with an interest modified to prevent matching
00302  * the same interest again.
00303  */
00304 int ccn_express_interest(struct ccn *h,
00305                          struct ccn_charbuf *namebuf,
00306                          struct ccn_closure *action,
00307                          struct ccn_charbuf *interest_template);
00308 
00309 /*
00310  * Register to receive interests on a prefix
00311  */
00312 int ccn_set_interest_filter(struct ccn *h, struct ccn_charbuf *namebuf,
00313                             struct ccn_closure *action);
00314 
00315 /*
00316  * Variation allows non-default forwarding flags
00317  */
00318 int ccn_set_interest_filter_with_flags(struct ccn *h,
00319                                        struct ccn_charbuf *namebuf,
00320                                        struct ccn_closure *action,
00321                                        int forw_flags);
00322 
00323 /*
00324  * ccn_put: send ccn binary
00325  * This checks for a single well-formed ccn binary object and 
00326  * sends it out (or queues it to be sent).  For normal clients,
00327  * this should be a ContentObject sent in response to an Interest,
00328  * but ccn_put does not check for that.
00329  * Returns -1 for error, 0 if sent completely, 1 if queued.
00330  */
00331 int ccn_put(struct ccn *h, const void *p, size_t length);
00332 
00333 /*
00334  * ccn_output_is_pending:
00335  * This is for client-managed select or poll.
00336  * Returns 1 if there is data waiting to be sent, else 0.
00337  */
00338 int ccn_output_is_pending(struct ccn *h);
00339 
00340 /*
00341  * ccn_run: process incoming
00342  * This may serve as the main event loop for simple apps by passing 
00343  * a timeout value of -1.
00344  * The timeout is in milliseconds.
00345  */
00346 int ccn_run(struct ccn *h, int timeout);
00347 
00348 /*
00349  * ccn_set_run_timeout: modify ccn_run timeout
00350  * This may be called from an upcall to change the timeout value.
00351  * The timeout is in milliseconds.  Returns old value.
00352  */
00353 int ccn_set_run_timeout(struct ccn *h, int timeout);
00354 
00355 /*
00356  * ccn_get: Get a single matching ContentObject
00357  * This is a convenience for getting a single matching ContentObject.
00358  * Blocks until a matching ContentObject arrives or there is a timeout.
00359  * If h is NULL or ccn_get is called from inside an upcall, a new connection
00360  * will be used and upcalls from other requests will not be processed while
00361  * ccn_get is active.
00362  * The pcobuf and compsbuf arguments may be supplied to save the work of
00363  * re-parsing the ContentObject.  Either or both may be NULL if this
00364  * information is not actually needed.
00365  * flags are not currently used, should be 0.
00366  * Returns 0 for success, -1 for an error.
00367  */
00368 int ccn_get(struct ccn *h,
00369             struct ccn_charbuf *name,
00370             struct ccn_charbuf *interest_template,
00371             int timeout_ms,
00372             struct ccn_charbuf *resultbuf,
00373             struct ccn_parsed_ContentObject *pcobuf,
00374             struct ccn_indexbuf *compsbuf,
00375             int flags);
00376 
00377 #define CCN_GET_NOKEYWAIT 1
00378 
00379 /* Handy if the content object didn't arrive in the usual way. */
00380 int ccn_verify_content(struct ccn *h,
00381                        const unsigned char *msg,
00382                        struct ccn_parsed_ContentObject *pco);
00383 
00384 /***********************************
00385  * Binary decoding
00386  * These routines require that the whole binary object be buffered.
00387  */
00388 
00389 struct ccn_buf_decoder {
00390     struct ccn_skeleton_decoder decoder;
00391     const unsigned char *buf;
00392     size_t size;
00393 };
00394 
00395 struct ccn_buf_decoder *ccn_buf_decoder_start(struct ccn_buf_decoder *d,
00396     const unsigned char *buf, size_t size);
00397 
00398 void ccn_buf_advance(struct ccn_buf_decoder *d);
00399 int ccn_buf_advance_past_element(struct ccn_buf_decoder *d);
00400 
00401 /* The match routines return a boolean - true for match */
00402 /* XXX - note, ccn_buf_match_blob doesn't match - it extracts the blob! */
00403 int ccn_buf_match_dtag(struct ccn_buf_decoder *d, enum ccn_dtag dtag);
00404 
00405 int ccn_buf_match_some_dtag(struct ccn_buf_decoder *d);
00406 
00407 int ccn_buf_match_some_blob(struct ccn_buf_decoder *d);
00408 int ccn_buf_match_blob(struct ccn_buf_decoder *d,
00409                        const unsigned char **bufp, size_t *sizep);
00410 
00411 int ccn_buf_match_udata(struct ccn_buf_decoder *d, const char *s);
00412 
00413 int ccn_buf_match_attr(struct ccn_buf_decoder *d, const char *s);
00414 
00415 /* On error, the parse routines enter an error state and return a negative value. */
00416 int ccn_parse_required_tagged_BLOB(struct ccn_buf_decoder *d,
00417                                    enum ccn_dtag dtag,
00418                                    int minlen, int maxlen);
00419 int ccn_parse_optional_tagged_BLOB(struct ccn_buf_decoder *d,
00420                                    enum ccn_dtag dtag,
00421                                    int minlen, int maxlen);
00422 int ccn_parse_nonNegativeInteger(struct ccn_buf_decoder *d);
00423 int ccn_parse_optional_tagged_nonNegativeInteger(struct ccn_buf_decoder *d,
00424                                                  enum ccn_dtag dtag);
00425 int ccn_parse_uintmax(struct ccn_buf_decoder *d, uintmax_t *result);
00426 int ccn_parse_tagged_string(struct ccn_buf_decoder *d,
00427                             enum ccn_dtag dtag, struct ccn_charbuf *store);
00428 /* check the decoder error state for these two - result can't be negative */
00429 uintmax_t ccn_parse_required_tagged_binary_number(struct ccn_buf_decoder *d,
00430                                                   enum ccn_dtag dtag,
00431                                                   int minlen, int maxlen);
00432 uintmax_t ccn_parse_optional_tagged_binary_number(struct ccn_buf_decoder *d,
00433                                                   enum ccn_dtag dtag,
00434                                                   int minlen, int maxlen,
00435                                                   uintmax_t default_value);
00436 /**
00437  * Enter an error state if element closer not found.
00438  */
00439 void ccn_buf_check_close(struct ccn_buf_decoder *d);
00440 
00441 /*
00442  * ccn_ref_tagged_BLOB: Get address & size associated with blob-valued element
00443  * Returns 0 for success, negative value for error.
00444  */
00445 int ccn_ref_tagged_BLOB(enum ccn_dtag tt,
00446                         const unsigned char *buf,
00447                         size_t start, size_t stop,
00448                         const unsigned char **presult, size_t *psize);
00449 
00450 /*
00451  * ccn_ref_tagged_string: Get address & size associated with
00452  * string(UDATA)-valued element.   Note that since the element closer
00453  * is a 0 byte, the string result will be correctly interpreted as a C string.
00454  * Returns 0 for success, negative value for error.
00455  */
00456 int ccn_ref_tagged_string(enum ccn_dtag tt,
00457                         const unsigned char *buf,
00458                         size_t start, size_t stop,
00459                         const unsigned char **presult, size_t *psize);
00460 
00461 int ccn_fetch_tagged_nonNegativeInteger(enum ccn_dtag tt,
00462             const unsigned char *buf, size_t start, size_t stop);
00463 
00464 /*********** Interest parsing ***********/
00465 
00466 /*
00467  * The parse of an interest results in an array of offsets into the 
00468  * wire representation, with the start and end of each major element and
00469  * a few of the inportant sub-elements.  The following enum allows those
00470  * array items to be referred to symbolically.  The *_B_* indices correspond
00471  * to beginning offsets and the *_E_* indices correspond to ending offsets.
00472  * An omitted element has its beginning and ending offset equal to each other.
00473  * Normally these offsets will end up in non-decreasing order.
00474  * Some aliasing tricks may be played here, e.g. since
00475  * offset[CCN_PI_E_ComponentLast] is always equal to
00476  * offset[CCN_PI_E_LastPrefixComponent],
00477  * we may define CCN_PI_E_ComponentLast = CCN_PI_E_LastPrefixComponent.
00478  * However, code should not rely on that,
00479  * since it may change from time to time as the
00480  * interest schema evolves.
00481  */
00482 enum ccn_parsed_interest_offsetid {
00483     CCN_PI_B_Name,
00484     CCN_PI_B_Component0,
00485     CCN_PI_B_LastPrefixComponent,
00486     CCN_PI_E_LastPrefixComponent,
00487     CCN_PI_E_ComponentLast = CCN_PI_E_LastPrefixComponent,
00488     CCN_PI_E_Name,
00489     CCN_PI_B_MinSuffixComponents,
00490     CCN_PI_E_MinSuffixComponents,
00491     CCN_PI_B_MaxSuffixComponents,
00492     CCN_PI_E_MaxSuffixComponents,
00493     CCN_PI_B_PublisherID, // XXX - rename
00494     CCN_PI_B_PublisherIDKeyDigest,
00495     CCN_PI_E_PublisherIDKeyDigest,
00496     CCN_PI_E_PublisherID,
00497     CCN_PI_B_Exclude,
00498     CCN_PI_E_Exclude,
00499     CCN_PI_B_ChildSelector,
00500     CCN_PI_E_ChildSelector,
00501     CCN_PI_B_AnswerOriginKind,
00502     CCN_PI_E_AnswerOriginKind,
00503     CCN_PI_B_Scope,
00504     CCN_PI_E_Scope,
00505     CCN_PI_B_InterestLifetime,
00506     CCN_PI_E_InterestLifetime,
00507     CCN_PI_B_Nonce,
00508     CCN_PI_E_Nonce,
00509     CCN_PI_B_OTHER,
00510     CCN_PI_E_OTHER,
00511     CCN_PI_E
00512 };
00513 
00514 struct ccn_parsed_interest {
00515     int magic;
00516     int prefix_comps;
00517     int min_suffix_comps;
00518     int max_suffix_comps;
00519     int orderpref;
00520     int answerfrom;
00521     int scope;
00522     unsigned short offset[CCN_PI_E+1];
00523 };
00524 
00525 enum ccn_parsed_Link_offsetid {
00526     CCN_PL_B_Name,
00527     CCN_PL_B_Component0,
00528     CCN_PL_E_ComponentLast,
00529     CCN_PL_E_Name,
00530     CCN_PL_B_Label,
00531     CCN_PL_E_Label,
00532     CCN_PL_B_LinkAuthenticator,
00533     CCN_PL_B_PublisherID,
00534     CCN_PL_B_PublisherDigest,
00535     CCN_PL_E_PublisherDigest,
00536     CCN_PL_E_PublisherID,
00537     CCN_PL_B_NameComponentCount,
00538     CCN_PL_E_NameComponentCount,
00539     CCN_PL_B_Timestamp,
00540     CCN_PL_E_Timestamp,
00541     CCN_PL_B_Type,
00542     CCN_PL_E_Type,
00543     CCN_PL_B_ContentDigest,
00544     CCN_PL_E_ContentDigest,
00545     CCN_PL_E_LinkAuthenticator,
00546     CCN_PL_E
00547 };
00548 
00549 struct ccn_parsed_Link {
00550     int name_ncomps;
00551     int name_component_count;
00552     int publisher_digest_type;
00553     int type;
00554     unsigned short offset[CCN_PL_E+1];
00555 };
00556 
00557 /*
00558  * ccn_parse_Link:
00559  * Returns number of name components, or a negative value for an error.
00560  * Fills in *link.
00561  * If components is not NULL, it is filled with byte indexes of
00562  * the start of each Component of the Name of the Link,
00563  * plus one additional value for the index of the end of the last component.
00564  */
00565 int
00566 ccn_parse_Link(struct ccn_buf_decoder *d,
00567                    struct ccn_parsed_Link *link,
00568                    struct ccn_indexbuf *components);
00569 
00570 /*
00571  * ccn_append_Link: TODO: fill in documentation
00572  */
00573 int
00574 ccnb_append_Link(struct ccn_charbuf *buf,
00575                  const struct ccn_charbuf *name,
00576                  const char *label,
00577                  const struct ccn_charbuf *linkAuthenticator
00578                  );
00579 
00580 /*
00581  * ccn_parse_LinkAuthenticator:
00582  */
00583 int
00584 ccn_parse_LinkAuthenticator(struct ccn_buf_decoder *d,
00585                struct ccn_parsed_Link *link);
00586 
00587 /*
00588  * ccn_parse_Collection_start: TODO: fill in documentation
00589  */
00590 
00591 int
00592 ccn_parse_Collection_start(struct ccn_buf_decoder *d);
00593 
00594 /*
00595  * ccn_parse_Collection_next: TODO: fill in documentation
00596  */
00597 
00598 int
00599 ccn_parse_Collection_next(struct ccn_buf_decoder *d,
00600                           struct ccn_parsed_Link *link,
00601                           struct ccn_indexbuf *components);
00602 
00603 /*
00604  * Bitmasks for AnswerOriginKind
00605  */
00606 #define CCN_AOK_CS      0x1     /* Answer from content store */
00607 #define CCN_AOK_NEW     0x2     /* OK to produce new content */
00608 #define CCN_AOK_DEFAULT (CCN_AOK_CS | CCN_AOK_NEW)
00609 #define CCN_AOK_STALE   0x4     /* OK to answer with stale data */
00610 #define CCN_AOK_EXPIRE  0x10    /* Mark as stale (must have Scope 0) */
00611 
00612 /*
00613  * ccn_parse_interest:
00614  * Returns number of name components, or a negative value for an error.
00615  * Fills in *interest.
00616  * If components is not NULL, it is filled with byte indexes of
00617  * the start of each Component of the Name of the Interest,
00618  * plus one additional value for the index of the end of the last component.
00619  */
00620 int
00621 ccn_parse_interest(const unsigned char *msg, size_t size,
00622                    struct ccn_parsed_interest *interest,
00623                    struct ccn_indexbuf *components);
00624 
00625 /*
00626  * Returns the lifetime of the interest in units of 2**(-12) seconds
00627  * (the same units as timestamps).
00628  */
00629 intmax_t ccn_interest_lifetime(const unsigned char *msg,
00630                                const struct ccn_parsed_interest *pi);
00631 /*
00632  * As above, but result is in seconds.  Any fractional part is truncated, so
00633  * this is not useful for short-lived interests.
00634  */
00635 int ccn_interest_lifetime_seconds(const unsigned char *msg,
00636                                   const struct ccn_parsed_interest *pi);
00637 
00638 /*********** ContentObject parsing ***********/
00639 /* Analogous to enum ccn_parsed_interest_offsetid, but for content */
00640 enum ccn_parsed_content_object_offsetid {
00641     CCN_PCO_B_Signature,
00642     CCN_PCO_B_DigestAlgorithm,
00643     CCN_PCO_E_DigestAlgorithm,
00644     CCN_PCO_B_Witness,
00645     CCN_PCO_E_Witness,
00646     CCN_PCO_B_SignatureBits,
00647     CCN_PCO_E_SignatureBits,
00648     CCN_PCO_E_Signature,
00649     CCN_PCO_B_Name,
00650     CCN_PCO_B_Component0,
00651     CCN_PCO_E_ComponentN,
00652     CCN_PCO_E_ComponentLast = CCN_PCO_E_ComponentN,
00653     CCN_PCO_E_Name,
00654     CCN_PCO_B_SignedInfo,
00655     CCN_PCO_B_PublisherPublicKeyDigest,
00656     CCN_PCO_E_PublisherPublicKeyDigest,
00657     CCN_PCO_B_Timestamp,
00658     CCN_PCO_E_Timestamp,
00659     CCN_PCO_B_Type,
00660     CCN_PCO_E_Type,
00661     CCN_PCO_B_FreshnessSeconds,
00662     CCN_PCO_E_FreshnessSeconds,
00663     CCN_PCO_B_FinalBlockID,
00664     CCN_PCO_E_FinalBlockID,
00665     CCN_PCO_B_KeyLocator,
00666     /* Exactly one of Key, Certificate, or KeyName will be present */
00667     CCN_PCO_B_Key_Certificate_KeyName,
00668     CCN_PCO_B_KeyName_Name,
00669     CCN_PCO_E_KeyName_Name,
00670     CCN_PCO_B_KeyName_Pub,
00671     CCN_PCO_E_KeyName_Pub,
00672     CCN_PCO_E_Key_Certificate_KeyName,
00673     CCN_PCO_E_KeyLocator,
00674     CCN_PCO_E_SignedInfo,
00675     CCN_PCO_B_Content,
00676     CCN_PCO_E_Content,
00677     CCN_PCO_E
00678 };
00679 
00680 struct ccn_parsed_ContentObject {
00681     int magic;
00682     enum ccn_content_type type;
00683     int name_ncomps;
00684     unsigned short offset[CCN_PCO_E+1];
00685     unsigned char digest[32];   /* Computed only when needed */
00686     int digest_bytes;
00687 };
00688 
00689 /*
00690  * ccn_parse_ContentObject:
00691  * Returns 0, or a negative value for an error.
00692  * Fills in *x with offsets of constituent elements.
00693  * If components is not NULL, it is filled with byte indexes
00694  * of the start of each Component of the Name of the ContentObject,
00695  * plus one additional value for the index of the end of the last component.
00696  * Sets x->digest_bytes to 0; the digest is computed lazily by calling
00697  * ccn_digest_ContentObject.
00698  */
00699 int ccn_parse_ContentObject(const unsigned char *msg, size_t size,
00700                             struct ccn_parsed_ContentObject *x,
00701                             struct ccn_indexbuf *components);
00702 
00703 void ccn_digest_ContentObject(const unsigned char *msg,
00704                               struct ccn_parsed_ContentObject *pc);
00705 
00706 /*
00707  * ccn_parse_Name: Parses a ccnb-encoded name
00708  * components may be NULL, otherwise is filled in with Component boundary offsets
00709  * Returns the number of Components in the Name, or -1 if there is an error.
00710  */
00711 int ccn_parse_Name(struct ccn_buf_decoder *d, struct ccn_indexbuf *components);
00712 
00713 /*
00714  * ccn_compare_names:
00715  * Returns a value that is negative, zero, or positive depending upon whether
00716  * the Name element of a is less, equal, or greater than the Name element of b.
00717  * a and b may point to the start of ccnb-encoded elements of type Name,
00718  * Interest, or ContentObject.  The size values should be large enough to
00719  * encompass the entire Name element.
00720  * The ordering used is the canonical ordering of the ccn name hierarchy.
00721  */
00722 int ccn_compare_names(const unsigned char *a, size_t asize,
00723                       const unsigned char *b, size_t bsize);
00724 
00725 /***********************************
00726  * Reading Names:
00727  * Names may be (minimally) read using the following routines,
00728  * based on the component boundary markers generated from a parse.
00729  */
00730 
00731 /*
00732  * ccn_indexbuf_comp_strcmp: perform strcmp of given val against 
00733  * name component at given index i (counting from 0).
00734  * Uses conventional string ordering, not the canonical CCNx ordering.
00735  * Returns negative, 0, or positive if val is less than, equal to,
00736  * or greater than the component.
00737  * Safe even on binary components, though the result may not be useful.
00738  * NOTE - this ordering is different from the canonical ordering
00739  * used by ccn_compare_names();
00740  */
00741 int ccn_name_comp_strcmp(const unsigned char *data,
00742                          const struct ccn_indexbuf *indexbuf,
00743                          unsigned int i,
00744                          const char *val);
00745 
00746 /*
00747  * ccn_name_comp_get: return a pointer to and size of component at
00748  * given index i.  The first component is index 0.
00749  */
00750 int ccn_name_comp_get(const unsigned char *data,
00751                       const struct ccn_indexbuf *indexbuf,
00752                       unsigned int i,
00753                       const unsigned char **comp, size_t *size);
00754 
00755 int ccn_name_next_sibling(struct ccn_charbuf *c);
00756 
00757 /***********************************
00758  * Reading content objects
00759  */
00760 
00761 int ccn_content_get_value(const unsigned char *data, size_t data_size,
00762                           const struct ccn_parsed_ContentObject *content,
00763                           const unsigned char **value, size_t *size);
00764 
00765 /* checking for final block */
00766 int
00767 ccn_is_final_block(struct ccn_upcall_info *info);
00768 
00769 /* content-object signing */
00770 
00771 /**
00772  * Parameters for creating signed content objects.
00773  *
00774  * A pointer to one of these may be passed to ccn_sign_content() for
00775  * cases where the default signing behavior does not suffice.
00776  * For the default (sign with the user's default key pair), pass NULL
00777  * for the pointer.
00778  *
00779  * The recommended way to us this is to create a local variable:
00780  *
00781  *   struct ccn_signing_params myparams = CCN_SIGNING_PARAMS_INIT;
00782  *
00783  * and then fill in the desired fields.  This way if additional parameters
00784  * are added, it won't be necessary to go back and modify exiting clients.
00785  * 
00786  * The template_ccnb may contain a ccnb-encoded SignedInfo to supply
00787  * selected fields from under the direction of sp_flags.
00788  * It is permitted to omit unneeded fields from the template, even if the
00789  * schema says they are manditory.
00790  *
00791  * If the pubid is all zero, the user's default key pair is used for
00792  * signing.  Otherwise the corresponding private key must have already
00793  * been supplied to the handle using ccn_load_private_key() or equivalent.
00794  *
00795  * The default signing key is obtained from ~/.ccnx/.ccnx_keystore unless
00796  * the CCNX_DIR is used to override the directory location.
00797  */
00798  
00799 struct ccn_signing_params {
00800     int api_version;
00801     int sp_flags;
00802     struct ccn_charbuf *template_ccnb;
00803     unsigned char pubid[32];
00804     enum ccn_content_type type;
00805     int freshness;
00806     // XXX where should digest_algorithm fit in?
00807 };
00808 
00809 #define CCN_SIGNING_PARAMS_INIT \
00810   { CCN_API_VERSION, 0, NULL, {0}, CCN_CONTENT_DATA, -1 }
00811 
00812 #define CCN_SP_TEMPL_TIMESTAMP      0x0001
00813 #define CCN_SP_TEMPL_FINAL_BLOCK_ID 0x0002
00814 #define CCN_SP_TEMPL_FRESHNESS      0x0004
00815 #define CCN_SP_TEMPL_KEY_LOCATOR    0x0008
00816 #define CCN_SP_FINAL_BLOCK          0x0010
00817 #define CCN_SP_OMIT_KEY_LOCATOR     0x0020
00818 
00819 int ccn_sign_content(struct ccn *h,
00820                      struct ccn_charbuf *resultbuf,
00821                      const struct ccn_charbuf *name_prefix,
00822                      const struct ccn_signing_params *params,
00823                      const void *data, size_t size);
00824 
00825 int ccn_load_private_key(struct ccn *h,
00826                          const char *keystore_path,
00827                          const char *keystore_passphrase,
00828                          struct ccn_charbuf *pubid_out);
00829 
00830 int ccn_load_default_key(struct ccn *h,
00831                          const char *keystore_path,
00832                          const char *keystore_passphrase);
00833 
00834 int ccn_get_public_key(struct ccn *h,
00835                        const struct ccn_signing_params *params,
00836                        struct ccn_charbuf *digest_result,
00837                        struct ccn_charbuf *result);
00838 
00839 int ccn_chk_signing_params(struct ccn *h,
00840                            const struct ccn_signing_params *params,
00841                            struct ccn_signing_params *result,
00842                            struct ccn_charbuf **ptimestamp,
00843                            struct ccn_charbuf **pfinalblockid,
00844                            struct ccn_charbuf **pkeylocator);
00845 
00846 /* low-level content-object signing */
00847 
00848 #define CCN_SIGNING_DEFAULT_DIGEST_ALGORITHM "SHA256"
00849 
00850 int ccn_signed_info_create(
00851     struct ccn_charbuf *c,              /* filled with result */
00852     const void *publisher_key_id,       /* input, (sha256) hash */
00853     size_t publisher_key_id_size,       /* input, 32 for sha256 hashes */
00854     const struct ccn_charbuf *timestamp,/* input ccnb blob, NULL for "now" */
00855     enum ccn_content_type type,         /* input */
00856     int freshness,                      /* input, -1 means omit */
00857     const struct ccn_charbuf *finalblockid, /* input, NULL means omit */
00858     const struct ccn_charbuf *key_locator); /* input, optional, ccnb encoded */
00859 
00860 int ccn_encode_ContentObject(struct ccn_charbuf *buf,
00861                              const struct ccn_charbuf *Name,
00862                              const struct ccn_charbuf *SignedInfo,
00863                              const void *data,
00864                              size_t size,
00865                              const char *digest_algorithm,
00866                              const struct ccn_pkey *private_key);
00867 
00868 /***********************************
00869  * Matching
00870  */
00871 
00872 
00873 /*
00874  * ccn_content_matches_interest: Test for a match
00875  * Return 1 if the ccnb-encoded content_object matches the 
00876  * ccnb-encoded interest_msg, otherwise 0.
00877  * The implicit_content_digest boolean says whether or not the
00878  * final name component is implicit (as in the on-wire format)
00879  * or explicit (as within ccnd's content store).
00880  * Valid parse information (pc and pi) may be provided to speed things
00881  * up; if NULL they will be reconstructed internally.
00882  */
00883 int ccn_content_matches_interest(const unsigned char *content_object,
00884                                  size_t content_object_size,
00885                                  int implicit_content_digest,
00886                                  struct ccn_parsed_ContentObject *pc,
00887                                  const unsigned char *interest_msg,
00888                                  size_t interest_msg_size,
00889                                  const struct ccn_parsed_interest *pi);
00890 
00891 /*
00892  * Test whether the given raw name is int the Exclude set.
00893  */
00894 int ccn_excluded(const unsigned char *excl,
00895                  size_t excl_size,
00896                  const unsigned char *nextcomp,
00897                  size_t nextcomp_size);
00898 
00899 /***********************************
00900  * StatusResponse
00901  */
00902 int ccn_encode_StatusResponse(struct ccn_charbuf *buf,
00903                               int errcode, const char *errtext);
00904 
00905 /***********************************
00906  * Debugging
00907  */
00908 
00909 /*
00910  * ccn_perror: produce message on standard error output describing the last
00911  * error encountered during a call using the given handle.
00912  * ccn_seterror records error info, ccn_geterror gets it.
00913  */
00914 void ccn_perror(struct ccn *h, const char *s);
00915 int ccn_seterror(struct ccn *h, int error_code);
00916 int ccn_geterror(struct ccn *h);
00917 
00918 /***********************************
00919  * Low-level binary formatting
00920  */
00921 
00922 /*
00923  * Append a ccnb start marker
00924  *
00925  * This forms the basic building block of ccnb-encoded data.
00926  * c is the buffer to append to.
00927  * Return value is 0, or -1 for error.
00928  */
00929 int ccn_charbuf_append_tt(struct ccn_charbuf *c, size_t val, enum ccn_tt tt);
00930 
00931 /**
00932  * Append a CCN_CLOSE
00933  *
00934  * Use this to close off an element in ccnb-encoded data.
00935  * @param c is the buffer to append to.
00936  * @returns 0 for success or -1 for error.
00937  */
00938 int ccn_charbuf_append_closer(struct ccn_charbuf *c);
00939 
00940 /***********************************
00941  * Slightly higher level binary formatting
00942  */
00943 
00944 /*
00945  * Append a non-negative integer as a UDATA.
00946  */
00947 int ccnb_append_number(struct ccn_charbuf *c, int nni);
00948 
00949 /*
00950  * Append a binary timestamp
00951  * as a BLOB using the ccn binary Timestamp representation (12-bit fraction).
00952  */
00953 int ccnb_append_timestamp_blob(struct ccn_charbuf *c,
00954                                enum ccn_marker marker,
00955                                intmax_t secs, int nsecs);
00956 
00957 /*
00958  * Append a binary timestamp, using the current time.
00959  */
00960 int ccnb_append_now_blob(struct ccn_charbuf *c, enum ccn_marker marker);
00961 
00962 /*
00963  * Append a start-of-element marker.
00964  */
00965 int ccnb_element_begin(struct ccn_charbuf *c, enum ccn_dtag dtag);
00966 
00967 /*
00968  * Append an end-of-element marker.
00969  * This is the same as ccn_charbuf_append_closer()
00970  */
00971 int ccnb_element_end(struct ccn_charbuf *c);
00972 
00973 /*
00974  * Append a tagged BLOB
00975  */
00976 int ccnb_append_tagged_blob(struct ccn_charbuf *c, enum ccn_dtag dtag,
00977                             const void *data, size_t size);
00978 
00979 /*
00980  * Append a tagged UDATA string, with printf-style formatting
00981  */
00982 int ccnb_tagged_putf(struct ccn_charbuf *c, enum ccn_dtag dtag,
00983                      const char *fmt, ...);
00984 
00985 /**
00986  * Versioning
00987  */
00988 
00989 /* Not all of these flags make sense with all of the operations */
00990 #define CCN_V_REPLACE  1 /**< if last component is version, replace it */
00991 #define CCN_V_LOW      2 /**< look for early version */
00992 #define CCN_V_HIGH     4 /**< look for newer version */
00993 #define CCN_V_EST      8 /**< look for extreme */
00994 #define CCN_V_LOWEST   (2|8)
00995 #define CCN_V_HIGHEST  (4|8)
00996 #define CCN_V_NEXT     (4|1)
00997 #define CCN_V_PREV     (2|1)
00998 #define CCN_V_NOW      16 /**< use current time */
00999 #define CCN_V_NESTOK   32 /**< version within version is ok */ 
01000 
01001 int ccn_resolve_version(struct ccn *h,
01002                         struct ccn_charbuf *name, /* ccnb encoded */
01003                         int versioning_flags,
01004                         int timeout_ms);
01005 
01006 int ccn_create_version(struct ccn *h,
01007                        struct ccn_charbuf *name,
01008                        int versioning_flags,
01009                        intmax_t secs, int nsecs);
01010 
01011 #endif
Generated on Tue Aug 21 14:54:17 2012 for Content-Centric Networking in C by  doxygen 1.6.3