Skip to content

Commit 1cf0043

Browse files
krzydynkrzydyn
committed
Complete API documentation
Change-Id: I1db65d8683dec66b8c4fb741bc993e1e9966e6d4
1 parent 17e6e54 commit 1cf0043

File tree

2 files changed

+113
-19
lines changed

2 files changed

+113
-19
lines changed

‎src/Tizen.Security.TEEC/Tizen.Security.TEEC/Libteec.cs

+35-19
Original file line numberDiff line numberDiff line change
@@ -26,20 +26,27 @@ namespace Tizen.Security.TEEC
2626
/// </summary>
2727
public class LoginMethod
2828
{
29-
public const uint Public = 0x00000000; ///< No login data is provided.
30-
public const uint User = 0x00000001; ///< Login data about the user running the Client Application process is provided.
31-
public const uint Group = 0x00000002; ///< Login data about the group running the Client Application process is provided.
32-
public const uint Application = 0x00000003; ///< Login data about the running Client Application itself is provided.
29+
/// <summary>No login data is provided.</summary>
30+
public const uint Public = 0x00000000;
31+
/// <summary>Login data about the user running the Client Application process is provided.</summary>
32+
public const uint User = 0x00000001;
33+
/// <summary>Login data about the group running the Client Application process is provided.</summary>
34+
public const uint Group = 0x00000002;
35+
/// <summary>Login data about the running Client Application itself is provided.</summary>
36+
public const uint Application = 0x00000003;
3337
}
3438

3539
/// <summary>
3640
/// This type denotes Value parameter
3741
/// </summary>
3842
public enum TEFValueType : UInt32
3943
{
40-
Input = 0x00000001, ///< The Parameter is a TEFValueType tagged as input.
41-
Output = 0x00000002, ///< The Parameter is a TEFValueType tagged as output.
42-
InOut = 0x00000003, ///< The Parameter is a TEFValueType tagged as both as input and output.
44+
/// <summary>The Parameter is a ValueType tagged as input.</summary>
45+
Input = 0x00000001,
46+
/// <summary>The Parameter is a ValueType tagged as output.</summary>
47+
Output = 0x00000002,
48+
/// <summary>The Parameter is a ValueType tagged as both as input and output.</summary>
49+
InOut = 0x00000003,
4350
}
4451

4552
/// <summary>
@@ -48,20 +55,27 @@ public enum TEFValueType : UInt32
4855
/// </summary>
4956
public enum TEFTempMemoryType : UInt32
5057
{
51-
Input = 0x00000005, ///< The Parameter is a TEFTempMemoryType and is tagged as input
52-
Output = 0x00000006, ///< Same as Input, but the Memory Reference is tagged as output
53-
InOut = 0x00000007, ///< A Temporary Memory Reference tagged as both input and output.
58+
/// <summary>The Parameter is a TempMemoryType and is tagged as input.</summary>
59+
Input = 0x00000005,
60+
/// <summary>Same as Input, but the Memory Reference is tagged as output.</summary>
61+
Output = 0x00000006,
62+
/// <summary>A Temporary Memory Reference tagged as both input and output.</summary>
63+
InOut = 0x00000007,
5464
}
5565

5666
/// <summary>
5767
/// This type denotes SharedMemoryReference parameter
5868
/// </summary>
5969
public enum TEFRegisteredMemoryType : UInt32
6070
{
61-
Whole = 0x0000000C, ///< The Parameter is a Registered Memory Reference that refers to the entirety of its parent Shared Memory block.
62-
PartialInput = 0x0000000D, ///< A Registered Memory Reference structure that refers to a partial region of its parent Shared Memory block and is tagged as input.
63-
PartialOutput = 0x0000000E, ///< A Registered Memory Reference structure that refers to a partial region of its parent Shared Memory block and is tagged as output.
64-
PartialInOut = 0x0000000F, ///< A Registered Memory Reference structure that refers to a partial region of its parent Shared Memory block and is tagged as both input and output
71+
/// <summary>The Parameter is a Registered Memory Reference that refers to the entirety of its parent Shared Memory block.</summary>
72+
Whole = 0x0000000C,
73+
/// <summary>A Registered Memory Reference structure that refers to a partial region of its parent Shared Memory block and is tagged as input.</summary>
74+
PartialInput = 0x0000000D,
75+
/// <summary>A Registered Memory Reference structure that refers to a partial region of its parent Shared Memory block and is tagged as output.</summary>
76+
PartialOutput = 0x0000000E,
77+
/// <summary>A Registered Memory Reference structure that refers to a partial region of its parent Shared Memory block and is tagged as both input and output.</summary>
78+
PartialInOut = 0x0000000F,
6579
}
6680

6781
/// <summary>
@@ -70,8 +84,10 @@ public enum TEFRegisteredMemoryType : UInt32
7084
[Flags]
7185
public enum SharedMemoryFlags : UInt32
7286
{
73-
Input = 0x00000001, ///< A flag indicates Shared Memory can be read
74-
Output = 0x00000002, ///< A flag indicates Shared Memory can be written
87+
/// <summary>A flag indicates Shared Memory can be read.</summary>
88+
Input = 0x00000001,
89+
/// <summary>A flag indicates Shared Memory can be written.</summary>
90+
Output = 0x00000002,
7591
}
7692

7793
/// <summary>
@@ -333,7 +349,7 @@ public void Dispose() {
333349
/// There can be up to four Parameter objects given in the {paramlist} array
334350
/// </summary>
335351
/// <param name="destination">The UUID of destination TA</param>
336-
/// <param name="loginMethod">The authentication algorithm @see LoginMethod</param>
352+
/// <param name="loginMethod">The authentication algorithm <see cref="LoginMethod" /></param>
337353
/// <param name="connectionData">The data to be verified by given login method</param>
338354
/// <param name="paramlist">The parameters to be passed to TA open-session-callback</param>
339355
public Session OpenSession(Guid destination, uint loginMethod, byte[] connectionData, Parameter[] paramlist)
@@ -358,7 +374,7 @@ public Session OpenSession(Guid destination)
358374
/// @see OpenSession(Guid destination, uint connectionMethod, byte[] connectionData, Parameter[] paramlist, CancellationToken token)
359375
/// </summary>
360376
/// <param name="destination">The UUID of destination TA</param>
361-
/// <param name="loginMethod">The authentication algorithm @see LoginMethod</param>
377+
/// <param name="loginMethod">The authentication algorithm <see cref="LoginMethod" /></param>
362378
/// <param name="connectionData">The data to be verified by given login method</param>
363379
/// <param name="paramlist">The parameters to be passed to TA open-session-callback</param>
364380
/// <param name="token">The token for task manipulation</param>
@@ -388,7 +404,7 @@ public Session OpenSession(Guid destination)
388404
/// <summary>
389405
/// This function registers a block of existing Client Application memory as a block of Shared Memory within
390406
/// the scope of the specified Context, in accordance with the parameters.
391-
/// The input {memaddr} MUST point to the shared memory region to register
407+
/// The input <paramref name="memaddr"/> MUST point to the shared memory region to register
392408
/// </summary>
393409
/// <param name="memaddr">The address of shared memory</param>
394410
/// <param name="size">The size of shared memory</param>

‎src/Tizen.Security.TEEC/Tizen.Security.TEEC/NamespaceDoc.cs

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
/**
2+
<summary>
3+
The communication API for connecting Client Applications running in a rich operating environment
4+
with security related Trusted Applications running inside a Trusted Execution Environment (TEE).
5+
</summary>
6+
7+
<remarks>
8+
<h2>Overview</h2>
9+
<para>
10+
A TEE provides an execution environment with security capabilities, which are either available to Trusted Applications
11+
running inside the TEE or exposed externally to Client Applications.
12+
The TEE Client API concentrates on the interface to enable efficient communications between
13+
a Client Application and a Trusted Application running inside the TEE.
14+
Higher level standards and protocol layers may be built on top of the foundation
15+
provided by the TEE Client API – for example, to cover common tasks such as secure storage,
16+
cryptography, and run-time installation of new Trusted Applications.
17+
The separation between the rich environment and the TEE is guaranted.
18+
</para>
19+
<para>
20+
The key design principles of the TEE Client API are:
21+
<list type="bullet">
22+
<item>
23+
<term>Client-side memory allocations</term>
24+
<description>
25+
Where possible the design of the TEE Client API has placed the responsibility for memory
26+
allocation on the calling Client Application code. This gives the Client developer choice of
27+
memory allocation locations, enabling simple optimizations such as stack-based allocation
28+
or enhanced flexibility using placements in static global memory or thread-local storage.<br />
29+
This design choice is evident in the API by the use of pointers to structures rather than
30+
opaque handles to represent any manipulated objects.
31+
</description>
32+
</item>
33+
<item>
34+
<term>Aim for zero-copy data transfer</term>
35+
<description>
36+
The features of the TEE Client API are chosen to maximize the possibility of zero-copy
37+
data transfer between the Client Application and the Trusted Application.<br />
38+
However, short messages can also be passed by copy, which avoids the overhead of
39+
sharing memory.
40+
</description>
41+
</item>
42+
<item>
43+
<term>Support memory sharing by pointers</term>
44+
<description>
45+
The TEE Client API will be used to implement higher-level APIs, such as cryptography or
46+
secure storage, where the caller will often provide memory buffers for input or output data
47+
using simple C pointers. The TEE Client API must allow efficient sharing of this type of
48+
memory, and as such does not rely on the Client Application being able to use bulk
49+
memory buffers allocated by the TEE Client API.
50+
</description>
51+
</item>
52+
<item>
53+
<term>Specify only communication mechanisms</term>
54+
<description>
55+
This API focuses on defining the underlying communications channel. It does not define
56+
the format of the messages which pass over the channel, or the protocols used by specific
57+
Trusted Applications.
58+
</description>
59+
</item>
60+
61+
</list>
62+
</para>
63+
</remarks>
64+
65+
<example>
66+
The following example demonstrates how to invoke command on Trused Application.
67+
<code>
68+
Guid ta_uuid = new Guid("TA-guid-put-here");
69+
Context ctx = new Context(null);
70+
Session ses = ctx.OpenSession(ta_uuid);
71+
Parameter[] p = { new Value(1,2,TEFValueType.In) };
72+
ses.InvokeCommand(1, p);
73+
ses.Close();
74+
ctx.Dispose();
75+
</code>
76+
</example>
77+
*/
78+
namespace Tizen.Security.TEEC {}

0 commit comments

Comments
 (0)