diff options
Diffstat (limited to 'libparc/parc/security/parc_Identity.h')
| -rwxr-xr-x | libparc/parc/security/parc_Identity.h | 343 |
1 files changed, 343 insertions, 0 deletions
diff --git a/libparc/parc/security/parc_Identity.h b/libparc/parc/security/parc_Identity.h new file mode 100755 index 00000000..c00af8fa --- /dev/null +++ b/libparc/parc/security/parc_Identity.h @@ -0,0 +1,343 @@ +/* + * 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 |