HttpAuth.h

00001 /*****************************************************************************
00002 *
00003 *  HttpAuth.h
00004 *  Copyright (C) 2011 Texas Instruments Incorporated - http://www.ti.com/
00005 *
00006 *  Redistribution and use in source and binary forms, with or without
00007 *  modification, are permitted provided that the following conditions
00008 *  are met:
00009 *
00010 *    Redistributions of source code must retain the above copyright
00011 *    notice, this list of conditions and the following disclaimer.
00012 *
00013 *    Redistributions in binary form must reproduce the above copyright
00014 *    notice, this list of conditions and the following disclaimer in the
00015 *    documentation and/or other materials provided with the   
00016 *    distribution.
00017 *
00018 *    Neither the name of Texas Instruments Incorporated nor the names of
00019 *    its contributors may be used to endorse or promote products derived
00020 *    from this software without specific prior written permission.
00021 *
00022 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
00023 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
00024 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00025 *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
00026 *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
00027 *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
00028 *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
00029 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
00030 *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
00031 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
00032 *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00033 *
00034 *****************************************************************************/
00035 #ifndef _HTTP_AUTH_H_
00036 #define _HTTP_AUTH_H_
00037 
00038 #include "HttpConfig.h"
00039 #include "HttpString.h"
00040 #include "HttpRequest.h"
00041 #ifdef HTTP_CORE_ENABLE_AUTH
00042 
00043 /** 
00044  * @defgroup HttpAuth HTTP Authentication
00045  * This module implements the HTTP digest access authentication routines.
00046  * Note this module is only compiled if HTTP_CORE_ENABLE_AUTH is defined in HttpConfig.h
00047  * 
00048  * When a "not authorized" response is sent to the client, the WWW-Authenticate header is built using HttpAuth_ResponseAuthenticate()
00049  * This in turn generates new nonce and opaque values which will be used for authentication.
00050  * Note that since only a single nonce is kept, only one client may ever be authenticated simultaneously.
00051  * When another request with Authorization header is received, it is verified using HttpAuth_RequestAuthenticate()
00052  * If all authentication tests pass, then the appropriate flag is set in the request to indicate that.
00053  *
00054  * @{
00055  */
00056 
00057 /**
00058  * Initialize the authentication module, so that it accepts the specified username and password
00059  * This function should be called during server initialization in order to set initial user credentials
00060  * This function may then be called at any time during the operation of the server in order to set different user credentials
00061  * @param username The authorized user's username 
00062  * @param password The authorized user's password
00063  */
00064 void HttpAuth_Init(struct HttpBlob username, struct HttpBlob password);
00065 
00066 /**
00067  * Builds and returns the WWW-Authenticate response header.
00068  * This implies generating a new nonce, etc.
00069  * Notes about return value:
00070  *     Upon entry, pWWWAuthenticate should point to the place in the packet-send buffer where the header needs to be generated, and also specify the maximum amount of bytes available for the header at that place
00071  *     Upon return, pWWWAuthenticate points to the same location, but specifies the actual length of the header.
00072  *     If the returned length is 0, this means that there was not enough room in the buffer for the header.
00073  *     In such a case, the core may try again with a larger buffer
00074  * @param pRequest All data about the request
00075  * @param[in,out] pWWWAuthenticate On entry specifies the memory location to build the header at, and the maximum size. On return, specifies the same location and the actual size of the header line
00076  */
00077 void HttpAuth_ResponseAuthenticate(struct HttpRequest* pRequest, struct HttpBlob* pWWWAuthenticate);
00078 
00079 /**
00080  * Check the authentication header in a request, and either authorize the request or deny it
00081  * If the authorization succeeds, then HTTP_REQUEST_FLAG_AUTHENTICATED is added to the request flags
00082  * @param pRequest All data about the request to authorize
00083  * @param authorization The full string of the Authorization header
00084  */
00085 void HttpAuth_RequestAuthenticate(struct HttpRequest* pRequest, struct HttpBlob authorization);
00086 
00087 /// @}
00088 
00089 #endif // HTTP_CORE_ENABLE_AUTH
00090 
00091 #endif // _HTTP_AUTH_H_
00092