Add comments to header file

Change-Id: I7ca1196e56c4b5ebaccefffba403037684bdeed9
Signed-off-by: Janusz Kozerski <j.kozerski@samsung.com>

2 files changed, 94 insertions, 12 deletions

diff --git a/src/imaevm.h b/src/imaevm.h
index d203eb1..7c64a07 100644
--- a/src/imaevm.h
+++ b/src/imaevm.h
@@ -10,6 +10,7 @@
  *                 <dmitry.kasatkin@intel.com>
  *                 <d.kasatkin@samsung.com>
  * Pawel Polawski  <p.polawski@samsung.com>
+ * Janusz Kozerski <j.kozerski@samsung.com>
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
@@ -215,38 +216,119 @@ enum lib_retval {
 	LIB_ERROR_ATTRIBUTE
 };
 
+
 enum ima_state {
-	IMA_STATE_DISABLED,
-	IMA_STATE_IGNORE,
-	IMA_STATE_ENFORCE,
-	IMA_STATE_FIX
+	IMA_STATE_DISABLED, /* IMA is turned off - no actions are done */
+	IMA_STATE_IGNORE,   /* IMA checks files integrity, errors are reported on
+	                     * measurement list, but there is no blocking access.
+	                     * If file hash was correct on open it is updated on close */
+	IMA_STATE_ENFORCE,  /* IMA checks files integrity - on errors access denied
+	                     * is returned when attempt to open.
+	                     * If file hash was correct on open it is updated on close */
+	IMA_STATE_FIX       /* IMA doesn't check files integrity. Hash of files is
+	                     * updated on file close */
 };
 
 enum evm_state {
-	EVM_STATE_DISABLED,
-	EVM_STATE_ENABLED,
-	EVM_STATE_FIX
+	EVM_STATE_DISABLED, /* EVM is turned off - no actions are done */
+	EVM_STATE_ENABLED,  /* EVM is check security.* xattrs integrity. On error access
+	                     * denied is returned when attempt to open. If security.evm was
+	                     *  correct on open it is updated on close */
+	EVM_STATE_FIX       /* No integrity check - Hash of file is updated on file close */
 };
 
 enum file_state {
-	FILE_STATE_OK,
-	FILE_STATE_TAMPERED,
-	FILE_STATE_UNKNOWN
+	FILE_STATE_OK,        /* File integrity is OK */
+	FILE_STATE_TAMPERED,  /* File is tampered */
+	FILE_STATE_UNKNOWN    /* File is not included in IMA policy or
+	                       * you have no rights to open the file */
 };
 
+/*
+ * Returns via param state of IMA (ima_state enum) and returns LIB_SUCCESS or
+ * LIB_ERROR_* on error
+ */
 int ima_get_state(int *state);
+
+/*
+ * Sets IMA state (ima_state enum) and returns LIB_SUCCESS or LIB_ERROR_* on error
+ */
 int ima_set_state(int state);
+
+/*
+ * Returns via param state of EVM (evm_state enum) and returns LIB_SUCCESS or
+ * LIB_ERROR_* on error
+ */
 int evm_get_state(int *state);
+
+/*
+ * Sets EVM state (evm_state enum) and returns LIB_SUCCESS or LIB_ERROR_* on error
+ */
 int evm_set_state(int state);
-int ima_set_xattr(const char *path);
+
+/*
+ * Sets security.ima extended attribute.
+ * Returns LIB_SUCCESS on success or LIB_ERROR_* on error
+ */
+int ima_set_xattr(const char *path, const char *ima);
+
+/*
+ * Gets security.ima extended attribute.
+ * Returns LIB_SUCCESS on success or LIB_ERROR_* on error
+ */
 int ima_get_xattr(const char *path, char **hash);
+
+/*
+ * Sets security.evm extended attribute.
+ * Returns LIB_SUCCESS on success or LIB_ERROR_* on error
+ */
 int evm_set_xattr(const char *path, const char *evm);
+
+/*
+ * Gets security.evm extended attribute.
+ * Returns LIB_SUCCESS on success or LIB_ERROR_* on error
+ */
 int evm_get_xattr(const char *path, char **hash);
+
+/*
+ * Gets file state (file_state enum).
+ * Returns LIB_SUCCESS on success or LIB_ERROR_* on error
+ */
 int get_file_state(const char *path, int *state);
 
+/*
+ * Returns policy (via param) as a array of char* (NULL terminated).
+ * E.g.: {"dont_measure fsmagic=0xf97cff8c",
+ *        "measure func=MMAP_CHECK mask=MAY_EXEC",
+ *        "appraise fowner=0",
+ *        NULL}
+ * The memory have to be free by the caller. The best way the free the
+ * memory is to call: ima_free_policy(char **policy)
+ * Returns LIB_SUCCESS on success or LIB_ERROR_* on error
+ */
 int ima_get_policy(char*** policy);
+
+/*
+ * For freeing the memory allocated for the policy
+ * Returns LIB_SUCCESS on success or LIB_ERROR_* on error
+ */
 int ima_free_policy(char **policy);
+
+/*
+ * Tries to load policy from char **policy into the kernel.
+ * The caller needs also to provide the signature as a char*
+ * Returns LIB_SUCCESS on success or LIB_ERROR_* on error
+ */
 int ima_set_policy(const char **policy, const char *policy_sig);
+
+/*
+ * Tries to load policy from file into the kernel. Signature for
+ * the policy must be present in the same location as policy_path.sig file.
+ * E.g. for the call:
+ *     ima_set_policy_file("/path/to/policy");
+ *     The signature must exist in location: /path/to/policy.sig
+ * Returns LIB_SUCCESS on success or LIB_ERROR_* on error
+ */
 int ima_set_policy_file(const char *policy_path);
 
 #ifdef __cplusplus
diff --git a/src/libimaevm.c b/src/libimaevm.c
index 99c5ac8..aaa21fe 100644
--- a/src/libimaevm.c
+++ b/src/libimaevm.c
@@ -965,7 +965,7 @@ int evm_set_state(int state)
 	return LIB_SUCCESS;
 }
 
-int ima_set_xattr(const char *path)
+int ima_set_xattr(const char *path, const char *hash)
 {
 	int ret;