haiku/docs/user/netservices/HttpAuthentication.dox

/*
 * Copyright 2013 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Adrien Destugues, pulkomandy@pulkomandy.tk
 *
 * Corresponds to:
 *		headers/private/netservices/HttpAuthentication.h		hrev54923
 *		src/kits/network/libnetservices/HttpAuthentication.cpp	hrev54923
 */

/*!
	\file HttpAuthentication.h
	\ingroup netservices
	\brief Authentication token for use in HTTP protocol communications.
*/

/*!
	\class BPrivate::Network::BHttpAuthentication
	\ingroup netservices
	\brief Authentication token for the HTTP protocol.

	This class allows managing of an authenticated http session. It stores the
	authentication credentials and realm and provides tools for generating the
	required nonces and hashes.

	An instance of this class should be used for the whole length of an HTTP
	authenticated session. Initialize it by calling Initialize() and setting the
	username and password (from the constructor or the setter methods). Then,
	for each page that requires authentication, generate a token using the
	Authorization() method.
*/

/*!
	\fn BHttpAuthentication::BHttpAuthentication()
	\brief Default constructor.

	This will create an unconfigured authentication object with the
	authentication method set to B_HTTP_AUTHENTICATION_NONE.

	You have to set the username and password, and initialize the object using
	the Initialize method with proper authentication data.
*/

/*!
	\fn BHttpAuthentication::BHttpAuthentication(const BString& username,
		const BString& password)
	\brief Create an authentication session with the given name and password.

	The authentication method is set to B_HTTP_AUTHENTICATION_NONE.
	This object can then be used with the Initialize method to bind it to an
	HTTP authenticated session.
*/

/*!
	\fn void BHttpAuthentication::SetUserName(const BString& username)
	\brief Set the user name.

	\param username the new user name.
*/

/*!
	\fn void BHttpAuthentication::SetPassword(const BString& password)
	\brief Set the password

	\param password the new password.
*/

/*!
	\fn void BHttpAuthentication::SetMethod(BHttpAuthenticationMethod method)
	\brief Set the authentication method

	\param method the new authentication method.
*/

/*!
	\fn status_t BHttpAuthentication::Initialize(const BString& wwwAuthenticate)
	\brief Initialize the object from the given authentication data

	This method will parse the given authentication challenge and initialize
	the authentication type to either B_HTTP_AUTHENTICATION_BASIC or 
	B_HTTP_AUTHENTICATION_DIGEST. The authentication parameters (realm, nonce,
	algorithm) and state (opaque, stale) are also parsed and stored.

	\param wwwAuthenticate the value of the WWW-Authenticate HTTP header field.
	\return B_OK if the request was parsed, B_ERROR if there is a parsing error,
		B_BAD_VALUE if the authentication string is empty.
*/

/*!
	\fn const BString& BHttpAuthentication::UserName() const
	\returns the user name.
*/

/*!
	\fn const BString& BHttpAuthentication::Password() const
	\returns the password.
*/

/*!
	\fn BHttpAuthenticationMethod BHttpAuthentication::Method() const
	\returns the authentication method
*/

/*!
	\fn BString BHttpAuthentication::Authorization(const BUrl& url,
		const BString& method) const
	\brief Generate an authentication reply for the given URL and method.

	For basic authentication, the reply is constant and is a Base64 encoding of
	the string made of 'username:password'. In digest mode, each request will
	have a different reply, so you must call this method for each page you want
	to authenticate with.

	\return the generated reply
*/