libekmfweb: Change the key state

EKMF Web maintains a key state for each key. Keys can be in state
PRE-ACTIVATION, ACTIVE, DEACTIVATED, COMPROMISED, DESTROYED, and
DESTROYED-COMPROMISED. Key states can be changed as defined in NIST
Special Publication 800-57 Part 1.

Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com>
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>

include/ekmfweb/ekmfweb.h

@@ -533,6 +533,13 @@ struct ekmf_key_info {
 	const char *updated_on;
 };
 
+#define EKMF_KEY_STATE_PRE_ACTIVATION		"PRE-ACTIVATION"
+#define EKMF_KEY_STATE_ACTIVE			"ACTIVE"
+#define EKMF_KEY_STATE_DEACTIVATED		"DEACTIVATED"
+#define EKMF_KEY_STATE_COMPROMISED		"COMPROMISED"
+#define EKMF_KEY_STATE_DESTROYED		"DESTROYED"
+#define EKMF_KEY_STATE_DESTROYED_COMPROMISED	"DESTROYED-COMPROMISED"
+
 /**
  * Callback function used with the ekmf_list_templates function. This
  * callback is called for each template found.
@@ -773,6 +780,41 @@ int ekmf_get_key_info(const struct ekmf_config *config, CURL **curl_handle,
 		      const char *key_uuid, struct ekmf_key_info **key,
 		      char **error_msg, bool verbose);
 
+/**
+ * Changes the state of a key identified by its UUID. To update a key,
+ * the timestamp from the last update is required. This can be found in
+ * the key info struct in field update_on.
+ *
+ * To perform a single request, set curl_handle to NULL. This will cause the
+ * function to initialize a new CURL handle, use it, and destroy it.
+ * If you plan to perform multiple requests to the same host, supply the address
+ * of a CURL pointer that is initially NULL. This function will then initialize
+ * a new CURL handle on the first call. On subsequent calls, pass in the address
+ * of the same CURL pointer so that the CURL handle is reused. After the last
+ * request, the CURL handle must be destroyed by calling ekmf_curl_destroy).
+ *
+ * @param config            the configuration structure
+ * @param curl_handle       address of a CURL handle used for reusing the same
+ *                          CURL handle with multiple requests.
+ * @param key_uuid          the UUID of the key to get info for
+ * @param new_state         the new state of the key
+ * @param updated_on        the timestamp of the last update (must match)
+ * @param error_msg         on return: If not NULL, then a textual error message
+ *                          is returned in case of a failing request. The caller
+ *                          must free the error string when it is not NULL.
+ * @param verbose           if true, verbose messages are printed
+ *
+ * @returns zero for success, a negative errno in case of an error.
+ *          -EACCES is returned, if no or no valid login token is available.
+ *          -EPERM is returned if the login token does not have permission to
+ *          update the key.
+ *          -EAGAIN is returned if the timestamp does not match, indicating that
+ *          the key has been updated in the meantime.
+ */
+int ekmf_set_key_state(const struct ekmf_config *config, CURL **curl_handle,
+		       const char *key_uuid, const char *new_state,
+		       const char *updated_on, char **error_msg, bool verbose);
+
 /**
  * Clones a key info structure by making a deep copy of all strings and
  * arrays.