API tools faq
paste
Advertisement
Guest User

SE API Interface

a guest
Sep 18th, 2018
167
0
Never
Add comment
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
C# 22.98 KB | None | 0 0
raw download clone embed print report
  1. /// <summary>
  2. /// This interface defines the functions that are provided by the Secure Element API (SE API)
  3. /// </summary>
  4. public interface ISeApi
  5. {
  6.     /// <summary>
  7.     /// The function initialize starts the initialization of the SE API by the operator of the corresponding application.
  8.     /// </summary>
  9.     /// <param name="description">short description of the Secure Element [INPUT PARAMETER, REQUIRED].</param>
  10.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  11.     /// <exception cref="ErrorStoringInitDataFailed">storing of the initialization data failed.</exception>
  12.     short Initialize(string description);
  13.    
  14.     /// <summary>
  15.     /// The function updateTime updates the current date/time that is maintained by the Secure Element by passing a new date/time value.
  16.     /// </summary>
  17.     /// <param name="newDateTime  new value for the date/time maintained by the Secure Element [INPUT PARAMETER, REQUIRED].</param>
  18.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  19.     /// <exception cref="ErrorSetTimeFailed">execution of the Secure Element functionality to set the time has failed.</exception>
  20.     /// <exception cref="ErrorRetrieveLogMessageFailed">execution of the Secure Element functionality to retrieve log message parts has failed.</exception>
  21.     /// <exception cref="ErrorStorageFailure">storing of the log message has failed.</exception>
  22.     short UpdateTime(DateTime newDateTime);
  23.    
  24.     /// <summary>
  25.     /// The function updateTime updates the current date/time that is maintained by the Secure Element by
  26.     /// using the functionality for time synchronization of the Secure Element.
  27.     /// </summary>
  28.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  29.     /// <exception cref="ErrorSetTimeFailed">execution of the Secure Element functionality to update the time has failed.</exception>
  30.     /// <exception cref="ErrorRetrieveLogMessageFailed">execution of the Secure Element functionality to retrieve log message parts has failed.</exception>
  31.     /// <exception cref="ErrorStorageFailure">storing of the log message has failed.</exception>
  32.     short UpdateTime();
  33.  
  34.     /// <summary>
  35.     /// Starts a new transaction, if the Secure Element is only used by one client.
  36.     /// </summary>
  37.     /// <param name="processData"> represents all the necessary information regarding the initial state of the process [INPUT PARAMETER, REQUIRED].</param>
  38.     /// <param name="processType">
  39.     /// identifies the type of the transaction as defined by the application. This string SHALL NOT contain more than 100 characters [INPUT PARAMETER, OPTIONAL].
  40.     /// </param>
  41.     /// <param name="additionalData">reserved for future use [INPUT PARAMETER, OPTIONAL].</param>
  42.     /// <param name="transactionNumber represents a transaction number that has been assigned by the Secure Element to the process [OUTPUT PARAMETER, REQUIRED].</param>
  43.     /// <param name="logTime">represents the point in time of the Secure Element when the log message was created [OUTPUT PARAMETER, REQUIRED].</param>
  44.     /// <param name="serialNumber">represents the the hash value over the key that is part of the certificate in the secure element [OUTPUT PARAMETER, REQUIRED].</param>
  45.     /// <param name="signatureCounter">represents the current value of the signature counter [OUTPUT PARAMETER, REQUIRED].</param>
  46.     /// <param name="signatureValue">represents the signature value   [OUTPUT PARAMETER, OPTIONAL].</param>
  47.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  48.     /// <exception cref="ErrorStartTransactionFailed">the execution of the Secure Element functionality to start a transaction failed.</exception>
  49.     /// <exception cref="ErrorRetrieveLogMessageFailed">the execution of the Secure Element functionality to retrieve log message parts has failed.</exception>
  50.     /// <exception cref="ErrorStorageFailure">storing of the log message failed.</exception>
  51.     short StartTransaction(byte [] processData, string processType,  byte [] additionalData,
  52.                             out long transactionNumber, out DateTime logTime, out byte[] serialNumber,
  53.                             out long signatureCounter, out byte[] signatureValue);
  54.     /// <summary>
  55.     /// Starts a new transaction, if the Secure Element is used by more than one client.
  56.     /// </summary>
  57.     /// <param name="clientID">MUST be present if the Secure Element is used by more than one client [INPUT PARAMETER, REQUIRED]
  58.     /// <param name="processData">represents all the necessary information regarding the initial state of the process [INPUT PARAMETER, REQUIRED]
  59.     /// <param name="processType">
  60.     /// identifies the type of the transaction as defined by the application. This string SHALL NOT contain more than 100 characters [INPUT PARAMETER, OPTIONAL].
  61.     /// </param>
  62.     /// <param name="additionalData">reserved for future use [INPUT PARAMETER, OPTIONAL].</param>
  63.     /// <param name="transactionNumber represents a transaction number that has been assigned by the Secure Element to the process [OUTPUT PARAMETER, REQUIRED].</param>
  64.     /// <param name="logTime">represents the point in time of the Secure Element when the log message was created [OUTPUT PARAMETER, REQUIRED].</param>
  65.     /// <param name="serialNumber">represents the the hash value over the key that is part of the certificate in the secure element [OUTPUT PARAMETER, REQUIRED].</param>
  66.     /// <param name="signatureCounter">represents the current value of the signature counter [OUTPUT PARAMETER, REQUIRED].</param>
  67.     /// <param name="signatureValue">represents the signature value   [OUTPUT PARAMETER, OPTIONAL].</param>
  68.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  69.     /// <exception cref="ErrorStartTransactionFailed">the execution of the Secure Element functionality to start a transaction failed.</exception>
  70.     /// <exception cref="ErrorRetrieveLogMessageFailed">the execution of the Secure Element functionality to retrieve log message parts has failed.</exception>
  71.     /// <exception cref="ErrorStorageFailure">storing of the log message failed.</exception>
  72.     short StartTransaction(long clientID, byte [] processData, string processType,  byte [] additionalData,
  73.                             out long transactionNumber,out DateTime logTime, out byte[] serialNumber,
  74.                             out long signatureCounter, out byte[] signatureValue);
  75.    
  76.     /// <summary>
  77.     /// Updates an existing transaction, if the Secure Element is used only by one client.
  78.     /// </summary>
  79.     /// <param name="transactionNumber">parameter is used to unambiguously identify the current transaction [INPUT PARAMETER, REQUIRED].</param>
  80.     /// <param name="processData">
  81.     /// represents all the new information regarding the state of the process since the start of the corresponding transaction or its last update [INPUT PARAMETER, REQUIRED].
  82.     /// </param>
  83.     /// <param name="processType">
  84.     /// identifies the type of the transaction as defined by the application. This string SHALL NOT contain more than 100 characters [INPUT PARAMETER, OPTIONAL].
  85.     /// </param>
  86.     /// <param name="logTime">represents the point in time of the Secure Element when the log message was created [OUTPUT PARAMETER, CONDITIONAL].</param>
  87.     /// <param name="signatureValue">represents the signature value   [OUTPUT PARAMETER, CONDITIONAL].</param>
  88.     /// <param name="signatureCounter  represents the current value of the signature counter [OUTPUT PARAMETER, CONDITIONAL].</param>
  89.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  90.     /// <exception cref="ErrorUpdateTransactionFailed">the execution of the Secure Element functionality to update a transaction failed.</exception>
  91.     /// <exception cref="ErrorLogMessageRetrievalFailed">the execution of the Secure Element functionality to retrieve log message parts has failed.</exception>
  92.     /// <exception cref="ErrorStorageFailure">storing of the log message failed.</exception>
  93.     /// <exception cref="ErrorNoTransaction">no transaction is known to be open under the provided transaction number.</exception>
  94.     short UpdateTransaction(long transactionNumber, byte [] processData, string processType,  
  95.                             out DateTime logTime, out byte[] signatureValue, out long signatureCounter);
  96.    
  97.     /// <summary>
  98.     /// Updates an existing transaction, if the Secure Element is used by more than one client.
  99.     /// </summary>
  100.     /// <param name="clientID">MUST be present if the Secure Element is used by more than one client [INPUT PARAMETER, REQUIRED].</param>
  101.     /// <param name="transactionNumber">parameter is used to unambiguously identify the current transaction [INPUT PARAMETER, REQUIRED].</param>
  102.     /// <param name="processData">
  103.     /// represents all the new information regarding the state of the process since the start of the corresponding transaction or its last update [INPUT PARAMETER, REQUIRED].
  104.     /// </param>
  105.     /// <param name="processType">
  106.     /// identifies the type of the transaction as defined by the application. This string SHALL NOT contain more than 100 characters [INPUT PARAMETER, OPTIONAL].
  107.     /// </param>
  108.     /// <param name="logTime">represents the point in time of the Secure Element when the log message was created [OUTPUT PARAMETER, CONDITIONAL].</param>
  109.     /// <param name="signatureValue">represents the signature value   [OUTPUT PARAMETER, CONDITIONAL].</param>
  110.     /// <param name="signatureCounter">represents the current value of the signature counter [OUTPUT PARAMETER, CONDITIONAL].</param>
  111.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  112.     /// <exception cref="ErrorUpdateTransactionFailed">the execution of the Secure Element functionality to update a transaction failed.</exception>
  113.     /// <exception cref="ErrorLogMessageRetrievalFailed">the execution of the Secure Element functionality to retrieve log message parts has failed.</exception>
  114.     /// <exception cref="ErrorStorageFailure">storing of the log message failed.</exception>
  115.     /// <exception cref="ErrorNoTransaction">no transaction is known to be open under the provided transaction number.</exception>
  116.     short UpdateTransaction(long clientID, long transactionNumber, byte [] processData, string processType,  
  117.                             out DateTime logTime, out byte[] signatureValue, out long signatureCounter);
  118.    
  119.     /// <summary>
  120.     /// Finishes an existing transaction, if the Secure Element is used only by one client.
  121.     /// </summary>
  122.     /// <param name="transactionNumber">parameter is used to unambiguously identify the current transaction [INPUT PARAMETER, REQUIRED].</param>
  123.     /// <param name="processData">represents all the information regarding the final state of the process [INPUT PARAMETER, REQUIRED].</param>
  124.     /// <param name="processType">
  125.     /// identifies the type of the transaction as defined by the application. This string SHALL NOT contain more than 100 characters [INPUT PARAMETER, OPTIONAL].
  126.     /// </param>
  127.     /// <param name="additionalData">reserved for future use [INPUT PARAMETER, OPTIONAL].</param>
  128.     /// <param name="logTime">represents the point in time of the Secure Element when the log message was created [OUTPUT PARAMETER, CONDITIONAL].</param>
  129.     /// <param name="signatureValue">represents the signature value [OUTPUT PARAMETER, OPTIONAL].</param>
  130.     /// <param name="signatureCounter">represents the current value of the signature counter [OUTPUT PARAMETER, REQUIRED].</param>
  131.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  132.     /// <exception cref="ErrorFinishTransactionFailed">the execution of the Secure Element functionality to finish a transaction failed.</exception>
  133.     /// <exception cref="ErrorRetrieveLogMessageFailed">the execution of the Secure Element functionality to retrieve log message parts has failed.</exception>
  134.     /// <exception cref="ErrorStorageFailure">storing of the log message failed.</exception>
  135.     short FinishTransaction (long transactionNumber, byte [] processData, string processType, byte [] additionalData,
  136.                               out DateTime logTime, out byte[] signatureValue, out long signatureCounter);
  137.    
  138.     /// <summary>
  139.     /// Finishes an existing transaction, if the Secure Element is used by more than one client.
  140.     /// </summary>
  141.     /// <param name="clientID">MUST be present if the Secure Element is used by more than one client [INPUT PARAMETER, REQUIRED].</param>
  142.     /// <param name="transactionNumber">parameter is used to unambiguously identify the current transaction [INPUT PARAMETER, REQUIRED].</param>
  143.     /// <param name="processData">represents all the information regarding the final state of the process [INPUT PARAMETER, REQUIRED].</param>
  144.     /// <param name="processType">
  145.     /// identifies the type of the transaction as defined by the application. This string SHALL NOT contain more than 100 characters [INPUT PARAMETER, OPTIONAL].
  146.     /// </param>
  147.     /// <param name="additionalData">reserved for future use [INPUT PARAMETER, OPTIONAL]
  148.     /// <param name="logTime">represents the point in time of the Secure Element when the log message was created [OUTPUT PARAMETER, CONDITIONAL].</param>
  149.     /// <param name="signatureValue">represents the signature value [OUTPUT PARAMETER, OPTIONAL].</param>
  150.     /// <param name="signatureCounter">represents the current value of the signature counter [OUTPUT PARAMETER, REQUIRED].</param>
  151.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  152.     /// <exception cref="ErrorFinishTransactionFailed">the execution of the Secure Element functionality to finish a transaction failed.</exception>
  153.     /// <exception cref="ErrorRetrieveLogMessageFailed">the execution of the Secure Element functionality to retrieve log message parts has failed.</exception>
  154.     /// <exception cref="ErrorStorageFailure">storing of the log message failed.</exception>
  155.     short FinishTransaction (long clientID, long transactionNumber, byte [] processData, string processType, byte [] additionalData,
  156.                              out DateTime logTime, out byte[] signatureValue, out long signatureCounter);
  157.    
  158.     /// <summary>
  159.     /// Exports the log messages, containing the process and protocol data, that correspond to a certain transaction
  160.     /// and optionally to a certain client. Furthermore, additional files that are needed to verify the signatures included in the log messages are exported.
  161.     /// </summary>
  162.     /// <param name="transactionNumber">indicates the transaction whose corresponding log messages are relevant for the export [INPUT PARAMETER, REQUIRED].</param>
  163.     /// <param name="clientID">MUST be present if the Secure Element is used by more than one client [INPUT PARAMETER, REQUIRED].</param>
  164.     /// <param name="exportData">selected log messages and additional files needed to verify the signatures included in the log messages [OUTPUT PARAMETER, REQUIRED].</param>
  165.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  166.     /// <exception cref="ErrorIdNotFound">no data has been found for the provided clientID.</exception>
  167.     /// <exception cref="ErrorTransactionIdNotFound">no data has been found for the provided transactionNumber.</exception>
  168.     short Export(long transactionNumber, long clientID,  out byte[] exportData);
  169.    
  170.     /// <summary>
  171.     /// Exports the log messages, containing the process and protocol data, that correspond to a certain transaction.
  172.     /// Furthermore, additional files that are needed to verify the signatures, included in the log messages, are exported.
  173.     /// </summary>
  174.     /// <param name="transactionNumber">indicates the transaction whose corresponding log messages are relevant for the export [INPUT PARAMETER, REQUIRED].</param>
  175.     /// <param name="exportData">selected log messages and additional files needed to verify the signatures included in the log messages [OUTPUT PARAMETER, REQUIRED] .</param>
  176.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  177.     /// <exception cref="ErrorTransactionIdNotFound">no data has been found for the provided transactionNumber.</exception>
  178.     short Export(long transactionNumber, out byte[] exportData);
  179.    
  180.     /// <summary>
  181.     /// Exports the log messages, containing the process and protocol data, that are relevant for a certain interval of transactions.
  182.     /// Furthermore, additional files that are needed to verify the signatures, included in the log messages, are exported.
  183.     /// </summary>
  184.     /// <param name="startTransactionNumber">defines the transaction number (inclusive) regarding the start of the interval of relevant log messages [INPUT PARAMETER, REQUIRED].</param>
  185.     /// <param name="endTransactionNumber">defines the transaction number (inclusive) regarding the end of the interval of relevant log messages [INPUT PARAMETER, REQUIRED].</param>
  186.     /// <param name="maximumNumberRecords">
  187.     /// if the value of this parameter is not 0, the function SHALL only return the log messages if the number of relevant records is less or equal to the number of maximum records.
  188.     /// If the parameter value is 0, the function SHALL return all stored log messages [INPUT PARAMETER, REQUIRED].
  189.     /// </param>
  190.     /// <param name="exportData">selected log messages and additional files needed to verify the signatures included in the log messages [OUTPUT PARAMETER, REQUIRED].</param>
  191.     /// <returns> if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  192.     /// <exception cref="ErrorParameterMismatch">mismatch in parameters of the function.</exception>
  193.     /// <exception cref="ErrorTransactionIdNotFound">no data has been found for the provided transaction numbers.</exception>
  194.     /// <exception cref="ErrorTooManyRecords">the amount of requested records exceeds the parameter maximumNumberRecords.</exception>
  195.     short Export(long startTransactionNumber, long endTransactionNumber, int maximumNumberRecords, out byte[] exportData);
  196.    
  197.     /// <summary>
  198.     /// Exports the log messages, containing the process and protocol data, that have been created in a certain period of time.
  199.     /// Furthermore, additional files that are needed to verify the signatures, included in the log messages, are exported.
  200.     /// </summary>
  201.     /// <param name="startDate">defines the starting time (inclusive) for the period in that the relevant log messages have been created.
  202.     ///                       The value for the parameter SHALL be encoded in UTC [INPUT PARAMETER, REQUIRED]
  203.     /// <param name="endDate">  defines the end time (inclusive) for the period in that relevant log messages have been created.
  204.     ///                       The value for the parameter SHALL be encoded in UTC [INPUT PARAMETER, REQUIRED]
  205.     /// <param name="maximumNumberRecords">
  206.     /// if the value of this parameter is not 0, the function SHALL only return the log messages if the number of relevant records is less or equal to the number of maximum records.
  207.     /// If the value of the parameter is 0, the function SHALL return all stored log messages [INPUT PARAMETER, REQUIRED].
  208.     /// </param>
  209.     /// <param name="exportData">selected log messages and additional files needed to verify the signatures included in the log messages [OUTPUT PARAMETER, REQUIRED].</param>
  210.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  211.     /// <exception cref="ErrorParameterMismatch">mismatch in parameters of the function.</exception>
  212.     /// <exception cref="ErrorNoDataAvailable">no data has been found for the provided selection.</exception>
  213.     /// <exception cref="ErrorTooManyRecords"> the amount of requested records exceeds the parameter maximumNumberRecords.</exception>
  214.     short Export(DateTime startDate, DateTime endDate, int maximumNumberRecords, out byte[] exportData);
  215.    
  216.     /// <summary>
  217.     /// Exports all stored log messages, containing the process and protocol data, and additional files that are needed to verify the signatures included in the log messages.
  218.     /// </summary>
  219.     /// <param name="maximumNumberRecords">
  220.     /// if the value of this parameter is not 0, the function SHALL only return the log messages if the number of relevant records is less or equal to the number of maximum records.
  221.     /// If the value of the parameter is 0, the function SHALL return all stored log messages [INPUT PARAMETER, REQUIRED].
  222.     /// </param>
  223.     /// <param name="exportData">log messages and additional files needed to verify the signatures included in the log messages [OUTPUT PARAMETER, REQUIRED].</param>
  224.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  225.     /// <exception cref="ErrorNoDataAvailable">no data has been found for the provided selection.</exception>
  226.     /// <exception cref="ErrorTooManyRecords"> the amount of requested records exceeds the parameter maximumNumberRecords.</exception>
  227.     short Export(int maximumNumberRecords, out byte[] exportData);
  228.    
  229.     /// <summary>
  230.     /// Returns the certificate that belongs to the current key pair used for creating the signatures contained in log messages.
  231.     /// </summary>
  232.     /// <param name="certificate">
  233.     /// this parameter MAY occur several times, each containing a card-verifiable certificate of the certificate chain belonging to the key pair that is currently used to create signatures
  234.     /// contained in log messages [OUTPUT PARAMETER, REQUIRED].
  235.     /// </param>
  236.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  237.     /// <exception cref="ErrorExportCertFailed">the execution of the Secure Element function for exporting the certificate failed.</exception>
  238.     short GetLogMessageCertificate(out byte[] certificate);
  239.     /// <summary>
  240.     /// Restores a backup in the SE API and storage. The function utilizes data that has been exported by the use of the export function.
  241.     /// </summary>
  242.     /// <param name="restoreData">contains the data that SHALL be restored in the SE API and storage [INTPUT PARAMETER, REQUIRED].</param>
  243.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  244.     /// <exception cref="ErrorRestoreFailed">the restore process has failed.</exception>
  245.     /// <exception cref="ErrorDeletingFailed">
  246.     /// deleting of the secured data from the storage and the initialization description from the SE API before the restoring has failed.
  247.     /// </exception>
  248.     short RestoreFromBackup (byte[] restoreData );
  249.    
  250.     /// <summary>
  251.     /// Reads a log message that bases on the last log message parts that haves been produced and processed by the Secure Element.
  252.     /// </summary>
  253.     /// <param name="logMessage">contains the last log message that the Secure Element has produced [OUTPUT PARAMETER, REQUIRED].</param>
  254.     /// <returns>if the execution of the function has been successful, the return value EXECUTION_OK SHALL be returned.</returns>
  255.     /// <exception cref="ErrorNoLogMessage">no log message parts have been found.</exception>
  256.     /// <exception cref="ErrorReadingLogMessage">error while retrieving log message parts.</exception>
  257.     short ReadLogMessage(out byte[] logMessage);
  258.              
  259.    
  260. }
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement
Public Pastes
Advertisement
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy.  OK, I Understand
Not a member of Pastebin yet?
Sign Up, it unlocks many cool features!