summaryrefslogtreecommitdiffstats
path: root/libparc/parc/security/parc_IdentityFile.h
diff options
context:
space:
mode:
Diffstat (limited to 'libparc/parc/security/parc_IdentityFile.h')
-rw-r--r--libparc/parc/security/parc_IdentityFile.h271
1 files changed, 271 insertions, 0 deletions
diff --git a/libparc/parc/security/parc_IdentityFile.h b/libparc/parc/security/parc_IdentityFile.h
new file mode 100644
index 00000000..c5ee4ac5
--- /dev/null
+++ b/libparc/parc/security/parc_IdentityFile.h
@@ -0,0 +1,271 @@
+/*
+ * 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_IdentityFile.h
+ * @ingroup security
+ * @brief This is a PARCIdentity represented as a PKCS12 keystore file.
+ *
+ * To create these files, use the `parc-publickey` command line tool. Or you could also
+ * use `openssl` to create the same file.
+ *
+ * A `PARCIdentityFile` is a concrete instance of a `PARCIdentity`. To create a
+ * `PARCIdentity` from a `PARCIdentityFile`, one would do the following:
+ *
+ * @code
+ * {
+ * const char *keystoreName = "my_identity.p12";
+ * const char *keystorePassword = "my_password";
+ *
+ * // Create the concrete identity instance from the PKCS12 file
+ * PARCIdentityFile *identityFile = parcIdentityFile_Create(keystoreName, keystorePassword);
+ *
+ * // Create a generic `PARCIdentity` from the concrete identity instance
+ * PARCIdentity *identity = parcIdentity_Create(identityFile, PARCIdentityFileAsPARCIdentity);
+ *
+ * // Now use the `PARCIdentity` for signing purposes (amongst other things)
+ * PARCSigner *signer = parcIdentity_GetSigner(identity);
+ * }
+ * @endcode
+ *
+ */
+#ifndef libparc_parc_IdentityFile_h
+#define libparc_parc_IdentityFile_h
+
+#include <parc/security/parc_Identity.h>
+
+struct parc_identity_file;
+typedef struct parc_identity_file PARCIdentityFile;
+
+/**
+ * The mapping of a PARCIdentityFile to the generic PARCIdentity.
+ */
+extern PARCIdentityInterface *PARCIdentityFileAsPARCIdentity;
+
+/**
+ * Create an instance of `PARCIdentityFile` from a given filename, and a password to unlock the stored information.
+ *
+ * The information is stored in PKCS 12 format.
+ *
+ * @param [in] fileName The name (relative path) to a file to be opened
+ * @param [in] password The password to be used to open the identity file
+ *
+ * @return NULL A `PARCIdentityFile` could not be allocated.
+ * @return PARCIdentityFile A newly allocated `PARCIdentityFile` that must be freed with `parcIdentityFile_Release()`
+ *
+ * Example:
+ * @code
+ * {
+ * PARCIdentityFile *file = parcIdentityFile_Create("./secret.p12", "1234");
+ * ...
+ * parcIdentityFile_Release(&file);
+ * }
+ * @endcode
+ */
+PARCIdentityFile *parcIdentityFile_Create(const char *fileName, const char *password);
+
+/**
+ * Increase the number of references to the given `PARCIdentityFile` instance.
+ *
+ * A new instance is not created,
+ * only that the given instance's reference count is incremented.
+ * Discard the acquired reference by invoking `parcIdentityFile_Release()`.
+ *
+ * @param [in] identity A pointer to a `PARCIdentityFile` instance.
+ *
+ * @return NULL An error occurred.
+ * @return non-NULL A pointer to a PARCIdentityFile instance.
+ *
+ * Example:
+ * @code
+ * {
+ * PARCIdentityFile *file = parcIdentityFile_Create("./secret.p12", "1234");
+ * PARCIdentityFile *secondHandle = parcIdentityFile_Acquire(file);
+ * // use both handles as needed
+ * parcIdentityFile_Release(&file);
+ * parcIdentityFile_Release(&secondHandle);
+ * }
+ * @endcode
+ */
+PARCIdentityFile *parcIdentityFile_Acquire(const PARCIdentityFile *identity);
+
+/**
+ * Decrease the number of references to the given `PARCIdentityFile` instance.
+ *
+ * This only decrements the reference count so long as count >= 1. If the count
+ * reaches zero, the object's memory is freed. The content pointer is always
+ * NULLified after invocation.
+ *
+ * @param [in,out] identityPtr A pointer to a `PARCIdentityFile` instance.
+ *
+ * Example:
+ * @code
+ * {
+ * PARCIdentityFile *file = parcIdentityFile_Create("./secret.p12", "1234");
+ * // use handle as needed
+ * parcIdentityFile_Release(&file);
+ * }
+ * @endcode
+ */
+void parcIdentityFile_Release(PARCIdentityFile **identityPtr);
+
+/**
+ * Determine if the PARCIdentityFile exists.
+ *
+ * It must exist and be a regular file.
+ *
+ * @param [in] identity A pointer to a valid PARCIdentity instance.
+ *
+ * @return true The file exists and is a regular file.
+ * @return false The file does not exist (see errno values for stat(2)) or is not a regular file.
+ *
+ * Example:
+ * @code
+ * {
+ * PARCIdentityFile *file = parcIdentityFile_Create("./secret.p12", "1234");
+ *
+ * if (parcIdentityFile_Exists(file) == true) {
+ * printf("The file exists\n");
+ * } else {
+ * printf("The file does not exist fos\n");
+ * }
+ * }
+ * @endcode
+ */
+bool parcIdentityFile_Exists(const PARCIdentityFile *identity);
+
+/**
+ * Retrieve the name of the file associated with this `PARCIdentityFile` instance.
+ *
+ * @param [in] identity A pointer to a `PARCIdentityFile` instance.
+ *
+ * @return NULL An error occurred.
+ * @return non-NULL A pointer to a PARCIdentityFile instance.
+ *
+ * Example:
+ * @code
+ * {
+ * PARCIdentityFile *file = parcIdentityFile_Create("./secret.p12", "1234");
+ * const char *fileName = parcIdentityFile_GetFileName(file);
+ * // use handle and/or file name as needed
+ * parcIdentityFile_Release(&file);
+ * }
+ * @endcode
+ */
+const char *parcIdentityFile_GetFileName(const PARCIdentityFile *identity);
+
+/**
+ * Retrieve the file password associated with this `PARCIdentityFile` instance.
+ *
+ * @param [in] identity A pointer to a `PARCIdentityFile` instance.
+ *
+ * @return NULL An error occurred.
+ * @return non-NULL A pointer to a PARCIdentityFile instance.
+ *
+ * Example:
+ * @code
+ * {
+ * PARCIdentityFile *file = parcIdentityFile_Create("./secret.p12", "1234");
+ * const char *password = parcIdentityFile_GetPassWord(file);
+ * // use handle and/or file name as needed
+ * parcIdentityFile_Release(&file);
+ * }
+ * @endcode
+ */
+const char *parcIdentityFile_GetPassWord(const PARCIdentityFile *identity);
+
+/**
+ * Create an instance of `PARCSigner` from the given `PARCIdentity`
+ *
+ * @param [in] identity A pointer to a PARCIdentity instance.
+ *
+ * @return NULL An error occurred
+ * @return PARCSigner A new `PARCSigner` instance created using the identity file for the public/private signing keys
+ *
+ * Example:
+ * @code
+ * {
+ * PARCIdentityFile *file = parcIdentityFile_Create("./secret.p12", "1234");
+ * PARCSigner *signer = parcIdentityFile_GetSigner(file);
+ * parcIdentityFile_Release(&file);
+ * // use the signer
+ * parcSigner_Release(&signer);
+ * }
+ * @endcode
+ */
+PARCSigner *parcIdentityFile_CreateSigner(const PARCIdentityFile *identity);
+
+/**
+ * Determine if two PARCIdentityFiles are equal.
+ *
+ * The following equivalence relations on non-null `PARCIdentityFile` instances are maintained:
+ *
+ * * It is reflexive: for any non-null reference value x, parcIdentityFile_Equals(x, x) must return true.
+ *
+ * * It is symmetric: for any non-null reference values x and y, parcIdentityFile_Equals(x, y) must return true if and only if
+ * parcIdentityFile_Equals(y x) returns true.
+ *
+ * * It is transitive: for any non-null reference values x, y, and z, if
+ * parcIdentityFile_Equals(x, y) returns true and
+ * parcIdentityFile_Equals(y, z) returns true,
+ * then parcIdentityFile_Equals(x, z) must return true.
+ *
+ * * It is consistent: for any non-null reference values x and y, multiple invocations of parcIdentityFile_Equals(x, y)
+ * consistently return true or consistently return false.
+ *
+ * * For any non-null reference value x, parcIdentityFile_Equals(x, NULL)) must return false.
+ *
+ * @param a A pointer to a PARCIdentityFile instance.
+ * @param b A pointer to a PARCIdentityFile instance.
+ * @return True if the referenced PARCIdentityFiles are equal.
+ *
+ * Example:
+ * @code
+ * {
+ * PARCIdentityFile *a = parcIdentityFile_Create(...);
+ * PARCIdentityFile *b = parcIdentityFile_Create(...);
+ * if (parcIdentityFile_Equals(a, b)) {
+ * // this is expected
+ * } else {
+ * // this is not expected
+ * }
+ * parcIdentityFile_Release(&a);
+ * parcIdentityFile_Release(&b);
+ * }
+ *
+ * }
+ * @endcode
+ */
+bool parcIdentityFile_Equals(const PARCIdentityFile *a, const PARCIdentityFile *b);
+
+/**
+ * Print a human readable representation of the given `PARCIdentityFile`.
+ *
+ * @param [in] indentation The level of indentation to use to pretty-print the output.
+ * @param [in] instance A pointer to the instance to display.
+ *
+ * Example:
+ * @code
+ * {
+ * PARCIdentityFile *instance = parcIdentityFile_Create("./secret.p12", "1234");
+ *
+ * parcIdentityFile_Display(instance, 0);
+ *
+ * parcIdentityFile_Release(&instance);
+ * }
+ * @endcode
+ */
+void parcIdentityFile_Display(const PARCIdentityFile *instance, int indentation);
+#endif // libparc_parc_IdentityFile_h