saslwrapper.h 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146
  1. /*
  2. * Licensed to the Apache Software Foundation (ASF) under one
  3. * or more contributor license agreements. See the NOTICE file
  4. * distributed with this work for additional information
  5. * regarding copyright ownership. The ASF licenses this file
  6. * to you under the Apache License, Version 2.0 (the
  7. * "License"); you may not use this file except in compliance
  8. * with the License. You may obtain a copy of the License at
  9. *
  10. * http://www.apache.org/licenses/LICENSE-2.0
  11. *
  12. * Unless required by applicable law or agreed to in writing,
  13. * software distributed under the License is distributed on an
  14. * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  15. * KIND, either express or implied. See the License for the
  16. * specific language governing permissions and limitations
  17. * under the License.
  18. */
  19. #include <stdint.h>
  20. #include <string>
  21. namespace saslwrapper {
  22. /**
  23. * The following type is used for output arguments (that are strings). The fact that it has
  24. * a unique name is used in a SWIG typemap to indicate output arguments. For scripting languages
  25. * such as Python and Ruby (which do not support output arguments), the outputs are placed in and
  26. * array that is returned by the function. For example, a function that looks like:
  27. *
  28. * bool function(const string& input, output_string& out1, output_string& out2);
  29. *
  30. * would be called (in Python) like this:
  31. *
  32. * boolResult, out1, out2 = function(input)
  33. */
  34. typedef std::string output_string;
  35. class ClientImpl;
  36. class Client {
  37. public:
  38. Client();
  39. ~Client();
  40. /**
  41. * Set attributes to be used in authenticating the session. All attributes should be set
  42. * before init() is called.
  43. *
  44. * @param key Name of attribute being set
  45. * @param value Value of attribute being set
  46. * @return true iff success. If false is returned, call getError() for error details.
  47. *
  48. * Available attribute keys:
  49. *
  50. * service - Name of the service being accessed
  51. * username - User identity for authentication
  52. * authname - User identity for authorization (if different from username)
  53. * password - Password associated with username
  54. * host - Fully qualified domain name of the server host
  55. * maxbufsize - Maximum receive buffer size for the security layer
  56. * minssf - Minimum acceptable security strength factor (integer)
  57. * maxssf - Maximum acceptable security strength factor (integer)
  58. * externalssf - Security strength factor supplied by external mechanism (i.e. SSL/TLS)
  59. * externaluser - Authentication ID (of client) as established by external mechanism
  60. */
  61. bool setAttr(const std::string& key, const std::string& value);
  62. bool setAttr(const std::string& key, uint32_t value);
  63. /**
  64. * Initialize the client object. This should be called after all of the properties have been set.
  65. *
  66. * @return true iff success. If false is returned, call getError() for error details.
  67. */
  68. bool init();
  69. /**
  70. * Start the SASL exchange with the server.
  71. *
  72. * @param mechList List of mechanisms provided by the server
  73. * @param chosen The mechanism chosen by the client
  74. * @param initialResponse Initial block of data to send to the server
  75. *
  76. * @return true iff success. If false is returned, call getError() for error details.
  77. */
  78. bool start(const std::string& mechList, output_string& chosen, output_string& initialResponse);
  79. /**
  80. * Step the SASL handshake.
  81. *
  82. * @param challenge The challenge supplied by the server
  83. * @param response (output) The response to be sent back to the server
  84. *
  85. * @return true iff success. If false is returned, call getError() for error details.
  86. */
  87. bool step(const std::string& challenge, output_string& response);
  88. /**
  89. * Encode data for secure transmission to the server.
  90. *
  91. * @param clearText Clear text data to be encrypted
  92. * @param cipherText (output) Encrypted data to be transmitted
  93. *
  94. * @return true iff success. If false is returned, call getError() for error details.
  95. */
  96. bool encode(const std::string& clearText, output_string& cipherText);
  97. /**
  98. * Decode data received from the server.
  99. *
  100. * @param cipherText Encrypted data received from the server
  101. * @param clearText (output) Decrypted clear text data
  102. *
  103. * @return true iff success. If false is returned, call getError() for error details.
  104. */
  105. bool decode(const std::string& cipherText, output_string& clearText);
  106. /**
  107. * Get the user identity (used for authentication) associated with this session.
  108. * Note that this is particularly useful for single-sign-on mechanisms in which the
  109. * username is not supplied by the application.
  110. *
  111. * @param userId (output) Authenticated user ID for this session.
  112. */
  113. bool getUserId(output_string& userId);
  114. /**
  115. * Get error message for last error.
  116. * This function will return the last error message then clear the error state.
  117. * If there was no error or the error state has been cleared, this function will output
  118. * an empty string.
  119. *
  120. * @param error Error message string
  121. */
  122. void getError(output_string& error);
  123. private:
  124. ClientImpl* impl;
  125. // Declare private copy constructor and assignment operator. Ensure that this
  126. // class is non-copyable.
  127. Client(const Client&);
  128. const Client& operator=(const Client&);
  129. };
  130. }