By default, if PEGASUS_USE_SYSLOG is defined, all the audit messages are written into the system log file. Each system log file entry (e.g. in the syslog file) has a well-defined tag (e.g. "cimserver audit ") to distinguish an entry made by audit logging. Otherwise, the audit message is written into a new file PegasusAudit.log which is defined in Logger.cpp. Platform maintainers may add support to write different audit type message or different audit event message to a different log file into the function "_writeAuditMessageToFile". This interface is not exposed externally.

 
The class is as follows: 
    class PEGASUS_COMMON_LINKAGE AuditLogger
    {
    public:

        enum AuditType
        {
            TYPE_AUTHENTICATION,
            TYPE_AUTHORIZATION,
            TYPE_CONFIGURATION,
            TYPE_CIMOPERATION
        };

        enum AuditSubType
        {
            SUBTYPE_LOCAL_AUTHENTICATION,
            SUBTYPE_BASIC_AUTHENTICATION,
            SUBTYPE_CERTIFICATE_BASED_AUTHENTICATION,
            SUBTYPE_CERTIFICATE_BASED_USER_VALIDATION,
            SUBTYPE_USER_GROUP_AUTHORIZATION,
            SUBTYPE_NAMESPACE_AUTHORIZATION,
            SUBTYPE_PRIVILEGED_USER_CHECK,
            SUBTYPE_TRUSTSTORE_CHANGE,
            SUBTYPE_CURRENT_CONFIGURATION,
            SUBTYPE_CURRENT_PROVIDER_REGISTRATION,
            SUBTYPE_CURRENT_ENVIRONMENT_VARIABLES,
            SUBTYPE_CONFIGURATION_CHANGE,
            SUBTYPE_PROVIDER_REGISTRATION_CHANGE,
            SUBTYPE_PROVIDER_MODULE_STATUS_CHANGE,
            SUBTYPE_SCHEMA_OPERATION,
            SUBTYPE_INSTANCE_OPERATION,
            SUBTYPE_INDICATION_OPERATION
        };

        enum AuditEvent
        {
            EVENT_START_UP,
            EVENT_AUTH_SUCCESS,
            EVENT_AUTH_FAILURE,
            EVENT_CREATE,
            EVENT_UPDATE,
            EVENT_DELETE,
            EVENT_INVOKE
        };


        /** Constructs and logs audit message of the current configurations
        @param propertyNames - All the current property names while the CIM
                               Server is running
        @param propertyValues - All the current property values while the CIM
                                Server is running
        */
        static void logCurrentConfig(
            const Array& propertyNames,
            const Array& propertyValues);
        );

        /** Constructs and logs audit message of the currently registered 
            providers while the CIM Server is running
            @param instances - all currently registered provider module 
            instances while the CIM Server is running  
        */
        static void logCurrentRegProvider(
            const Array < CIMInstance > & instances
        );

        /** Constructs and logs audit message of the current environment 
            variables while the CIM Server is running 
        */
        static void logCurrentEnvironmentVar();

        /** Constructs and logs audit message of setting the specified 
            configuration property to the specified value
            @param userName - The user name for this operation
            @param propertyName - The specified configuration property name
            @param prePropertyValue - The previous value of the changed config
                                      property
            @param newPropertyValue - The new value of the changed config
                                      property
            @param isPlanned - True, sets planned value of the 
                               specified configuration  property;
                               Otherwise, sets current value of the
                               specified configuration  property 
        */
        static void logSetConfigProperty(
            const String & userName,
            const String & propertyName,
            const String & prePropertyValue,
            const String & newPropertyValue,
            Boolean isPlanned);


        /**
            Constructs and logs audit message of a CIM class update operation
            @param cimMethodName - The name of the CIM operation performed
            @param eventType - The AuditEvent associated with the CIM operation
            @param userName - User name for this operation
            @param ipAddr - Client IP address for this operation
            @param nameSpace - The namespace for the operation
            @param className - The name of the class
            @param statusCode - The CIM status code for the operation
        */
        static void logUpdateClassOperation(
            const char* cimMethodName,
            AuditEvent eventType,
            const String& userName,
            const String& ipAddr,
            const CIMNamespaceName& nameSpace,
            const CIMName& className,
            CIMStatusCode statusCode);

        /**
            Constructs and logs audit message of a CIM qualifier update operation
            @param cimMethodName - The name of the CIM operation performed
            @param eventType - The AuditEvent associated with the CIM operation
            @param userName - User name for this operation
            @param ipAddr - Client IP address for this operation
            @param nameSpace - The namespace for the operation
            @param name - The name of the qualifier
            @param statusCode - The CIM status code for the operation
        */
        static void logUpdateQualifierOperation(
            const char* cimMethodName,
            AuditEvent eventType,
            const String& userName,
            const String& ipAddr,
            const CIMNamespaceName& nameSpace,
            const CIMName& name,
            CIMStatusCode statusCode);

        /**
            Constructs and logs audit message of a CIM instance update operation
            @param cimMethodName - The name of the CIM operation performed
            @param eventType - The AuditEvent associated with the CIM operation
            @param userName - The user name for this operation
            @param ipAddr - Client IP address for this operation
            @param nameSpace - The namespace for the operation
            @param instanceName - The name of the affected instance
            @param moduleName - The provider module name that serves the request
            @param providerName - The provider name that serves the request
            @param statusCode - The CIM status code for the operation
        */
        static void logUpdateInstanceOperation(
            const char* cimMethodName,
            AuditEvent eventType,
            const String& userName,
            const String& ipAddr,
            const CIMNamespaceName& nameSpace,
            const CIMObjectPath& instanceName,
            const String& moduleName,
            const String& providerName,
            CIMStatusCode statusCode);

        /**
            Constructs and logs audit message of a CIM InvokeMethod operation
            @param userName - The user name for this operation
            @param ipAddr - Client IP address for this operation
            @param nameSpace - The namespace for the operation
            @param objectName - The name of the object on which the method is
                invoked
            @param methodName - The name of the method to be executed
            @param moduleName - The provider module name that serves the request
            @param providerName - The provider name that serves the request
            @param statusCode - The CIM status code for the operation
        */
        static void logInvokeMethodOperation(
            const String& userName,
            const String& ipAddr,
            const CIMNamespaceName& nameSpace,
            const CIMObjectPath& objectName,
            const CIMName& methodName,
            const String& moduleName,
            const String& providerName,
            CIMStatusCode statusCode);

            /** Constructs and logs audit message of a provider module status change
            @param moduleName - The name of the provider module
            @param currentModuleStatus - The current status of the provider module
            @param newModuleStatus - The new status of the provider module
        */
        static void logUpdateProvModuleStatus(
            const String & moduleName,
            const Array currentModuleStatus,
            const Array newModuleStatus);

        /** Constructs and logs audit message of local authentication
            @param userName - The user name for this operation
            @param successful - True on successful basic authentication,
                                false otherwise
        */
        static void logLocalAuthentication(
            const String& userName,
            Boolean successful);

        /** Constructs and logs audit message of basic authentication
            @param userName - The user name for this operation
            @param ipAddr - Client IP address for this operation
            @param successful - True on successful basic authentication,
                                false otherwise
        */
        static void logBasicAuthentication(
            const String& userName,
            const String& ipAddr,
            Boolean successful);

       /** Constructs and logs audit message of certificate based authentication
           @param issuerName - The issuer name of this certificate
           @param subjectName - The subject name of this certificate
           @param serialNumber - The serial number of this certificate
           @param ipAddr - Client IP address for this operation
           @param successful - True on successful basic authentication,
                               false otherwise
       */
       static void logCertificateBasedAuthentication(
           const String& issuerName,
           const String& subjectName,
           const String& serialNumber,
           const String& ipAddr,
           Boolean successful);

       /** Constructs and logs audit message of certificate based user validation
           @param userName - The username associated with this certificate
           @param issuerName - The issuer name of this certificate
           @param subjectName - The subject name associated with the certificate
           @param serialNumber - The serial number of this certificate
           @param ipAddr - Client IP address for this operation
           @param successful - True on successful user validation,
                               false otherwise
       */
       static void logCertificateBasedUserValidation(
           const String& userName,
           const String& issuerName,
           const String& subjectName,
           const String& serialNumber,
           const String& ipAddr,
           Boolean successful);

         typedef void (*PEGASUS_AUDITLOGINITIALIZE_CALLBACK_T)();


	typedef void (*PEGASUS_AUDITLOG_CALLBACK_T) (AuditType,
            AuditSubType, AuditEvent, Uint32, MessageLoaderParms &);


        /**
            Registers an audit log initialize callback
            If a non-null initialize callback function is registered, 
            it will be called when the audit log is enabled.
            @param auditLogInitializeCallback - The audit log initialize 
                                                callback function
        */
        static void setInitializeCallback(
            PEGASUS_AUDITLOGINITIALIZE_CALLBACK_T auditLogInitializeCallback);

        /** If the enabled is true, the audit log initialize callback function 
            is called to communicate that the audit log is enabled.
            @param enabled - True on config property "enableAuditLog" is 
                             enabled, false otherwise
        */  
        static void setEnabled(Boolean enabled);

        static Boolean isEnabled();

        /**
            Registers writing audit messages to a file callback
            @param writeAuditMessageCallback - The callback function to write
                                               audit message
        */
        static void writeAuditLogToFileCallback(
            PEGASUS_AUDITLOG_CALLBACK_T writeAuditMessageCallback);

    private:
    
        static Boolean _auditLogFlag;

        /** 
            Callback function to be called when the audit log is enabled 
        */
        static PEGASUS_AUDITLOGINITIALIZE_CALLBACK_T _auditLogInitializeCallback;


        /**
            The function to write audit messages
        */
        static PEGASUS_AUDITLOG_CALLBACK_T _writeAuditMessageToFile;

        /** Default function to write a auditMessage to a file
            @param AuditType - Type of audit record (Authentication etc)
            @param AuditSubType - Sub type of audit record (Local_Authentication etc)
            @param AuditEvent - Event of audit record (Start_Up etc)
            @param logLevel - Pegasus Severity (WARNING etc)            
            All the audit messages are passed with pegasus severity 
            "INFORMATION", except authentication attempts failed messages or
            authorization failed messages are passed with pegasus severity 
            "WARNING"
            @param msgParms - The message loader parameters
        */
        static void _writeAuditMessageToFile(
            _AuditType auditType,
            _AuditSubType auditSubType,  
            _AuditEvent auditEvent,
            Uint32 logLevel,
            MessageLoaderParms & msgParms);

        /**
            gets module status value
            @param moduleStatus - The module status
        */
        static String _getModuleStatusValue(const Array  moduleStatus);

    }

• A new configuration property, "enableAuditLog", is added to ConfigManager and DefaultProperty tables

• A callback function "auditLogInitializeCallback" is added in the CIM Server module to log all the "startup" contents and is registered as the audit logger initiation callback function. It gets all the instances of class PG_ConfigSetting from Config Manager, gets all the currently registered provider module instance from Provider Registration Manager, and logs all the "startup" contents by using functions: logCurrentConfig(), logCurrentRegProvider(), and logCurrentEnvironmentVar();

• The client IP address is saved in the HTTPConnection when a connection is accepted. The IP address is included in the HTTPMessages that are read from the connection, is included in the CIMOperationRequestMessages that are created when an HTTPMessage is decoded, and is included in the AuthenticationInfo Object when the authentication is enabled.

• Authentication handlers are modified to pass corresponding audit parameters to AuditLogger class for authentication attempts to the CIM Server, both successful and failed.

• The CIMOperationRequestDispatcher modules is modified to pass corresponding audit parameters to AuditLogger class for most CIM "write" operations, such as CreateClass, DeleteClass, ModifyClass, CreateInstance, DeleteInstance, ModifyInstance, InvokeMethod, SetQualifier, and deleteQualifier.

• The ConfigSettingProvider is modified to pass corresponding audit parameters to AuditLogger class for configuration changes after the audit log is enabled

• The ProviderRegistration Manager module is modified to pass corresponding audit parameters to AuditLogger class for provider module status changes after the audit log is enabled

Test Plan

The audit log is tested in the automated test suite. An uint test is added to src/Pegasus/Common/tests/AuditLogger directory. The test creates various audit cases and verifies the result.

Rationale

To avoid flooding the log file with too much detail, only the CIM "write" operations are logged. The CIM "read" operations, indication generation, indication delivery, and indication consumptions are not logged in this release. They could be considered for the future, once the use model is better understood after users have had experience with this feature. Note: the categories of CIM "write" and "read" operations used here are consistent with the defines in pegasus user authorization module.

Any private data must not be logged (e.g. passwd info). Since pegasus does not have a mechanism to identify which parameter value of a method contains sensitive (private) data, method parameters (except "schema-related" parameters suc as class names and qualifier names) are not logged.

The audit data of Indication operations and Provider Registration operations are already included by the CIM Instance operations. If more specific information is needed for these operations, they could be considered in the future release after users have had experience with this feature.

Authorization and certificate based authentication audit logging are not included in Pegasus 2.6 release because the complication of the SSL implementation, it doesn't appear to be straight forward to implement within 2.6 timeframe. They could be considered in the future release.

Authorization audit logging is not included. It could be considered for a future release.

Certificate based authentication audit logging is included in the 2.7 release.