Changeset 1264

Timestamp:

02/13/08 12:33:38 (11 months ago)

Author:

dbuss

Message:

#346 Added base documentation, enhanced a number of events to be more descriptive and added some event logging. Updated sample.

Location:

trunk/rp/common/python

Files:

• doc (added)
• docs (added)
• docs/__init__.html (added)
• docs/event.html (added)
• docs/infocardlib.html (added)
• docs/xmlseclibs.html (added)
• infocard/event.py (modified) (4 diffs)
• infocard/infocardlib.py (modified) (21 diffs)
• infocard/xmlseclibs.py (modified) (32 diffs)
• samples/index.html (modified) (1 diff)
• samples/process_infocard.psp (modified) (2 diffs)

trunk/rp/common/python/infocard/event.py

@@ -1 @@
-#  Copyright (c) 2007 Novell, Inc.
+#  Copyright (c) 2007, 2008 Novell, Inc.
 #  All Rights Reserved.
  
@@ -8 +8 @@
 #  This library is distributed in the hope that it will be useful,
 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 #  GNU Lesser General Public License for more details.
  
@@ -28 +28 @@
 NOTSET = logging.NOTSET
 
-config_fields = ['CRITICAL', 'DEBUG', 'ERROR', 'FATAL', 'INFO']
-
-class IEventLog:
-        """An interface for managing related events, including inline filtering
-        """
-        
-        
-        def add_event( eid, text, level):
-                """Add an event to the queue, filtering as needed
-                """
-                
+config_fields = ['CRITICAL', 'DEBUG', 'ERROR', 'FATAL', 'INFO', 'NOTSET']
 
 class BasicEventLog:
-        """ Implementation of a basic event log.
+    """ Implementation of a basic event log.
     
     This event log is not intended to be a process level event log, rather it is
@@ -47 +37 @@
     This event log allows specific tags to be upgraded or downgraded in severity
     based on configuration
+    """
+
+    def __init__(self, options=None):
+        """ Process options for basic event log.
+        
+        Currently the only options are for overriding severities based on 
+        the event tag.   To configure a dictionary where the name of the config_fields
+        is the key name and the event tags are the value.  Event tags are space seperated.
+        ({'INFO' : 'parse-locate-encrypted signature-missing-InclusiveNameSpaces'},
+                                                {'NOTSET' : 'bogus-message'})
+        
+        """
+        self.events = [] #array of errors, warnings, and other significant events
+        self.options = {}
+        if options:
+            for field in config_fields:
+                if options.has_key(field):
+                    self.options[field] = options[field]
+#                   self.events.append(Event("setting %s to %s" % (field, options[field])))
+
+    def _get_severity(self, severity, tag):
+        """ Internal routine to see if the tag has a configured override for it's
+        severity.   
+        
+        Returns the configured severity if set, otherwise returns the passed 
+        severity."""
+        if tag:
+            for field in config_fields:
+                if self.options.has_key(field) and (re.search(tag, self.options[field]) is not None):
+                    mapped_severity = logging.getLevelName(field)
+#                   self.events.append(Event("tag %s has severity %s instead of %s" % (tag, field, logging.getLevelName(severity))))
+                    return mapped_severity
+        return severity
+
+    def add_event(self, text, severity=NOTSET, tag=None):
+        """Add an event to the event queue, may upgrade or downgrade the 
+        severity, depending on the currently active options."""
+        
+        event = Event(text, self._get_severity(severity, tag), tag)
+        self.events.append(event)
+        
+    def has_severity(self, severity):
+        """Get a count of the number of items of equal or greater than the passed
+        severity, with CRITICAL being the largest, and NOTSET being the lowest.
+        
+        Useful to check and see if any actual errors occured, in contrast to 
+        informational events.
+        """
+        count = 0
+        for event in self.events:
+            if event.severity >= severity:
+                count += 1
+#       self.events.append(Event("examined %d events and found %d events of %s or greater" % (len(self.events), count, logging.getLevelName(severity))))
+        return count
+            
+class Event:
+    """Object to hold an indivdual event.
     
-        """
-        config_fields = ['CRITICAL', 'DEBUG', 'ERROR', 'FATAL', 'INFO']
-        def __init__(self, options=None):
-                """
-                """
-                self.events = [] #array of errors, warnings, and other significant events
-                self.options = {}
-                if options:
-                        for field in config_fields:
-                                if options.has_key(field):
-                                        self.options[field] = options[field]
-#                                       self.events.append(Event("setting %s to %s" % (field, options[field])))
-
-        def _get_severity(self, severity, tag):
-                if tag:
-                        for field in config_fields:
-                                if self.options.has_key(field) and (re.search(tag, self.options[field]) is not None):
-                                        mapped_severity = logging.getLevelName(field)
-#                                       self.events.append(Event("tag %s has severity %s instead of %s" % (tag, field, logging.getLevelName(severity))))
-                                        return mapped_severity
-                return severity
-
-        def add_event(self, text, severity=NOTSET, tag=None):
-                """ add an event to the event queue, may upgrade or downgrade the 
-                severity, depending on the currently active options."""
-                
-                event = Event(text, self._get_severity(severity, tag), tag)
-                self.events.append(event)
-                
-        def has_severity(self, severity):
-                """ used to get a count of the number of items of equal or greater 
-                severity with CRITICAL being the largest, and NOTSET being the lowest.
-                Useful to check and see if any actual errors occured, in contrast to 
-                informational events.
-                """
-                count = 0
-                for event in self.events:
-                        if event.severity >= severity:
-                                count += 1
-#               self.events.append(Event("examined %d events and found %d events of %s or greater" % (len(self.events), count, logging.getLevelName(severity))))
-                return count
-                        
-class Event:
-        """Structure to trace an indivdual event."""
-        text = None
-        tag = None
-        severity = NOTSET
-        #todo add a datetime
-        
-        def __init__(self, text, severity=NOTSET, tag=None):
-                self.text = text
-                self.severity = severity
-                self.tag = tag
-                
-        
+    Nothing fancy here just a plain old object.
+    
+    Todo:: it would be nice to timestamp these 
+    """
+    
+    text = None
+    tag = None
+    severity = NOTSET
+    
+    def __init__(self, text, severity=NOTSET, tag=None):
+        self.text = text
+        self.severity = severity
+        self.tag = tag
+        
+    

trunk/rp/common/python/infocard/infocardlib.py

@@ -1 +1 @@
 #  Copyright (c) 2007, 2008 Novell, Inc.
 #  All Rights Reserved.
-#
+
 #  This library is free software; you can redistribute it and/or
 #  modify it under the terms of the GNU Lesser General Public License as
@@ -83 +83 @@
 BEARER_TOKEN = 'urn:oasis:names:tc:SAML:1.0:cm:bearer'
 HOLDER_OF_KEY_TOKEN = 'urn:oasis:names:tc:SAML:1.0:cm:holder-of-key'
+SENDER_VOUCHES_TOKEN = "urn:oasis:names:tc:SAML:1.0:cm:sender-vouches"
 
 """ public identifiers for meta data about the token
@@ -113 +114 @@
 
 class InfoCardProcessor:
-
+    """Base object for consumers who wish to build a python based RP for 
+    processing information cards and dealing with cardspace.
+    
+    This object may be created and configured once then used to evaluate many 
+    security tokens
+        
+    """
+    
     def __init__(self):
         self.options = {}
 
     def setDecode(self, privateKey, passPhrase = None, isFile=False, isCert = True):
+        """Setup the cert/private key used to decrypt tokens.  In many cases this 
+        will be the servers ssl cert.
+        
+        always returns None
+        """
         if isFile:
             fp = open(privateKey, 'rb')
@@ -130 +143 @@
 
     def setClaims(self, required, optional = None, multivalued = None):
+        """Helper function to simplify setting of the optional and required
+        claims, as well as which claims may be multivalued.
+        
+        Failure to tell the processor which claims are expected may result in
+        errors being reported.   The process helps verify that all required claims
+        were received and that no additional claims were sent.
+        
+        Todo: insert empty claim handling
+        Todo: insert custom claim transformations
+        
+        always returns None
+        """
         self.options[OPTION_required_claims] = required
         self.options[OPTION_optional_claims] = optional
@@ -135 +160 @@
 
     def setOptions(self, options):
+        """Set options for processing the security token
+        
+        The most common options relate to the overriding of event severity, please
+        see evemt.py for details of option name and values.
+        """
         for name in options.keys():
             self.options[name] = options[name]
@@ -145 +175 @@
 
     def processToken(self, xmlToken = None):
-        """Parse the token"""
+        """Parse the token using prevously configured keys, claims and options.
+        
+        returns a SecToken objec, the returned secToken may or may not be valid,
+        it is up to the caller to check secToken.isValid()
+        """
 
         secToken = SecToken(self.options)
@@ -155 +189 @@
 
 class SecToken:
-    """ Class for the parsing and holding of security token data"""
+    """ Class for the parsing and holding of security token data
+        
+        Instantiate, configure, process, check validity
+        Typiclly not directly instanciated, instead InfoCardProcessor is used to 
+        hold the common configuration and as a factory for creating SecTokens
+        
+        Todo:  currently only supports SAML 1.0/1.1 tokens, that should be abstracted out
+        to allow for many token types.
+        
+    """
 
     def __init__(self, options=None):
@@ -177 +220 @@
             
     def processToken(self, xmlToken, options):
-        """ process the token, until processed no data is present
+        """Process the token, until processed no data is present
+        
+        returns True if valid, False if invalid.   Events are logged to 
+        self.eventLog detialing failure reasons.
         """
         
@@ -185 +231 @@
                 self.eventLog.add_event("Token not supplied or empty", 
                     event.FATAL, 'empty-token')
-            objenc = xmlseclibs.XMLSecEnc(self.eventLog)
-            self.cryptedDom = minidom.parseString(self.crypted)
-            encData = objenc.locateEncryptedData(self.cryptedDom)
-            if not encData:
-                self.eventLog.add_event("Cannot locate encrypted"\
-                    " data in security token, please ensure all requests"\
-                    " are sent over SSL.", event.ERROR, 'parse-locate-encrypted')
-                self.decrypted = self.cryptedDom
             else:
-                objenc.setNode(encData)
-                objenc.type = encData.getAttribute("Type")
-
-                key = None
-                objKey = objenc.locateKey()
-                if (objKey):
-                    self.objKeyInfo = objenc.locateKeyInfo(objKey)
-                    if (self.objKeyInfo):
-                        if (self.objKeyInfo.isEncrypted):
-                            objencKey = self.objKeyInfo.encryptedCtx
-                            self.objKeyInfo.loadKey(
-                                self._option(options, OPTION_CryptoKey), 
-                                self._option(options, OPTION_CryptoKeyPass),
-                                self._option(options, OPTION_CryptoKeyIsFile), 
-                                self._option(options, OPTION_CryptoKeyIsCert))
-                            key = objencKey.decryptKey(self.objKeyInfo)
-
-                if (not objKey) or (not key):
-                    self.eventLog.add_event("Error loading key to handle"\
-                    "Decryption", event.FATAL, 'parse-keyload')
+                objenc = xmlseclibs.XMLSecEnc(self.eventLog)
+                self.cryptedDom = minidom.parseString(self.crypted)
+                encData = objenc.locateEncryptedData(self.cryptedDom)
+                if not encData:
+                    self.eventLog.add_event("Cannot locate encrypted"\
+                        " data in security token, please ensure all requests"\
+                        " are sent over SSL.", event.ERROR, 'parse-locate-encrypted')
+                    self.decrypted = self.cryptedDom
                 else:
-                    objKey.loadKey(key)
-                    decrypt = objenc.decryptNode(objKey, False)
-                    if decrypt:
-                        # we have the saml token so load er up
-                        self.decrypted = minidom.parseString(decrypt)
+                    objenc.setNode(encData)
+                    objenc.type = encData.getAttribute("Type")
+    
+                    key = None
+                    objKey = objenc.locateKey()
+                    if (objKey):
+                        self.objKeyInfo = objenc.locateKeyInfo(objKey)
+                        if (self.objKeyInfo):
+                            if (self.objKeyInfo.isEncrypted):
+                                objencKey = self.objKeyInfo.encryptedCtx
+                                self.objKeyInfo.loadKey(
+                                    self._option(options, OPTION_CryptoKey), 
+                                    self._option(options, OPTION_CryptoKeyPass),
+                                    self._option(options, OPTION_CryptoKeyIsFile), 
+                                    self._option(options, OPTION_CryptoKeyIsCert))
+                                key = objencKey.decryptKey(self.objKeyInfo)
+                            else:
+                                self.eventLog.add_event("ObjectKeyInfo is not encrypted",
+                                    event.INFO, 'parse-object-key-info')
+    
+                    if (not objKey) or (not key):
+                        self.eventLog.add_event("Error loading key to handle"\
+                        "Decryption", event.FATAL, 'parse-keyload')
                     else:
-                        self.eventLog.add_event('Unable to decrypt token',
-                            event.FATAL, 'decrypt')
+                        objKey.loadKey(key)
+                        decrypt = objenc.decryptNode(objKey, False)
+                        if decrypt:
+                            # we have the saml token so load er up
+                            self.decrypted = minidom.parseString(decrypt)
+                        else:
+                            self.eventLog.add_event('Unable to decrypt token',
+                                event.FATAL, 'decrypt')
             if not self.decrypted:
                 self.eventLog.add_event('Unable to parse decrypted token to DOM',
@@ -244 +294 @@
             self.eventLog.add_event("Exception encountered while processing Security Token, exception: %s " % (str(errorMsg)), 
                     event.FATAL, 'exception')
+        return self.isValid
 
     def _setupMiscData(self, options):
-        """Setup all of the data about the token we can, not some data like the
+        """Setup all of the data about the token we can, note that some data like the
         audience, valid before/after are set in _isValid
+        
+        Todo:: currently saml specific
+        
+        
         """
         rootNode = self.decrypted.documentElement
@@ -260 +315 @@
 
     def _isValid(self, options):
-        """ Validate the SAML token
+        """ Validate the token, including signature validation, validity period,
+        osis interop tests, and that the expected claims are present.
+        
+        There are some metadata items cached by this function
+        
+        Todo:: currently saml specific
         """
         data = self.decrypted.documentElement.namespaceURI
@@ -293 +353 @@
             if (self.objKeyInfo):
                 # Handle any additional key processing such as encrypted keys here
-#               self.eventLog.add_event("Potential additional key processing required: %s, %u" \
+#                self.eventLog.add_event("Potential additional key processing required: %s, %u" \
 #                   % (self.objKeyInfo.type, objKey.isEncrypted),
 #                   event.INFO)
                 pass
+#            else:
+#             self.eventLog.add_event("No Key Info found for %u" \
+#                   % (objKey.isEncrypted),  event.INFO)
             retVal = objXMLSecDSig.verify(objKey)
             if not retVal:
@@ -337 +400 @@
 
         if not self.metadata.has_key(META_Audience): 
-            self.eventLog.add_event("Security Token does not contain "\
-                "an Audience restriction.", event.ERROR, 'validate-audience-present')
+            self.eventLog.add_event("Your IdP did not include an Audience "\
+                "restriction in the Security Token.", event.ERROR, 'validate-audience-present')
 
         query = '/mysaml:Assertion/mysaml:AttributeStatement/mysaml:Subject/mysaml:SubjectConfirmation/mysaml:ConfirmationMethod'
@@ -345 +408 @@
             self.metadata[META_SubjectConfirmation] = node.firstChild.data
             if (not self._doesMatchFuzzy(BEARER_TOKEN, self.metadata[META_SubjectConfirmation], None, None) and
-               not self._doesMatchFuzzy(HOLDER_OF_KEY_TOKEN, self.metadata[META_SubjectConfirmation], None, None)):
-                    self.eventLog.add_event("Passed Configuration data \"%s\" doesn't match "\
+               not self._doesMatchFuzzy(HOLDER_OF_KEY_TOKEN, self.metadata[META_SubjectConfirmation], None, None)
+               and not  self._doesMatchFuzzy(SENDER_VOUCHES_TOKEN, self.metadata[META_SubjectConfirmation], None, None)):
+                    self.eventLog.add_event("Passed configuration data \"%s\" doesn't match "\
                     "expected configuration data\"%s\"" % 
-                    (self.metadata[META_SubjectConfirmation], 'holder-of-key or bearer'),
+                    (self.metadata[META_SubjectConfirmation], 'holder-of-key or bearer or sender vouches'),
                     event.ERROR, 'mismatched-confirmation') 
             break
@@ -390 +454 @@
 
     def _doesMatchFuzzy(self, expected, got, clearTag, eventTag):
+        """Lienient matching for items which may be allowed to be missing
+        
+        returns true if item is not required or matches.  returns False and logs
+        the event on failure.
+        """
         if not got or not expected or expected == got or re.match(expected, got):
             return True
@@ -399 +468 @@
             return False;
 
-    #TODO handle namespaces, claim name mapping, multiple values!
     def _setupAssertions(self, options):
+        """Build a cache of assertion names/values
+        
+        Todo:: handle namespaces, claim name mapping, multiple values, empty 
+        value handling and value attributes!
+        
+        at compleation self.assertions is setup.  Assertions should be accessed
+        by calling getAssertionValues, not by accessing self.assertions.
+        """
         if not self.assertions or len(self.assertions) == 0:
             mvClaims = []
@@ -446 +522 @@
     def getAssertionValues(self, identifier=None):
         """Allows retrivial of any claim or assertion associated with the security token
+        
+        Todo::  visit and finish this function
         Returns either the data or None
-        visit and finish this function!
         """
         #is the identifier a URI or just a short name?
@@ -460 +537 @@
         except Exception:
             claim = identifier
-
+            
 #       self.eventLog.add_event("Looking for ns: \"%s\"   claim: \"%s\" " \
 #           % (ns, claim), 
@@ -483 +560 @@
             return claims
 
-
     def getMetaDataValues(self, identifier=None):
         """Allows retrivial of any meta data associated with the security token
+        
+        Note: currently all meta data is single valued!
         Pass a specific string for the identifier and receive either a 
         string or None
         If the identifier is None then a dictionary of all meta data is returned
-        Currently all meta data is single valued!
         """
         if identifier:
@@ -500 +577 @@
 
     def _getCardKeyHash(self):
+        """Internal routine to generate a generic cardkey hash,  the result is 
+        stored in self.metadata[META_CardKeyHash]
+        """
         try:
             return self.metadata[META_CardKeyHash]
@@ -517 +597 @@
             return self.metadata[META_CardKeyHash]
 
-# TODO: need work on ISO date checking - skip for now
 def checkDateConditions(start=None, end=None, difference=300):
+    """Validate a datetime is in range.   
+    
+    difference in seconds allows for clock skew.
+    
+    Todo:: need work on ISO date checking - skip for now
+    
+    returns True if time is in range False if not in range
+    """
     currentTime = datetime.datetime.now()
     if (start):
         startTime = datetime.datetime.fromtimestamp(xml.utils.iso8601.parse(start))
-        # Allow for a 5 minute difference in Time
+        # Allow for a difference in clock syncronization,  
         d = datetime.timedelta(minutes=difference)
         if ((not startTime) or ((startTime - d) > currentTime)):

trunk/rp/common/python/infocard/xmlseclibs.py

@@ -1 @@
-#  Copyright (c) 2007 Novell, Inc.
+#  Copyright (c) 2007,2008 Novell, Inc.
 #  All Rights Reserved.
-#
+
 #  This library is free software; you can redistribute it and/or
 #  modify it under the terms of the GNU Lesser General Public License as
@@ -74 +74 @@
 
 def report_event(eventLog, text, severity = event.NOTSET, tag = None):
+    """ module level function for either remembering the event or throwing an
+    exception if eventlonging is not configured.
+    """
     if eventLog:
         eventLog.add_event(text, severity, tag)
@@ -81 +84 @@
 
 class XMLSecurityKey:
+    """Class for encrypting/decrypting data, and remembering information about .
+    the methods and keys for doing so.
+    
+    Hides from the caller the details of which library (openssl or mcrypt) is 
+    used for a particular cipher.
+    
+    """
     TRIPLEDES_CBC = 'http://www.w3.org/2001/04/xmlenc#tripledes-cbc'
     AES128_CBC = 'http://www.w3.org/2001/04/xmlenc#aes128-cbc'
@@ -173 +183 @@
 
     def loadKey(self, key, passPhrase = None, isFile=False, isCert = True):
+        """ setup key information in object
+        
+        This function fails if key can't be loaded succesfully
+        Returns None on success and failure, reports errors to the configured event log.
+        """
         if isFile:
             fp = open(key, 'rb')
@@ -218 +233 @@
         return None
 
-    #TODO: Convert encryptMcrypt
     def encryptMcrypt(self, data):
+        """Encrypted using the mcrypt library
+        
+        This function should not be called directly, rather call encryptData and
+        let that function switch based on the configured library.
+        
+        Todo::
+        Not currently called, appears to be incomplete, possibly containing some
+        phpisms
+        """
         td = mcrypt_module_open(self.cryptParams['cipher'], '', self.cryptParams['mode'], '')
-        self.iv = mcrypt_create_iv (mcrypt_enc_get_iv_size(td), MCRYPT_RAND)
+        self.iv = mcrypt_create_iv(mcrypt_enc_get_iv_size(td), MCRYPT_RAND)
         mcrypt_generic_init(td, self.key, self.iv)
         encrypted_data = self.iv.mcrypt_generic(td, data)
@@ -229 +252 @@
 
     def decryptMcrypt(self, data):
+        """Decrypt using the mcrypt library 
+        
+        This function should not be called directly, rather call decryptData and
+        let that function switch based on the configured library.
+        
+        Todo:: currently only supports MCRYPT_MODE_CBC 
+        
+        returns None on failure, decrypted data on success.   No events logged 
+        """
         dCipher = self.cryptParams['cipher']
         iv_length = dCipher.block_size