Configuring Authentication in Your iSCSI-Based Storage Network

Setting up authentication for your iSCSI devices is optional.

In a secure environment, authentication is not required because only trusted initiators can access the targets.

In a less secure environment, the target cannot determine if a connection request is truly from a given host. In that case, the target can authenticate an initiator by using the Challenge-Handshake Authentication Protocol (CHAP).

CHAP authentication uses the notion of a challenge and response, which means that the target challenges the initiator to prove its identity. For the challenge/response method to work, the target must know the initiator's secret key, and the initiator must be set up to respond to a challenge. Refer to the array vendor's documentation for instructions on setting up the secret key on the array.

iSCSI supports unidirectional and bidirectional authentication:

Unidirectional authentication enables the target to authenticate the identity of the initiator.
Bidirectional authentication adds a second level of security by enabling the initiator to authenticate the identity of the target.

How to Configure CHAP Authentication for Your iSCSI Initiator

This procedure assumes that you are logged in to the local system where you want to securely access the configured iSCSI target device.

Become superuser.
Determine whether you want to configure unidirectional or bidirectional CHAP.
- Unidirectional authentication, the default method, enables the target to validate the initiator. Complete steps 3–5 only.
- Bidirectional authentication adds a second level of security by enabling the initiator to authenticate the target. Complete steps 3–9.
Unidirectional CHAP – Set the secret key on the initiator.
For example, the following command initiates a dialogue to define the CHAP secret key.
```
initiator# iscsiadm modify initiator-node --CHAP-secret
```
Note - The CHAP secret length must be a minimum of 12 characters and a maximum of 16 characters.
(Optional) Unidirectional CHAP – Set the CHAP name on the initiator.
By default, the initiator's CHAP name is set to the initiator node name.
You can use the following command to change the initiator's CHAP name.
```
initiator# iscsiadm modify initiator-node --CHAP-name new-CHAP-name
```
In the Solaris environment, the CHAP name is always set to the initiator node name by default. The CHAP name can be set to any length text that is less than 512 bytes. The 512-byte length limit is a Solaris limitation. However, if you do not set the CHAP name, it is set to the initiator node name upon initialization.
Unidirectional CHAP – Enable CHAP authentication on the initiator after the secret has been set.
```
initiator# iscsiadm modify initiator-node --authentication CHAP
```
CHAP requires that the initiator node have both a user name and a password. The user name is typically used by the target to look up the secret for the given username.
Select one of the following to enable or disable Bidirectional CHAP.
- Bidirectional CHAP – Enable bidirectional authentication parameters on the target.
  
  For example:
```
initiator# iscsiadm modify target-param -B enable eui.5000ABCD78945E2B
```
- Disable bidirectional CHAP. For example:
```
initiator# iscsiadm modify target-param -B disable eui.5000ABCD78945E2B
```
Bidirectional CHAP – Set the authentication method to CHAP on the target.
For example:
```
initiator# iscsiadm modify target-param --authentication CHAP eui.5000ABCD78945E2B
```
Bidirectional CHAP – Set the target device secret key on the target.
For example, the following command initiates a dialogue to define the CHAP secret key:
```
initiator# iscsiadm modify target-param --CHAP-secret eui.5000ABCD78945E2B
```
Bidirectional CHAP - Set the CHAP name on the target.
By default, the target's CHAP name is set to the target name.
You can use the following command to change the target's CHAP name:
```
initiator# iscsiadm modify target-param --CHAP-name target-CHAP-name
```

How to Configure CHAP Authentication for Your iSCSI Target

This procedure assumes that you are logged in to the local system that contains the iSCSI targets.

Become superuser.
Set the CHAP secret name for the target.
A convention is to use the host name for the secret name. For example:
```
target# iscsitadm modify admin -H stormpike
```
Specify the CHAP secret.
The CHAP secret must be between 12 and 16 characters. For example:
```
target# iscsitadm modify admin -C
Enter secret: xxxxxx
Re-enter secret: xxxxxx
```
Create an initiator object that will be associated with one or more targets.
This step is done so that you can associate a friendly name (normally the host name, in this case monster620) with the IQN value, instead of typing it in every time. For example:
```
# iscsitadm create initiator -n iqn.1986-03.com.sun: 01:00e081553307.4399f40e monster620
```
Provide the same CHAP name that was used on the initiator.
This name can be different from the friendly name that was used for the initiator object. For example:
```
target# iscsitadm modify initiator -H monster620 monster620
```

Use the same CHAP secret that was used on the initiator.

For example:

target# iscsitadm modify initiator -C monster620
Enter secret: xxxxxx
Re-enter secret: xxxxxx

Associate the initiator object with one or more targets.
For example:
```
target# iscsitadm modify target -l monster620 sandbox
```

Using a Third-Party RADIUS Server to Simplify CHAP Management in Your iSCSI Configuration

You can use a third-party RADIUS server to simplify CHAP secret management. A RADIUS server is a centralized authentication service. While you must still specify the initiator's CHAP secret, you are no longer required to specify each target's CHAP secret on each initiator when using bidirectional authentication with a RADIUS server.

For more information, see:

CHAP – http://www.ietf.org/rfc/rfc1994.txt
RADIUS – http://www.ietf.org/rfc/rfc2865.txt

How to Configure RADIUS for Your iSCSI Configuration

This procedure assumes that you are logged in to the local system where you want to securely access the configured iSCSI target device.

Become superuser.
Configure the initiator node with the IP address and port (the default port is 1812) of the RADIUS server.
For example:
```
initiator# iscsiadm modify initiator-node --radius-server 10.0.0.72:1812
```
Configure the initiator node with the shared secret of the RADIUS server.
```
initiator# iscsiadm modify initiator-node --radius-shared-secret
```
Note - The Solaris iSCSI implementation requires that the RADIUS server is configured with a shared secret before the Solaris iSCSI software can interact with the RADIUS server.

Enable the RADIUS server.

initiator# iscsiadm modify initiator-node --radius-access enable

Solaris iSCSI and RADIUS Server Error Messages

This section describes the error messages that are related to a Solaris iSCSI and RADIUS server configuration, along with potential solutions for recovery.

empty RADIUS shared secret

Cause: The RADIUS server is enabled on the initiator, but the RADIUS shared secret is not set.

Solution: Configure the initiator with the RADIUS shared secret. For more information, see How to Configure RADIUS for Your iSCSI Configuration.

WARNING: RADIUS packet authentication failed

Cause: The initiator failed to authenticate the RADIUS data packet. This error can occur if the shared secret configured on the initiator node is different from the shared secret on the RADIUS server.

Reconfigure the initiator with the correct RADIUS shared secret. For more information, see How to Configure RADIUS for Your iSCSI Configuration.

Skip Navigation Links
Exit Print View
	System Administration Guide: Devices and File Systems Oracle Solaris 10 1/13 Information Library