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