001/*
002 * Copyright (c) 2013 - 2016 TDP Ltd All Rights Reserved.
003 * TDP Ltd grants permission, free of charge, to any person obtaining copies
004 * of this software and its associated documentation files (the "Software"),
005 * to deal in the Software without restriction, including to use, copy, adapt,
006 * publish, distribute, display, perform, sublicense, and sell copies of the
007 * Software, subject to the following condition: You must include the above
008 * copyright notice and this permission notice in all full or partial copies
009 * of the Software.
010 * 
011 * TDP LTD PROVIDES THE SOFTWARE "AS IS," WITHOUT ANY EXPRESS OR IMPLIED WARRANTY,
012 * INCLUDING WITHOUT THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
013 * PARTICULAR PURPOSE, AND NON-INFRINGMENT. TDP LTD, THE AUTHORS OF THE SOFTWARE,
014 * AND THE OWNERS OF COPYRIGHT IN THE SOFTWARE ARE NOT LIABLE FOR ANY CLAIM, DAMAGES,
015 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
016 * FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
017 * THE SOFTWARE.
018 */
019package cz.tdp.kshield.integration;
020
021import cz.tdp.kshield.client.ClientMessage;
022import cz.tdp.kshield.client.KShieldClientException;
023import cz.tdp.kshield.client.UserInfo;
024
025
026/**
027 * Processes KeyShield SSO Server authentication
028 */
029public interface AuthenticationService
030{
031  /**
032   * Retrieves userInfo from KeyShield SSO Server, Returns null if ip address is not validated by server, ip address cannot by validated or ip address is empty
033   * Non-null return value means that ipAddr was approved by KeyShield SSO Server
034   * 
035   * @param ipAddr IP address (usually from servlet request)
036   * @return valid user data for given ipAddr retrieved from KeyShield SSO Server or null
037   * @throws IllegalStateException if service is not initialized
038   */
039  UserInfo createUserInfo(String ipAddr);
040  
041  /**
042   * Sends message to another user(s) idetified by IP or FDN
043   * 
044   * @param from Name (Full Name) of message sender
045   * @param to Message target (IP or FDN)
046   * @param message Message text
047   * @throws IllegalStateException if service is not initialized
048   * @throws KShieldInvalidApiKeyException in case of Rejected API Key (Used API key must have been properly configured at KShield SSO Server)
049   * @throws KShieldClientException in case of other communication or validation error
050   */
051  void sendClientMessage(String from, String to, String message) throws KShieldClientException;
052  
053  /**
054   * Sends message to another user(s) idetified by IP or FDN
055   * 
056   * @param msg Client message data
057   * @throws IllegalStateException if service is not initialized
058   * @throws KShieldInvalidApiKeyException in case of Rejected API Key (Used API key must have been properly configured at KShield SSO Server)
059   * @throws KShieldClientException in case of other communication or validation error
060   */
061  void sendClientMessage(ClientMessage msg) throws KShieldClientException;
062  
063  /**
064   * Checks KeyShield SSO Server status
065   * 
066   * @throws IllegalStateException if service is not initialized
067   * @throws KShieldInvalidApiKeyException in case of Rejected API Key
068   * @throws KShieldClientException in case of other communication or validation error
069   */
070  void checkService() throws KShieldClientException;
071  
072  /**
073   * Initializes Authentication service after creation
074   */
075  void init();
076  
077  /**
078   * Cleanup Authentication service before destruction
079   */
080  void destroy();
081}