diff options
Diffstat (limited to 'libparc/parc/security/parc_Identity.h')
| -rwxr-xr-x | libparc/parc/security/parc_Identity.h | 343 |
1 files changed, 0 insertions, 343 deletions
diff --git a/libparc/parc/security/parc_Identity.h b/libparc/parc/security/parc_Identity.h deleted file mode 100755 index c00af8fa..00000000 --- a/libparc/parc/security/parc_Identity.h +++ /dev/null @@ -1,343 +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_Identity.h - * @ingroup security - * @brief A generic cryptographic identity that is assigned to an entity - * (user, group, process) and is associated with a set of cryptographic - * material, e.g., public and private keys. - * - * Identities are used for authentication and authorization purposes. - * To illustrate their use, consider the following model. Digital signatures - * are computed with a private key owned by some entity. This private - * key is associated with an identity. It is said that the digital signature - * in this case was procured by an entity with the identity associated - * with the private key. Moreover, verifying this digital signature with - * the corresponding public key is analogous to verifying that the signature - * was generated by an entity with the corresponding identity. - * - * The relationship between identities and entities means that an entity may have - * multiple identities, each of which is associated with its own set of cryptographic - * information. - * - * Finally, an identity is typically backed by a file which stores the set of - * cryptographic material. For instance, once an identity may be represented as a - * PKCS12 (public and private) key store. Other concrete identity implementations - * may have different backing stores (i.e., not files, but services) with - * different notions of secret passwords. - * - */ -#ifndef libparc_parc_Identity_h -#define libparc_parc_Identity_h - -#include <parc/algol/parc_Object.h> -#include <parc/security/parc_Signer.h> -#include <parc/security/parc_CryptoHashType.h> - -struct parc_identity; -typedef struct parc_identity PARCIdentity; - -typedef struct parc_identity_interface { - /** - * @see parcIdentity_Acquire - */ - PARCIdentity *(*Acquire)(void *identity); - - /** - * @see parcIdentity_Release - */ - void (*Release)(void **identityPtr); - - /** - * @see parcIdentity_GetPassWord - */ - void *(*GetPassWord)(const void *original); - - /** - * @see parcIdentity_GetFileName - */ - void *(*GetFileName)(const void *original); - - /** - * @see parcIdentity_CreateSigner - */ - PARCSigner *(*GetSigner)(const void *identity, PARCCryptoHashType hash); - - /** - * @see parcIdentity_Equals - */ - bool (*Equals)(const void *a, const void *b); - - /** - * @see `parcIdentity_Display` - */ - void (*Display)(const void *identity, size_t indentation); -} PARCIdentityInterface; - -#ifdef PARCLibrary_DISABLE_VALIDATION -# define parcIdentity_OptionalAssertValid(_instance_) -#else -# define parcIdentity_OptionalAssertValid(_instance_) parcIdentity_AssertValid(_instance_) -#endif - -/** - * Determine if an instance of `PARCIdentity` is valid. - * - * Valid means the internal state of the type is consistent with its required current or future behaviour. - * This may include the validation of internal instances of types. - * - * @param [in] identity A pointer to a `PARCIdentity` instance. - * - * @return true The instance is valid. - * @return false The instance is not valid. - * - * Example: - * @code - * { - * PARCIdentity *instance = parcIdentity_Create(); - * - * if (parcIdentity_IsValid(instance)) { - * printf("Instance is valid.\n"); - * } - * } - * @endcode - */ -bool parcIdentity_IsValid(const PARCIdentity *identity); - -/** - * Assert that the given `PARCIdentity` instance is valid. - * - * @param [in] identity A pointer to a valid PARCIdentity instance. - * - * Example: - * @code - * { - * PARCIdentity *a = parcIdentity_Create(); - * - * parcIdentity_AssertValid(a); - * - * printf("Instance is valid.\n"); - * - * parcIdentity_Release(&b); - * } - * @endcode - */ -void parcIdentity_AssertValid(const PARCIdentity *identity); - -/** - * Create an instance of PARCIdentity from the given pointer to a subtype - * and the subtype's `PARCIdentityInterface` instance. - * - * A new reference to @p instance is acquired. - * - * @param [in] instance A pointer to a suitable subtype of `PARCIdentity`. - * @param [in] interface A poitner to the subtype's `PARCIdentityInterface` instance. - * - * @return NULL Memory could not be allocated. - * @return non-NULL A pointer to a `PARCIdentity` instance. - * - * Example: - * @code - * { - * PARCIdentity *identity = parcIdentity_Create(...); - * - * parcIdentity_Release(&identity); - * } - * @endcode - */ -PARCIdentity *parcIdentity_Create(PARCObject *instance, const PARCIdentityInterface *interface); - -/** - * Increase the number of references to a `PARCIdentity` instance. - * - * Note that new `PARCIdentity` is not created, - * only that the given `PARCIdentity` reference count is incremented. - * Discard the reference by invoking `parcIdentity_Release`. - * - * @param [in] identity A pointer to the original instance. - * @return The value of the input parameter @p instance. - * - * Example: - * @code - * { - * PARCIdentity *identity = parcIdentity_Create(...); - * PARCIdentity *i2 = parcIdentity_Acquire(identity); - * // use both as needed - * parcIdentity_Release(&i2); - * parcIdentity_Release(&identity); - * } - * @endcode - * - * @see parcIdentity_Release - */ -PARCIdentity *parcIdentity_Acquire(const PARCIdentity *identity); - -/** - * 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] identityPtr A pointer to a pointer to the instance to release. - * - * - * Example: - * @code - * { - * PARCIdentity *identity = parcIdentity_Create(...); - * - * parcIdentity_Release(&identity); - * } - * @endcode - */ -void parcIdentity_Release(PARCIdentity **identityPtr); - -/** - * Retrieve the file name associated with this identity. - * - * In the case of an identity file, this is the actual file name. - * Other concrete identity implementations may have different notions of secret passwords. - * - * NOTE: This function is set to be removed from the PARCIdentity API. - * - * @param [in] identity A `PARCIdentity` instance. - * - * @return A nul-terminated string containing the file name. - * - * Example: - * @code - * { - * PARCIdentity *identity = parcIdentity_Create(...); - * char *fileName = parcIdentity_GetFileName(identity); - * // use the filename - * parcIdentity_Release(&identity); - * } - * @endcode - */ -const char *parcIdentity_GetFileName(const PARCIdentity *identity); - -/** - * Retrieve the secret password associated with this identity.. - * - * In the case of an identity file, the password will be one that opens the file for access. - * Other concrete identity implementations may have different notions of secret passwords. - * - * NOTE: This function is set to be removed from the PARCIdentity API. - * - * @param [in] identity A `PARCIdentity` instance. - * - * @return A character array containing the identity password. - * - * Example: - * @code - * { - * PARCIdentity *identity = parcIdentity_Create(...); - * char *pw = parcIdentity_GetPassWord(identity); - * // use the password pw - * parcIdentity_Release(&identity); - * } - * @endcode - */ -const char *parcIdentity_GetPassWord(const PARCIdentity *identity); - -/** - * Create an instance of `PARCSigner` from the given `PARCIdentity`. - * - * The `PARCSigner` instance must be released via `parcSignature_Release()`. - * - * @param [in] identity A pointer to a PARCIdentity instance. - * - * @return PARCSigner A newly allocated `PARCSigner` instance based off this identity. - * - * Example: - * @code - * { - * PARCIdentity *identity = parcIdentity_Create(...); - * PARCSigner *signer = parcIdentity_CreateSigner(identity); - * - * // use the signer as needed... - * - * parcSigner_Release(&signer); - * parcIdentity_Release(&identity); - * } - * @endcode - */ -PARCSigner *parcIdentity_CreateSigner(const PARCIdentity *identity, PARCCryptoHashType hash); - -/** - * Determine if two PARCIdentity are equal. - * - * The following equivalence relations on non-null `XXX` instances are maintained: * - * * It is reflexive: for any non-null reference value x, parcIdentity_Equals(x, x) must return true. - * - * * It is symmetric: for any non-null reference values x and y, PARCIdentity_Equals(x, y) must return true if and only if - * parcIdentity_Equals(y x) returns true. - * - * * It is transitive: for any non-null reference values x, y, and z, if - * parcIdentity_Equals(x, y) returns true and - * parcIdentity_Equals(y, z) returns true, - * then parcIdentity_Equals(x, z) must return true. - * - * * It is consistent: for any non-null reference values x and y, multiple invocations of parcIdentity_Equals(x, y) - * consistently return true or consistently return false. - * - * * For any non-null reference value x, parcIdentity_Equals(x, NULL)) must return false. - * - * @param a A pointer to a PARCIdentity instance. - * @param b A pointer to a PARCIdentity instance. - * @return True if the referenced PARCIdentity are equal. - * - * Example: - * @code - * { - * PARCIdentity *a = parcIdentity_Create(...); - * PARCIdentity *b = parcIdentity_Create(...); - * parcIdentity_Equals(a, b) - * if (parcIdentity_Equals(a, b)) { - * // this is expected - * } else { - * // this is not expected - * } - * parcIdentity_Release(&a); - * parcIdentity_Release(&b); - * } - * @endcode - */ -bool parcIdentity_Equals(const PARCIdentity *a, const PARCIdentity *b); - -/** - * Print a human readable representation of the given `PARCIdentity`. - * - * @param [in] identity A pointer to the instance to display. - * @param [in] indentation The level of indentation to use to pretty-print the output. - * - * Example: - * @code - * { - * PARCIdentity *instance = parcIdentity_Create(...); - * - * parcIdentity_Display(instance, 0); - * - * parcIdentity_Release(&instance); - * } - * @endcode - */ -void parcIdentity_Display(const PARCIdentity *identity, int indentation); -#endif // libparc_parc_Identity_h |