/*
 * 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>

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);

    /**
     * @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);

/**
 * 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