GUACAMOLE-197: Clean up comments and configured parameters.

extensions/guacamole-auth-radius/src/main/java/org/apache/guacamole/auth/radius/ConfigurationService.java

@@ -53,8 +53,9 @@ public String getRadiusServer() throws GuacamoleException {
     }
 
     /**
-     * Returns the authentication port of the RADIUS server configured with
-     * guacamole.properties.
+     * Returns the UDP port that will be used to communicate authentication
+     * and authorization information to the RADIUS server, as configured in
+     * guacamole.properties.  By default this will be 1812.
      *
      * @return
      *     The authentication port of the RADIUS server, as configured with
@@ -71,8 +72,9 @@ public int getRadiusAuthPort() throws GuacamoleException {
     }
 
     /**
-     * Returns the accounting port of the RADIUS server configured with
-     * guacamole.properties. 
+     * Returns the UDP port that will be used to communicate accounting
+     * information to the RADIUS server, as configured in
+     * guacamole.properties.  The default is 1813.
      *
      * @return
      *     The accouting port of the RADIUS server, as configured with
@@ -89,8 +91,9 @@ public int getRadiusAcctPort() throws GuacamoleException {
     }
 
     /**
-     * Returns the shared secret of the RADIUS server configured with
-     * guacamole.properties. 
+     * Returns the shared secret used to communicate with the RADIUS server,
+     * as configured in guacamole.properties.  This must match the value
+     * in the RADIUS server configuration.
      *
      * @return
      *     The shared secret of the RADIUS server, as configured with
@@ -106,8 +109,11 @@ public String getRadiusSharedSecret() throws GuacamoleException {
     }
 
     /**
-     * Returns the authentication protocol of the RADIUS server
-     * from guacamole.properties.
+     * Returns the authentication protocol Guacamole should use when
+     * communicating with the RADIUS server, as configured in
+     * guacamole.properties.  This must match the configuration
+     * of the RADIUS server, so that the RADIUS server and Guacamole
+     * client are "speaking the same language."
      *
      * @return
      *     The authentication protocol of the RADIUS server, 
@@ -123,8 +129,8 @@ public String getRadiusAuthProtocol() throws GuacamoleException {
     }
 
     /**
-     * Returns the number of retries for connecting to the RADIUS server
-     * from guacamole.properties.
+     * Returns the maximum number of retries for connecting to the RADIUS server
+     * from guacamole.properties.  The default number of retries is 5.
      *
      * @return
      *     The number of retries for connection to the RADIUS server,
@@ -133,19 +139,19 @@ public String getRadiusAuthProtocol() throws GuacamoleException {
      * @throws GuacamoleException
      *     If guacamole.properties cannot be parsed.
      */
-    public int getRadiusRetries() throws GuacamoleException {
+    public int getRadiusMaxRetries() throws GuacamoleException {
         return environment.getProperty(
-            RadiusGuacamoleProperties.RADIUS_RETRIES,
+            RadiusGuacamoleProperties.RADIUS_MAX_RETRIES,
             5
         );
     }
 
     /**
-     * Returns the timeout for connecting to the RADIUS server
-     * from guacamole.properties.
+     * Returns the timeout, in seconds, for connecting to the RADIUS server
+     * from guacamole.properties.  The default timeout is 60 seconds.
      *
      * @return
-     *     The timeout for connection to the RADIUS server,
+     *     The timeout, in seconds, for connection to the RADIUS server,
      *     from guacamole.properties.
      *
      * @throws GuacamoleException
@@ -159,8 +165,9 @@ public int getRadiusTimeout() throws GuacamoleException {
     }
 
     /**
-     * Returns the CA file for validating certificates for
-     * encrypted connections as specified in guacamole.properties
+     * Returns the CA file for validating certificates for encrypted
+     * connections to the RADIUS server, as configured in
+     * guacamole.properties.
      *
      * @return
      *     The file name for the CA file for validating
@@ -178,7 +185,8 @@ public String getRadiusCAFile() throws GuacamoleException {
     /**
      * Returns the key file for the client for creating encrypted
      * connections to RADIUS servers as specified in
-     * guacamole.properties.
+     * guacamole.properties.  By default a file called radius.pem
+     * is used.
      *
      * @return
      *     The file name for the client certificate/key pair
@@ -213,7 +221,8 @@ public String getRadiusCAPassword() throws GuacamoleException {
     /**
      * Returns the type of store that the CA file represents
      * so that it can be correctly processed by the RADIUS
-     * library, as configured in guacamole.properties.
+     * library, as configured in guacamole.properties.  By
+     * default the pem type is used.
      *
      * @return
      *     The type of store that the CA file is encoded
@@ -248,7 +257,8 @@ public String getRadiusKeyPassword() throws GuacamoleException {
     /**
      * Returns the type of store that the key file represents
      * so that it can be correctly processed by the RADIUS
-     * library, as configured in guacamole.properties.
+     * library, as configured in guacamole.properties.  By
+     * default the pem type is used.
      *
      * @return
      *     The type of store that the key file is encoded
@@ -268,7 +278,9 @@ public String getRadiusKeyType() throws GuacamoleException {
      * Returns the boolean value of whether or not the
      * RADIUS library should trust all server certificates
      * or should validate them against known CA certificates,
-     * as configured in guacamole.properties.
+     * as configured in guacamole.properties.  By default
+     * this is false, indicating that server certificates
+     * must be validated against a known good CA.
      *
      * @return
      *     True if the RADIUS client should trust all

extensions/guacamole-auth-radius/src/main/java/org/apache/guacamole/auth/radius/RadiusConnectionService.java

@@ -26,6 +26,7 @@
 import java.net.UnknownHostException;
 import java.security.NoSuchAlgorithmException;
 import org.apache.guacamole.GuacamoleException;
+import org.apache.guacamole.GuacamoleServerException;
 import org.apache.guacamole.environment.LocalEnvironment;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -68,11 +69,15 @@ public class RadiusConnectionService {
      * Creates a new instance of RadiusClient, configured with parameters
      * from guacamole.properties.
      *
+     * @return
+     *     A RadiusClient instance, configured with server, shared secret,
+     *     ports, and timeout, as configured in guacamole.properties.
+     *
      * @throws GuacamoleException
      *     If an error occurs while parsing guacamole.properties, or if the
      *     configuration of RadiusClient fails.
      */
-    private RadiusClient createRadiusConnection() {
+    private RadiusClient createRadiusConnection() throws GuacamoleException {
 
         // Create the RADIUS client with the configuration parameters
         try {
@@ -82,31 +87,34 @@ private RadiusClient createRadiusConnection() {
                                             confService.getRadiusAcctPort(),
                                             confService.getRadiusTimeout());
         }
-        catch (GuacamoleException e) {
-            logger.error("Unable to initialize RADIUS client: {}", e.getMessage());
-            logger.debug("Failed to init RADIUS client.", e);
-        }
         catch (UnknownHostException e) {
-            logger.error("Unable to resolve host: {}", e.getMessage());
             logger.debug("Failed to resolve host.", e);
+            throw new GuacamoleServerException("Unable to resolve RADIUS server host.", e);
         }
         catch (IOException e) {
-            logger.error("Unable to communicate with host: {}", e.getMessage());
             logger.debug("Failed to communicate with host.", e);
+            throw new GuacamoleServerException("Failed to communicate with RADIUS server.", e);
         }
 
-        return null;
-
     }
 
     /**
      * Creates a new instance of RadiusAuthentictor, configured with
      * parameters specified within guacamole.properties.
      *
+     * @param radiusClient
+     *     A RadiusClient instance that has been initialized to
+     *     communicate with a RADIUS server.
+     *
      * @return
      *     A new RadiusAuthenticator instance which has been configured
      *     with parameters from guacamole.properties, or null if
      *     configuration fails.
+     *
+     * @throws GuacamoleException
+     *     If the configuration cannot be read or the inner protocol is
+     *     not configured when the client is set up for a tunneled
+     *     RADIUS connection.
      */
     private RadiusAuthenticator setupRadiusAuthenticator(RadiusClient radiusClient)
             throws GuacamoleException {
@@ -168,10 +176,13 @@ private RadiusAuthenticator setupRadiusAuthenticator(RadiusClient radiusClient)
      *
      * @param username
      *     The username for the authentication
+     *
+     * @param secret
+     *     The secret, usually a password or challenge response, to send
+     *     to authenticate to the RADIUS server.
+     *
      * @param state
      *     The previous state of the RADIUS connection
-     * @param response
-     *     The response to the RADIUS challenge
      *
      * @return
      *     A RadiusPacket with the response of the server.
@@ -228,12 +239,12 @@ public RadiusPacket authenticate(String username, String secret, String state)
 
             radAuth.setupRequest(radiusClient, radAcc);
             radAuth.processRequest(radAcc);
-            RadiusResponse reply = radiusClient.sendReceive(radAcc, confService.getRadiusRetries());
+            RadiusResponse reply = radiusClient.sendReceive(radAcc, confService.getRadiusMaxRetries());
 
             // We receive a Challenge not asking for user input, so silently process the challenge
             while((reply instanceof AccessChallenge) && (reply.findAttribute(Attr_ReplyMessage.TYPE) == null)) {
                 radAuth.processChallenge(radAcc, reply);
-                reply = radiusClient.sendReceive(radAcc, confService.getRadiusRetries());
+                reply = radiusClient.sendReceive(radAcc, confService.getRadiusMaxRetries());
             }
             return reply;
         }
@@ -252,6 +263,28 @@ public RadiusPacket authenticate(String username, String secret, String state)
         }
     }
 
+    /**
+     * Send a challenge response to the RADIUS server by validating the input and
+     * then sending it along to the authenticate method.
+     *
+     * @param username
+     *     The username to send to the RADIUS server for authentication.
+     *
+     * @param response
+     *     The response phrase to send to the RADIUS server in response to the
+     *     challenge previously provided.
+     *
+     * @param state
+     *     The state data provided by the RADIUS server in order to continue
+     *     the RADIUS conversation.
+     *
+     * @return
+     *     A RadiusPacket containing the server's response to the authentication
+     *     attempt.
+     *
+     * @throws GuacamoleException
+     *     If an error is encountered trying to talk to the RADIUS server.
+     */
     public RadiusPacket sendChallengeResponse(String username, String response, String state)
             throws GuacamoleException {
 

extensions/guacamole-auth-radius/src/main/java/org/apache/guacamole/auth/radius/RadiusGuacamoleProperties.java

@@ -88,17 +88,17 @@ private RadiusGuacamoleProperties() {}
     };
 
     /**
-     * The number of retries when attempting a RADIUS packet transaction.
+     * The maximum number of retries when attempting a RADIUS packet transaction.
      */
-    public static final IntegerGuacamoleProperty RADIUS_RETRIES = new IntegerGuacamoleProperty() {
+    public static final IntegerGuacamoleProperty RADIUS_MAX_RETRIES = new IntegerGuacamoleProperty() {
 
         @Override
-        public String getName() { return "radius-retries"; }
+        public String getName() { return "radius-max-retries"; }
 
     };
 
     /**
-     * The network timeout when attempting a RADIUS packet transaction.
+     * The network timeout, in seconds, when attempting a RADIUS packet transaction.
      */
     public static final IntegerGuacamoleProperty RADIUS_TIMEOUT = new IntegerGuacamoleProperty() {
 

extensions/guacamole-auth-radius/src/main/java/org/apache/guacamole/auth/radius/form/RadiusChallengeResponseField.java

@@ -41,21 +41,28 @@ public class RadiusChallengeResponseField extends Field {
     /**
      * The message the RADIUS server sent back in the challenge.
      */
-    private final String replyMsg;
+    private final String challenge;
 
     /**
-     * Initialize the field with the reply message and the state.
+     * Initialize the field with the challenge sent back by the RADIUS server.
+     *
+     * @param challenge
+     *     The challenge message sent back by the RADIUS server.
      */
-    public RadiusChallengeResponseField(String replyMsg) {
+    public RadiusChallengeResponseField(String challenge) {
         super(PARAMETER_NAME, RADIUS_FIELD_TYPE);
-        this.replyMsg = replyMsg;
+        this.challenge = challenge;
 
     }
 
     /**
-     * Get the value of the replyMsg field.
+     * Get the challenge sent by the RADIUS server.
+     *
+     * @return
+     *     A String that indicates the challenge returned
+     *     by the RADIUS server.
      */
-    public String getReplyMsg() {
-        return replyMsg;
+    public String getChallenge() {
+        return challenge;
     }
 }

extensions/guacamole-auth-radius/src/main/java/org/apache/guacamole/auth/radius/form/RadiusStateField.java

@@ -45,14 +45,23 @@ public class RadiusStateField extends Field {
     private final String radiusState;
 
     /**
-     * Initialize the field with the reply message and the state.
+     * Initialize the field with the state returned by the RADIUS server.
+     *
+     * @param radiusState
+     *     The state returned by the RADIUS server.
      */
     public RadiusStateField(String radiusState) {
         super(PARAMETER_NAME, RADIUS_FIELD_TYPE);
         this.radiusState = radiusState;
 
     }
 
+    /**
+     * Get the state provided by the RADIUS server.
+     *
+     * @return
+     *     The state provided by the RADIUS server.
+     */
     public String getRadiusState() {
         return radiusState;
     }

extensions/guacamole-auth-radius/src/main/resources/controllers/radiusResponseController.js

@@ -25,6 +25,6 @@ angular.module('guacRadius').controller('radiusResponseController', ['$scope', '
         function radiusResponseController($scope, $injector) {
 
     // Populate the reply message field
-    $scope.radiusPlaceholder = $scope.field.replyMsg;
+    $scope.radiusPlaceholder = $scope.field.challenge;
 
 }]);