aboutsummaryrefslogtreecommitdiffstats
path: root/libparc/parc/security/parc_KeyId.h
diff options
context:
space:
mode:
Diffstat (limited to 'libparc/parc/security/parc_KeyId.h')
-rwxr-xr-xlibparc/parc/security/parc_KeyId.h348
1 files changed, 0 insertions, 348 deletions
diff --git a/libparc/parc/security/parc_KeyId.h b/libparc/parc/security/parc_KeyId.h
deleted file mode 100755
index daa2a2fe..00000000
--- a/libparc/parc/security/parc_KeyId.h
+++ /dev/null
@@ -1,348 +0,0 @@
-/*
- * 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 parc_KeyId.h
- * @ingroup security
- * @brief Represent a key by an octet string
- *
- * A KeyId is a hash digest used to identify a key. These are used as key entries in hash-table
- * based key stores that cache raw keys. Instead of transferring raw keys, parties may exchange
- * KeyIds used to index into key stores for constant-time key retrieval. This exchange
- * expects that the raw key will be present in the key store. If not, the lookup will fail.
- * Consequently, KeyIds are not used to encapsulate or transfer raw keys.
- *
- */
-#include <parc/algol/parc_Buffer.h>
-#include <parc/algol/parc_BufferComposer.h>
-
-#ifndef libparc_parc_KeyId_h
-#define libparc_parc_KeyId_h
-
-struct parc_keyid;
-/**
- * @typedef PARCKeyId
- * @brief A KeyId is a hash digest used to identify a key.
- */
-
-typedef struct parc_keyid PARCKeyId;
-
-/**
- * @def parcKeyId_OptionalAssertValid
- * Optional validation of the given instance.
- *
- * Define `PARCLibrary_DISABLE_VALIDATION` to disable validation.
- */
-#ifdef PARCLibrary_DISABLE_VALIDATION
-# define parcKeyId_OptionalAssertValid(_instance_)
-#else
-# define parcKeyId_OptionalAssertValid(_instance_) parcKeyId_AssertValid(_instance_)
-#endif
-
-/**
- * Create a `PARCKeyId` from the given pre-computed-key identifier.
- *
- * A reference to the given identifer is created and the caller is responsible for releasing the remaining references.
- *
- * @param [in] preComputedKeyId A pointer to a `PARCBuffer` instance containing the pre-computed-key identifier.
- * @return A pointer to an allocated `PARCKeyId` that must be released via `parcKeyId_Release`.
- *
- * Example:
- * @code
- * {
- * PARCBuffer *keybits = parcBuffer_Wrap("Hello", 5, 0, 5);
- * PARCKeyId *keyid = parcKeyId_Create(keybits);
- * parcBuffer_Release(&keybits);
- * // do something with keyid
- * parcKeyId_Release(&keyid);
- * }
- * @endcode
- */
-PARCKeyId *parcKeyId_Create(PARCBuffer *preComputedKeyId);
-
-/**
- * Increase the number of references to a `PARCKeyId`.
- *
- * Note that new `PARCKeyId` is not created,
- * only that the given `PARCKeyId` reference count is incremented.
- * Discard the reference by invoking `parcKeyId_Release`.
- *
- * @param [in] instance A pointer to the instance of `PARCKeyId`.
- * @return The value of the input parameter @p instance.
- *
- * Example:
- * @code
- * {
- * PARCBuffer *buffer = parcBuffer_Wrap("Hello", 5, 0, 5);
- * PARCKeyId *instance = parcKeyId_CreateFromByteBuffer(buffer);
- * parcBuffer_Release(&buffer);
- *
- * PARCKeyId *reference = parcKeyId_Acquire(instance);
- *
- * parcKeyId_Release(&instance);
- * parcKeyId_Release(&reference);
- * }
- * @endcode
- *
- * @see parcKeyId
- */
-PARCKeyId *parcKeyId_Acquire(const PARCKeyId *instance);
-
-/**
- * Assert a valid PARCKeyId instance.
- *
- * @param [in] keyId A pointer to a `PARCKeyId` instance.
- *
- * Example:
- * @code
- * {
- * PARCBuffer *buffer = parcBuffer_Wrap("Hello", 5, 0, 5);
- * PARCKeyId *instance = parcKeyId_CreateFromByteBuffer(buffer);
- * parcBuffer_Release(&buffer);
- *
- * parcKeyId_AssertValid(&instance);
- * parcKeyId_Release(&instance);
- * }
- * @endcode
- * @see parcKeyId_OptionalAssertValid
- */
-void parcKeyId_AssertValid(const PARCKeyId *keyId);
-
-/**
- * Create a copy of the KeyId from the specified `PARCKeyId` instance.
- *
- * A deep copy is performed, acquiring handles to objects when needed.
- *
- * @param [in] original A pointer to a `PARCKeyId` instance containing the pre-computerd-key identifier.
- * @return A pointer to a newly allocated `PARCKeyId` that must be released via `parcKeyId_Release`.
- *
- * Example:
- * @code
- * {
- * PARCBuffer *keybits = parcBuffer_Wrap("Hello", 5, 0, 5);
- * PARCKeyId *keyid = parcKeyId_Create(keybits);
- * parcBuffer_Release(&keybits);
- * // do something with keyid
- * parcKeyId_Release(&keyid);
- * }
- * @endcode
- */
-PARCKeyId *parcKeyId_Copy(const PARCKeyId *original);
-
-/**
- * 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 `PARCKeyId` instance to release.
- *
- * Example:
- * @code
- * {
- * PARCBuffer *buffer = parcBuffer_Wrap("Hello", 5, 0, 5);
- * PARCKeyId *instance = parcKeyId_CreateFromByteBuffer(buffer);
- * parcBuffer_Release(&buffer);
- *
- * parcKeyId_Release(&instance);
- * }
- * @endcode
- */
-void parcKeyId_Release(PARCKeyId **object);
-
-/**
- * Determine if two `PARCKeyId` instances are equal.
- *
- * Two `PARCKeyId` instances are equal if, and only if,
- *
- * The following equivalence relations on non-null `PARCKeyId` instances are maintained:
- *
- * * It is reflexive: for any non-null reference value x, `parcKeyId_Equals(x, x)`
- * must return true.
- *
- * * It is symmetric: for any non-null reference values x and y,
- * `parcKeyId_Equals(x, y)` must return true if and only if
- * `parcKeyId_Equals(y, x)` returns true.
- *
- * * It is transitive: for any non-null reference values x, y, and z, if
- * `parcKeyId_Equals(x, y)` returns true and
- * `parcKeyId_Equals(y, z)` returns true,
- * then `parcKeyId_Equals(x, z)` must return true.
- *
- * * It is consistent: for any non-null reference values x and y, multiple
- * invocations of `parcKeyId_Equals(x, y)` consistently return true or
- * consistently return false.
- *
- * * For any non-null reference value x, `parcKeyId_Equals(x, NULL)` must
- * return false.
- *
- * @param a A pointer to a `PARCKeyId` instance.
- * @param b A pointer to a `PARCKeyId` instance.
- * @return true if the two `PARCKeyId` instances are equal.
- *
- * Example:
- * @code
- * {
- * PARCKeyId *a = parcKeyId_Create(...);
- * PARCKeyId *b = parcKeyId_Create(...);
- *
- * if (parcKeyId_Equals(a, b)) {
- * // equal
- * } else {
- * // unequal
- * }
- * }
- * @endcode
- */
-bool parcKeyId_Equals(const PARCKeyId *a, const PARCKeyId *b);
-
-/**
- * Get the digest bytes of a `PARCKeyId` instance;
- *
- * @param [in] keyid A pointer to a `PARCKeyId` instance.
- *
- * @return A pointer to a (shared) {@link PARCBuffer} instance containing the digest bytes of the `PARCKeyId`.
- *
- * Example:
- * @code
- * {
- * PARCBuffer *buffer = parcBuffer_Wrap("Hello", 5, 0, 5);
- * PARCKeyId *instance = parcKeyId_CreateFromByteBuffer(buffer);
- * PARCBuffer *bytes = parcKeyId_GetKeyId(instance);
- * // use or display the bytes buffer as needed
- * }
- * @endcode
- */
-const PARCBuffer *parcKeyId_GetKeyId(const PARCKeyId *keyid);
-
-/**
- * Returns a hash code value for the given instance.
- *
- * The general contract of `parcKeyId_HashCode` is:
- *
- * Whenever it is invoked on the same instance more than once during an
- * execution of an application,
- * the {@link parcKeyId_HashCode} function must consistently return the same value,
- * provided no information used in a corresponding {@link parcKeyId_Equals}
- * comparisons on the instance is modified.
- *
- * This value need not remain consistent from one execution of an application to
- * another execution of the same application.
- * If two instances are equal according to the {@link parcKeyId_Equals} function,
- * then calling the {@link parcKeyId_HashCode} function on each of the two instances must
- * produce the same integer result.
- *
- * It is not required that if two instances are unequal according to the
- * {@link parcKeyId_Equals} function,
- * then calling the {@link parcKeyId_HashCode}
- * method on each of the two objects must produce distinct integer results.
- *
- * @param [in] keyid A pointer to the `PARCKeyId` instance.
- *
- * @return The hashcode for the given instance.
- *
- * Example:
- * @code
- * {
- * PARCKeyId *x = parcKeyId_Create(...);
- * uint32_t hashValue = parcKeyId_HashCode(array);
- * parcKeyId_Release(&x);
- * }
- * @endcode
- */
-PARCHashCode parcKeyId_HashCode(const PARCKeyId *keyid);
-
-/**
- * Compute a non-cryptographic hash of a `PARCKeyId` instance from a void pointer.
- *
- * This is useful for use in {@link PARCHashCodeTable}.
- *
- * @param [in] keyId A pointer to the instance to be hashed
- *
- * @return A 32-bit non-cryptographic hash of the instance.
- *
- * Example:
- * @code
- * {
- * PARCKeyId *x = parcKeyId_Create(...);
- * uint32_t hash = parcKeyId_HashCode((void*)x);
- * // use the hash to index into a table, or something else
- * }
- * @endcode
- *
- * @see parcKeyId_HashCode
- */
-PARCHashCode parcKeyId_HashCodeFromVoid(const void *keyId);
-
-/**
- * Append a representation of the specified instance to the given
- * {@link PARCBufferComposer}.
- *
- * @param [in] keyId A pointer to a `PARCKeyId` instance.
- * @param [in] composer A pointer to a `PARCBufferComposer` instance.
- *
- * @return NULL Cannot allocate memory.
- * @return non-NULL The given `PARCBufferComposer`.
- *
- * Example:
- * @code
- * {
- * PARCBufferComposer *result = parcBufferComposer_Create();
- *
- * parcKeyId_BuildString(instance, result);
- *
- * char *string = parcBuffer_ToString(parcBufferComposer_ProduceBuffer(result));
- * printf("Hello: %s\n", string);
- * parcMemory_Deallocate((void **)&string);
- *
- * parcBufferComposer_Release(&result);
- * }
- * @endcode
- */
-PARCBufferComposer *parcKeyId_BuildString(const PARCKeyId *keyId, PARCBufferComposer *composer);
-
-/**
- * Produce a null-terminated 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 Cannot allocate memory.
- * @return non-NULL A pointer to an allocated,
- * null-terminated C string that must be deallocated via {@link parcMemory_Deallocate}.
- *
- * Example:
- * @code
- * {
- * PARCKeyId *instance = parcKeyId_Create(...);
- *
- * char *string = parcKeyId_ToString(instance);
- *
- * printf("Hello: %s\n", string);
- * parcMemory_Deallocate((void **)&string);
- *
- * parcKeyId_Release(&instance);
- * }
- * @endcode
- *
- * @see parcKeyId_BuildString
- */
-char *parcKeyId_ToString(const PARCKeyId *instance);
-#endif // libparc_parc_KeyId_h