Add comments to header file

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

diff --git a/src/imaevm.h b/src/imaevm.h
index d203eb1..7c64a07 100644 (file)
--- 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 (file)
--- 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;