net.java.sip.communicator.impl.protocol.sip.security
Class SipSecurityManager

java.lang.Object
  net.java.sip.communicator.impl.protocol.sip.security.SipSecurityManager

public class SipSecurityManager
extends Object

The class handles authentication challenges, caches user credentials and takes care (through the SecurityAuthority interface) about retrieving passwords.

Version:

1.0

Author:

Emil Ivov, Jeroen van Bemmel

Constructor Summary

SipSecurityManager(AccountID accountID)
Default constructor for the security manager.

Method Summary

void	cacheCredentials(String realm, UserCredentials credentials) Caches realm and credentials for later usage.
javax.sip.header.AuthorizationHeader	getCachedAuthorizationHeader(String callID) Returns an authorization header cached against the specified callID or null if no auth.
SecurityAuthority	getSecurityAuthority() Returns the SecurityAuthority instance that SipSecurityManager uses to obtain user credentials.
javax.sip.ClientTransaction	handleChallenge(javax.sip.message.Response challenge, javax.sip.ClientTransaction challengedTransaction, javax.sip.SipProvider transactionCreator) Uses securityAuthority to determine a set of valid user credentials for the specified Response (Challenge) and appends it to the challenged request so that it could be retransmitted.
javax.sip.ClientTransaction	handleChallenge(javax.sip.message.Response challenge, javax.sip.ClientTransaction challengedTransaction, javax.sip.SipProvider transactionCreator, long newCSeq) Uses securityAuthority to determine a set of valid user credentials for the specified Response (Challenge) and appends it to the challenged request so that it could be retransmitted.
javax.sip.ClientTransaction	handleForbiddenResponse(javax.sip.message.Response forbidden, javax.sip.ClientTransaction endedTransaction, javax.sip.SipProvider transactionCreator) Handles a 403 Forbidden response.
void	setHeaderFactory(javax.sip.header.HeaderFactory headerFactory) Set the header factory to be used when creating authorization headers
void	setSecurityAuthority(SecurityAuthority authority) Sets the SecurityAuthority instance that should be queried for user credentials.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SipSecurityManager

public SipSecurityManager(AccountID accountID)

Default constructor for the security manager.

Parameters:

accountID - the id of the account that this security manager is going to serve.

Method Detail

setHeaderFactory

public void setHeaderFactory(javax.sip.header.HeaderFactory headerFactory)

Set the header factory to be used when creating authorization headers

Parameters:

headerFactory - the header factory that we'll be using when creating authorization headers.

handleChallenge

public javax.sip.ClientTransaction handleChallenge(javax.sip.message.Response challenge,
                                                   javax.sip.ClientTransaction challengedTransaction,
                                                   javax.sip.SipProvider transactionCreator)
                                            throws javax.sip.SipException,
                                                   javax.sip.InvalidArgumentException,
                                                   OperationFailedException,
                                                   NullPointerException

Uses securityAuthority to determine a set of valid user credentials for the specified Response (Challenge) and appends it to the challenged request so that it could be retransmitted. Fredrik Wickstrom reported that dialog cseq counters are not incremented when resending requests. He later uncovered additional problems and proposed a way to fix them (his proposition was taken into account).

Parameters:

challenge - the 401/407 challenge response

challengedTransaction - the transaction established by the challenged request

transactionCreator - the JAIN SipProvider that we should use to create the new transaction.

Returns:

a transaction containing a reoriginated request with the necessary authorization header.

Throws:

javax.sip.SipException - if we get an exception white creating the new transaction

javax.sip.InvalidArgumentException - if we fail to create a new header containing user credentials.

NullPointerException - if an argument or a header is null.

OperationFailedException - if we fail to acquire a password from our security authority.

handleChallenge

public javax.sip.ClientTransaction handleChallenge(javax.sip.message.Response challenge,
                                                   javax.sip.ClientTransaction challengedTransaction,
                                                   javax.sip.SipProvider transactionCreator,
                                                   long newCSeq)
                                            throws javax.sip.SipException,
                                                   javax.sip.InvalidArgumentException,
                                                   OperationFailedException,
                                                   NullPointerException

Uses securityAuthority to determine a set of valid user credentials for the specified Response (Challenge) and appends it to the challenged request so that it could be retransmitted. Fredrik Wickstrom reported that dialog cseq counters are not incremented when resending requests. He later uncovered additional problems and proposed a way to fix them (his proposition was taken into account).

Parameters:

challenge - the 401/407 challenge response

challengedTransaction - the transaction established by the challenged request

transactionCreator - the JAIN SipProvider that we should use to create the new transaction.

newCSeq - if the caller is generating its own cseqs can supply such, otherwise can provide -1 for auto generating it. Mean that the value from the initial request will be incremented.

Returns:

a transaction containing a reoriginated request with the necessary authorization header.

Throws:

javax.sip.SipException - if we get an exception white creating the new transaction

javax.sip.InvalidArgumentException - if we fail to create a new header containing user credentials.

NullPointerException - if an argument or a header is null.

OperationFailedException - if we fail to acquire a password from our security authority.

setSecurityAuthority

public void setSecurityAuthority(SecurityAuthority authority)

Sets the SecurityAuthority instance that should be queried for user credentials.

Parameters:

authority - the SecurityAuthority instance that should be queried for user credentials.

getSecurityAuthority

public SecurityAuthority getSecurityAuthority()

Returns the SecurityAuthority instance that SipSecurityManager uses to obtain user credentials.

Returns:

the SecurityAuthority instance that SipSecurityManager uses to obtain user credentials.

handleForbiddenResponse

public javax.sip.ClientTransaction handleForbiddenResponse(javax.sip.message.Response forbidden,
                                                           javax.sip.ClientTransaction endedTransaction,
                                                           javax.sip.SipProvider transactionCreator)
                                                    throws javax.sip.InvalidArgumentException,
                                                           javax.sip.TransactionUnavailableException

Handles a 403 Forbidden response. Contrary to the handleChallenge method this one would not attach an \ authentication header to the request since there was no challenge in the response.As a result the use of this method would result in sending one more request and receiving one more failure response. Not quite efficient ... but what do you want ... life is tough.

Parameters:

forbidden - the 401/407 challenge response

endedTransaction - the transaction established by the challenged request

transactionCreator - the JAIN SipProvider that we should use to create the new transaction.

Returns:

the client transaction that can be used to try and reregister.

Throws:

javax.sip.InvalidArgumentException - if we fail to create a new header containing user credentials.

javax.sip.TransactionUnavailableException - if we get an exception white creating the new transaction

cacheCredentials

public void cacheCredentials(String realm,
                             UserCredentials credentials)

Caches realm and credentials for later usage.

Parameters:

realm - the

credentials - UserCredentials

getCachedAuthorizationHeader

public javax.sip.header.AuthorizationHeader getCachedAuthorizationHeader(String callID)

Returns an authorization header cached against the specified callID or null if no auth. header has been previously cached for this callID.

Parameters:

callID - the ID of the call that we'd like to reString

Returns:

the AuthorizationHeader cached against the specified call ID or null if no such header has been cached.