You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@teaclave.apache.org by ms...@apache.org on 2021/02/09 22:19:39 UTC
[incubator-teaclave] branch master updated: Add doc of C bindings
This is an automated email from the ASF dual-hosted git repository.
mssun pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-teaclave.git
The following commit(s) were added to refs/heads/master by this push:
new 0e4d5d0 Add doc of C bindings
0e4d5d0 is described below
commit 0e4d5d085ec096bcddb65913a75fb5b3cf240eb7
Author: Mingshen Sun <bo...@mssun.me>
AuthorDate: Tue Feb 9 11:42:22 2021 -0800
Add doc of C bindings
---
sdk/c/teaclave_client_sdk.h | 259 ++++++++++++++++++++++++++++++++++++++++++++
sdk/rust/src/bindings.rs | 69 ++++++++++++
2 files changed, 328 insertions(+)
diff --git a/sdk/c/teaclave_client_sdk.h b/sdk/c/teaclave_client_sdk.h
index 96f40dd..2fb38e1 100644
--- a/sdk/c/teaclave_client_sdk.h
+++ b/sdk/c/teaclave_client_sdk.h
@@ -34,89 +34,348 @@ typedef struct AuthenticationClient AuthenticationClient;
typedef struct FrontendClient FrontendClient;
+/**
+ * Connect to Teaclave Authentication Service.
+ *
+ * This function connects and establishes trusted channel to the remote
+ * authentication service with `address`. The function gets *enclave info* from
+ * the file located in `enclave_info_path`. The file in `as_root_ca_cert_path`
+ * will be used to verify the attestation report from the remote service.
+ *
+ * # Arguments
+ *
+ * * `address`: address of remote services, normally,it's a domain name with port number.
+ * * `enclave_info_path`: file path of the *enclave info* TOML file.
+ * * `as_root_ca_cert_path`: file path of the certificate for remote attestation service.
+ *
+ * # Return
+ *
+ * * The function returns an opaque pointer (handle) of the service. On error,
+ * the function returns NULL.
+ */
struct AuthenticationClient *teaclave_connect_authentication_service(const char *address,
const char *enclave_info_path,
const char *as_root_ca_cert_path);
+/**
+ * Close and free the authentication service handle, i.e., the
+ * `AuthenticaionClient` type opaque pointer. The function returns 0 for
+ * success. On error, the function returns 1.
+ */
int teaclave_close_authentication_service(struct AuthenticationClient *client);
+/**
+ * Register a new user with `user_id` and `user_password`. The function returns
+ * 0 for success. On error, the function returns 1.
+ */
int teaclave_user_register(struct AuthenticationClient *client,
const char *user_id,
const char *user_password);
+/**
+ * Login a new user with `user_id` and `user_password`. The login session token
+ * will be save in the `token` buffer, and length will be set in the
+ * `token_len` argument. The function returns 0 for success. On error, the
+ * function returns 1.
+ */
int teaclave_user_login(struct AuthenticationClient *client,
const char *user_id,
const char *user_password,
char *token,
size_t *token_len);
+/**
+ * Connect to Teaclave Frontend Service.
+ *
+ * This function connects and establishes trusted channel to the remote
+ * frontend service with `address`. The function gets *enclave info* from
+ * the file located in `enclave_info_path`. The file in `as_root_ca_cert_path`
+ * will be used to verify the attestation report from the remote service.
+ *
+ * # Arguments
+ *
+ * * `address`: address of remote services, normally,it's a domain name with port number.
+ * * `enclave_info_path`: file path of the *enclave info* TOML file.
+ * * `as_root_ca_cert_path`: file path of the certificate for remote attestation service.
+ *
+ * # Return
+ *
+ * * The function returns an opaque pointer (handle) of the service. On error,
+ * the function returns NULL.
+ */
struct FrontendClient *teaclave_connect_frontend_service(const char *address,
const char *enclave_info_path,
const char *as_root_ca_cert_path);
+/**
+ * Close and free the frontend service handle, i.e., the `FrontendClient` type
+ * opaque pointer. The function returns 0 for success. On error, the function
+ * returns 1.
+ */
int teaclave_close_frontend_service(struct FrontendClient *client);
+/**
+ * Set user's credential with `user_id` and `user_token`. The function returns
+ * 0 for success. On error, the function returns 1.
+ */
int teaclave_set_credential(struct FrontendClient *client,
const char *user_id,
const char *user_token);
+/**
+ * Invoke task with `task_id`. The function returns 0 for success. On error,
+ * the function returns 1.
+ */
int teaclave_invoke_task(struct FrontendClient *client, const char *task_id);
+/**
+ * Get task result of `task_id`. The result will be save in the `task_result`
+ * buffer, and set corresponding `task_result_len` argument. Note that this is
+ * a blocking function and wait for the return of the task. The function
+ * returns 0 for success. On error, the function returns 1.
+ */
int teaclave_get_task_result(struct FrontendClient *client,
const char *task_id,
char *task_result,
size_t *task_result_len);
+/**
+ * Send JSON serialized request to the service with the `client` and
+ * get the serialized response.
+ *
+ * # Arguments
+ *
+ * * `client`: service client.
+ * * `serialized_request`; JSON serialized request
+ * * `serialized_response`: buffer to store the JSON serialized response.
+ * * `serialized_response_len`: length of the allocated
+ * `serialized_response`, will be set as the length of
+ * `serialized_response` when return successfully.
+ *
+ * # Return
+ *
+ * The function returns 0 for success. On error, the function returns 1.
+ */
int teaclave_user_register_serialized(struct AuthenticationClient *client,
const char *serialized_request,
char *serialized_response,
size_t *serialized_response_len);
+/**
+ * Send JSON serialized request to the service with the `client` and
+ * get the serialized response.
+ *
+ * # Arguments
+ *
+ * * `client`: service client.
+ * * `serialized_request`; JSON serialized request
+ * * `serialized_response`: buffer to store the JSON serialized response.
+ * * `serialized_response_len`: length of the allocated
+ * `serialized_response`, will be set as the length of
+ * `serialized_response` when return successfully.
+ *
+ * # Return
+ *
+ * The function returns 0 for success. On error, the function returns 1.
+ */
int teaclave_user_login_serialized(struct AuthenticationClient *client,
const char *serialized_request,
char *serialized_response,
size_t *serialized_response_len);
+/**
+ * Send JSON serialized request to the service with the `client` and
+ * get the serialized response.
+ *
+ * # Arguments
+ *
+ * * `client`: service client.
+ * * `serialized_request`; JSON serialized request
+ * * `serialized_response`: buffer to store the JSON serialized response.
+ * * `serialized_response_len`: length of the allocated
+ * `serialized_response`, will be set as the length of
+ * `serialized_response` when return successfully.
+ *
+ * # Return
+ *
+ * The function returns 0 for success. On error, the function returns 1.
+ */
int teaclave_register_function_serialized(struct FrontendClient *client,
const char *serialized_request,
char *serialized_response,
size_t *serialized_response_len);
+/**
+ * Send JSON serialized request to the service with the `client` and
+ * get the serialized response.
+ *
+ * # Arguments
+ *
+ * * `client`: service client.
+ * * `serialized_request`; JSON serialized request
+ * * `serialized_response`: buffer to store the JSON serialized response.
+ * * `serialized_response_len`: length of the allocated
+ * `serialized_response`, will be set as the length of
+ * `serialized_response` when return successfully.
+ *
+ * # Return
+ *
+ * The function returns 0 for success. On error, the function returns 1.
+ */
int teaclave_get_function_serialized(struct FrontendClient *client,
const char *serialized_request,
char *serialized_response,
size_t *serialized_response_len);
+/**
+ * Send JSON serialized request to the service with the `client` and
+ * get the serialized response.
+ *
+ * # Arguments
+ *
+ * * `client`: service client.
+ * * `serialized_request`; JSON serialized request
+ * * `serialized_response`: buffer to store the JSON serialized response.
+ * * `serialized_response_len`: length of the allocated
+ * `serialized_response`, will be set as the length of
+ * `serialized_response` when return successfully.
+ *
+ * # Return
+ *
+ * The function returns 0 for success. On error, the function returns 1.
+ */
int teaclave_register_input_file_serialized(struct FrontendClient *client,
const char *serialized_request,
char *serialized_response,
size_t *serialized_response_len);
+/**
+ * Send JSON serialized request to the service with the `client` and
+ * get the serialized response.
+ *
+ * # Arguments
+ *
+ * * `client`: service client.
+ * * `serialized_request`; JSON serialized request
+ * * `serialized_response`: buffer to store the JSON serialized response.
+ * * `serialized_response_len`: length of the allocated
+ * `serialized_response`, will be set as the length of
+ * `serialized_response` when return successfully.
+ *
+ * # Return
+ *
+ * The function returns 0 for success. On error, the function returns 1.
+ */
int teaclave_register_output_file_serialized(struct FrontendClient *client,
const char *serialized_request,
char *serialized_response,
size_t *serialized_response_len);
+/**
+ * Send JSON serialized request to the service with the `client` and
+ * get the serialized response.
+ *
+ * # Arguments
+ *
+ * * `client`: service client.
+ * * `serialized_request`; JSON serialized request
+ * * `serialized_response`: buffer to store the JSON serialized response.
+ * * `serialized_response_len`: length of the allocated
+ * `serialized_response`, will be set as the length of
+ * `serialized_response` when return successfully.
+ *
+ * # Return
+ *
+ * The function returns 0 for success. On error, the function returns 1.
+ */
int teaclave_create_task_serialized(struct FrontendClient *client,
const char *serialized_request,
char *serialized_response,
size_t *serialized_response_len);
+/**
+ * Send JSON serialized request to the service with the `client` and
+ * get the serialized response.
+ *
+ * # Arguments
+ *
+ * * `client`: service client.
+ * * `serialized_request`; JSON serialized request
+ * * `serialized_response`: buffer to store the JSON serialized response.
+ * * `serialized_response_len`: length of the allocated
+ * `serialized_response`, will be set as the length of
+ * `serialized_response` when return successfully.
+ *
+ * # Return
+ *
+ * The function returns 0 for success. On error, the function returns 1.
+ */
int teaclave_assign_data_serialized(struct FrontendClient *client,
const char *serialized_request,
char *serialized_response,
size_t *serialized_response_len);
+/**
+ * Send JSON serialized request to the service with the `client` and
+ * get the serialized response.
+ *
+ * # Arguments
+ *
+ * * `client`: service client.
+ * * `serialized_request`; JSON serialized request
+ * * `serialized_response`: buffer to store the JSON serialized response.
+ * * `serialized_response_len`: length of the allocated
+ * `serialized_response`, will be set as the length of
+ * `serialized_response` when return successfully.
+ *
+ * # Return
+ *
+ * The function returns 0 for success. On error, the function returns 1.
+ */
int teaclave_approve_task_serialized(struct FrontendClient *client,
const char *serialized_request,
char *serialized_response,
size_t *serialized_response_len);
+/**
+ * Send JSON serialized request to the service with the `client` and
+ * get the serialized response.
+ *
+ * # Arguments
+ *
+ * * `client`: service client.
+ * * `serialized_request`; JSON serialized request
+ * * `serialized_response`: buffer to store the JSON serialized response.
+ * * `serialized_response_len`: length of the allocated
+ * `serialized_response`, will be set as the length of
+ * `serialized_response` when return successfully.
+ *
+ * # Return
+ *
+ * The function returns 0 for success. On error, the function returns 1.
+ */
int teaclave_invoke_task_serialized(struct FrontendClient *client,
const char *serialized_request,
char *serialized_response,
size_t *serialized_response_len);
+/**
+ * Send JSON serialized request to the service with the `client` and
+ * get the serialized response.
+ *
+ * # Arguments
+ *
+ * * `client`: service client.
+ * * `serialized_request`; JSON serialized request
+ * * `serialized_response`: buffer to store the JSON serialized response.
+ * * `serialized_response_len`: length of the allocated
+ * `serialized_response`, will be set as the length of
+ * `serialized_response` when return successfully.
+ *
+ * # Return
+ *
+ * The function returns 0 for success. On error, the function returns 1.
+ */
int teaclave_get_task_serialized(struct FrontendClient *client,
const char *serialized_request,
char *serialized_response,
diff --git a/sdk/rust/src/bindings.rs b/sdk/rust/src/bindings.rs
index 41386af..be7b072 100644
--- a/sdk/rust/src/bindings.rs
+++ b/sdk/rust/src/bindings.rs
@@ -45,6 +45,23 @@ macro_rules! unwrap_or_return_one {
};
}
+/// Connect to Teaclave Authentication Service.
+///
+/// This function connects and establishes trusted channel to the remote
+/// authentication service with `address`. The function gets *enclave info* from
+/// the file located in `enclave_info_path`. The file in `as_root_ca_cert_path`
+/// will be used to verify the attestation report from the remote service.
+///
+/// # Arguments
+///
+/// * `address`: address of remote services, normally,it's a domain name with port number.
+/// * `enclave_info_path`: file path of the *enclave info* TOML file.
+/// * `as_root_ca_cert_path`: file path of the certificate for remote attestation service.
+///
+/// # Return
+///
+/// * The function returns an opaque pointer (handle) of the service. On error,
+/// the function returns NULL.
#[no_mangle]
pub extern "C" fn teaclave_connect_authentication_service(
address: *const c_char,
@@ -78,6 +95,9 @@ pub extern "C" fn teaclave_connect_authentication_service(
Box::into_raw(Box::new(client))
}
+/// Close and free the authentication service handle, i.e., the
+/// `AuthenticaionClient` type opaque pointer. The function returns 0 for
+/// success. On error, the function returns 1.
#[no_mangle]
pub unsafe extern "C" fn teaclave_close_authentication_service(
client: *mut AuthenticationClient,
@@ -91,6 +111,8 @@ pub unsafe extern "C" fn teaclave_close_authentication_service(
0
}
+/// Register a new user with `user_id` and `user_password`. The function returns
+/// 0 for success. On error, the function returns 1.
#[no_mangle]
pub extern "C" fn teaclave_user_register(
client: &mut AuthenticationClient,
@@ -111,6 +133,10 @@ pub extern "C" fn teaclave_user_register(
0
}
+/// Login a new user with `user_id` and `user_password`. The login session token
+/// will be save in the `token` buffer, and length will be set in the
+/// `token_len` argument. The function returns 0 for success. On error, the
+/// function returns 1.
#[no_mangle]
pub extern "C" fn teaclave_user_login(
client: &mut AuthenticationClient,
@@ -147,6 +173,23 @@ pub extern "C" fn teaclave_user_login(
0
}
+/// Connect to Teaclave Frontend Service.
+///
+/// This function connects and establishes trusted channel to the remote
+/// frontend service with `address`. The function gets *enclave info* from
+/// the file located in `enclave_info_path`. The file in `as_root_ca_cert_path`
+/// will be used to verify the attestation report from the remote service.
+///
+/// # Arguments
+///
+/// * `address`: address of remote services, normally,it's a domain name with port number.
+/// * `enclave_info_path`: file path of the *enclave info* TOML file.
+/// * `as_root_ca_cert_path`: file path of the certificate for remote attestation service.
+///
+/// # Return
+///
+/// * The function returns an opaque pointer (handle) of the service. On error,
+/// the function returns NULL.
#[no_mangle]
pub extern "C" fn teaclave_connect_frontend_service(
address: *const c_char,
@@ -180,6 +223,9 @@ pub extern "C" fn teaclave_connect_frontend_service(
Box::into_raw(Box::new(client))
}
+/// Close and free the frontend service handle, i.e., the `FrontendClient` type
+/// opaque pointer. The function returns 0 for success. On error, the function
+/// returns 1.
#[no_mangle]
pub unsafe extern "C" fn teaclave_close_frontend_service(client: *mut FrontendClient) -> c_int {
if client.is_null() {
@@ -191,6 +237,8 @@ pub unsafe extern "C" fn teaclave_close_frontend_service(client: *mut FrontendCl
0
}
+/// Set user's credential with `user_id` and `user_token`. The function returns
+/// 0 for success. On error, the function returns 1.
#[no_mangle]
pub extern "C" fn teaclave_set_credential(
client: &mut FrontendClient,
@@ -208,6 +256,8 @@ pub extern "C" fn teaclave_set_credential(
0
}
+/// Invoke task with `task_id`. The function returns 0 for success. On error,
+/// the function returns 1.
#[no_mangle]
pub extern "C" fn teaclave_invoke_task(
client: &mut FrontendClient,
@@ -224,6 +274,10 @@ pub extern "C" fn teaclave_invoke_task(
}
}
+/// Get task result of `task_id`. The result will be save in the `task_result`
+/// buffer, and set corresponding `task_result_len` argument. Note that this is
+/// a blocking function and wait for the return of the task. The function
+/// returns 0 for success. On error, the function returns 1.
#[no_mangle]
pub extern "C" fn teaclave_get_task_result(
client: &mut FrontendClient,
@@ -254,6 +308,21 @@ pub extern "C" fn teaclave_get_task_result(
macro_rules! generate_function_serialized {
( $client_type:ident, $c_function_name:ident, $rust_function_name:ident) => {
+ /// Send JSON serialized request to the service with the `client` and
+ /// get the serialized response.
+ ///
+ /// # Arguments
+ ///
+ /// * `client`: service client.
+ /// * `serialized_request`; JSON serialized request
+ /// * `serialized_response`: buffer to store the JSON serialized response.
+ /// * `serialized_response_len`: length of the allocated
+ /// `serialized_response`, will be set as the length of
+ /// `serialized_response` when return successfully.
+ ///
+ /// # Return
+ ///
+ /// The function returns 0 for success. On error, the function returns 1.
#[no_mangle]
pub extern "C" fn $c_function_name(
client: &mut $client_type,
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@teaclave.apache.org
For additional commands, e-mail: commits-help@teaclave.apache.org