src/include/security-server.h

   1 /*
   2  *  security-server
   3  *
   4  *  Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd All Rights Reserved
   5  *
   6  *  Contact: Bumjin Im <bj.im@samsung.com>
   7  *
   8  *  Licensed under the Apache License, Version 2.0 (the "License");
   9  *  you may not use this file except in compliance with the License.
  10  *  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *  Unless required by applicable law or agreed to in writing, software
  15  *  distributed under the License is distributed on an "AS IS" BASIS,
  16  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  *  See the License for the specific language governing permissions and
  18  *  limitations under the License
  19  *
  20  */
  21
  22 #ifndef SECURITY_SERVER_H
  23 #define SECURITY_SERVER_H
  24
  25 #include <sys/types.h>
  26 #include <privilege-control.h>
  27
  28 /**
  29  * @file    security-server.h
  30  * @version 1.0
  31  * @brief   This file contains APIs of the Security Server
  32 */
  33
  34 /**
  35  * @defgroup SecurityFW
  36  * @{
  37  *
  38  * @defgroup SECURITY_SERVER Security Server
  39  * @version  1.0
  40  * @brief    Security Server client library functions
  41  *
  42 */
  43
  44 /**
  45  * @addtogroup SECURITY_SERVER
  46  * @{
  47 */
  48
  49 /*
  50  * ====================================================================================================
  51  * <tt>
  52  *
  53  * Revision History:
  54  *
  55  *  -- Company Name -- | Modification Date | Description of Changes
  56  *  -----------------------------------------------------------------------
  57  *   --- Samsung ------ | --- 2010-07-25 -- | First created
  58  *
  59  *    </tt>
  60  */
  61
  62 /**
  63  * \name Return Codes
  64  * exported by the foundation API.
  65  * result codes begin with the start error code and extend into negative direction.
  66  * @{
  67 */
  68 #define SECURITY_SERVER_API_SUCCESS 0
  69 /*! \brief   indicating the result of the one specific API is successful */
  70 #define SECURITY_SERVER_API_ERROR_SOCKET -1
  71
  72 /*! \brief   indicating the socket between client and Security Server has been failed  */
  73 #define SECURITY_SERVER_API_ERROR_BAD_REQUEST -2
  74
  75 /*! \brief   indicating the response from Security Server is malformed */
  76 #define SECURITY_SERVER_API_ERROR_BAD_RESPONSE -3
  77
  78 /*! \brief   indicating the transmitting request has been failed */
  79 /* deprecated unused */
  80 #define SECURITY_SERVER_API_ERROR_SEND_FAILED -4
  81
  82 /*! \brief   indicating the receiving response has been failed */
  83 /* deprecated unused */
  84 #define SECURITY_SERVER_API_ERROR_RECV_FAILED -5
  85
  86 /*! \brief   indicating requesting object is not exist */
  87 #define SECURITY_SERVER_API_ERROR_NO_SUCH_OBJECT -6
  88
  89 /*! \brief   indicating the authentication between client and server has been failed */
  90 #define SECURITY_SERVER_API_ERROR_AUTHENTICATION_FAILED -7
  91
  92 /*! \brief   indicating the API's input parameter is malformed */
  93 #define SECURITY_SERVER_API_ERROR_INPUT_PARAM -8
  94
  95 /*! \brief   indicating the output buffer size which is passed as parameter is too small */
  96 #define SECURITY_SERVER_API_ERROR_BUFFER_TOO_SMALL -9
  97
  98 /*! \brief   indicating system  is running out of memory state */
  99 #define SECURITY_SERVER_API_ERROR_OUT_OF_MEMORY -10
 100
 101 /*! \brief   indicating the access has been denied by Security Server */
 102 #define SECURITY_SERVER_API_ERROR_ACCESS_DENIED -11
 103
 104 /*! \brief   indicating Security Server has been failed for some reason */
 105 #define SECURITY_SERVER_API_ERROR_SERVER_ERROR -12
 106
 107 /*! \brief   indicating given cookie is not exist in the database  */
 108 #define SECURITY_SERVER_API_ERROR_NO_SUCH_COOKIE -13
 109
 110 /*! \brief   indicating there is no phone password set  */
 111 #define SECURITY_SERVER_API_ERROR_NO_PASSWORD -14
 112
 113 /*! \brief   indicating password exists in system  */
 114 #define SECURITY_SERVER_API_ERROR_PASSWORD_EXIST -15
 115
 116 /*! \brief   indicating password mismatch  */
 117 #define SECURITY_SERVER_API_ERROR_PASSWORD_MISMATCH -16
 118
 119 /*! \brief   indicating password retry timeout is not occurred yet  */
 120 #define SECURITY_SERVER_API_ERROR_PASSWORD_RETRY_TIMER -17
 121
 122 /*! \brief   indicating password retry timeout is not occurred yet  */
 123 #define SECURITY_SERVER_API_ERROR_PASSWORD_MAX_ATTEMPTS_EXCEEDED -18
 124
 125 /*! \brief   indicating password retry timeout is not occurred yet  */
 126 #define SECURITY_SERVER_API_ERROR_PASSWORD_EXPIRED -19
 127
 128 /*! \brief   indicating password retry timeout is not occurred yet  */
 129 #define SECURITY_SERVER_API_ERROR_PASSWORD_REUSED -20
 130
 131 /*! \brief   indicating getting smack label from socket failed  */
 132 #define SECURITY_SERVER_API_ERROR_GETTING_SOCKET_LABEL_FAILED -21
 133
 134 /*! \brief   indicating getting smack label from file failed  */
 135 #define SECURITY_SERVER_API_ERROR_GETTING_FILE_LABEL_FAILED -22
 136
 137 /*! \brief   indicating setting smack label for file failed  */
 138 #define SECURITY_SERVER_API_ERROR_SETTING_FILE_LABEL_FAILED -23
 139
 140 /*! \brief   indicating file already exists  */
 141 #define SECURITY_SERVER_API_ERROR_FILE_EXIST -24
 142
 143 /*! \brief   indicating file does not exist  */
 144 #define SECURITY_SERVER_API_ERROR_FILE_NOT_EXIST -25
 145
 146 /*! \brief   indicating file open error  */
 147 #define SECURITY_SERVER_API_ERROR_FILE_OPEN_FAILED -26
 148
 149 /*! \brief   indicating file creation error  */
 150 #define SECURITY_SERVER_API_ERROR_FILE_CREATION_FAILED -27
 151
 152 /*! \brief   indicating file deletion error  */
 153 #define SECURITY_SERVER_API_ERROR_FILE_DELETION_FAILED -28
 154
 155 /*! \brief   indicating the error with unknown reason */
 156 #define SECURITY_SERVER_API_ERROR_UNKNOWN -255
 157 /** @}*/
 158
 159
 160 #ifdef __cplusplus
 161 extern "C" {
 162 #endif
 163
 164
 165
 166 /**
 167  * \par Description:
 168  * Retreives Linux group ID from object name which is passed by parameter
 169  *
 170  * \par Purpose:
 171  * This API may be used before security_server_check_privilege() API by middleware daemon to get group ID of a specific object.
 172  *
 173  * \par Typical use case:
 174  * In middleware daemon, before checking privilege of a service the daemon need to know the GID of the service. This API support the functionality.
 175  *
 176  * \par Method of function operation:
 177  * Opens /etc/group file and searches the object name as group name. If there is matching result, returns GID as integer
 178  *
 179  * \par Sync (or) Async:
 180  * This is a Synchronous API.
 181  *
 182  * \par Important notes:
 183  * - This API is only allowed to be called by pre-defined middleware daemon
 184  *
 185  * \param[in] object Name of the object which is kwnown by the caller.
 186  *
 187  * \return matching gid (positive integer) on success, or negative error code on error.
 188  *
 189  * \par Prospective clients:
 190  * Inhouse middleware
 191  *
 192  * \par Known issues/bugs:
 193  * None
 194  *
 195  * \pre None
 196  *
 197  * \post None
 198  *
 199  * \see /etc/group,
 200  * security_server_get_object_name(), security_server_check_privilege()
 201  *
 202  * \remarks None
 203  *
 204  * \par Sample code:
 205  * \code
 206  * #include <security-server.h>
 207  * ...
 208  * int retval;
 209  *
 210  * // You have to make sure that  the input param '*object' is defined in the platform
 211  * retval = security_server_get_gid("telephony_makecall");
 212  * if(retval < 0)
 213  * {
 214  *      printf("%s", "Error has occurred\n");
 215  *      exit(0);
 216  * }
 217  * ...
 218  * \endcode
 219  *
 220  * Access to this function requires SMACK rule: "<app_label> security-server::api-get-gid w"
 221 */
 222 int security_server_get_gid(const char *object);
 223
 224 /**
 225  * \par Description:
 226  * Request cookie to the Security Server. Cookie is a random bit stream which is used as ticket for user space object.
 227  *
 228  * \par Purpose:
 229  * This API may be used by application and client middleware process to get access to middleware daemons.
 230  *
 231  * \par Typical use case:
 232  * When an application process wants to get access to some middleware object, first call this API to get cookie value. Then it calls the service API to get service with the cookie value.
 233  *
 234  * \par Method of function operation:
 235  * Caller process just send request message. Security Server checks proc file system to get list of gIDs the caller belongs, then create a random cookie and responds to caller.
 236  *
 237  * \par Sync (or) Async:
 238  * This is a Synchronous API.
 239  *
 240  * \par Important notes:
 241  * Cookie needs to be stored relatively secure.
 242  *
 243  * \param[out] cookie Place holder for cookie value.
 244  * \param[in] max_cookie Allocated byte size of parameter "cookie".
 245  *
 246  * \return 0 on success, or negative error code on error.
 247  *
 248  * \par Prospective clients:
 249  * Any process
 250  *
 251  * \par Known issues/bugs:
 252  * None
 253  *
 254  * \pre output parameter cookie must be malloced before calling this API not to make memory curruption
 255  * Size of the cookie can be retrieved by security_server_get_cookie_size() API.
 256  *
 257  * \post None
 258  *
 259  * \see security_server_check_privilege(), security_server_get_cookie_size()
 260  *
 261  * \remarks None
 262  *
 263  * \par Sample code:
 264  * \code
 265  * #include <security-server.h>
 266  * ...
 267  * int retval;
 268  * size_t cookie_size;
 269  * cookie_size = security_server_get_cookie_size();
 270  * unsigned char cookie[cookie_size];
 271  *
 272  * // Call the API
 273  * retval = security_server_request_cookie(cookie, cookie_size);
 274  * if(retval < 0)
 275  * {
 276  *      printf("%s", "Error has occurred\n");
 277  *      exit(0);
 278  * }
 279  * ...
 280  * \endcode
 281  *
 282  * Access to this function not requires SMACK rule
 283 */
 284 int security_server_request_cookie(char *cookie, size_t bufferSize);
 285
 286
 287
 288 /**
 289  * \par Description:
 290  * This API gets the cookie's byte size which is issued by Security Server.
 291  *
 292  * \par Purpose:
 293  * This API may be used by application and middleware process to get size of cookie before getting and storing cookie value.
 294  *
 295  * \par Typical use case:
 296  * When an application process wants to get access to some middleware object, first call this API to get cookie value. Then it calls the service API to get service with the cookie value.
 297  *
 298  * \par Method of function operation:
 299  * This API just returns pre-defined integer value as cookie size.
 300  *
 301  * \par Sync (or) Async:
 302  * This is a Synchronous API.
 303  *
 304  * \par Important notes:
 305  * None
 306  *
 307  * \return Always returns byte size of the cookie.
 308  *
 309  * \par Prospective clients:
 310  * Any process
 311  *
 312  * \par Known issues/bugs:
 313  * None
 314  *
 315  * \pre None
 316  *
 317  * \post None
 318  *
 319  * \see security_server_request_cookie()
 320
 321  * \remarks None
 322  *
 323  * \par Sample code:
 324  * \code
 325  * #include <security-server.h>
 326  * ...
 327  * int retval;
 328  * size_t cookie_size;
 329  *
 330  * // API calling
 331  * cookie_size = security_server_get_cookie_size();
 332  * unsigned char cookie[cookie_size];
 333  *
 334  * char objectname[20];
 335  * retval = security_server_request_cookie(cookie, cookie_size);
 336  * if(retval < 0)
 337  * {
 338  *      printf("%s", "Error has occurred\n");
 339  *      exit(0);
 340  * }
 341  * ...
 342  * \endcode
 343  *
 344  * Access to this function not requires SMACK rule
 345 */
 346 int security_server_get_cookie_size(void);
 347
 348
 349
 350 /**
 351  * \par Description:
 352  * This API checks the cookie is allowed to access to given object.
 353  *
 354  * \par Purpose:
 355  * This API may be used by middleware process to ask the client application has privilege for the given object.
 356  *
 357  * \par Typical use case:
 358  * When middleware server receives request message from client application process with cookie value, it calls this API to ask to Security Server that the client application has privilege to access the service. If yes, then the middleware daemon can continue service, if not, it can return error to client application.
 359  *
 360  * \par Method of function operation:
 361  * When Security Server receives this request, it searches cookie database and check the cookie is there, if there is matching cookie, then it checks the cookie has the privilege. It returns success if there is match, if not, it returns error.
 362  *
 363  * \par Sync (or) Async:
 364  * This is a Synchronous API.
 365  *
 366  * \par Important notes:
 367  * Cookie value needs to be stored relatively secure\n
 368  * Privilege should be pre-defined by Platform design.
 369  *
 370  * \param[in] cookie Received cookie value from client application
 371  * \param[in] privilege Object group ID which the client application wants to access
 372  *
 373  * \return 0 on success, or negative error code on error.
 374  *
 375  * \par Prospective clients:
 376  * Only pre-defiend middleware daemons
 377  *
 378  * \par Known issues/bugs:
 379  * None
 380  * \pre None
 381  *
 382  * \post None
 383  *
 384  * \see security_server_request_cookie(), security_server_get_gid(), security_server_get_cookie_size()
 385  *
 386  * \remarks None
 387  *
 388  * \par Sample code:
 389  * \code
 390  * #include <security-server.h>
 391  * ...
 392  * int retval;
 393  * size_t cookie_size;
 394  * int call_gid;
 395  * cookie_size = security_server_get_cookie_size();
 396  * unsigned char recved_cookie[cookie_size];
 397  *
 398  * ... // Receiving request with cookie
 399  *
 400  * call_gid = security_server_get_gid("telephony_makecall");
 401  * retval = security_server_check_privilege(recved_cookie, (gid_t)call_gid);
 402  * if(retval < 0)
 403  * {
 404  *      if(retval == SECURITY_SERVER_API_ERROR_ACCESS_DENIED)
 405  *      {
 406  *              printf("%s", "access has been denied\n");
 407  *              return;
 408  *      }
 409  *      printf("%s", "Error has occurred\n");
 410  * }
 411  * ...
 412  *
 413  * \endcode
 414  *
 415  * Access to this function requires SMACK rule: "<app_label> security-server::api-cookie-check w"
 416 */
 417 int security_server_check_privilege(const char *cookie, gid_t privilege);
 418
 419 int security_server_check_privilege_by_cookie(const char *cookie,
 420                                               const char *object,
 421                                               const char *access_rights);
 422
 423 /**
 424  * \par Description:
 425  * This API searchs a cookie value and returns PID of the given cookie.
 426  *
 427  * \par Purpose:
 428  * This API may be used by middleware process to ask the client application has privilege for the given object.
 429  *
 430  * \par Typical use case:
 431  * In some cases, a middleware server wants to know PID of the application process. But if the middleware server uses non-direct IPC such as dbus, it's nearly impossible to know and guarantee peer PID. By using this API, the middleware server can retrieve a PID of the requesting process.
 432  *
 433  * \par Method of function operation:
 434  * When Security Server receives this request, it searches cookie database and check the cookie is there, if there is matching cookie, then it returns corresponding PID for the cookie.
 435  *
 436  * \par Sync (or) Async:
 437  * This is a Synchronous API.
 438  *
 439  * \par Important notes:
 440  * Cookie value needs to be stored relatively secure\n
 441  * This API is abled to be called only by pre-defined middleware servers.
 442  *
 443  * \param[in] cookie Received cookie value from client application. Cookie is not a null terminated human readable string. Make sure you're code doesn't have any string related process on the cookie.
 444  *
 445  * \return positive integer on success meaning the PID, 0 means the cookie is for root process, negative integer error code on error.
 446  *
 447  * \par Prospective clients:
 448  * Only pre-defined middleware daemons
 449  *
 450  * \par Known issues/bugs:
 451  * None
 452  *
 453  * \pre None
 454  *
 455  * \post None
 456  *
 457  * \see security_server_request_cookie(), security_server_get_cookie_size()
 458  *
 459  * \remarks the cookie is not a null terminated string. Cookie is a BINARY byte stream of such length which can be retrieved by security_server_get_cookie_size() API.
 460  * Therefore, please do not use strcpy() family to process cookie value. You MUST use memcpy() function to process cookie value.
 461  * You also have to know that the cookie value doesn't carry any null terminator. So you don't need to allocate 1 more byte of the cookie size.
 462  *
 463  * \par Sample code:
 464  * \code
 465  * #include <security-server.h>
 466  * ...
 467  * int peerpid;
 468  * size_t cookie_size;
 469  * gid_t call_gid;
 470  * cookie_size = security_server_get_cookie_size();
 471  * unsigned char recved_cookie[cookie_size];
 472  *
 473  * ... // Receiving request with cookie
 474  *
 475  * peerpid = security_server_get_cookie_pid(recved_cookie);
 476  * if(peerpid < 0)
 477  * {
 478  *      printf("%s", "Error has occurred\n");
 479  * }
 480  * ...
 481  *
 482  * \endcode
 483  *
 484  * Access to this function requires SMACK rule: "<app_label> security-server::api-cookie-check w"
 485 */
 486 int security_server_get_cookie_pid(const char *cookie);
 487
 488
 489
 490 /**
 491  * \par Description:
 492  * This API checks phone validity of password, to check existance, expiration, remaining attempts.
 493  *
 494  * \par Purpose:
 495  * This API should be used by applications which needs phone password check. Caller application should behave properly after this API call.
 496  *
 497  * \par Typical use case:
 498  * Lock screen can call this API before it shows unlock screen, if there is password, lock screen can show password input UI, if not, lock screen can show just unlock screen
 499  *
 500  * \par Method of function operation:
 501  * Sends a validate request to security server and security server replies with password information.
 502  *
 503  * \par Sync (or) Async:
 504  * This is a Synchronous API.
 505  *
 506  * \par Important notes:
 507  * Password file should be stored safely. The password file will be stored by security server and only allowed itself to read/write, and data is will be securely hashed\n
 508  *
 509  * \param[out] current_attempts Number of password check missed attempts.
 510  * \param[out] max_attempts Number of maximum attempts that the password locks. 0 means infinite
 511  * \param[out] valid_secs Remaining time in second which represents this password will be expired. 0xFFFFFFFF means infinite
 512  *
 513  * \return 0 if there is no password set, other negative integer error code on error.
 514  *
 515  * \par Prospective clients:
 516  * Applications which can unlock UI
 517  *
 518  * \par Known issues/bugs:
 519  * None
 520  *
 521  * \pre None
 522  *
 523  * \post None
 524  *
 525  * \see security_server_set_pwd(), security_server_chk_pwd()
 526  *
 527  * \remarks If password file is corrupted or accidentally deleted, this API may not synchronized with security-server, but security-server will check file status on next request.
 528  *
 529  * \par Sample code:
 530  * \code
 531  * #include <security-server.h>
 532  * ...
 533  * int ret;
 534  * unsigned int attempt, max_attempt, expire_sec;
 535  *
 536  * ret = security_server_is_pwd_valid(&attempt, &max_attempt, &expire_sec);
 537  * if(is_pwd_set == SECURITY_SERVER_API_ERROR_NO_PASSWORD)
 538  * {
 539  *      printf("%s", "There is no password exists\n");
 540  * }
 541  * else if(is_pwd_set == SECURITY_SERVER_API_SUCCESS && expire_sec > 0 && attempt < max_attempts)
 542  * {
 543  *      printf("%s", "Password is valid by now\n");
 544  * }
 545  * else
 546  * {
 547  *      printf("%s", "Something wrong\n");
 548  * }
 549  * ...
 550  *
 551  * \endcode
 552  *
 553  * Access to this function requires SMACK rule: "<app_label> security-server::api-password-check w"
 554 */
 555 int security_server_is_pwd_valid(unsigned int *current_attempts,
 556                                  unsigned int *max_attempts,
 557                                  unsigned int *valid_secs);
 558
 559
 560
 561 /**
 562  * \par Description:
 563  * This API sets phone password only if current password matches.
 564  *
 565  * \par Purpose:
 566  * This API should be used by setting application when the user changes his/her phone password.
 567  *
 568  * \par Typical use case:
 569  * Setting application calls this API to change phone password. Caller needs current password to grant the change.
 570  *
 571  * \par Method of function operation:
 572  * Sends current password with new password to security-server, security-server checks current password and set new password to current only when current password is correct. Caller application can determine maximum number of attempts and expiration time in days
 573  *
 574  * \par Sync (or) Async:
 575  * This is a Synchronous API.
 576  *
 577  * \par Important notes:
 578  * There is retry timer on this API to limit replay attack. You will get error if you called this API too often.\n
 579  *
 580  * \param[in] cur_pwd Null terminated current password string. It can be NULL pointer if there is no password set yet - by calling security_server_is_pwd_empty()
 581  * \param[in] new_pwd Null terminated new password string. It must not a NULL pointer.
 582  * \param[in] max_challenge Maximum number of attempts that user can try to check the password without success in serial. 0 means infinity.
 583  * \param[in] valid_period_in_days. Number of days that this password is valid. 0 means infinity
 584  *
 585  * \return 0 on success, negative integer error code on error.
 586  *
 587  * \par Prospective clients:
 588  * Platform's THE ONLY setting application and some dedicated privileged processes
 589  *
 590  * \par Known issues/bugs:
 591  * None
 592  *
 593  * \pre None
 594  *
 595  * \post None
 596  *
 597  * \see security_server_is_pwd_valid(), security_server_chk_pwd(), security_server_reset_pwd()
 598  *
 599  * \remarks Only setting application can call this API. The password file will be access controlled and securely hashed. Security-server will remain previous password file to recover unexpected password file corruption.
 600  * \remarks If current password exists and it's expired, or max attempts reached, you cannot call this API. You have to call security_server_reset_pwd() API.
 601  *
 602  * \par Sample code:
 603  * \code
 604  * #include <security-server.h>
 605  * ...
 606  * int ret;
 607  * unsigned int attempt, max_attempt, expire_sec;
 608  *
 609  * ret = security_server_is_pwd_valid(&attempt, &max_attempt, &expire_sec);
 610  * if(is_pwd_set == SECURITY_SERVER_API_ERROR_NO_PASSWORD)
 611  * {
 612  *      printf("%s", "There is no password exists\n");
 613  *      ret = security_server_set_pwd(NULL, "this_is_new_pwd", 20, 365);
 614  *      if(ret != SECURITY_SERVER_API_SUCCESS)
 615  *      {
 616  *              printf("%s", "we have error\n");
 617  *              ...
 618  *      }
 619  * }
 620  * else if(is_pwd_set == SECURITY_SERVER_API_SUCCESS && expire_sec > 0 && attempt < max_attempts)
 621  * {
 622  *      printf("%s", "Password is valid by now\n");
 623  *      ret = security_server_set_pwd("this_is_current_pwd", "this_is_new_pwd", 20, 365);
 624  *      if(ret != SECURITY_SERVER_API_SUCCESS)
 625  *      {
 626  *              printf("%s", "we have error\n");
 627  *              ...
 628  *      }
 629  * }
 630  * else
 631  * {
 632  *      printf("%s", "Something wrong\n");
 633  * }
 634  * ...
 635  *
 636  * \endcode
 637  *
 638  * Access to this function requires SMACK rule: "<app_label> security-server::api-password-set w"
 639 */
 640 int security_server_set_pwd(const char *cur_pwd,
 641                             const char *new_pwd,
 642                             const unsigned int max_challenge,
 643                             const unsigned int valid_period_in_days);
 644
 645
 646 /**
 647  * \par Description:
 648  * This API sets validity period for currently setup password.
 649  *
 650  * \par Purpose:
 651  * This API should be used by Enterprise authorities to modify password policy. To be used only with valid password setup.
 652  *
 653  * \par Typical use case:
 654  * Authorized application calls this API to change current passwords validity when password policy needs to be changed.
 655  *
 656  * \par Method of function operation:
 657  * Function attempts to find currently set password and changes its current validity to passed number of days. Retry counter for the password is reset to zero.
 658  * If there is no password set, function returns proper error code.
 659  *
 660  * \par Sync (or) Async:
 661  * This is a Synchronous API.
 662  * \param[in] valid_period_in_days. Number of days that this password is valid. 0 means infinity
 663  *
 664  * \return 0 on success, negative integer error code on error.
 665  *
 666  * \par Prospective clients:
 667  * Platform's THE ONLY setting application and some dedicated privileged processes
 668  *
 669  * \par Known issues/bugs:
 670  * Identifying calling peer is not ready yet, should be based on SMACK somehow.
 671  *
 672  * \see security_server_is_pwd_valid(), security_server_chk_pwd(), security_server_reset_pwd()
 673  *
 674  * Access to this function requires SMACK rule: "<app_label> security-server::api-password-set w"
 675  */
 676 int security_server_set_pwd_validity(const unsigned int valid_period_in_days);
 677
 678
 679 /**
 680  * \par Description:
 681  * This API sets maximum number of attempts for currently setup password.
 682  *
 683  * \par Purpose:
 684  * This API should be used by Enterprise authorities to modify password policy. To be used only with valid password setup.
 685  *
 686  * \par Typical use case:
 687  * Authorized application calls this API to change current passwords max attempt number when password policy needs to be changed.
 688  *
 689  * \par Method of function operation:
 690  * Function attempts to find currently set password and changes its max attempt number to passed one. Retry counter for the password is reset to zero.
 691  * If there is no password set, function returns proper error code.
 692  *
 693  * \par Sync (or) Async:
 694  * This is a Synchronous API.
 695  * \param[in] max_challenge Maximum number of attempts that user can try to check the password without success in serial. 0 means infinity.
 696  *
 697  * \return 0 on success, negative integer error code on error.
 698  *
 699  * \par Prospective clients:
 700  * Platform's THE ONLY setting application and some dedicated privileged processes
 701  *
 702  * \par Known issues/bugs:
 703  * Identifying calling peer is not ready yet, should be based on SMACK somehow.
 704  *
 705  * \see security_server_is_pwd_valid(), security_server_chk_pwd(), security_server_reset_pwd()
 706  *
 707  * Access to this function requires SMACK rule: "<app_label> security-server::api-password-set w"
 708  */
 709 int security_server_set_pwd_max_challenge(const unsigned int max_challenge);
 710
 711 /**
 712  * \par Description:
 713  * This API sets phone password without performing any checks connected with provided password. It
 714  * should be used only if current password is invalid or user forgot the password.
 715  *
 716  * \par Purpose:
 717  * This API should be used by setting application or dedicated processes when the user changes his/her phone password.
 718  *
 719  * \par Typical use case:
 720  * User forgets the password. He calls emergency manager(auto or manual)  for reset password. Emergency manager calls this API and reset phone password.
 721  *
 722  * \par Method of function operation:
 723  * Resetting phone password with input string without any matching current password. Function does
 724  * no checks before password replacement (expiration time check, currently set password checks,
 725  * history check and attempt count check are skipped).
 726  *
 727  * \par Sync (or) Async:
 728  * This is a Synchronous API.
 729  *
 730  * \par Important notes:
 731  * There is retry timer on this API to limit replay attack. You will get error if you called this API too often.\n
 732  *
 733  * \param[in] new_pwd Null terminated new password string. It must not a NULL pointer.
 734  * \param[in] max_challenge Maximum number of attempts that user can try to check the password without success in serial. 0 means infinity.
 735  * \param[in] valid_period_in_days. Number of days that this password is valid. 0 means infinity
 736  *
 737  * \return 0 on success, negative integer error code on error.
 738  *
 739  * \par Prospective clients:
 740  * Platform's THE ONLY setting application and some dedicated privileged processes
 741  *
 742  * \par Known issues/bugs:
 743  * None
 744  *
 745  * \pre None
 746  *
 747  * \post None
 748  *
 749  * \see security_server_is_pwd_valid(), security_server_chk_pwd(), security_server_set_pwd()
 750  *
 751  * \remarks Only dedicated applications can call this API. The password file will be access controlled and securely hashed. Security-server will remain previous password file to recover unexpected password file corruption.
 752  *
 753  * \par Sample code:
 754  * \code
 755  * #include <security-server.h>
 756  * ...
 757  * int ret;
 758  *
 759  *      ret = security_server_reset_pwd("this_is_new_pwd", 20, 365);
 760  *      if(retval != SECURITY_SERVER_API_SUCCESS)
 761  *      {
 762  *              printf("%s", "we have error\n");
 763  *              ...
 764  *      }
 765  * ...
 766  *
 767  * \endcode
 768  *
 769  * Access to this function requires SMACK rule: "<app_label> security-server::api-password-reset w"
 770 */
 771 int security_server_reset_pwd(const char *new_pwd,
 772                               const unsigned int max_challenge,
 773                               const unsigned int valid_period_in_days);
 774
 775 /**
 776  * \par Description:
 777  * This API compares stored phone password with challenged input value.
 778  *
 779  * \par Purpose:
 780  * This API should be used by applications which has phone UI lock capability.
 781  *
 782  * \par Typical use case:
 783  * Lock screen calls this API after user typed phone password and pressed okay.
 784  *
 785  * \par Method of function operation:
 786  * Sends challenged password to security-server, security-server compares hashed current password and hashed challenged password.
 787  *
 788  * \par Sync (or) Async:
 789  * This is a Synchronous API.
 790  *
 791  * \par Important notes:
 792  * There is retry timer on this API to limit replay attack. You will get error if you called this API too often.\n
 793  *
 794  * \param[in] challenge Null terminated challenged password string. It must not a NULL pointer.
 795  * \param[out] current_attempts Number of password check missed attempts.
 796  * \param[out] max_attempts Number of maximum attempts that the password locks. 0 means infinite
 797  * \param[out] valid_secs Remaining time in second which represents this password will be expired. 0xFFFFFFFF means infinite
 798  *
 799  * \return 0 on success, negative integer error code on error.
 800  *
 801  * \par Prospective clients:
 802  * Applications which has phone UI lock feature.
 803  *
 804  * \par Known issues/bugs:
 805  * None
 806  *
 807  * \pre None
 808  *
 809  * \post None
 810  *
 811  * \see security_server_is_pwd_valid(), security_server_set_pwd()
 812  *
 813  * \remarks The password file will be acces controlled and securely hashed. Security-server will remain previous password file to recover unexpected password file curruption.
 814  *
 815  * \par Sample code:
 816  * \code
 817  * #include <security-server.h>
 818  * ...
 819  * int retval;
 820  * unsigned int attempt, max_attempt, expire_sec;
 821  *
 822  * retval = security_server_chk_pwd("is_this_password", &attmpt, &max_attempt, &expire_sec);
 823  * if(retval == SECURITY_SERVER_API_ERROR_PASSWORD_MISMATCH)
 824  * {
 825  *      printf("%s", "Oh you typed wrong password\n");
 826  *      ...
 827  * }
 828  * else if(retval == SECURITY_SERVER_API_SUCCESS)
 829  * {
 830  *      printf("%s", "You remember your password.\n");
 831  *      ...
 832  * }
 833  * ...
 834  *
 835  * \endcode
 836  *
 837  * Access to this function requires SMACK rule: "<app_label> security-server::api-password-check w"
 838 */
 839 int security_server_chk_pwd(const char *challenge,
 840                             unsigned int *current_attempt,
 841                             unsigned int *max_attempt,
 842                             unsigned int *valid_secs);
 843
 844
 845 /**
 846  * \par Description:
 847  * This API set the number of password history which should be maintained. Once this number set, user cannot reuse recent number of passwords which is described in this history value
 848  *
 849  * \par Purpose:
 850  * This API should be used only by dedicated process in the platform.
 851  *
 852  * \par Typical use case:
 853  * Enterprise manager calls this API when the enterprise wants to enforce harder password policy.
 854  *
 855  * \par Method of function operation:
 856  * When enterprise manager (MDM) is trying to change the security policy for phone password, it calls this API background to change the history policy.
 857  *
 858  * \par Sync (or) Async:
 859  * This is a Synchronous API.
 860  *
 861  * \par Important notes:
 862  * There is retry timer on this API to limit replay attack. You will get error if you called this API too often.\n
 863  *
 864  * \param[in] history_size Number of history to be checked when user tries to change password. Maximum is currently 50
 865  *
 866  * \return 0 on success, negative integer error code on error.
 867  *
 868  * \par Prospective clients:
 869  * MDM client, Enterprise manager.
 870  *
 871  * \par Known issues/bugs:
 872  * None
 873  *
 874  * \pre None
 875  *
 876  * \post None
 877  *
 878  * \see security_server_set_pwd()
 879  *
 880  * \remarks The password file will be access controlled and securely hashed. Security-server will remain previous password file to recover unexpected password file curruption.
 881  *
 882  * \par Sample code:
 883  * \code
 884  * #include <security-server.h>
 885  * ...
 886  * int retval;
 887  *
 888  * ret = security_server_set_pwd_history(100);
 889  *      if(ret != SECURITY_SERVER_API_SUCCESS)
 890  *      {
 891  *              printf("%s", "You have error\n");
 892  *              ...
 893  *      }
 894  * ...
 895  *
 896  * \endcode
 897  *
 898  * Access to this function requires SMACK rule: "<app_label> security-server::api-password-set w"
 899 */
 900 int security_server_set_pwd_history(int history_size);
 901
 902 /*
 903  * This function allows to get process SMACK label by passing cookie assigned
 904  * to process. Function returns pointer to allocated buffer with label.
 905  * User has to free the buffer after using.
 906  *
 907  * \param[in] Pointer to cookie
 908  *
 909  * \return Pointer to SMACK label or NULL
 910  *
 911  * \par For free label use free(), label allocated by calloc()
 912  *      User responsibility is to free resource.
 913  *
 914  * Access to this function requires SMACK rule: "<app_label> security-server::api-cookie-check w"
 915  */
 916 char *security_server_get_smacklabel_cookie(const char *cookie);
 917
 918 /*
 919  * This function allows to get process SMACK label by passing socket descriptor.
 920  * Function returns pointer to allocated buffer with label.
 921  * User has to free the buffer after using.
 922  *
 923  * \param[in] Socket descriptor
 924  *
 925  * \return Pointer to SMACK label or NULL
 926  *
 927  * \par For free label use free(), label allocated by calloc().
 928  *      User responsibility is to free resource.
 929  *
 930  * Access to this function not requires SMACK rule
 931  */
 932 char *security_server_get_smacklabel_sockfd(int fd);
 933
 934 /*
 935  * This function will give permissions "rwxat" from
 936  * (subject) customer_label to caller process (object).
 937  * Object label will be extracted from socket.
 938  *
 939  * \param[in] CUSTOMER_LABEL execute label of the process that should have access to caller.
 940  * \param[in] CUSTOMER_PID all rules applied by this function should be removed from system
 941  *                         when process with CUSTOMER_PID dies.
 942  *
 943  * \return SECURITY_SERVER_API_SUCCESS on success
 944  * \return SECURITY_SERVER_API_ERROR_GETTING_SOCKET_LABEL_FAILED
 945  * \return SECURITY_SERVER_API_ERROR_ACCESS_DENIED
 946  * \return SECURITY_SERVER_API_ERROR_BAD_REQUEST input params were rejected by security-server
 947  * \return SECURITY_SERVER_API_ERROR_INPUT_PARAM input params were rejected by client library
 948  * \return SECURITY_SERVER_API_ERROR_SOCKET connection to security server failed.
 949  *
 950  * Important: In current implementation CUSTOMER_PID is ignored! This mean that rules applied
 951  * by this function won't be revoke until device reset!
 952  *
 953  * Access to this function requires SMACK rule: "<app_label> security-server::api-data-share w"
 954  * */
 955 int security_server_app_give_access(const char *customer_label, int customer_pid);
 956
 957 /*
 958  * This function allows middleware to check privileges of process with specified PID or socket
 959  * file descriptor.
 960  * Service is able to check process access to the specified object label with specified
 961  * access rights.
 962  *
 963  * \param[in] PID id of process or SOCKFD socket file descriptor to be checked
 964  * \param[in] SMACK object label
 965  * \param[in] SMACK access rights to be checked
 966  *
 967  * \return Privilege confirm or error code
 968  * \return SECURITY_SERVER_API_SUCCESS - on succes
 969  *
 970  * Access to this function requires SMACK rule: "<app_label> security-server::api-privilege-by-pid w"
 971  */
 972 int security_server_check_privilege_by_pid(int pid, const char *object, const char *access_rights);
 973
 974 int security_server_check_privilege_by_sockfd(int sockfd,
 975                                               const char *object,
 976                                               const char *access_rights);
 977 /*
 978  * This function allows middleware to enable permissions for specified app_id.
 979  *
 980  * \param[in] Application ID
 981  * \param[in] Application type defined in enum at the beginning of this file
 982  * \param[in] Permissions list
 983  * \param[in] Persistent
 984  *
 985  * \return SECURITY_SERVER_API_SUCCESS on success or error code on fail
 986  *
 987  * Access to this function requires SMACK rule: "<app_label> security-server::api-app-permissions w"
 988  */
 989 int security_server_app_enable_permissions(const char *app_id, app_type_t app_type, const char **perm_list, int persistent);
 990
 991 /*
 992  * This function allows middleware to disable permissions for specified app_id.
 993  *
 994  * \param[in] Application ID
 995  * \param[in] Application type defined in enum at the beginning of this file
 996  * \param[in] Permissions list
 997  *
 998  * \return SECURITY_SERVER_API_SUCCESS on success or error code on fail
 999  *
1000  * Access to this function requires SMACK rule: "<app_label> security-server::api-app-permissions w"
1001  */
1002 int security_server_app_disable_permissions(const char *app_id, app_type_t app_type, const char **perm_list);
1003
1004 /*
1005  * This function allows middleware to get UID assigned to cookie
1006  *
1007  * \param[in] Cookie
1008  * \param[out] Handler to store UID
1009  *
1010  * \return SECURITY_SERVER_API_SUCCESS on success or error code on fail
1011  *
1012  * Access to this function requires SMACK rule: "<app_label> security-server::api-cookie-check w"
1013  */
1014 int security_server_get_uid_by_cookie(const char *cookie, uid_t *uid);
1015
1016 /*
1017  * This function allows middleware to check if an app has the specified privilege
1018  * enabled.
1019  *
1020  * \param[in] Application ID
1021  * \param[in] Application type
1022  * \param[in] Privilege name
1023  * \param[out] Handler to store the result. It is set to 1 (true) if privilege is enabled, 0 (false) otherwise
1024  *
1025  * \return SECURITY_SERVER_API_SUCCESS on success or error code on fail
1026  *
1027  * Access to this function requires SMACK rule: "<app_label> security-server::api-app-privilege-by-name w"
1028  */
1029 int security_server_app_has_privilege(const char *app_id,
1030                                       app_type_t app_type,
1031                                       const char *privilege_name,
1032                                       int *result);
1033
1034 /*
1035  * This function allows middleware to check if caller app has the specified privilege
1036  * enabled. Security Server gets caller app smack label from the IPC socket.
1037  *
1038  * \param[in] Application type
1039  * \param[in] Privilege name
1040  * \param[out] Handler to store the result. It is set to 1 (true) if privilege is enabled, 0 (false) otherwise
1041  *
1042  * \return SECURITY_SERVER_API_SUCCESS on success or error code on fail
1043  *
1044  * Access to this function requires SMACK rule: "<app_label> security-server::api-app-privilege-by-name w"
1045  */
1046 int security_server_app_caller_has_privilege(app_type_t app_type,
1047                                              const char *privilege_name,
1048                                              int *result);
1049
1050 /*
1051  * This function allows middleware to get GID assigned to cookie
1052  *
1053  * \param[in] Cookie
1054  * \param[out] Handler to store GID
1055  *
1056  * \return SECURITY_SERVER_API_SUCCESS on success or error code on fail
1057  *
1058  * Access to this function requires SMACK rule: "<app_label> security-server::api-cookie-check w"
1059  */
1060 int security_server_get_gid_by_cookie(const char *cookie, gid_t *gid);
1061
1062 /*
1063  * This function allows to create, if doesn't exist, or open existing file by
1064  * Security Server on behalf of calling process in secured directory.
1065  *
1066  * \param[in] File name to create/open
1067  * \param[out] File descriptor
1068  *
1069  * \return SECURITY_SERVER_API_SUCCESS on success or error code on fail
1070  *
1071  * Access to this function requires SMACK rule: "<app_label> security-server::api-open-for w"
1072  */
1073 int security_server_open_for(const char *filename, int *fd) __attribute__((deprecated));
1074
1075 /*
1076  * This function allows to create, if doesn't exist, file by Security Server on
1077  * behalf of calling process in secured directory. File gets smack label of
1078  * designated client process, passed as 'client_label' argument, which is
1079  * allowed to read created file.
1080  *
1081  * \param[in] File name to create
1082  * \param[in] Label of designated client
1083  * \param[out] File descriptor
1084  *
1085  * \return SECURITY_SERVER_API_SUCCESS on success or one of error codes on fail
1086  * \return SECURITY_SERVER_API_ERROR_ACCESS_DENIED
1087  * \return SECURITY_SERVER_API_ERROR_SOCKET
1088  * \return SECURITY_SERVER_API_ERROR_INPUT_PARAM
1089  * \return SECURITY_SERVER_API_ERROR_GETTING_SOCKET_LABEL_FAILED
1090  * \return SECURITY_SERVER_API_ERROR_FILE_CREATION_FAILED
1091  * \return SECURITY_SERVER_API_ERROR_SETTING_FILE_LABEL_FAILED
1092  * \return SECURITY_SERVER_API_ERROR_FILE_EXIST
1093  *
1094  * Access to this function requires SMACK rule: "<app_label> security-server::api-open-for w"
1095  */
1096 int security_server_shared_file_open(const char *filename, const char *client_label, int *fd);
1097
1098 /*
1099  * This function allows to open existing file by Security Server on behalf of
1100  * calling process in secured directory. Security Server checks smack label
1101  * of calling process and if it's the same as file label access to file is
1102  * granted.
1103  *
1104  * \param[in] File name to open
1105  * \param[out] File descriptor
1106  *
1107  * \return SECURITY_SERVER_API_SUCCESS on success or one of error codes on fail
1108  * \return SECURITY_SERVER_API_ERROR_ACCESS_DENIED
1109  * \return SECURITY_SERVER_API_ERROR_SOCKET
1110  * \return SECURITY_SERVER_API_ERROR_INPUT_PARAM
1111  * \return SECURITY_SERVER_API_ERROR_GETTING_SOCKET_LABEL_FAILED
1112  * \return SECURITY_SERVER_API_ERROR_GETTING_FILE_LABEL_FAILED
1113  * \return SECURITY_SERVER_API_ERROR_AUTHENTICATION_FAILED
1114  * \return SECURITY_SERVER_API_ERROR_FILE_NOT_EXIST
1115  *
1116  * Access to this function requires SMACK rule: "<app_label> security-server::api-open-for w"
1117  */
1118 int security_server_shared_file_reopen(const char *filename, int *fd);
1119
1120 /*
1121  * This function allows to delete existing file by Security Server on behalf of
1122  * calling process in secured directory. Security Server checks smack label
1123  * of calling process and if it's the same as file label data file is deleted.
1124  *
1125  * \param[in] File name to delete
1126  *
1127  * \return SECURITY_SERVER_API_SUCCESS on success or one of error codes on fail
1128  * \return SECURITY_SERVER_API_ERROR_ACCESS_DENIED
1129  * \return SECURITY_SERVER_API_ERROR_SOCKET
1130  * \return SECURITY_SERVER_API_ERROR_INPUT_PARAM
1131  * \return SECURITY_SERVER_API_ERROR_GETTING_SOCKET_LABEL_FAILED
1132  * \return SECURITY_SERVER_API_ERROR_GETTING_FILE_LABEL_FAILED
1133  * \return SECURITY_SERVER_API_ERROR_AUTHENTICATION_FAILED
1134  * \return SECURITY_SERVER_API_ERROR_FILE_DELETION_FAILED
1135  * \return SECURITY_SERVER_API_ERROR_FILE_NOT_EXIST
1136  *
1137  * Access to this function requires SMACK rule: "<app_label> security-server::api-open-for w"
1138  */
1139 int security_server_shared_file_delete(const char *filename);
1140
1141 #ifdef __cplusplus
1142 }
1143 #endif
1144
1145 /**
1146  * @}
1147 */
1148
1149 /**
1150  * @}
1151 */
1152
1153 #endif