am_web.h revision 4fe4e4f798a84a46e567f64ceadd3648eb0582d4
/* -*- Mode: C -*- */
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the License at
* See the License for the specific language governing
* permission and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at opensso/legal/CDDLv1.0.txt.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* your own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* $Id: am_web.h,v 1.4 2008/08/19 19:11:38 veiming Exp $
*/
#ifndef AM_WEB_H
#define AM_WEB_H
#if defined(WINNT) && !(AM_STATIC_LIB)
#if defined(AM_BUILDING_LIB)
#else /* if defined(AM_BUILDING_LIB) */
#endif
#else /* if defined(WINNT) */
#define AM_WEB_EXPORT
#endif
#if !defined(WINNT)
#define AM_WEB_ALLOW_USER_MSG "User %s was allowed access to %s."
#define AM_WEB_DENIED_USER_MSG "User %s was denied access to %s."
#endif
#include <stdlib.h>
#include <am.h>
#include "am_policy.h"
#define AM_RESERVED NULL
/**
* -------- constants --------
*/
#define AM_WEB_ACTION_ALLOWED "allow"
#define AM_WEB_ACTION_DENIED "deny"
/*
* Constants used in looking up HTTP headers or request attributes.
*
* NOTE: These constants must be all lowercase or the lookup will fail.
*/
#define CONTENT_LENGTH_HDR "content-length"
#define COOKIE_HDR "cookie"
#define HOST_HDR "host"
#define PATH_INFO "path-info"
#define REQUEST_IP_ADDR "ip"
#define REQUEST_METHOD "method"
#define REQUEST_QUERY "query"
#define REQUEST_URI "uri"
#define REQUEST_PROTOCOL "protocol"
#define REQUEST_CLF "clf-request"
#define AUTH_USER_VAR "auth-user"
#define AUTH_TYPE_VAR "auth-type"
#define GOTO_PARAMETER "goto"
#define REQUEST_METHOD_TYPE "sunwMethod"
#define REFERER_SERVLET "refererservlet"
#define FORM_METHOD_POST "POST"
#define FORM_METHOD_GET "GET"
#define HTTP_PROTOCOL_STR "http://"
#define HTTPS_PROTOCOL_STR "https://"
#define AM_WEB_PROPERTY_PREFIX "com.sun.am.policy.agents.config."
#define AM_WEB_PROPERTY_PREFIX_OLD "com.sun.am.policy.agents."
#define AM_WEB_CHECK_CLIENT_IP_PROPERTY_OLD AM_WEB_PROPERTY_PREFIX_OLD "client_ip_validation_enable"
#define AM_WEB_REVERSE_NOT_ENFORCED_LIST_OLD AM_WEB_PROPERTY_PREFIX_OLD "reverse_the_meaning_of_notenforcedList"
#define AM_WEB_NOT_ENFORCED_IPADDRESS_OLD AM_WEB_PROPERTY_PREFIX_OLD "notenforced_client_IP_address_list"
#define AM_WEB_IGNORE_POLICY_EVALUATION_IF_NOT_ENFORCED AM_WEB_PROPERTY_PREFIX "ignore_policy_evaluation_if_notenforced"
#define AM_WEB_POST_CACHE_CLEANPUP_INTERVAL_OLD AM_WEB_PROPERTY_PREFIX_OLD "postcachecleanupinterval"
#define AM_WEB_POST_CACHE_DATA_PRESERVE_OLD AM_WEB_PROPERTY_PREFIX_OLD "is_postdatapreserve_enabled"
#define AM_WEB_LOGOUT_COOKIE_RESET_PROPERTY_OLD AM_WEB_PROPERTY_PREFIX_OLD "logout.cookie_reset_list"
/* Following are log related properties */
/* Followings are for the attribute related properties */
#define AM_POLICY_PROFILE_ATTRS_COOKIE_MAX_AGE AM_WEB_PROPERTY_PREFIX "profile.attribute.cookie.maxage"
#define AM_POLICY_ATTRS_MULTI_VALUE_SEPARATOR AM_WEB_PROPERTY_PREFIX "attribute.multi_value_separator"
/* Followings are for the Header attribute modes */
#define AM_POLICY_SET_ATTRS_AS_COOKIE "HTTP_COOKIE"
#define AM_POLICY_SET_ATTRS_AS_COOKIE_OLD "COOKIE"
#define AM_POLICY_SET_ATTRS_AS_HEADER "HTTP_HEADER"
#define AM_POLICY_SET_ATTRS_AS_HEADER_OLD "HEADER"
#define AM_POLICY_SET_ATTRS_AS_NONE "NONE"
#define AM_COMMON_PROPERTY_PREFIX_IIS6_REPLAYPASSWD_KEY AM_COMMON_PROPERTY_PREFIX "replaypasswd.key"
#define AM_WEB_OWA_ENABLED_SESSION_TIMEOUT_URL AM_WEB_PROPERTY_PREFIX "iis.owa_enabled_session_timeout_url"
#define AM_WEB_NO_CHILD_THREAD_ACTIVATION_DELAY AM_WEB_PROPERTY_PREFIX "no_child_thread_activation_delay"
/*
* Enough space to hold PRTime key in a string
*/
#define AM_WEB_MAX_POST_KEY_LENGTH 64
/*
* Enough space to hold a formatted TCP port number and terminating NULL.
*/
#define AM_WEB_MAX_PORT_STR_LEN 6
/*
* Return values of am_web_is_cookie_present
*/
#define AM_WEB_COOKIE_EXIST 2
#define AM_WEB_COOKIE_MODIFIED 1
#define AM_WEB_COOKIE_ABSENT 0
#define AM_WEB_COOKIE_ERROR -1
/*
* Auth-Type identifier for OpenSSO authentication.
*/
#define AM_WEB_AUTH_TYPE_VALUE "DSAME"
/*
* Auth-Type ACCESS status.
*/
typedef enum {
AM_ACCESS_DENY = 0,
/*
* For agents request processing
*/
typedef enum {
typedef enum {
AM_WEB_RESULT_OK, /* access check was OK */
AM_WEB_RESULT_OK_DONE, /* OK and handled (for ex. notification) */
AM_WEB_RESULT_FORBIDDEN, /* access forbidden */
AM_WEB_RESULT_REDIRECT, /* redirected */
AM_WEB_RESULT_ERROR /* internal error */
typedef struct {
char *url; /* The full request URL */
char *query; /* query string if any */
char *path_info; /* path info if any */
char *client_ip; /* client IP if any */
char *cookie_header_val; /* the cookie header value if any */
void *reserved; /* reserved - do not set this */
/**
* for calling am_web_process_request for agents request processing.
*/
/**
* Get post data.
* The post data returned must be null terminated and will be freed by
* calling the free_post_data function.
* Should return AM_SUCCESS on success, any other error will result in
* HTTP internal error result.
*/
typedef struct {
void **args;
/**
* Free the post data in get_post_data. Can be null if not needed.
* Should return AM_SUCCESS if successful. If not status will be
* logged as warning but ignored.
*/
typedef struct {
void **args;
/**
* Set (and check) user
* Should return AM_SUCCESS on success, any other error will result in
* HTTP forbidden result.
*/
typedef struct {
void **args;
/**
* Set the request method.
* Should return AM_SUCCESS on success, any other error will result in
* HTTP internal error result.
*
* Arguments:
*
* args - agent defined arguments to pass in.
* method - the request method to set.
*
*/
typedef am_status_t (*am_web_set_method_func_t)(
typedef struct {
void **args;
/**
* Render the http result, one of am_web_result_t.
* For AM_WEB_RESULT_OK_DONE, agent should return a HTTP respons code 200 OK
* and the body of the HTTP response should be set to the string in the
* data argument.
* For AM_WEB_RESSULT_REDIRECT, agent should return a HTTP response code 302,
* and Location header should be set to the redirect url in the data argument.
*/
typedef struct {
void **args;
/**
* Set a header in the request.
* If a header of the same name already exists it should be replaced
* with another header of the same name.
*
* Arguments:
*
* args - agent defined arguments to pass in.
* name - the header name
* val - the header value
*
* Return:
*
* This function should return AM_SUCCESS if the header was successfully set
* and appropriate am_status_t code otherwise.
*/
typedef am_status_t (*am_web_set_header_in_request_func_t)(
typedef struct {
void **args;
/**
* Set(Add) a header in response.
* The header should be added to the response even if another header
* of the same name already exists.
*
* Arguments:
*
* args - agent defined arguments to pass in.
* name - the header name
* val - the header value
*
* Return:
*
* This function should return AM_SUCCESS if the header was successfully set
* and appropriate am_status_t code otherwise.
*/
typedef am_status_t (*am_web_add_header_in_response_func_t)(
typedef struct {
void **args;
/**
* structure for all the functions above
*/
typedef struct {
// get post data
// the post data returned must be null terminated.
// free the post data returned in get_post_data. Can be null if not needed
// set user in the web container.
// set method
// set a request header
// add a response header
// render http result
/**
* -------- policy methods --------
*/
/**
* Method to initialize the Agent Toolkit.
*/
/**
* Method to clean up the Agent Toolkit
*/
/*
* Evaluates the access control policies for a specified web-resource and
* action.
*
* Parameters:
* sso_token The sso_token from the OpenSSO cookie. This
* parameter may be NULL if there is no cookie present.
*
* url The URL whose accessibility is being determined.
* This parameter may not be NULL.
*
* action_name
* The action (GET, POST, etc.) being performed on the
* specified URL. This parameter may not be NULL.
*
* client_ip
* The IP address of the client attempting to access the
* specified URL. If client IP validation is turned on,
* then this parameter may not be NULL.
*
* env_parameter_map
* A map containing additional information about the user
* attempting to access the specified URL. This parameter
* may not be NULL.
*
* advices_map_ptr
* An output parameter where an am_map_t can be stored
* if the policy evaluation produces any advice information.
* This parameter may not be NULL.
*
* Returns:
* AM_SUCCESS
* if the evaluation was performed successfully and access
* is to be allowed to the specified resource
*
* AM_NO_MEMORY
* if the evaluation was not successfully completed due to
* insufficient memory being available
*
* AM_INVALID_ARGUMENT
* if any of the url, action_name, env_parameter_map, or
* advices_map_ptr parameters is NULL or if client IP validation
* is enabled and the client_ip parameter is NULL.
*
* AM_INVALID_SESSION
* if the specified sso_token does not refer to a currently
* valid session
*
* AM_ACCESS_DENIED
* if the policy information indicates that the user does
* not have permission to access the specified resource or
* any error is detected other than the ones listed above
*/
const char *path_info, const char *action_name,
/*
* Determines whether the request contains is an OpenSSO
* notification message intended for the policy SDK.
*/
/*
* Returns true if the URL being accessed by the user is in the not
* enforced list.
*/
const char *path_info);
/*
* Returns true if the given IP address is present in the list of
* not enforced IP addresses.
*/
/*
* Returns if the requested URL is a Valid FQDN resource.
*/
/*
* Handles notification data received by an agent. This code handles
* generating logging messages for the event and any error that may
* occur during the processing of the notification.
*/
/*
* This function returns a string representing the URL for redirection that
* is appropriate to the provided status code and advice map returned by
* the Policy SDK. This may either redirect the user to the login URL or
* the access denied URL. If the redirection is to the login URL then the
* URL will include any exsisting information specified in the URL from the
* configuration file, like org value etc., followed by the specified goto
* parameter value, which will be used by OpenSSO after the user has
* successfully authenticated.
*
* The function am_web_get_redirect_url(), has been deprecated and
* must not be used. It is supported only for backward compatibility
* reasons.
* The last parameter reserved must be passed with NULL.
*
* Note: If the redirect_url returned is NOT NULL, the caller of this function
* must call am_web_free_memory(void *) to free the pointer.
*/
const am_map_t advice_map,
const char *goto_url,
const char* method,
void *reserved,
char ** redirect_url);
/*
* This function sets the LDAP attributes in header.
* The method will be called when ldapattribute.mode is set to "HEADER"
*
* Parameters:
* key key whose value to be set.
*
* attrValues The value string that will be set.
*
* args container specific argument containing request.
*
* Returns:
* AM_SUCCESS
* if the setting is successful.
*
*/
typedef am_status_t (*am_web_result_set_header_func_t)(
const char *key,
const char *attrValues,
void **args);
/*
* This function sets the LDAP attributes in header through cookie in response.
* The method will be called when ldapattribute.mode is set to "COOKIE"
*
* Parameters:
* cookieValues The string containing cookie value that will be set.
*
* args container specific argument containing request.
*
* Returns:
* AM_SUCCESS
* if the setting is successful.
*/
const char *cookieValues,
void **args);
/*
* This function sets the LDAP attributes in header through cookie in request.
* The method will be called when ldapattribute.mode is set to "COOKIE"
*
* Parameters:
* cookieValues The string containing cookie value that will be set.
*
* args container specific argument containing request.
*
* Returns:
* AM_SUCCESS
* if the setting is successful.
*/
const char *cookieValues,
void **args);
/*
* This function at present is DUMMY. will be needed for cookie synchronization.
* has been added to get the interface.
*
* Parameters:
* cookieName Name of the cookie to be synchronized with.
*
* dproCookie
*
* args container specific argument containing request.
*
* Returns:
* AM_SUCCESS
* if the setting is successful.
*/
typedef am_status_t (*am_web_get_cookie_sync_func_t)(
const char *cookieName,
char **dproCookie,
void **args);
/*
* NOTE - This function replaces am_web_do_result_attr_map_set() in the
* previous version of the library. The old interface is still provided
* in the library but deprecated. Users need to explicity declare it as
* follows to use it.
* am_status_t am_web_do_result_attr_map_set(
* am_policy_result *result,
* am_status_t (*setFunc)(const char *,
* const char *,
* void **),
* void **args);
*
* This function processes attr_response_map of am_policy_result_t
* and performs the appropriate set action that is passed in.
*
*/
void **args);
/*
* This function the reset_cookie headers for the cookies
* specified in the configuration file and invokes the set action
* that caller (i.e. the agent) passes in for each of them.
*/
void **args);
/*
* This function sets the iPlanetDirectoryPro cookie for each domain
* configured in the com.sun.am.policy.agents.cookieDomainList property.
* It builds the set-cookie header for each domain specified in the
* property, and calls the callback function 'setFunc' in the first
* argument to actually set the cookie.
* This function is called by am_web_check_cookie_in_query() and
* am_web_check_cookie_in_post() which are called in CDSSO mode
* to set the iPlanetDirectoryPro cookie in the cdsso response.
*/
/*
* This function is used to get the cookie sent in the SAML assertion
* from the OpenSSO
*/
am_web_remove_parameter_from_query(const char* inpString, const char *remove_str, char **outString );
void ** args, char ** dpro_cookie,
char ** request_url,
char *response,
am_status_t (*set_cookie)(const char *, void **),
void (*set_method)(void **, char *)
);
void **args, char **dpro_cookie,
const char *query, char **request_url,
am_status_t (*set_cookie)(const char *, void **),
void (*set_method)(void **, char *)
);
/*
* Free memory previously allocated by a am_web_* routine.
*/
/*
* Method to retrieve the name of the OpenSSO cookie.
*/
AM_WEB_EXPORT const char *am_web_get_cookie_name();
/*
* Method to retrieve the name of the OpenSSO notification Url.
*/
AM_WEB_EXPORT const char *am_web_get_notification_url();
/*
* Method to retrieve the name of the Agent Server Host.
*/
AM_WEB_EXPORT const char *am_web_get_agent_server_host();
/*
* Method to retrieve the name of the Agent Server Port.
*/
/**
* -------- logging --------
*/
/*
* --------- POST cache preservation -------
*/
/*
* Temporary structure to store post data before it is inserted in
* POST hash table
* Members :
* value
* String value for POST data
* url
* Destination URL for the POST request
*/
typedef struct am_web_postcache_data {
char *value;
char *url;
/*
* Temporary structure to hold dummy url, action url
* POST preservation key. All three of these variables
* are required for POST preservation. Client passes
* in the request URL for POST to public function
* am_web_create_post_preserve_urls which creates
* this structure and returns a pointer to the client
*
* Members :
* dummy_url
* Dummy URL for redirect for POST preservation
* action_url
* Destination URL for POST request
* post_time_key
* Unique key to tag POST data entry
*/
typedef struct post_urls {
char *dummy_url;
char *action_url;
char *post_time_key;
} post_urls_t;
/*
* Method to find out if POST data preservation is enabled
* by clients through AMAgent.Properties
* Returns :
* boolean_t
* True or False depending on whether POST
* preservation is switched on or off.
*
*/
/*
* Method to insert POST data entry in the POST cache
* Parameters:
* key
* POST data preservation key for every entry
* value
* Structure to store POST data value and redirect URL
*
* Returns:
* boolean_t
* True or False depending on whether insertion was
* successful or a failure
*
*/
const am_web_postcache_data_t *value);
/*
* Method to lookup POST data in the POST cache
*
* Parameters:
* key
* Key to search POST data entry in POST data structure
*
* Returns:
* am_web_postcache_data_t
* Data structure containing POST data and redirect URL
*
*/
am_web_postcache_lookup(const char *key,
/*
* Method to remove POST data from the POST cache
*
* Parameters:
* key
* Key to remove an entry from POST data structure
*
* Returns:
*
*/
/*
* Method to construct dummy post url, action url and unique key
*
* Parameters:
* request_url
* The request URL for POST in the HTTP request
*
* Returns:
* post_urls_t
* Data structure that contains Dummy redirect URL, POST destination
* URL and POST preservation key. Dummy redirect URL is filtered by
* web server SAF to identify POST preservation redirects from general
* redirects. All three of these variables are required for POST
* preservation.
*
*/
char *request_url);
/*
* Method to clean up datastructure containing dummy post url, action url and
* unique key
*
* Paramaters:
* posturl_struct
* Pointer to POST preservation URL data structure post_urls_t
*
* Returns
*
*/
/*
* Method to clean up data structure containing post string value,
* redirect url
*
* Paramaters:
* const am_web_postcache_data_t
* Pointer to POST data entry
*
* Returns
*
*/
AM_WEB_EXPORT void
/*
* Create the html form with the javascript that submits the POST
* with the invisible name value pairs
*
* Parameters:
* key
* Unique key to identify POST data entry. It is used to
* remove post data once the page is re-posted
* postdata
* POST data entry as a browser encoded string
* actionurl
* POST destination URL
*
* Returns
* char *
* POST form to be resubmitted
*
*/
const char *postdata,
const char *actionurl);
/*
* Check whether a cookie is present.
*
* Parameters:
* cookie
* Pointer to a cookie.
* value
* Pointer to a value.
* new_cookie
* Pointer to a pointer to the location of the new cookie.
*
* Returns
* 2,1,0 or -1 as defined above
*
*/
const char *value,
char **new_cookie);
/*
* Resets the cookie configured to be reset on logout.
* The reset function passed in is called for each cookie that is configured.
* If the function failed for any cookie, the last failed status is returned.
*/
void **args);
/*
* Returns true if url is a logout url, false otherwise.
*/
/**
* When a user comes back from the CDSSO authentication, there are a
* list of Liberty parameters added when the user was redirected
* for authentication. This function removes those extra parameters, so
* that the request could be forwarded to the applications as it came
* from the browser.
*
* Parameter:
* inpString: Request URL that was recieved after authentication
* containing Liberty attributes.
* outString: Address of output string where all the Liberty
* attributes are cleaned up. Must be pre-allocated
* by caller with same size as inpString.
*
*
* Returns:
* am_status_t:
* AM_SUCCESS if operation was successful, appropriate
* error codes otherwise.
*/
/**
* Processes a request access check and returns a HTTP result to be
* rendered by the agent. Result can be OK, OK-done,
* forbidden, error, or redirect with a redirect URL.
* The render status is returned in the render_sts argument.
* See am_web_request_func_t for description of each function.
*/
/**
* Converts a am_web_req_method_t number to a string as defined in RFC 2068.
* If the method number passed is unrecognized, "UNKNOWN" is returned.
*/
AM_WEB_EXPORT const char *
/**
* Converts a method string as defined in RFC 2068 to a am_web_req_method_t
* number. If the string is unrecognized AM_WEB_REQUEST_UNKNOWN is returned.
*/
am_web_method_str_to_num(const char *method_str);
/**
* Returns the name of a am_web_result_t as a string.
* For example, AM_WEB_RESULT_OK returns "AM_WEB_RESULT_OK".
* If the result code passed is unrecognized, "Unknown result code"
* is returned.
*/
AM_WEB_EXPORT const char *
/**
* Sets the given cookie in the cookie header in the request.
* Arguments:
* cookie header - the cookie header in the request
* set_cookie_value - the cookie name and value in set-cookie response
* header form. this should be the same argument as
* the cookieValues argument of the
* am_web_result_set_header_attr_in_request_func_t function.
* new_cookie_header - contains either null, or the original cookie_header, or
* a new point containing the new cookie header value which
* needs to be freed by the caller.
*/
char **new_cookie_header);
const char *redirect_url,
char **advice_response);
/*
* Method to determine if the auth-type value "dsame"
* in the IIS6 agent should be replaced by "Basic"
*/
AM_WEB_EXPORT const char *am_web_get_authType();
/**
* Method will take the host header, server host name
* port, protocol, query parameter, URI and return the
* URL to be used for agent purposes.
* Parameters:
* host_hdr
* value of host header string as sent by browser
* protocol
* Protocol the container is servicing
* hostname
* Host name as known to the container
* port
* port number as known to the container
* uri
* URI of the request
* query
* query parameters sent with the request
* req_url
* OUT parameter which will be populated with the
* value of URL string to be used by Agent
* Returns:
* am_status_t
* the status of operation.
*/
char **req_url);
/*
* Method to determine if the override_host_port is set
* for the Proxy agent
*/
/*
* Method to determine the version number of AM with which the agent is
* interacting
*/
AM_WEB_EXPORT char * am_web_get_am_revision_number();
/*
* Method to get the value of user id param
*/
AM_WEB_EXPORT const char * am_web_get_user_id_param();
AM_WEB_EXPORT const char * am_web_is_owa_enabled_session_timeout_url();
#endif /* not AM_WEB_H */