1 files changed, 422 insertions, 0 deletions
diff --git a/libccnx-common/ccnx/common/ccnx_WireFormatMessage.h b/libccnx-common/ccnx/common/ccnx_WireFormatMessage.h
new file mode 100755
index 00000000..7a61e23b
--- /dev/null
+++ b/libccnx-common/ccnx/common/ccnx_WireFormatMessage.h
@@ -0,0 +1,422 @@
+/*
+ * Copyright (c) 2017 Cisco and/or its affiliates.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @brief A structure of functions to enable accessing a CCNxTlvDictionary as a
+ *        wire format object.
+ *
+ */
+
+#ifndef __CCNx_Common__ccnx_WireFormatMessage__
+#define __CCNx_Common__ccnx_WireFormatMessage__
+
+#include <ccnx/common/internal/ccnx_WireFormatMessageInterface.h>
+#include <ccnx/common/internal/ccnx_TlvDictionary.h>
+
+#include <parc/security/parc_CryptoHash.h>
+
+typedef CCNxTlvDictionary CCNxWireFormatMessage;
+
+/**
+ * Creates a new CCNxWireFormatMessage instance from the `wireFormat` buffer passed in.
+ * The schema version and the message type are determined from `wireFormat`.
+ *
+ * @param wireFormat - a buffer, in wire format, representing the message to created.
+ * @return A new instance of CCNxWireFormatMessage that must eventually be released by calling
+ *          {@link ccnxWireFormatMessage_Release}.
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ * @see ccnxWireFormatMessage_Release
+ */
+CCNxWireFormatMessage *ccnxWireFormatMessage_Create(const PARCBuffer *wireFormat);
+
+/**
+ * Creates dictionary of Interest type from the wire format
+ *
+ *   <#Discussion#>
+ *
+ * @param <#param1#>
+ * @return <#return#>
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+CCNxWireFormatMessage *ccnxWireFormatMessage_FromInterestPacketType(const CCNxTlvDictionary_SchemaVersion schemaVersion, const PARCBuffer *wireFormat);
+
+/**
+ * Creates dictionary of Interest type from the wire format
+ *
+ *   <#Discussion#>
+ *
+ * @param <#param1#>
+ * @return <#return#>
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+CCNxWireFormatMessage *ccnxWireFormatMessage_FromInterestPacketTypeIoVec(const CCNxTlvDictionary_SchemaVersion schemaVersion, const CCNxCodecNetworkBufferIoVec *vec);
+
+/**
+ * Creates a dictionary of ContentObject type from the wire format
+ *
+ * <#Paragraphs Of Explanation#>
+ *
+ * @param [<#in out in,out#>] <#name#> <#description#>
+ *
+ * @return <#value#> <#explanation#>
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+CCNxWireFormatMessage *ccnxWireFormatMessage_FromContentObjectPacketType(const CCNxTlvDictionary_SchemaVersion schemaVersion, const PARCBuffer *wireFormat);
+
+/**
+ * Creates a dictionary of Control type from the wire format
+ *
+ * <#Paragraphs Of Explanation#>
+ *
+ * @param [<#in out in,out#>] <#name#> <#description#>
+ *
+ * @return <#value#> <#explanation#>
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+CCNxWireFormatMessage *ccnxWireFormatMessage_FromControlPacketType(const CCNxTlvDictionary_SchemaVersion schemaVersion, const PARCBuffer *wireFormat);
+
+#ifdef Libccnx_DISABLE_VALIDATION
+#  define ccnxWireFormatMessage_OptionalAssertValid(_instance_)
+#else
+#  define ccnxWireFormatMessage_OptionalAssertValid(_instance_) ccnxWireFormatMessage_AssertValid(_instance_)
+#endif
+
+/**
+ * Assert that the given `CCNxWireFormatMessage` instance is valid.
+ *
+ * @param [in] instance A pointer to a valid CCNxWireFormatMessage instance.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxWireFormatMessage *a = ccnxWireFormatMessage_Create();
+ *
+ *     ccnxWireFormatMessage_AssertValid(a);
+ *
+ *     printf("Instance is valid.\n");
+ *
+ *     ccnxWireFormatMessage_Release(&b);
+ * }
+ * @endcode
+ */
+void ccnxWireFormatMessage_AssertValid(const CCNxWireFormatMessage *message);
+
+/**
+ * Returns the PARCBuffer that wraps the entire wireformat representation
+ *
+ * May be NULL if there is no wire format yet (e.g. you're going down the stack before the codec)
+ *
+ * @param [<#in#> | <#out#> | <#in,out#>] <#name#> <#description#>
+ *
+ * @return <#value#> <#explanation#>
+ *
+ * Example:
+ * @code
+ * {
+ *     <#example#>
+ * }
+ * @endcode
+ */
+PARCBuffer *ccnxWireFormatMessage_GetWireFormatBuffer(const CCNxWireFormatMessage *dictionary);
+
+/**
+ * Returns the CCNxCodecNetworkBufferIoVec that wraps the entire wireformat representation
+ *
+ * May be NULL if there is no wire format yet (e.g. you're going down the stack before the codec), or it
+ * may be NULL because the wireformat is wrapped in a PARCBuffer instead.
+ *
+ * @param [<#in#> | <#out#> | <#in,out#>] <#name#> <#description#>
+ *
+ * @return <#value#> <#explanation#>
+ *
+ * Example:
+ * @code
+ * {
+ *     <#example#>
+ * }
+ * @endcode
+ */
+CCNxCodecNetworkBufferIoVec *ccnxWireFormatMessage_GetIoVec(const CCNxWireFormatMessage *dictionary);
+
+
+/**
+ * Sets the wire format buffer in a Dictionary
+ *
+ * You can only put the wire format once.  Will store its down reference to the wire format, so
+ * caller should release their copy when done with it.
+ *
+ * @param [<#in out in,out#>] <#name#> <#description#>
+ *
+ * @return true Value was put in the dictionary
+ * @return false Value not put, likely already existed
+ *
+ * Example:
+ * @code
+ * {
+ *
+ * }
+ * @endcode
+ */
+bool ccnxWireFormatMessage_PutWireFormatBuffer(CCNxWireFormatMessage *dictionary, PARCBuffer *buffer);
+
+/**
+ * Sets the wire format buffer in a Dictionary
+ *
+ * You can only put the wire format once.  Will store its down reference to the wire format, so
+ * caller should release their copy when done with it.
+ *
+ * @param [<#in out in,out#>] <#name#> <#description#>
+ *
+ * @return true Value was put in the dictionary
+ * @return false Value not put, likely already existed
+ *
+ * Example:
+ * @code
+ * {
+ *
+ * }
+ * @endcode
+ */
+bool ccnxWireFormatMessage_PutIoVec(CCNxWireFormatMessage *dictionary, CCNxCodecNetworkBufferIoVec *vec);
+
+/**
+ * Writes the wire format to the specified file
+ *
+ * The file will be truncated to 0.  If there is no wire format, the file will remain at 0 bytes.
+ *
+ * You can view the packet with the Wireshark plugin.  First convert it to a TCP enapsulation
+ * (the program text2pcap is included as part of WireShark).  The part "- filename.pcap" means that
+ * text2pcap will read from stdin (the "-") and write to "filename.pcap".  Text2pcap requires a
+ * text format derived from "od" or from "hexdump".
+ *
+ *     od -Ax -tx1 -v filename | text2pcap -T 9695,9695 - filename.pcap
+ *     tshark -r filename.pcap -V
+ *
+ *
+ * @param [<#in out in,out#>] <#name#> <#description#>
+ *
+ * @return <#value#> <#explanation#>
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+void ccnxWireFormatMessage_WriteToFile(const CCNxWireFormatMessage *dictionary, const char *filename);
+
+/**
+ * Write to the dictionary the start of the protection region
+ *
+ * The protected region is the byte range that is protected by the signature (validation payload).
+ * This sets the validation region in the dictionary.
+ *
+ * @param [<#in out in,out#>] <#name#> <#description#>
+ *
+ * @return false A validation region is already set, cannot overwrite
+ * @return true The validation region was set in the dictionary
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+bool ccnxWireFormatMessage_SetProtectedRegionStart(CCNxWireFormatMessage *dictionary, size_t startPosition);
+
+/**
+ * Write to the dictionary the length of the protection region
+ *
+ * The protected region is the byte range that is protected by the signature (validation payload).
+ *
+ * @param [<#in out in,out#>] <#name#> <#description#>
+ *
+ * @return false A validation region is already set, cannot overwrite
+ * @return true The validation region was set in the dictionary
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+bool ccnxWireFormatMessage_SetProtectedRegionLength(CCNxWireFormatMessage *dictionary, size_t length);
+
+/**
+ * Runs a hasher over the protected part of the wire format message
+ *
+ * The protected part of the wire format message is from the start of the CCNx Message
+ * through the end of the Validation Algorithm.
+ *
+ * If no validation algorithm block exists, then there is no protection region and
+ * we cannot compute the hash.
+ *
+ * The protection region is computed by the CCNxCodecTlvDecoder and stored in the dictionary.
+ *
+ * @param [<#in out in,out#>] <#name#> <#description#>
+ *
+ * @return null There is no protection region
+ * @return non-null The computed hash
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+PARCCryptoHash *ccnxWireFormatMessage_HashProtectedRegion(const CCNxWireFormatMessage *dictionary, PARCCryptoHasher *hasher);
+
+/**
+ * Calculates the ContentObject Hash, which is the SHA256 hash of the protected part of the wire format message.
+ *
+ * The protected part of the wire format message is from the start of the CCNx Message
+ * through the end of the Validation Algorithm.
+ *
+ * The protection region is computed by the CCNxCodecTlvDecoder and stored in the dictionary.
+ *
+ * This function must only be called on a dictionary that contains a ContentObject and a WireFormat buffer.
+ *
+ * @param [in] dictionary The ContentObject message on which to calculate its hash.
+ *
+ * @return null if we could not calculate the hash. This could mean the protected region wasn't set, or it wasn't a ContentObject.
+ * @return non-null The computed hash
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+
+PARCCryptoHash *ccnxWireFormatMessage_CreateContentObjectHash(CCNxWireFormatMessage *dictionary);
+
+/**
+ * Returns a pointer to the CCNxTlvDictionary underlying the specified CCNxWireFormatMessage.
+ *
+ * @param message - The CCNxWireFormatMessage instance from which to retrieve the CCNxTlvDictionary.
+ * @return A pointer to the underlying CCNxTlvDictionary
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+CCNxTlvDictionary *ccnxWireFormatMessage_GetDictionary(const CCNxWireFormatMessage *message);
+
+/**
+ * Increase the number of references to a `CCNxWireFormatMessage`.
+ *
+ * Note that a new `CCNxWireFormatMessage` is not created,
+ * only that the given `CCNxWireFormatMessage` reference count is incremented.
+ * Discard the reference by invoking {@link ccnxWireFormatMessage_Release}.
+ *
+ * @param [in] message A pointer to the original instance.
+ * @return The value of the input parameter @p instance.
+ *
+ * Example:
+ * @code
+ * {
+ *
+ *     CCNxWireFormat *reference = ccnxWireFormatMessage_Acquire(message);
+ *
+ *     ...
+ *
+ *     ccnxWireFormatMessage_Release(&reference);
+ *
+ * }
+ * @endcode
+ *
+ * @see {@link ccnxWireFormatMessage_Release}
+ */
+CCNxWireFormatMessage *ccnxWireFormatMessage_Acquire(const CCNxWireFormatMessage *message);
+
+/**
+ * Release a previously acquired reference to the specified instance,
+ * decrementing the reference count for the instance.
+ *
+ * The pointer to the instance is set to NULL as a side-effect of this function.
+ *
+ * If the invocation causes the last reference to the instance to be released,
+ * the instance is deallocated and the instance's implementation will perform
+ * additional cleanup and release other privately held references.
+ *
+ * @param [in,out] messageP A pointer to a pointer to the instance to release.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxWireFormatMessage *reference = ccnxWireFormatMessage_Acquire(message);
+ *
+ *     ...
+ *
+ *     ccnxWireFormatMessage_Release(&reference);
+ *
+ * }
+ * @endcode
+ *
+ * @see {@link ccnxWireFormatMessage_Acquire}
+ */
+void ccnxWireFormatMessage_Release(CCNxWireFormatMessage **messageP);
+
+/**
+ * Write a hoplimit to a messages attached wire format io vectors or buffers
+ *
+ * @param [in] message
+ * @param [in] hoplimit
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+bool ccnxWireFormatMessage_SetHopLimit(CCNxWireFormatMessage *message, uint32_t hoplimit);
+
+/**
+ * Given an Interest (as a CCNxWireFormatMessage), convert it to an InterestReturn and
+ * set the return code of the InterestReturn. This does not create a new instance, but
+ * simply modifies the supplied Interest in place.
+ *
+ * @param [in] message - the Interest (as a CCNxWireFormatMessage) to convert.
+ * @param [in] returnCode - the InterestReturn code to embed in the message.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxWireFormatMessage *interest = <...>;
+ *
+ *     CCNxWireFormatMessage *interestReturn =
+ *         ccnxWireFormatMessage_ConvertInterestToInterestReturn(interest,
+ *             CCNxInterestReturn_ReturnCode_HopLimitExceeded);
+ *
+ * }
+ * @endcode
+ */
+bool ccnxWireFormatMessage_ConvertInterestToInterestReturn(CCNxWireFormatMessage *message, uint8_t returnCode);
+#endif /* defined(__CCNx_Common__ccnx_WireFormatMessage__) */