source: TI12-security/trunk/NDGSecurity/python/ndg_security_common/ndg/security/common/credentialwallet.py @ 6730

"""Credential Wallet classes

NERC DataGrid Project
"""
__author__ = "P J Kershaw"
__date__ = "30/11/05"
__copyright__ = "(C) 2009 Science and Technology Facilities Council"
__license__ = "BSD - see LICENSE file in top-level directory"
__contact__ = "Philip.Kershaw@stfc.ac.uk"
__revision__ = '$Id:credentialwallet.py 4378 2008-10-29 10:30:14Z pjkersha $'

import logging
log = logging.getLogger(__name__)
logging.basicConfig(level=logging.DEBUG)

import os
import warnings

# Check Attribute Certificate validity times
from datetime import datetime, timedelta

from ConfigParser import ConfigParser

from ndg.saml.utils import SAMLDateTime
from ndg.saml.saml2.core import Assertion

from ndg.security.common.utils.configfileparsers import (     
                                                    CaseSensitiveConfigParser,)


class _CredentialWalletException(Exception):    
    """Generic Exception class for CredentialWallet module.  Overrides 
    Exception to enable writing to the log"""
    def __init__(self, *arg, **kw):
        if len(arg) > 0:
            log.error(arg[0])
            
        Exception.__init__(self, *arg, **kw)


class CredentialWalletError(_CredentialWalletException):    
    """Exception handling for NDG Credential Wallet class.  Overrides Exception
    to enable writing to the log"""


class CredentialWalletAttributeRequestDenied(CredentialWalletError):    
    """Handling exception where CredentialWallet is denied authorisation by an
    Attribute Authority.
  
    @type __extAttCertList: list
    @ivar __extAttCertList: list of candidate Attribute Certificates that
    could be used to try to get a mapped certificate from the target 
    Attribute Authority
    
    @type __trustedHostInfo: dict
    @ivar __trustedHostInfo: dictionary indexed by host name giving 
    details of Attribute Authority URI and roles for trusted hosts"""
    
    def __init__(self, *args, **kw):
        """Raise exception for attribute request denied with option to give
        caller hint to certificates that could used to try to obtain a
        mapped certificate
        
        @type extAttCertList: list
        @param extAttCertList: list of candidate Attribute Certificates that
        could be used to try to get a mapped certificate from the target 
        Attribute Authority
        
        @type trustedHostInfo: dict 
        @param trustedHostInfo: dictionary indexed by host name giving 
        details of Attribute Authority URI and roles for trusted hosts"""
        
        self.__trustedHostInfo = kw.pop('trustedHostInfo', {})
        self.__extAttCertList = kw.pop('extAttCertList', [])
            
        CredentialWalletError.__init__(self, *args, **kw)

    def _getTrustedHostInfo(self):
        """Get message text"""
        return self.__trustedHostInfo

    trustedHostInfo = property(fget=_getTrustedHostInfo, 
                               doc="URI and roles details for trusted hosts")
       
    def _getExtAttCertList(self):
        """Return list of candidate Attribute Certificates that could be used
        to try to get a mapped certificate from the target Attribute Authority
        """
        return self.__extAttCertList

    extAttCertList = property(fget=_getExtAttCertList,
                              doc="list of candidate Attribute Certificates "
                              "that could be used to try to get a mapped "
                              "certificate from the target Attribute "
                              "Authority")

          
class _MetaCredentialWallet(type):
    """Enable CredentialWallet to have read only class variables e.g.
    
    print CredentialWallet.accessDenied 
    
    ... is allowed but,
    
    CredentialWallet.accessDenied = None
    
    ... raises - AttributeError: can't set attribute"""
    
    def _getAccessDenied(cls):
        '''accessDenied get method'''
        return False
    
    accessDenied = property(fget=_getAccessDenied)
    
    def _getAccessGranted(cls):
        '''accessGranted get method'''
        return True
    
    accessGranted = property(fget=_getAccessGranted)

class CredentialContainer(object):
    """Container for cached credentials"""
    ID_ATTRNAME = 'id'
    ITEM_ATTRNAME = 'credential'
    ISSUERNAME_ATTRNAME = 'issuerName'
    ATTRIBUTE_AUTHORITY_URI_ATTRNAME = 'attributeAuthorityURI'
    CREDENTIAL_TYPE_ATTRNAME = 'type'
    
    __ATTRIBUTE_NAMES = (
        ID_ATTRNAME,
        ITEM_ATTRNAME,
        ISSUERNAME_ATTRNAME,
        ATTRIBUTE_AUTHORITY_URI_ATTRNAME,
        CREDENTIAL_TYPE_ATTRNAME
    )
    __slots__ = tuple(["__%s" % n for n in __ATTRIBUTE_NAMES])
    
    def __init__(self, _type=None):
        self.__type = None
        self.type = _type
        
        self.__id = -1
        self.__credential = None
        self.__issuerName = None
        self.__attributeAuthorityURI = None

    def _getType(self):
        return self.__type

    def _setType(self, value):
        if not isinstance(value, type):
            raise TypeError('Expecting %r for "type" attribute; got %r' %
                            (type, type(value)))       
        self.__type = value

    type = property(_getType, _setType, 
                    doc="Type for credential - set to None for any type")

    def _getId(self):
        return self.__id

    def _setId(self, value):
        if not isinstance(value, int):
            raise TypeError('Expecting int type for "id" attribute; got %r' %
                            type(value))
        self.__id = value

    id = property(_getId, 
                  _setId, 
                  doc="Numbered identifier for credential - "
                      "set to -1 for new credentials")

    def _getCredential(self):
        return self.__credential

    def _setCredential(self, value):
        # Safeguard type attribute referencing for unpickling process - this
        # method may be called before type attribute has been set
        _type = getattr(self, 
                        CredentialContainer.CREDENTIAL_TYPE_ATTRNAME, 
                        None)
        
        if _type is not None and not isinstance(value, _type):
            raise TypeError('Expecting %r type for "credential" attribute; '
                            'got %r' % type(value))
        self.__credential = value

    credential = property(_getCredential, 
                          _setCredential, 
                          doc="Credential object")

    def _getIssuerName(self):
        return self.__issuerName

    def _setIssuerName(self, value):
        self.__issuerName = value

    issuerName = property(_getIssuerName, 
                          _setIssuerName, 
                          doc="Name of issuer of the credential")

    def _getAttributeAuthorityURI(self):
        return self.__attributeAuthorityURI

    def _setAttributeAuthorityURI(self, value):
        """String or None type are allowed - The URI may be set to None if
        a local Attribute Authority instance is being invoked rather
        one hosted via a remote URI
        """
        if not isinstance(value, (basestring, type(None))):
            raise TypeError('Expecting string or None type for '
                            '"attributeAuthorityURI"; got %r instead' % 
                            type(value))
        self.__attributeAuthorityURI = value

    attributeAuthorityURI = property(_getAttributeAuthorityURI,
                                     _setAttributeAuthorityURI, 
                                     doc="Attribute Authority Service URI")

    def __getstate__(self):
        '''Enable pickling'''
        thisDict = dict([(attrName, getattr(self, attrName))
                         for attrName in CredentialContainer.__ATTRIBUTE_NAMES])
        
        return thisDict
        
    def __setstate__(self, attrDict):
        '''Enable pickling for use with beaker.session'''
        try:
            for attr, val in attrDict.items():
                setattr(self, attr, val)
        except Exception, e:
            pass
       

class CredentialWalletBase(object):
    """Abstract base class for NDG and SAML Credential Wallet implementations
    """ 
    CONFIG_FILE_OPTNAMES = ("userId", )
    __slots__ = ("__credentials", "__credentialsKeyedByURI", "__userId")
    
    def __init__(self):
        self.__userId = None
        self.__credentials = {}
        self.__credentialsKeyedByURI = {}

    @classmethod
    def fromConfig(cls, cfg, **kw):
        '''Alternative constructor makes object from config file settings
        @type cfg: basestring /ConfigParser derived type
        @param cfg: configuration file path or ConfigParser type object
        @rtype: ndg.security.common.credentialWallet.SAMLCredentialWallet
        @return: new instance of this class
        '''
        credentialWallet = cls()
        credentialWallet.parseConfig(cfg, **kw)
        
        return credentialWallet

    def parseConfig(self, cfg, prefix='', section='DEFAULT'):
        '''Virtual method defines interface to read config file settings
        @type cfg: basestring /ConfigParser derived type
        @param cfg: configuration file path or ConfigParser type object
        @type prefix: basestring
        @param prefix: prefix for option names e.g. "certExtApp."
        @type section: baestring
        @param section: configuration file section from which to extract
        parameters.
        '''
        raise NotImplementedError(CredentialWalletBase.parseConfig.__doc__)

    def addCredential(self, 
                      credential, 
                      attributeAuthorityURI=None,
                      bUpdateCredentialRepository=True):
        """Add a new attribute certificate to the list of credentials held.

        @type credential: determined by derived class implementation e.g.
        SAML assertion
        @param credential: new attribute Certificate to be added
        @type attributeAuthorityURI: basestring
        @param attributeAuthorityURI: input the Attribute Authority URI from
        which credential was retrieved.  This is added to a dict to enable 
        access to a given Attribute Certificate keyed by Attribute Authority 
        URI. See the getCredential method.
        @type bUpdateCredentialRepository: bool
        @param bUpdateCredentialRepository: if set to True, and a repository 
        exists it will be updated with the new credentials also
        
        @rtype: bool
        @return: True if certificate was added otherwise False.  - If an
        existing certificate from the same issuer has a later expiry it will
        take precedence and the new input certificate is ignored."""
        raise NotImplementedError(CredentialWalletBase.addCredential.__doc__)
            
    def audit(self):
        """Check the credentials held in the wallet removing any that have
        expired or are otherwise invalid."""
        raise NotImplementedError(CredentialWalletBase.audit.__doc__)

    def updateCredentialRepository(self, auditCred=True):
        """Copy over non-persistent credentials held by wallet into the
        perminent repository.
        
        @type auditCred: bool
        @param auditCred: filter existing credentials in the repository
        removing invalid ones"""
        raise NotImplementedError(
                    CredentialWalletBase.updateCredentialRepository.__doc__)
        
    def _getCredentials(self):
        """Get Property method.  Credentials dict is read-only but also see 
        addCredential method
        
        @rtype: dict
        @return: cached ACs indesed by issuing organisation name"""
        return self.__credentials

    # Publish attribute
    credentials = property(fget=_getCredentials,
                           doc="List of credentials linked to issuing "
                               "authorities")

    def _getCredentialsKeyedByURI(self):
        """Get Property method for credentials keyed by Attribute Authority URI
        Credentials dict is read-only but also see addCredential method
        
        @rtype: dict
        @return: cached ACs indexed by issuing Attribute Authority"""
        return self.__credentialsKeyedByURI
    
    # Publish attribute
    credentialsKeyedByURI = property(fget=_getCredentialsKeyedByURI,
                                     doc="List of Attribute Certificates "
                                         "linked to attribute authority URI")
        
    def _getUserId(self):
        return self.__userId

    def _setUserId(self, value):
        if not isinstance(value, basestring):
            raise TypeError('Expecting string type for "userId"; got %r '
                            'instead' % type(value))
        self.__userId = value

    userId = property(_getUserId, _setUserId, 
                      doc="User Identity for this wallet")

    def __getstate__(self):
        '''Enable pickling for use with beaker.session'''
        _dict = {}
        for attrName in CredentialWalletBase.__slots__:
            # Ugly hack to allow for derived classes setting private member
            # variables
            if attrName.startswith('__'):
                attrName = "_CredentialWalletBase" + attrName
                
            _dict[attrName] = getattr(self, attrName)
            
        return _dict
  
    def __setstate__(self, attrDict):
        '''Enable pickling for use with beaker.session'''
        for attrName, val in attrDict.items():
            setattr(self, attrName, val)


class SAMLCredentialWallet(CredentialWalletBase):
    """CredentialWallet for Earth System Grid supporting caching of SAML 
    Attribute Assertions
    """
    CONFIG_FILE_OPTNAMES = CredentialWalletBase.CONFIG_FILE_OPTNAMES + (
                           "clockSkewTolerance", )
    __slots__ = ("__clockSkewTolerance",)
    
    CREDENTIAL_REPOSITORY_NOT_SUPPORTED_MSG = ("SAMLCredentialWallet doesn't "
                                               "support the "
                                               "CredentialRepository "
                                               "interface")

    def __init__(self):
        super(SAMLCredentialWallet, self).__init__()
        self.__clockSkewTolerance = timedelta(seconds=0.)

    def _getClockSkewTolerance(self):
        return self.__clockSkewTolerance

    def _setClockSkewTolerance(self, value):
        if isinstance(value, (float, int, long)):
            self.__clockSkewTolerance = timedelta(seconds=value)
            
        elif isinstance(value, basestring):
            self.__clockSkewTolerance = timedelta(seconds=float(value))
        else:
            raise TypeError('Expecting float, int, long or string type for '
                            '"clockSkewTolerance"; got %r' % type(value))

    clockSkewTolerance = property(_getClockSkewTolerance, 
                                  _setClockSkewTolerance, 
                                  doc="Allow a tolerance (seconds) for "
                                      "checking timestamps of the form: "
                                      "notBeforeTime - tolerance < now < "
                                      "notAfterTime + tolerance")

    def parseConfig(self, cfg, prefix='', section='DEFAULT'):
        '''Read config file settings
        @type cfg: basestring /ConfigParser derived type
        @param cfg: configuration file path or ConfigParser type object
        @type prefix: basestring
        @param prefix: prefix for option names e.g. "certExtApp."
        @type section: baestring
        @param section: configuration file section from which to extract
        parameters.
        '''  
        if isinstance(cfg, basestring):
            cfgFilePath = os.path.expandvars(cfg)
            _cfg = CaseSensitiveConfigParser()
            _cfg.read(cfgFilePath)
            
        elif isinstance(cfg, ConfigParser):
            _cfg = cfg   
        else:
            raise AttributeError('Expecting basestring or ConfigParser type '
                                 'for "cfg" attribute; got %r type' % type(cfg))
        
        prefixLen = len(prefix)
        for optName, val in _cfg.items(section):
            if prefix and optName.startswith(prefix):
                optName = optName[prefixLen:]
                
            setattr(self, optName, val)

    def addCredential(self, 
                      credential, 
                      attributeAuthorityURI=None,
                      bUpdateCredentialRepository=False,
                      verifyCredential=True):
        """Add a new assertion to the list of assertion credentials held.

        @type credential: SAML assertion
        @param credential: new assertion to be added
        @type attributeAuthorityURI: basestring
        @param attributeAuthorityURI: input the Attribute Authority URI from
        which credential was retrieved.  This is added to a dict to enable 
        access to a given Attribute Certificate keyed by Attribute Authority 
        URI. See the getCredential method.
        @type bUpdateCredentialRepository: bool
        @param bUpdateCredentialRepository: if set to True, and a repository 
        exists it will be updated with the new credentials also. Nb. a derived
        class will need to be implemented to enable this capability - see
        the updateCredentialRepository method.
        @type verifyCredential: bool
        @param verifyCredential: if set to True, test validity of credential
        by calling isValidCredential method.
        
        @rtype: bool
        @return: True if credential was added otherwise False.  - If an
        existing certificate from the same issuer has a later expiry it will
        take precedence and the new input certificate is ignored."""
        
        # Check input
        if not isinstance(credential, Assertion):
            raise CredentialWalletError("Input credential must be an "
                                        "%r type object" % Assertion)        

        if verifyCredential and not self.isValidCredential(credential):
            raise CredentialWalletError("Validity time error with assertion %r"
                                        % credential)
        
        # Check to see if there is an existing Attribute Certificate held
        # that was issued by the same host.  If so, compare the expiry time.
        # The one with the latest expiry will be retained and the other
        # ignored
        bUpdateCred = True
        if credential.issuer is None:
            raise AttributeError("Adding SAML assertion to wallet: no issuer "
                                 "set")
            
        issuerName = credential.issuer.value
        
        if issuerName in self.credentials:
            # There is an existing certificate held with the same issuing
            # host name as the new certificate
            credentialOld = self.credentials[issuerName].credential

            # If the new certificate has an earlier expiry time then ignore it
            bUpdateCred = (credential.conditions.notOnOrAfter > 
                           credentialOld.conditions.notOnOrAfter)

        if bUpdateCred:
            thisCredential = CredentialContainer(Assertion)
            thisCredential.credential = credential
            thisCredential.issuerName = issuerName
            thisCredential.attributeAuthorityURI = attributeAuthorityURI
            
            self.credentials[issuerName] = thisCredential
            
            if attributeAuthorityURI:
                self.credentialsKeyedByURI[
                    attributeAuthorityURI] = thisCredential 

            # Update the Credentials Repository - the permanent store of user
            # authorisation credentials.  This allows credentials for previous
            # sessions to be re-instated
            if bUpdateCredentialRepository:
                self.updateCredentialRepository()

        # Flag to caller to indicate whether the input certificate was added
        # to the credentials or an exsiting certificate from the same issuer
        # took precedence
        return bUpdateCred
                        
    def audit(self):
        """Check the credentials held in the wallet removing any that have
        expired or are otherwise invalid."""

        log.debug("SAMLCredentialWallet.audit ...")
        
        for issuerName, issuerEntry in self.credentials.items():
            if not self.isValidCredential(issuerEntry.credential):
                self.credentialsKeyedByURI.pop(
                    issuerEntry.attributeAuthorityURI,
                    None)
                    
                del self.credentials[issuerName]

    def updateCredentialRepository(self, auditCred=True):
        """No Credential Repository support is required"""
        msg = SAMLCredentialWallet.CREDENTIAL_REPOSITORY_NOT_SUPPORTED_MSG
        log.warning(msg)
        warnings.warn(msg)

    def isValidCredential(self, assertion):
        """Validate SAML assertion time validity"""
        utcNow = datetime.utcnow()
        if utcNow < assertion.conditions.notBefore - self.clockSkewTolerance:
            msg = ('The current clock time [%s] is before the SAML Attribute '
                   'Response assertion conditions not before time [%s] ' 
                   '(with clock skew tolerance = %s)' % 
                   (SAMLDateTime.toString(utcNow),
                    assertion.conditions.notBefore,
                    self.clockSkewTolerance))
            log.warning(msg)
            return False
            
        if (utcNow >= 
            assertion.conditions.notOnOrAfter + self.clockSkewTolerance):
            msg = ('The current clock time [%s] is on or after the SAML '
                   'Attribute Response assertion conditions not on or after '
                   'time [%s] (with clock skew tolerance = %s)' % 
                   (SAMLDateTime.toString(utcNow),
                    assertion.conditions.notOnOrAfter,
                    self.clockSkewTolerance))
            log.warning(msg)
            return False
            
        return True
    
    def __getstate__(self):
        '''Enable pickling for use with beaker.session'''
        _dict = super(SAMLCredentialWallet, self).__getstate__()
        
        for attrName in SAMLCredentialWallet.__slots__:
            # Ugly hack to allow for derived classes setting private member
            # variables
            if attrName.startswith('__'):
                attrName = "_SAMLCredentialWallet" + attrName
                
            _dict[attrName] = getattr(self, attrName)
            
        return _dict
        
        
class CredentialRepositoryError(_CredentialWalletException):   
    """Exception handling for NDG Credential Repository class."""


class CredentialRepository(object):
    """CredentialWallet's abstract interface class to a Credential Repository. 
    The Credential Repository is abstract store of user currently valid user
    credentials.  It enables retrieval of attribute certificates from a user's
    previous session(s)"""
        
    def __init__(self, propFilePath=None, dbPPhrase=None, **prop):
        """Initialise Credential Repository abstract base class.  Derive from 
        this class to define Credentail Repository interface Credential
        Wallet 

        If the connection string or properties file is set a connection
        will be made

        @type dbPPhrase: string
        @param dbPPhrase: pass-phrase to database if applicable
        
        @type propFilePath: string
        @param propFilePath: file path to a properties file.  This could 
        contain configuration parameters for the repository e.g.  database 
        connection parameters
        
        @type **prop: dict
        @param **prop: any other keywords required
        """
        raise NotImplementedError(
            self.__init__.__doc__.replace('\n       ',''))


    def addUser(self, userId, dn=None):
        """A new user to Credentials Repository
        
        @type userId: string
        @param userId: userId for new user
        @type dn: string
        @param dn: users Distinguished Name (optional)"""
        raise NotImplementedError(
            self.addUser.__doc__.replace('\n       ',''))

                            
    def auditCredentials(self, userId=None, **attCertValidKeys):
        """Check the attribute certificates held in the repository and delete
        any that have expired

        @type userId: basestring/list or tuple
        @param userId: audit credentials for the input user ID or list of IDs
        @type attCertValidKeys: dict
        @param **attCertValidKeys: keywords which set how to check the 
        Attribute Certificate e.g. check validity time, XML signature, version
         etc.  Default is check validity time only - See AttCert class"""
        raise NotImplementedError(
            self.auditCredentials.__doc__.replace('\n       ',''))


    def getCredentials(self, userId):
        """Get the list of credentials for a given users DN
        
        @type userId: string
        @param userId: users userId, name or X.509 cert. distinguished name
        @rtype: list 
        @return: list of Attribute Certificates"""
        raise NotImplementedError(
            self.getCredentials.__doc__.replace('\n       ',''))

        
    def addCredentials(self, userId, attCertList):
        """Add new attribute certificates for a user.  The user must have
        been previously registered in the repository

        @type userId: string
        @param userId: users userId, name or X.509 cert. distinguished name
        @type attCertList: list
        @param attCertList: list of attribute certificates"""
        raise NotImplementedError(
            self.addCredentials.__doc__.replace('\n       ',''))


class NullCredentialRepository(CredentialRepository):
    """Implementation of Credential Repository interface with empty stubs.  
    Use this class in the case where no Credential Repository is required"""
    
    def __init__(self, propFilePath=None, dbPPhrase=None, **prop):
        """Null Credential Repository __init__ placeholder"""

    def addUser(self, userId):
        """Null Credential Repository addUser placeholder"""
                            
    def auditCredentials(self, **attCertValidKeys):
        """Null Credential Repository addUser placeholder"""

    def getCredentials(self, userId):
        """Null Credential Repository getCredentials placeholder"""
        return []
       
    def addCredentials(self, userId, attCertList):
        """Null Credential Repository addCredentials placeholder"""