001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package org.jboss.security.srp;
023:
024: import java.rmi.RemoteException;
025: import java.security.KeyException;
026: import java.security.NoSuchAlgorithmException;
027:
028: /** An interface describing the message exchange of the SRP protocol as
029: described in RFC2945. This is an RMI compatible interface in that all methods
030: declare that they throw a RemoteException, but it does not extend from
031: java.rmi.Remote so that it cannot be used in place of a Remote object.
032: For an RMI interface see the SRPRemoteServerInterface.
033:
034: There are two versions of each method. One that takes an arbitrary session number
035: and one that does not. The session number form allows a user to maintain mutiple
036: SRP sessions.
037:
038: @see org.jboss.security.srp.SRPRemoteServerInterface
039:
040: @author Scott.Stark@jboss.org
041: @version $Revision: 57210 $
042: */
043: public interface SRPServerInterface {
044: /** Get the SRP parameters to use for this session.
045: * @param username, the SRP username
046: * @return the users SRPParameters object
047: */
048: public SRPParameters getSRPParameters(String username)
049: throws KeyException, RemoteException;
050:
051: /** Get the SRP parameters to use for this session and create an arbitrary session id
052: * to allow for multiple SRP sessions for this user.
053: * @param username, the SRP username
054: * @param mutipleSessions, a flag that if true indicates the user may initiate mutiple
055: * sessions and an arbitrary session id will be created.
056: * @return an array of {SRPParameters, Integer} where element[0] is the SRPParameters
057: * object and element[1] is the session id as an Integer.
058: */
059: public Object[] getSRPParameters(String username,
060: boolean mutipleSessions) throws KeyException,
061: RemoteException;
062:
063: /** Initiate the SRP algorithm. The client sends their username and the
064: public key A to begin the SRP handshake.
065: @param username, the user ID by which the client is known.
066: @param A, the client public key = (g ^ a) % N
067: @return byte[], ephemeral server public key B = (v + g ^ b) % N
068: @throws KeyException, thrown if the username is not known by the server.
069: @throws RemoteException, thrown by remote implementations
070: */
071: public byte[] init(String username, byte[] A)
072: throws SecurityException, NoSuchAlgorithmException,
073: RemoteException;
074:
075: /** Initiate the SRP algorithm. The client sends their username and the
076: public key A to begin the SRP handshake.
077: @param username, the user ID by which the client is known.
078: @param A, the client public key = (g ^ a) % N
079: @param sessionID, the arbitrary session id obtained from getSRPParameters. A 0
080: indicates there is no sessionID.
081: @return byte[], ephemeral server public key B = (v + g ^ b) % N
082: @throws KeyException, thrown if the username is not known by the server.
083: @throws RemoteException, thrown by remote implementations
084: */
085: public byte[] init(String username, byte[] A, int sessionID)
086: throws SecurityException, NoSuchAlgorithmException,
087: RemoteException;
088:
089: /** Verify the session key hash. The client sends their username and M1
090: hash to validate completion of the SRP handshake.
091:
092: @param username, the user ID by which the client is known. This is repeated to simplify
093: the server session management.
094: @param M1, the client hash of the session key; M1 = H(H(N) xor H(g) | H(U) | A | B | K)
095: @return M2, the server hash of the client challenge; M2 = H(A | M1 | K)
096: @throws SecurityException, thrown if M1 cannot be verified by the server
097: @throws RemoteException, thrown by remote implementations
098: */
099: public byte[] verify(String username, byte[] M1)
100: throws SecurityException, RemoteException;
101:
102: public byte[] verify(String username, byte[] M1, int sessionID)
103: throws SecurityException, RemoteException;
104:
105: /** Verify the session key hash. The client sends their username and M1
106: hash to validate completion of the SRP handshake.
107:
108: @param username, the user ID by which the client is known. This is repeated to simplify
109: the server session management.
110: @param M1, the client hash of the session key; M1 = H(H(N) xor H(g) | H(U) | A | B | K)
111: @param auxChallenge, an arbitrary addition data item that my be used as an additional
112: challenge. One example usage would be to send a hardware generated token that was encrypted
113: with the session private key for validation by the server.
114: @return M2, the server hash of the client challenge; M2 = H(A | M1 | K)
115: @throws SecurityException, thrown if M1 cannot be verified by the server
116: @throws RemoteException, thrown by remote implementations
117: */
118: public byte[] verify(String username, byte[] M1, Object auxChallenge)
119: throws SecurityException, RemoteException;
120:
121: public byte[] verify(String username, byte[] M1,
122: Object auxChallenge, int sessionID)
123: throws SecurityException, RemoteException;
124:
125: /** Close the SRP session for the given username.
126: */
127: public void close(String username) throws SecurityException,
128: RemoteException;
129:
130: public void close(String username, int sessionID)
131: throws SecurityException, RemoteException;
132: }
|