diff options
Diffstat (limited to 'libccnx-common/ccnx/common/ccnx_KeyLocator.h')
| -rwxr-xr-x | libccnx-common/ccnx/common/ccnx_KeyLocator.h | 376 |
1 files changed, 376 insertions, 0 deletions
diff --git a/libccnx-common/ccnx/common/ccnx_KeyLocator.h b/libccnx-common/ccnx/common/ccnx_KeyLocator.h new file mode 100755 index 00000000..e48b80a7 --- /dev/null +++ b/libccnx-common/ccnx/common/ccnx_KeyLocator.h @@ -0,0 +1,376 @@ +/* + * 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. + */ + +/** + * @file ccnx_KeyLocator.h + * @ingroup Signature + * @brief A `CCNxKeyLocator` encapsulates the information and/or data necessary to retrieve a `PARCKey`. + * + * There are at least two ways in which a `PARCKey` can be instantiated: + * + * (1) By embedding and subsequently extracting the raw key data in a message, and + * (2) By specifying a link for a key so that an interest can be issued to obtain the key content + * + * A key locator encapsulates both methods. The API provides functions to create key locators + * for each key retrieval type and use them to retrieve `PARCKey` methods. + * + */ +#ifndef libccnx_ccnx_KeyLocator_h +#define libccnx_ccnx_KeyLocator_h + +#include <stdbool.h> + +#include <ccnx/common/ccnx_Link.h> + +#include <parc/security/parc_Key.h> + +/** + * @typedef CCNxKeyLocatorType + * @brief Locator types for finding keys. + */ +typedef enum { + CCNxKeyLocatorType_None = 0, + CCNxKeyLocatorType_Link = 1, + CCNxKeyLocatorType_Key = 2 +} CCNxKeyLocatorType; + +struct ccnx_key_locator; + +/** + * @typedef CCNxKeyLocator + * @brief A `CCNxKeyLocator` encapsulates the information and/or data necessary to retrieve a {@link PARCKey}. + */ +typedef struct ccnx_key_locator CCNxKeyLocator; + +/** + * Create a `CCNxKeyLocator` instance from a {@link PARCKey} instance. + * + * @param [in] key The `PARCKey` instance which is used to construct the `CCNxKeyLocator` instance. + * + * @return `CCNxKeyLocator` A new `CCNxKeyLocator` instance. + * + * Example: + * @code + * { + * PARCKey *key = ... + * CCNxKeyLocator *keyLocator = ccnxKeyLocator_CreateFromKey(key); + * // use the keyLocator instance + * } + * @endcode + */ +CCNxKeyLocator *ccnxKeyLocator_CreateFromKey(PARCKey *key); + +/** + * Create a `CCNxKeyLocator` instance from a {@link CCNxName} instance. + * + * @param [in] keyLink The `CCNxLink` instance used to create the `CCNxKeyLocator` instance + * + * @return `CCNxKeyLocator` A new `CCNxKeyLocator` instance. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci//name"); + * CCNxLink *keyURILink = ccnxLink_Create(name, NULL, NULL); + * + * CCNxKeyLocator *keyLocator = ccnxKeyLocator_CreateFromKeyLink(keyURILink); + * // use the keyLocator instance + * } + * @endcode + */ +CCNxKeyLocator *ccnxKeyLocator_CreateFromKeyLink(CCNxLink *keyLink); + +/** + * Retrieve the {@link CCNxKeyLocatorType} associated with this `CCNxKeyLocator`. + * + * The locator type will specify one of the three methods used to obtain a + * PARCKey: (1) embedded keys, (2) certificates, or (3) key (content) names. + * + * @param [in] keyLocator The `CCNxKeyLocator` instance from which the location + * type is retrieved. + * + * @return A `CCNxKeyLocatorType` value. + * + * Example: + * @code + * { + * CCNxName *name = ccnxLink_Create("lci//name"); + * CCNxLink *keyURILink = ccnxName_CreateFromCString(name, NULL, NULL); + * + * CCNxKeyLocator *keyLocator = ccnxKeyLocator_CreateFromKeyLink(keyURILink); + * CCNxKeyLocatorType locatorType = ccnxKeyLocator_GetType(keyLocator); + * // use the locator type + * } + * @endcode + */ +CCNxKeyLocatorType ccnxKeyLocator_GetType(const CCNxKeyLocator *keyLocator); + +/** + * Determine if the key locator type is type `CCNxKeyLocatorType_Key`. + * + * @param [in] keyLocator `CCNxKeyLocator` instance being examined. + * + * @return true If the key locator type is type `CCNxKeyLocatorType_Key` + * @return false Otherwise + * + * Example: + * @code + * { + * ... + * PARCKey *key = ... + * CCNxKeyLocator *keyLocator = ccnxKeyLocator_CreateFromKey(key); + * bool isKeyType = ccnxKeyLocator_IsKey(keyLocator); + * // isKeyType will be true + * } + * @endcode + */ +bool ccnxKeyLocator_IsKey(const CCNxKeyLocator *keyLocator); + +/** + * Determine if the key locator type is type `CCNxKeyLocatorType_Link`. + * + * @param [in] keyLocator `CCNxKeyLocator` instance being examined. + * + * @return true If the key locator type is type `CCNxKeyLocatorType_Link` + * @return false Otherwise + * + * Example: + * @code + * { + * ... + * CCNxName *name = ccnxName_CreateFromCString("lci:/name"); + * CCNxLink *keyURILink = ccnxLink_Create(name, NULL, NULL); + * CCNxKeyLocator *keyLocator = ccnxKeyLocator_CreateFromKeyLink(keyURILink); + * bool isKeyNameType = ccnxKeyLocator_IsKeyLink(keyLocator); + * // isKeyNameType will be true + * } + * @endcode + */ +bool ccnxKeyLocator_IsKeyLink(const CCNxKeyLocator *keyLocator); + +/** + * Produce a null-terminated C-string representation of the specified instance. + * + * The non-null result must be freed by the caller via {@link parcMemory_Deallocate}. + * + * @param [in] instance A pointer to the instance. + * + * @return NULL Memory could not be allocated. + * @return non-NULL A null-terminated string that must be deallocated via `parcMemory_Deallocate`. + * + * Example: + * @code + * { + * ... + * CCNxName *name = ccnxName_CreateFromCString("lci:/name"); + * CCNxKeyLocator *keyLocator = ccnxKeyLocator_FromKeyName(name); + * char *stringRep = ccnxKeyLocator_ToString(keyLocator); + * } + * @endcode + */ +char *ccnxKeyLocator_ToString(const CCNxKeyLocator *instance); + +/** + * Retrieve the {@link CCNxLink} instance from the specified `CCNxKeyLocator` instance. + * + * The type of the key locator must be `CCNxKeyLocatorType_Link` prior to invocation, + * else a trap will be invoked. + * + * @param [in] keyLocator The `CCNxKeyLocator` from which the name is extracted. + * + * @return A non-NULL `CCNxName` instance. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_Create("lci//name"); + * CCNxLink *keyURILink = ccnxLink_CreateFromURI(name, NULL, NULL); + * + * CCNxKeyLocator *keyLocator = ccnxKeyLocator_CreateFromKeyLink(keyURILink); + * CCNxLink *copy = ccnxKeyLocator_GetKeyLink(keyLocator); + * // use the link copy + * } + * @endcode + */ +CCNxLink *ccnxKeyLocator_GetKeyLink(const CCNxKeyLocator *keyLocator); + +/** + * Retrieve the {@link PARCKey} instance from the specified `CCNxKeyLocator` instance. + * + * The type of the key locator must be `CCNxKeyLocatorType_Key` prior to invocation, + * else a trap will be invoked. + * + * @param [in] keyLocator The `CCNxKeyLocator` from which the key is extracted. + * + * @return A non-NULL `PARCKey` instance. + * + * Example: + * @code + * { + * PARCKey *key = ...; + * CCNxKeyLocator *keyLocator = ccnxKeyLocator_FromKey(key); + * CCNxKey *copy = ccnxKeyLocator_GetKey(keyLocator); + * // use the key copy + * } + * @endcode + */ +PARCKey *ccnxKeyLocator_GetKey(const CCNxKeyLocator *keyLocator); + +/** + * Determine if two `CCNxKeyLocators` are equal. + * + * The following equivalence relations on non-null `CCNxKeyLocator` instances are maintained: + * + * * It is reflexive: for any non-null reference value x, `ccnxKeyLocator_Equals(x, x)` must return true. + * + * * It is symmetric: for any non-null reference values x and y, `ccnxKeyLocator_Equals(x, y)` must return true if and only if + * `ccnxKeyLocator_Equals(y x)` returns true. + * + * * It is transitive: for any non-null reference values x, y, and z, if + * `ccnxKeyLocator_Equals(x, y)` returns true and + * `ccnxKeyLocator_Equals(y, z)` returns true, + * then `ccnxKeyLocator_Equals(x, z)` must return true. + * + * * It is consistent: for any non-null reference values x and y, multiple invocations of `ccnxKeyLocator_Equals(x, y)` + * consistently return true or consistently return false. + * + * * For any non-null reference value x, `ccnxKeyLocator_Equals(x, NULL)` must return false. + * + * @param a A pointer to a `CCNxKeyLocator` instance. + * @param b A pointer to a `CCNxKeyLocator` instance. + * @return True if the referenced `CCNxKeyLocators` are equal. + * + * Example: + * @code + * { + * CCNxName *name1 = ccnxLink_Create("lci//name"); + * CCNxLink *keyURILink1 = ccnxName_CreateFromCString(name1, NULL, NULL); + * + * CCNxKeyLocator *keyLocator1 = ccnxKeyLocator_FromKeyName(keyURILink1); + * + * CCNxName *name2 = ccnxLink_Create("lci//name"); + * CCNxLink *keyURILink2 = ccnxName_CreateFromCString(name2, NULL, NULL); + * + * CCNxKeyLocator *keyLocator2 = ccnxKeyLocator_FromKeyName(keyURILink2); + * + * if (ccnxKeyLocator_Equals(keyLocator1, keyLocator2)) { + * // true + * } else { + * // false + * } + * } + * @endcode + */ +bool ccnxKeyLocator_Equals(const CCNxKeyLocator *a, const CCNxKeyLocator *b); + +/** + * Create a copy of the given `CCNxKeyLocator` instance. + * + * This creates a deep copy of the `CCNxKeyLocator` instance, acquiring handles to internal object + * references when needed. + * + * @param [in] original The `CCNxKeyLocator` instance which is being copied + * + * @return `CCNxKeyLocator` A copy of the specified `CCNxKeyLocator` + * + * Example: + * @code + * { + * ... + * CCNxName *keyURIName = ccnxName_CreateFromCString("lci://name"); + * CCNxKeyLocator *keyLocator = ccnxKeyLocator_FromKeyName(keyURIName); + * CCNxKeyLocator *copy = ccnxKeyLocator_Copy(keyLocator); + * // use the copied instance + * } + * @endcode + */ +CCNxKeyLocator *ccnxKeyLocator_Copy(const CCNxKeyLocator *original); + +/** + * Increase the number of references to a `CCNxKeyLocator`. + * + * Note that new `CCNxKeyLocator` is not created, + * only that the given `CCNxKeyLocator` reference count is incremented. + * Discard the reference by invoking {@link ccnxKeyLocator_Release}. + * + * @param instance A pointer to the original instance. + * @return The value of the input parameter @p instance. + * + * Example: + * @code + * { + * ... + * + * CCNxKeyLocator *keyLocator = ccnxKeyLocator_Acquire(instance); + * + * ccnxKeyLocator_Release(&keyLocator); + * + * } + * @endcode + * + * @see `ccnxKeyLocator_Release` + */ +CCNxKeyLocator *ccnxKeyLocator_Acquire(const CCNxKeyLocator *instance); + +/** + * 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] object A pointer to a pointer to the instance to release. + * + * + * Example: + * @code + * { + * ... + * + * CCNxKeyLocator *cert = ccnxKeyLocator_Acquire(instance); + * + * ccnxKeyLocator_Release(&cert); + * + * } + * @endcode + */ +void ccnxKeyLocator_Release(CCNxKeyLocator **object); + +#ifdef Libccnx_DISABLE_VALIDATION +# define ccnxKeyLocator_OptionalAssertValid(_instance_) +#else +# define ccnxKeyLocator_OptionalAssertValid(_instance_) ccnxKeyLocator_AssertValid(_instance_) +#endif +/** + * Check that the pointer to the `KeyLocator` is valid. It should be non-null, + * and any required referenced data should be valid. + * + * @param [in] object A pointer to the instance to check. + * + * Example: + * @code + * { + * ... + * + * ccnxKeyLocator_AssertValid(keyLocator); + * + * } + * @endcode + */ +void ccnxKeyLocator_AssertValid(const CCNxKeyLocator *object); +#endif // libccnx_ccnx_KeyLocator_h |