Content-Centric Networking CCNx Reference Implementation The CCNx reference implementation provides the libraries and components required to build and run applications that use and demonstrate the basic CCNx protocols for experimental and research purposes. The protocol specifications and the reference implementation are at an early research stage of development, and are released to enable collaboration with researchers. What is provided at this time is pure infrastructure, with no applications of interest. Documentation is also minimal, and so using the release software will require technical sophistication and a willingness to read the code. The CCNx reference implementation is open source software. Please see the file LICENSE for important licensing details and limitations. For more information about CCNx, see our website at http://www.ccnx.org This file provides introductory information in the following sections: 1. Package contents 2. Supported platforms 3. Build and install instructions 4. Running the programs 5. Runtime files 6. Support and contact information 7. Notices ================================================== 1. Package contents ================================================== This distribution includes broadly the following things: A) Preliminary specifications of CCNx protocol, application protocols and conventions. B) C/POSIX reference implementation of CCNx forwarder, library, primitive utilities, skeleton API docs, and unit test suite. The C implementation is required for all CCNx communication. C) Java reference implementation of library including primitive repository support (persistent storage of CCNx data), primitive utilities, skeleton API docs, and unit test suite. The Java library has more functionality implemented or started than the C library and may be an easier place to start experimenting. D) Minimal sample app (ccnChat) to demonstrate basic communication on local LAN. E) Experimental plugins for vlc (media transport) and wireshark (packet dissector) Documentation is built from source files of various kinds (using a combination of doxygen and asciidoc) BUT the distribution includes pre-built documentation so it is not necessary to have a build environment and toolchain configured to start reading. Point your browser at doc/index.html to get started. The file tree is organized as follows: README - this file LICENSE - license terms that apply to the distribution MANIFEST - listing of every file in the distribution MD5 - MD5 sum for every file in the distribution SHA1 - SHA1 sum for every file in the distribution configure - master configure script. Note that configure scripts are hand-written at this time, not generated by autoconf doc/ - documentation tree. doc/technical - specifications doc/ccode - API documentation generated from C code doc/javacode - API documentation generated from Java code csrc/ - C code tree csrc/include/ccn - C header files csrc/lib - C application library implementation csrc/ccnd - CCN daemon, the user-space forwarder implementation csrc/libexec - connectivity utilities, especially ccndc, the ccnd configurator and connectivity agent csrc/cmd - simple command-line utilities csrc/conf - OS-specific configuration scripts etc. csrc/contrib - third-party library needed for certain platforms that are POSIX-deficient csrc/test - C test suite csrc/util - launch script support javasrc/ - Java code tree. The usual Java conventions are used for mapping package names to the file tree, with root package org.ccnx.ccn. javasrc/src - Java source tree javasrc/lib - third-party libraries javasrc/tools - convenience scripts schema - XML schema and DTD files apps - experimental/sample apps tree apps/ccnChat - simple text chat sample in Java apps/vlc - vlc plugin for media transport experiments apps/wireshark - wireshark plugin dissector for decoding CCNx packets After building, the following notable directories will appear: bin/ - command-line tools you can run, providing convenience access to mixture of C and Java utilities and samples lib/ - all libraries needed for applications (both C and Java) include/ - headers needed for applications in C javasrc/build - Java build outputs from ant (javasrc/bin is equivalent for Eclipse) Note that these directories are entirely generated and will be removed by some clean targets, so don't use them for anything you want to keep. ================================================== 2. Supported platforms ================================================== OS PLATFORMS Only Unix-like platforms are currently supported. CCNx code is tested on Ubuntu Linux, MacOS, Solaris, and FreeBSD. Some packaging for Cygwin is currently provided but is not fully supported and there is no other support for Windows platforms yet. C LANGUAGE REQUIREMENTS For parts of the system written in C, you will require a standard toolchain including gcc, make etc. and the following libraries which are not included in the distribution. libcrypto >= 0.9.8 from openssl available from http://openssl.org/source/ expat available from http://sourceforge.net/projects/expat/ libpcap available from http://www.tcpdump.org (optional, needed for certain utilities only) libxml2 available from xmlsoft.org In addition, you will need vlc and wireshark to build and use the CCNx plugins for those packages. Please see the individual README files for more information. See csrc/README* files for further notes about what needs to be installed or configured on each OS. JAVA LANGUAGE REQUIREMENTS For parts of the system written in Java, CCNx code is tested with Sun Java JDK 1.5 and 1.6 only, with ant used as the canonical build tool. You will need: ant (>= 1.7.0 tested) extra libraries for JDK1.5 only (see below) Eclipse .project and .classpath files are included in the distribution so you can create Eclipse projects easily. There are two Eclipse Java projects defined: one in javasrc (Eclipse name Java_CCN) and one in apps/ccnChat (Eclipse name ccnChat). Please let us know if JDK1.5 support is important to you, as we plan to eliminate it in the near future. The CCNx distribution includes JAR files for required libraries for JDK1.6. ONLY IF you are going to run on JDK1.5 you must obtain a few additional library files independently: Bouncy Castle Provider for JDK1.5: bcprov-jdk15-143.jar (http://www.bouncycastle.org/download/bcprov-jdk15-143.jar) XML Streaming API: jsr173_api.jar AND jsr173_1.0_ri.jar (http://jcp.org/aboutJava/communityprocess/final/jsr173/index.html) Copy the extra JAR files into lib/ AND javasrc/lib, again ONLY IF you are running on JDK1.5. SPECIAL PLATFORM NOTES [Fedora] JDK1.5 on Fedora has been seen to be extremely slow at seeding the random number generator, which causes major delays for certain operations such as generating the initial keystore file. We recommend using JDK1.6 on Fedora. [Solaris] You will need to use gmake rather than make. ================================================== 3. Build and install instructions ================================================== Note that the overall build handles both the C and Java code, so you will need to have requirements for both met in order to avoid errors. See the section above. BUILDING In the root directory: ./configure make The top-level build will compile both C and Java code. The above is sufficient to run programs locally out of bin/ and build apps referencing lib/ and include/. TESTING To run the complete test suite (both C and Java): make test MACHINE INSTALL (OPTIONAL) To install to a standard location on your machine you may also use make install FURTHER DOCUMENTATION See the notes in the Content-Centric Networking in C in the top-level documentation. ================================================== 4. Running the programs ================================================== These notes assume that you have performed the build steps listed above, but not performed a machine install. Everything may be run directly out of the build tree using programs in bin/. CCND All CCNx programs require that a ccnd be running: bin/ccndstart To start ccnd sending output to a log file instead of the terminal, set the CCND_LOG environment variable with the path of the file you want to write. Any existing file with that name will be overwritten. For a listing of other environment variables that are available (including debug message controls) run: bin/ccnd -h Note that you should not ordinarily run ccnd directly, but use the ccndstart script. For experiments on one machine it is sufficient to have a ccnd running without using a ccnd configuration file, however for multiple machine experimentation you will need to use ccndc to configure the inter-machine forwarding of interest/content. If a $HOME/.ccnx/ccnd.conf file is present then ccndstart will execute ccndc -f $HOME/.ccnx/ccnd.conf For a sample file, see csrc/libexec/ccnd.conf.sample REPOSITORY The repository provides persistent storage of CCNx content backed by a filesystem, and responds to interests in the content it has available. bin/ccn_repo will give a usage message showing options. Start a repository with the name of a directory to use for its backing store. The directory does not need to exist already, e.g.: bin/ccn_repo ~/my_ccnx_repo When launched in this way, the ccn_repo will turn into a daemon. Note the PID given in the output so you can terminate it later, e.g.: bin/ccn_repo stop 17328 Do not run two repositories on the same backing store directory at the same time. The experimental implementation has no protection to prevent this. It is sometimes very helpful to get a debug dump of the names of content held by a repository. You can do this with the command: bin/ccn_repo signal nametree OR bin/ccn_repo signal nametreewide This will produce output in a file in the repository backing directory. This file is overwritten every time you send such a signal. The repository takes an optional configuration file to control some settings, but this is not well documented at this time. See javasrc/src/org/ccnx/ccn/test/repo/origPolicy.xml for a sample. Most important is probably the parameter which controls the CCNx name prefix which the repository will monitor. By default this is / which means that writes will be accepted for any name and reads serviced for any name for which there is content. UTILITIES There are a variety of simple utilities in bin/. Some of them have usage messages, but the handling of arguments and usage messages is inconsistent as of this release. Here are a few notable utilities: ccnexplore - primitive GUI browser in Java, usable to browse only repo content since it requires name enumeration support available only there. Also allows writing files to repo. ccnls - primitive content listing by retrieval ccnlsrepo - command-line content listing from repo (via name enumeration) ccnputfile - command-line tool to send file as CCNx data (asks repo to receive unless -raw arg given) ccngetfile - command-line tool to retrieve CCNx content and store it in file ccnchat - the ccnChat sample application ================================================== 5. Runtime files ================================================== Beware that running the experimental software will create a variety of files, and that this list may not be complete: ~/.ccnx - per-user directory, used primarily for personal keystore and key cache ~/.rmi-server-* - per-user files Java daemon RMI interface objects. These are supposed to be cleared away automatically but that does not occur if processes are terminated manually and in other cases. Repository directories are also created if you run a repository, but in that case you must tell the program what directory to use. ================================================== 6. Support and contact information ================================================== Please see our website at http://www.ccnx.org ================================================== 7. Notices ================================================== CCNx CCNx is free software; you can redistribute it and/or modify it under the terms of the appropriate licenses as covered in the file LICENSE and noted in each source file. This software is distributed in hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file LICENSE for more information. ------------------------- CRYPTOGRAPHIC SOFTWARE This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See for more information. In addition, this software is subject to U.S. export laws and regulations. Any use of information here by you is without recourse to the Palo Alto Research Center, Inc. (PARC) and is at your own risk. PARC makes NO WARRANTY or representation that the information contained here is accurate, current, or complete. PARC is in no way responsible for any damages, whether direct, consequential, incidental, or otherwise, suffered by you as a result of using or relying upon such information for any purpose. The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing cryptographic functions with asymmetric algorithms. The form and manner of this distribution makes it eligible for export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for both object code and source code. The included cryptographic software is the Bouncy Castle provider which is itself classified under ECCN 5D002 and approved for export under License Exception TSU. It is included in this distribution for the convenience of users. For more information about export control of CCNx software, please see the page http://www.ccnx.org/exports ------------------------- BOUNCY CASTLE The Bouncy Castle cryptographic provider redistributed herein is: Copyright (c) 2000 - 2009 The Legion Of The Bouncy Castle (http://www.bouncycastle.org) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ------------------------- JUNIT The JUnit software redistributed herein is covered under the Common Public License, and is subject to the following exclusions and disclaimers from that license: EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations. EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. JUnit source code is available from http://github.com/KentBeck/junit ------------------------- W3C SOFTWARE (XML Schema definitions) XML Schema definitions are redistributed herein for validation tests. The file XMLSchema.xsd has been modified (February 15, 2008) to remove a web reference from schemaLocation as noted in the file included in the distribution. Copyright © 2001 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved. This work is distributed under the W3C® Software License [1] in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 W3C® SOFTWARE NOTICE AND LICENSE http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 This work (and included software, documentation such as READMEs, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions. Permission to copy, modify, and distribute this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications: 1. The full text of this NOTICE in a location viewable to users of the redistributed or derivative work. 2. Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the W3C Software Short Notice should be included (hypertext is preferred, text is permitted) within the body of any redistributed or derivative code. 3. Notice of any changes or modifications to the files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.) THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION. The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.