diff options
Diffstat (limited to 'qpid/extras/sasl/include/saslwrapper.h')
| -rw-r--r-- | qpid/extras/sasl/include/saslwrapper.h | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/qpid/extras/sasl/include/saslwrapper.h b/qpid/extras/sasl/include/saslwrapper.h new file mode 100644 index 0000000000..bb2a9af7ff --- /dev/null +++ b/qpid/extras/sasl/include/saslwrapper.h @@ -0,0 +1,146 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. +*/ + +#include <stdint.h> +#include <string> + +namespace saslwrapper { + + /** + * The following type is used for output arguments (that are strings). The fact that it has + * a unique name is used in a SWIG typemap to indicate output arguments. For scripting languages + * such as Python and Ruby (which do not support output arguments), the outputs are placed in and + * array that is returned by the function. For example, a function that looks like: + * + * bool function(const string& input, output_string& out1, output_string& out2); + * + * would be called (in Python) like this: + * + * boolResult, out1, out2 = function(input) + */ + typedef std::string output_string; + class ClientImpl; + + class Client { + public: + + Client(); + ~Client(); + + /** + * Set attributes to be used in authenticating the session. All attributes should be set + * before init() is called. + * + * @param key Name of attribute being set + * @param value Value of attribute being set + * @return true iff success. If false is returned, call getError() for error details. + * + * Available attribute keys: + * + * service - Name of the service being accessed + * username - User identity for authentication + * authname - User identity for authorization (if different from username) + * password - Password associated with username + * host - Fully qualified domain name of the server host + * maxbufsize - Maximum receive buffer size for the security layer + * minssf - Minimum acceptable security strength factor (integer) + * maxssf - Maximum acceptable security strength factor (integer) + * externalssf - Security strength factor supplied by external mechanism (i.e. SSL/TLS) + * externaluser - Authentication ID (of client) as established by external mechanism + */ + bool setAttr(const std::string& key, const std::string& value); + bool setAttr(const std::string& key, uint32_t value); + + /** + * Initialize the client object. This should be called after all of the properties have been set. + * + * @return true iff success. If false is returned, call getError() for error details. + */ + bool init(); + + /** + * Start the SASL exchange with the server. + * + * @param mechList List of mechanisms provided by the server + * @param chosen The mechanism chosen by the client + * @param initialResponse Initial block of data to send to the server + * + * @return true iff success. If false is returned, call getError() for error details. + */ + bool start(const std::string& mechList, output_string& chosen, output_string& initialResponse); + + /** + * Step the SASL handshake. + * + * @param challenge The challenge supplied by the server + * @param response (output) The response to be sent back to the server + * + * @return true iff success. If false is returned, call getError() for error details. + */ + bool step(const std::string& challenge, output_string& response); + + /** + * Encode data for secure transmission to the server. + * + * @param clearText Clear text data to be encrypted + * @param cipherText (output) Encrypted data to be transmitted + * + * @return true iff success. If false is returned, call getError() for error details. + */ + bool encode(const std::string& clearText, output_string& cipherText); + + /** + * Decode data received from the server. + * + * @param cipherText Encrypted data received from the server + * @param clearText (output) Decrypted clear text data + * + * @return true iff success. If false is returned, call getError() for error details. + */ + bool decode(const std::string& cipherText, output_string& clearText); + + /** + * Get the user identity (used for authentication) associated with this session. + * Note that this is particularly useful for single-sign-on mechanisms in which the + * username is not supplied by the application. + * + * @param userId (output) Authenticated user ID for this session. + */ + bool getUserId(output_string& userId); + + /** + * Get error message for last error. + * This function will return the last error message then clear the error state. + * If there was no error or the error state has been cleared, this function will output + * an empty string. + * + * @param error Error message string + */ + void getError(output_string& error); + + private: + ClientImpl* impl; + + // Declare private copy constructor and assignment operator. Ensure that this + // class is non-copyable. + Client(const Client&); + const Client& operator=(const Client&); + }; + +} |