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

Generated on Thu Feb 16 00:43:59 2012 for Content-Centric Networking in C by  doxygen 1.5.6