From: Krzysztof Dynowski Date: Fri, 19 May 2017 09:29:51 +0000 (+0200) Subject: Update API documentation (feature,privilege,exception) X-Git-Tag: submit/tizen/20170522.082336~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F73%2F130173%2F7;p=platform%2Fcore%2Fcsapi%2Flibteec.git Update API documentation (feature,privilege,exception) Change-Id: I75123295aac4fc113607296b1bd7fade7fb92188 --- diff --git a/Tizen.Security.TEEC/Tizen.Security.TEEC/Libteec.cs b/Tizen.Security.TEEC/Tizen.Security.TEEC/Libteec.cs index d24b793..437e13e 100644 --- a/Tizen.Security.TEEC/Tizen.Security.TEEC/Libteec.cs +++ b/Tizen.Security.TEEC/Tizen.Security.TEEC/Libteec.cs @@ -24,6 +24,7 @@ namespace Tizen.Security.TEEC /// /// This type denotes Session Login Method used in OpenSession /// + /// 4 public class LoginMethod { /// No login data is provided. @@ -39,6 +40,7 @@ namespace Tizen.Security.TEEC /// /// This type denotes Value parameter /// + /// 4 public enum TEFValueType : UInt32 { /// The Parameter is a ValueType tagged as input. @@ -53,6 +55,7 @@ namespace Tizen.Security.TEEC /// This type denotes TempMemoryReference parameter /// describing a region of memory which needs to be temporarily registered for the duration of the operation. /// + /// 4 public enum TEFTempMemoryType : UInt32 { /// The Parameter is a TempMemoryType and is tagged as input. @@ -66,6 +69,7 @@ namespace Tizen.Security.TEEC /// /// This type denotes SharedMemoryReference parameter /// + /// 4 public enum TEFRegisteredMemoryType : UInt32 { /// The Parameter is a Registered Memory Reference that refers to the entirety of its parent Shared Memory block. @@ -81,6 +85,7 @@ namespace Tizen.Security.TEEC /// /// This type denotes SharedMemory access direction /// + /// 4 [Flags] public enum SharedMemoryFlags : UInt32 { @@ -94,6 +99,7 @@ namespace Tizen.Security.TEEC /// This type denotes a Shared Memory block which has either been registered /// with the implementation or allocated by it. /// + /// 4 public sealed class SharedMemory { internal Interop.TEEC_SharedMemory shm; @@ -104,6 +110,7 @@ namespace Tizen.Security.TEEC /// /// This property represents shared memory size in bytes. /// + /// 4 public UInt32 Size { get { return shm.size; } @@ -111,6 +118,7 @@ namespace Tizen.Security.TEEC /// /// This property represents start address of shared memory block. /// + /// 4 public IntPtr Address { get { return shm.buffer; } @@ -120,6 +128,9 @@ namespace Tizen.Security.TEEC /// This function makes a copy and is designed for convenient operations on small buffers. /// For large buffers direct address should be used. /// + /// 4 + /// Source data buffer to copy data from + /// Starting offset in source shared memory public void SetData(byte[] data, int dstOffs) { //TODO copy data into shared memory starting at given offset @@ -128,6 +139,9 @@ namespace Tizen.Security.TEEC /// This function makes a copy and is designed for convenient operations on small buffers. /// For large buffers direct address should be used. /// + /// 4 + /// Destination data buffer to copy data into + /// Starting offset in destination shared memory public void GetData(byte[] data, int srcOffs) { //TODO copy data from shared memory starting at given offset @@ -139,6 +153,7 @@ namespace Tizen.Security.TEEC /// also used for cancellation of operations, which may be desirable even if no payload is passed. /// Parameters are used to exchange data between CA and TA /// + /// 4 public abstract class Parameter { internal Parameter(uint t) @@ -151,6 +166,7 @@ namespace Tizen.Security.TEEC /// /// This type defines a template for parameter types. /// + /// 4 public abstract class BaseParameter : Parameter where TEnum : struct, IComparable, IFormattable, IConvertible // as close to Enum as possible { internal BaseParameter(TEnum t) : base((uint)(object)t) @@ -161,14 +177,23 @@ namespace Tizen.Security.TEEC /// /// This property represents access type to this parameter. /// + /// 4 public TEnum Type { get; } } /// /// This type defines a temporary memory reference. /// + /// 4 public sealed class TempMemoryReference : BaseParameter { + /// + /// Constructs Prameter object which holds info about temporary memory copied to/from TA + /// + /// 4 + /// Address of allocated memory buffer + /// Size of the buffer + /// Kind of access allowed for TA public TempMemoryReference(IntPtr buffer, uint size, TEFTempMemoryType type) : base(type) { @@ -178,18 +203,29 @@ namespace Tizen.Security.TEEC /// /// This property represents memory address of buffer. /// + /// 4 public IntPtr Buffer { get; } /// /// This property represents size of buffer. /// + /// 4 public uint Size { get; } }; /// /// This type defines a memory reference that uses a pre-registered or pre-allocated Shared Memory block. /// + /// 4 public sealed class RegisteredMemoryReference : BaseParameter { + /// + /// Constructs Prameter object which holds info about registered memory shared with TA + /// + /// 4 + /// Shared memory - registered or allocated + /// Size of the buffer part + /// Offset of buffer in shared memory + /// Kind of access allowed for TA public RegisteredMemoryReference(SharedMemory parent, uint size, uint offset, TEFRegisteredMemoryType type) : base(type) { @@ -200,14 +236,17 @@ namespace Tizen.Security.TEEC /// /// This property represents SharedMemory that is referred to. /// + /// 4 public SharedMemory Parent { get; } /// /// This property represents size (in bytes) of SharedMemory. /// + /// 4 public uint Size { get; } /// /// This property represents offset (in bytes) from the begin of SharedMemory. /// + /// 4 public uint Offset { get; } }; @@ -215,8 +254,16 @@ namespace Tizen.Security.TEEC /// This type defines a parameter that is not referencing shared memory, but carries instead small raw data /// passed by value. /// + /// 4 public sealed class Value : BaseParameter { + /// + /// Constructs Prameter object which holds info about int values copied to/from TA + /// + /// 4 + /// User paramter A + /// User paramter B + /// Kind of access allowed for TA public Value(uint a, uint b, TEFValueType type) : base(type) { @@ -226,10 +273,12 @@ namespace Tizen.Security.TEEC /// /// This property represents unsigned integer A. /// + /// 4 public uint A { get; } /// /// This property represents unsigned integer B. /// + /// 4 public uint B { get; } }; @@ -237,6 +286,7 @@ namespace Tizen.Security.TEEC /// /// This type denotes a TEE Session, the logical container linking a Client Application with a particular Trusted Application. /// + /// 4 public sealed class Session { private Interop.TEEC_Context context; @@ -267,6 +317,13 @@ namespace Tizen.Security.TEEC /// This function closes a Session which has been opened with a Trusted Application. /// All Commands within the Session MUST have completed before this function can be called. /// + /// 4 + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. public void Close() { Interop.Libteec.CloseSession(ref session); //session = null; @@ -276,11 +333,19 @@ namespace Tizen.Security.TEEC /// This function invokes a Command within the specified Session. /// The parameter commandID is an identifier that is used to indicate which of the exposed Trusted /// Application functions should be invoked. The supported command identifier values are defined by the - /// Trusted Application‟s protocol. - /// There can be up to four Parameter objects given in the {paramlist} array + /// Trusted Application's protocol. + /// There can be up to four Parameter objects given in the array /// + /// 4 /// The command /// The array of parameters + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. + /// The argument is wrong public void InvokeCommand(uint commandID, Parameter[] paramlist) { Interop.TEEC_Operation op = new Interop.TEEC_Operation(); @@ -301,9 +366,18 @@ namespace Tizen.Security.TEEC /// /// Asynchronous version of InvokeCommand /// + /// 4 /// The command /// The array of parameters /// The token for task manipulation + /// Returns Task executing invoke command in backgroung + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. + /// One of arguments is wrong public async Task InvokeCommandAsync(uint commandID, Parameter[] paramlist, CancellationToken token = default(CancellationToken)) { await Task.Factory.StartNew(() => InvokeCommand(commandID, paramlist)); @@ -314,15 +388,23 @@ namespace Tizen.Security.TEEC /// /// This type denotes a TEE Context, the main logical container linking a Client Application with a particular TEE. /// + /// 4 public sealed class Context : IDisposable { private Interop.TEEC_Context context; /// /// This function (constructor) initializes a new TEE Context, forming a connection between this Client Application and the - /// TEE identified by the string identifier name (empty name denotes default TEE). + /// TEE identified by the string identifier name (empty or null name denotes default TEE). /// + /// 4 /// The TEE name + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. public Context(string name) { context = new Interop.TEEC_Context(); @@ -338,6 +420,13 @@ namespace Tizen.Security.TEEC /// /// This function implements IDisposable interface /// + /// 4 + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. public void Dispose() { Interop.Libteec.FinalizeContext(ref context); //context.imp = null; @@ -348,10 +437,19 @@ namespace Tizen.Security.TEEC /// The target Trusted Application is identified by a UUID passed in the parameter destination. /// There can be up to four Parameter objects given in the {paramlist} array /// + /// 4 /// The UUID of destination TA /// The authentication algorithm /// The data to be verified by given login method /// The parameters to be passed to TA open-session-callback + /// Returns opened session + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. + /// One of arguments is wrong public Session OpenSession(Guid destination, uint loginMethod, byte[] connectionData, Parameter[] paramlist) { Session ses = new Session(context); @@ -361,7 +459,16 @@ namespace Tizen.Security.TEEC /// /// @see OpenSession(Guid destination, uint connectionMethod, byte[] connectionData, Parameter[] paramlist, CancellationToken token) /// + /// 4 /// The UUID of destination TA + /// Returns opened session + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. + /// The argument is wrong public Session OpenSession(Guid destination) { Session ses = new Session(context); @@ -373,11 +480,20 @@ namespace Tizen.Security.TEEC /// Asynchronous version of OpenSession /// @see OpenSession(Guid destination, uint connectionMethod, byte[] connectionData, Parameter[] paramlist, CancellationToken token) /// + /// 4 /// The UUID of destination TA /// The authentication algorithm /// The data to be verified by given login method /// The parameters to be passed to TA open-session-callback /// The token for task manipulation + /// Returns Task executing session open in backgroung + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. + /// One of arguments is wrong public async Task OpenSessionAsync(Guid destination, uint loginMethod, byte[] connectionData, Parameter[] paramlist, CancellationToken token = default(CancellationToken)) { Task task = Task.Factory.StartNew(() => @@ -390,8 +506,17 @@ namespace Tizen.Security.TEEC /// Asynchronous version of OpenSession /// @see OpenSession(Guid destination, uint connectionMethod, byte[] connectionData, Parameter[] paramlist, CancellationToken token) /// + /// 4 /// The UUID of destination TA /// The token for task manipulation + /// Returns Task executing session open in backgroung + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. + /// One of arguments is wrong public async Task OpenSessionAsync(Guid destination, CancellationToken token = default(CancellationToken)) { Task task = Task.Factory.StartNew(() => @@ -406,9 +531,18 @@ namespace Tizen.Security.TEEC /// the scope of the specified Context, in accordance with the parameters. /// The input MUST point to the shared memory region to register /// + /// 4 /// The address of shared memory /// The size of shared memory /// The flags describing access modes (Input and/or Output) + /// Returns SharedMemory handler + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. + /// The argument is wrong public SharedMemory RegisterSharedMemory(IntPtr memaddr, UInt32 size, SharedMemoryFlags flags) { Interop.TEEC_SharedMemory shm = new Interop.TEEC_SharedMemory(); @@ -424,8 +558,16 @@ namespace Tizen.Security.TEEC /// This function allocates a new block of memory as a block of Shared Memory within the scope of the /// specified Context, in accordance with the parameters. /// + /// 4 /// The size of shared memory /// The flags describing access modes (Input and/or Output) + /// Returns SharedMemory handler + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. public SharedMemory AllocateSharedMemory(UInt32 size, SharedMemoryFlags flags) { Interop.TEEC_SharedMemory shm = new Interop.TEEC_SharedMemory(); @@ -446,7 +588,15 @@ namespace Tizen.Security.TEEC /// underlying memory from the TEE, but the memory region will stay available to the Client Application for /// other purposes as the memory is owned by it. /// + /// 4 /// The shared memory object returned by RegisterSharedMemory or AllocateSharedMemory + /// http://tizen.org/privilege/tee.client + /// partner + /// http://tizen.org/feature/security.tee + /// Thrown when application does not have privilege to access this method. + /// The required feature is not supported. + /// The operation is invalid. + /// The argument is wrong public void ReleaseSharedMemory(SharedMemory shm) { Interop.Libteec.ReleaseSharedMemory(ref shm.shm);