diff options
| -rw-r--r-- | src/server/iscsi.c | 30 | ||||
| -rw-r--r-- | src/server/iscsi.h | 850 |
2 files changed, 534 insertions, 346 deletions
diff --git a/src/server/iscsi.c b/src/server/iscsi.c index 4e96e06..48a4883 100644 --- a/src/server/iscsi.c +++ b/src/server/iscsi.c @@ -34,9 +34,9 @@ * @brief iSCSI implementation for DNBD3. * * This file contains the iSCSI implementation according to - * RFC7143 for dnbd3-server. + * RFC7143 for dnbd3-server.\n * All server-side network sending and client-side network - * receiving code is done here. + * receiving code is done here.\n * @see https://www.rfc-editor.org/rfc/rfc7143 */ @@ -140,10 +140,10 @@ uint8_t *iscsi_sprintf_alloc(const char *format, ... ) * @brief Creates an empty hash map with either specified or default capacity. * * Creates a ultra hardcore speed optimized empty hash map and - * allocates enough buckets to hold default capacity elements. + * allocates enough buckets to hold default capacity elements.\n * The speed optimizations require all keys having a size of * a multiple of 8 bytes with zero padding. Also the capacity - * always nas to be a power of two. + * always nas to be a power of two.\n * TODO: Move all hash map related functions to different source file * later and implement in a lock-free way for better concurrency. * @@ -358,7 +358,7 @@ static iscsi_hashmap_bucket *iscsi_hashmap_find_entry(iscsi_hashmap *map, const * @brief Creates a key suitable for hashmap usage (ensures 8-byte boundary and zero padding). * * Creates a key from data and size and ensures - * its requirements for usage in hash map buckets. + * its requirements for usage in hash map buckets.\n * Currently keys to be used in a hash map bucket * require a size of multiple by 8 bytes with * the zero padding. @@ -433,7 +433,7 @@ int iscsi_hashmap_key_destroy_value_callback(uint8_t *key, const size_t key_size * * Adds a key / value pair to a specified hash map * bucket list, if it doesn't exist already. The - * buckets are resized automatically if required. + * buckets are resized automatically if required.\n * This function neither does make a copy of the key, * nor of the value. Keys should be allocated using * the function iscsi_hashmap_key_create or freed by @@ -488,7 +488,7 @@ int iscsi_hashmap_put(iscsi_hashmap *map, const uint8_t *key, const size_t key_s * does exist, value will be set in `*out_in`, * meaning the value of the pair will be in * '*out_in` regardless of whether or not it it - * existed in the first place. + * existed in the first place.\n * The buckets are resized automatically if required. * This function neither does make a copy of the key, * nor of the value. Keys should be allocated using @@ -549,7 +549,7 @@ int iscsi_hashmap_get_put(iscsi_hashmap *map, const uint8_t *key, const size_t k * invoked in order to allow, e.g. deallocation of * resources, if necessary. The buckets are resized * automatically if required. This function neither - * does make a copy of the key, nor of the value. + * does make a copy of the key, nor of the value.\n * Keys should be allocated using the function * iscsi_hashmap_key_create or freed by using * iscsi_hashmap_key_destroy in order to ensure the @@ -701,7 +701,7 @@ void iscsi_hashmap_remove(iscsi_hashmap *map, const uint8_t *key, const size_t k /** * @brief Marks an element for removal by setting key and value both to NULL, but invokes a callback function before actual marking for removal. * - * Removes an element from the bucket list of the hash map. + * Removes an element from the bucket list of the hash map.\n * Buckets are marked as removed by setting their key and * value to NULL. The actual removal will be done upon next * resize operation. A callback function is invoked if the @@ -850,7 +850,7 @@ void iscsi_destroy_packet(iscsi_bhs_packet *packet_data) * * Constructs and appends an Additional Header Segment (AHS) to already allocated * packet data. There is no guarantee that the pointer stays the same. Any references - * to the old structure need to be updated! + * to the old structure need to be updated!\n * This function currently throws away any data beyond AHS. * * @param[in] packet_data Pointer to packet data to append to. If NULL, a Basic @@ -970,9 +970,9 @@ iscsi_ahs_packet *iscsi_get_ahs_packet(const iscsi_bhs_packet *packet_data, cons /** * @brief Allocate and initialize an iSCSI DS packet and append to existing data stream. * - * Constructs and appends DataSegment (DS) to already allocated packet data. + * Constructs and appends DataSegment (DS) to already allocated packet data.\n * There is no guarantee that the pointer stays the same. Any references - * to the old structure need to be updated! + * to the old structure need to be updated!\n * This function currently erases an already available DataSegment and * throws away any data beyond DS. * @@ -1054,7 +1054,7 @@ static const uint32_t crc32c_lut[] = { // Created with a polynomial reflect valu /** * @brief Calculates digest (CRC32C). * - * Calculates CRC32C with 0x82F63B78 polynomial reflect according to iSCSI specs + * Calculates CRC32C with 0x82F63B78 polynomial reflect according to iSCSI specs.\n * TODO: Implement optimized SSE4.2 and ARM versions * * @param[in] data Pointer to data to calculate CRC32C for. @@ -1116,7 +1116,7 @@ int iscsi_validate_header_digest(const iscsi_bhs_packet *packet_data) * @brief Calculate iSCSI data digest (CRC32C). * * Calculates data digest (CRC32) with 0x82F63B78 polynomial reflect - * of a whole DataSegment (CRC32C) according to the iSCSI specs. + * of a whole DataSegment (CRC32C) according to the iSCSI specs.\n * The resulting CRC32C will be stored in the iSCSI packet. * * @param[in] packet_data Pointer to ISCSI DS packet to calculate CRC32C for. @@ -1234,7 +1234,7 @@ static int iscsi_validate_key_value_pairs(const uint8_t *packet_data, uint len) /** * @brief Check if valid iSCSI packet and validate if necessarily. * - * Checks whether packet data is an iSCSI packet or not. + * Checks whether packet data is an iSCSI packet or not.\n * Since iSCSI doesn't have a magic identifier for its packets, a * partial heuristic approach is needed for it. There is not always * a guarantee that a packet clearly belongs to iSCSI. If header diff --git a/src/server/iscsi.h b/src/server/iscsi.h index b120533..8047dbc 100644 --- a/src/server/iscsi.h +++ b/src/server/iscsi.h @@ -813,7 +813,7 @@ typedef struct __attribute__((packed)) iscsi_ds_cmd_data { * @brief iSCSI Flag and Task Attributes for SCSI command packet data. * * Flags and Task Attributes: - * At least one of the W and F bits MUST be set to 1. + * At least one of the W and F bits MUST be set to 1.\n * Either or both of R and W MAY be 1 when the Expected Data Transfer * Length and/or the Bidirectional Read Expected Data Transfer Length * are 0, but they MUST NOT both be 0 when the Expected Data Transfer @@ -854,7 +854,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_cmd_packet { * unidirectional read operation (W flag set to 0 and R flag set to 1), * the initiator uses this field to specify the number of bytes of data * it expects the target to transfer to the initiator. It corresponds - * to the SAM-2 byte count. + * to the SAM-2 byte count.\n * For bidirectional operations (both R and W flags are set to 1), this * field contains the number of data bytes involved in the write * transfer. For bidirectional operations, an additional header segment @@ -865,7 +865,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_cmd_packet { * If the Expected Data Transfer Length for a write and the length of * the immediate data part that follows the command (if any) are the * same, then no more data PDUs are expected to follow. In this case, - * the F bit MUST be set to 1. + * the F bit MUST be set to 1.\n * If the Expected Data Transfer Length is higher than the * FirstBurstLength (the negotiated maximum amount of unsolicited data * the target will accept), the initiator MUST send the maximum amount @@ -1131,7 +1131,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_response_packet { * This field contains a copy of the SNACK Tag of the last SNACK Tag * accepted by the target on the same connection and for the command for * which the response is issued. Otherwise, it is reserved and should - * be set to 0. + * be set to 0.\n * After issuing a R-Data SNACK, the initiator must discard any SCSI * status unless contained in a SCSI Response PDU carrying the same * SNACK Tag as the last issued R-Data SNACK for the SCSI command on the @@ -1180,7 +1180,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_response_packet { * @brief ExpDataSN or Reserved. * * This field indicates the number of Data-In (read) PDUs the target has - * sent for the command. + * sent for the command.\n * This field MUST be 0 if the response code is not Command Completed at * Target or the target sent no Data-In PDUs for the command. */ @@ -1318,7 +1318,7 @@ typedef struct __attribute__((packed)) iscsi_task_mgmt_func_req_packet { * * If an ABORT TASK is issued for a task created by an immediate * command, then the RefCmdSN MUST be that of the task management - * request itself (i.e., the CmdSN and RefCmdSN are equal). + * request itself (i.e., the CmdSN and RefCmdSN are equal).\n * For an ABORT TASK of a task created by a non-immediate command, the * RefCmdSN MUST be set to the CmdSN of the task identified by the * Referenced Task Tag field. Targets must use this field when the task @@ -1411,7 +1411,7 @@ typedef struct __attribute__((packed)) iscsi_task_mgmt_func_response_packet { * cancels all pending operations across all LUs known to the issuing * initiator. For the TARGET COLD RESET function, the target MUST then * close all of its TCP connections to all initiators (terminates all - * sessions). + * sessions).\n * The mapping of the response code into a SCSI service response code * value, if needed, is outside the scope of this document. However, in * symbolic terms, Response values 0 and 1 map to the SCSI service @@ -1420,25 +1420,25 @@ typedef struct __attribute__((packed)) iscsi_task_mgmt_func_response_packet { * Response values map to the SCSI service response of FUNCTION * REJECTED. If a Task Management Function Response PDU does not arrive * before the session is terminated, the SCSI service response is - * SERVICE DELIVERY OR TARGET FAILURE. + * SERVICE DELIVERY OR TARGET FAILURE.\n * The response to ABORT TASK SET and CLEAR TASK SET MUST only be issued * by the target after all of the commands affected have been received * by the target, the corresponding task management functions have been * executed by the SCSI target, and the delivery of all responses * delivered until the task management function completion has been * confirmed (acknowledged through the ExpStatSN) by the initiator on - * all connections of this session. - * For the ABORT TASK function, - * a) if the Referenced Task Tag identifies a valid task leading to a + * all connections of this session.\n + * For the ABORT TASK function,\n + * -# if the Referenced Task Tag identifies a valid task leading to a * successful termination, then targets must return the "Function * complete" response. - * b) if the Referenced Task Tag does not identify an existing task + * -# if the Referenced Task Tag does not identify an existing task * but the CmdSN indicated by the RefCmdSN field in the Task * Management Function Request is within the valid CmdSN window * and less than the CmdSN of the Task Management Function Request * itself, then targets must consider the CmdSN as received and * return the "Function complete" response. - * c) if the Referenced Task Tag does not identify an existing task + * -# if the Referenced Task Tag does not identify an existing task * and the CmdSN indicated by the RefCmdSN field in the Task * Management Function Request is outside the valid CmdSN window, * then targets must return the "Task does not exist" response @@ -1510,7 +1510,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_data_out_req_packet { * This is the data payload length of a SCSI Data-In or SCSI Data-Out * PDU. The sending of 0-length data segments should be avoided, but * initiators and targets MUST be able to properly receive 0-length data - * segments. + * segments.\n * The data segments of Data-In and Data-Out PDUs SHOULD be filled to * the integer number of 4-byte words (real payload), unless the F bit * is set to 1. @@ -1535,7 +1535,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_data_out_req_packet { * On outgoing data, the Target Transfer Tag is provided to the target * if the transfer is honoring an R2T. In this case, the Target * Transfer Tag field is a replica of the Target Transfer Tag provided - * with the R2T. + * with the R2T.\n * The Target Transfer Tag values are not specified by this protocol, * except that the value 0xFFFFFFFF is reserved and means that the * Target Transfer Tag is not supplied. @@ -1568,10 +1568,10 @@ typedef struct __attribute__((packed)) iscsi_scsi_data_out_req_packet { * The Buffer Offset field contains the offset of this PDU payload data * within the complete data transfer. The sum of the buffer offset and * length should not exceed the expected transfer length for the - * command. + * command.\n * The order of data PDUs within a sequence is determined by * DataPDUInOrder. When set to Yes, it means that PDUs have to be in - * increasing buffer offset order and overlays are forbidden. + * increasing buffer offset order and overlays are forbidden.\n * The ordering between sequences is determined by DataSequenceInOrder. * When set to Yes, it means that sequences have to be in increasing * buffer offset order and overlays are forbidden. @@ -1636,7 +1636,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_data_out_req_packet { * perspective, and it MUST NOT do so more frequently. The target MUST * NOT set to 1 the A bit for sessions with ErrorRecoveryLevel=0. The * initiator MUST ignore the A bit set to 1 for sessions with - * ErrorRecoveryLevel=0. + * ErrorRecoveryLevel=0.\n * On receiving a Data-In PDU with the A bit set to 1 on a session with * ErrorRecoveryLevel greater than 0, if there are no holes in the read * data until that Data-In PDU, the initiator MUST issue a SNACK of type @@ -1666,7 +1666,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_data_out_req_packet { * having its own F bit. Splitting the data stream into sequences does * not affect DataSN counting on Data-In PDUs. It MAY be used as a * "change direction" indication for bidirectional operations that need - * such a change. + * such a change.\n * DataSegmentLength MUST NOT exceed MaxRecvDataSegmentLength for the * direction it is sent, and the total of all the DataSegmentLength of * all PDUs in a sequence MUST NOT exceed MaxBurstLength (or @@ -1676,7 +1676,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_data_out_req_packet { * MaxRecvDataSegmentLength (as PDUs may be limited in length by the * capabilities of the sender). Using a DataSegmentLength of 0 may * increase beyond what is reasonable for the number of PDUs and should - * therefore be avoided. + * therefore be avoided.\n * For bidirectional operations, the F bit is 1 for both the end of the * input sequences and the end of the output sequences */ @@ -1720,7 +1720,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_data_in_response_packet { * This is the data payload length of a SCSI Data-In or SCSI Data-Out * PDU. The sending of 0-length data segments should be avoided, but * initiators and targets MUST be able to properly receive 0-length data - * segments. + * segments.\n * The data segments of Data-In and Data-Out PDUs SHOULD be filled to * the integer number of 4-byte words (real payload), unless the F bit * is set to 1. @@ -1746,7 +1746,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_data_in_response_packet { * the target if the A bit is set to 1; otherwise, they are reserved. * The Target Transfer Tag and LUN are copied by the initiator into the * SNACK of type DataACK that it issues as a result of receiving a SCSI - * Data-In PDU with the A bit set to 1. + * Data-In PDU with the A bit set to 1.\n * The Target Transfer Tag values are not specified by this protocol, * except that the value 0xFFFFFFFF is reserved and means that the * Target Transfer Tag is not supplied. @@ -1768,7 +1768,7 @@ typedef struct __attribute__((packed)) iscsi_scsi_data_in_response_packet { * * For input (read) or bidirectional Data-In PDUs, the DataSN is the * input PDU number within the data transfer for the command identified - * by the Initiator Task Tag. + * by the Initiator Task Tag.\n * R2T and Data-In PDUs, in the context of bidirectional commands, share * the numbering sequence. */ @@ -1780,10 +1780,10 @@ typedef struct __attribute__((packed)) iscsi_scsi_data_in_response_packet { * The Buffer Offset field contains the offset of this PDU payload data * within the complete data transfer. The sum of the buffer offset and * length should not exceed the expected transfer length for the - * command. + * command.\n * The order of data PDUs within a sequence is determined by * DataPDUInOrder. When set to Yes, it means that PDUs have to be in - * increasing buffer offset order and overlays are forbidden. + * increasing buffer offset order and overlays are forbidden.\n * The ordering between sequences is determined by DataSequenceInOrder. * When set to Yes, it means that sequences have to be in increasing * buffer offset order and overlays are forbidden. @@ -1901,9 +1901,9 @@ typedef struct __attribute__((packed)) iscsi_r2t_packet { /** * @brief Buffer Offset. * - * The target therefore also specifies a buffer offset that - * indicates the point at which the data transfer should begin, relative - * to the beginning of the total data transfer. + * The target therefore also specifies a buffer offset that indicates + * the point at which the data transfer should begin, relative to the + * beginning of the total data transfer. */ uint32_t buf_offset; @@ -1963,19 +1963,19 @@ typedef struct __attribute__((packed)) iscsi_r2t_packet { * * The target indicates that it will drop the connection. * The Parameter1 field indicates the CID of the connection that - * is going to be dropped. + * is going to be dropped.\n * The Parameter2 field (Time2Wait) indicates, in seconds, the * minimum time to wait before attempting to reconnect or - * reassign. + * reassign.\n * The Parameter3 field (Time2Retain) indicates the maximum time * allowed to reassign commands after the initial wait (in - * Parameter2). + * Parameter2).\n * If the initiator does not attempt to reconnect and/or reassign * the outstanding commands within the time specified by * Parameter3, or if Parameter3 is 0, the target will terminate * all outstanding commands on this connection. In this case, no * other responses should be expected from the target for the - * outstanding commands on this connection. + * outstanding commands on this connection.\n * A value of 0 for Parameter2 indicates that reconnect can be * attempted immediately. */ @@ -1985,16 +1985,16 @@ typedef struct __attribute__((packed)) iscsi_r2t_packet { * @brief SCSI Asynchronous Message Event: Session Drop Notification. * * The target indicates that it will drop all the connections - * of this session. - * The Parameter1 field is reserved. + * of this session.\n + * The Parameter1 field is reserved.\n * The Parameter2 field (Time2Wait) indicates, in seconds, the - * minimum time to wait before attempting to reconnect. + * minimum time to wait before attempting to reconnect.\n * The Parameter3 field (Time2Retain) indicates the maximum time * allowed to reassign commands after the initial wait (in - * Parameter2). + * Parameter2).\n * If the initiator does not attempt to reconnect and/or reassign * the outstanding commands within the time specified by - * Parameter3, or if Parameter3 is 0, the session is terminated. + * Parameter3, or if Parameter3 is 0, the session is terminated.\n * In this case, the target will terminate all outstanding * commands in this session; no other responses should be * expected from the target for the outstanding commands in this @@ -2047,7 +2047,7 @@ typedef struct __attribute__((packed)) iscsi_r2t_packet { * * An Asynchronous Message may be sent from the target to the initiator * without corresponding to a particular command. The target specifies - * the reason for the event and sense data. + * the reason for the event and sense data.\n * Some Asynchronous Messages are strictly related to iSCSI, while * others are related to SCSI */ @@ -2219,7 +2219,7 @@ typedef struct __attribute__((packed)) iscsi_text_req_packet { * When the Target Transfer Tag is set to the reserved value 0xFFFFFFFF, * it tells the target that this is a new request, and the target resets * any internal state associated with the Initiator Task Tag (resets the - * current negotiation state). + * current negotiation state).\n * The target sets the Target Transfer Tag in a Text Response to a value * other than the reserved value 0xFFFFFFFF whenever it indicates that * it has more data to send or more operations to perform that are @@ -2228,16 +2228,17 @@ typedef struct __attribute__((packed)) iscsi_text_req_packet { * Target Transfer Tag from the response to the next Text Request, the * initiator tells the target to continue the operation for the specific * Initiator Task Tag. The initiator MUST ignore the Target Transfer - * Tag in the Text Response when the F bit is set to 1. + * Tag in the Text Response when the F bit is set to 1.\n * This mechanism allows the initiator and target to transfer a large * amount of textual data over a sequence of text-command/text-response - * exchanges or to perform extended negotiation sequences. + * exchanges or to perform extended negotiation sequences.\n * If the Target Transfer Tag is not 0xFFFFFFFF, the LUN field MUST be - * sent by the target in the Text Response. + * sent by the target in the Text Response.\n * A target MAY reset its internal negotiation state if an exchange is * stalled by the initiator for a long time or if it is running out of - * resources. - * Long Text Responses are handled as shown in the following example: + * resources.\n + * Long Text Responses are handled as shown in the following example:\n + * @verbatim * I->T Text SendTargets=All (F = 1, TTT = 0xFFFFFFFF) * T->I Text <part 1> (F = 0, TTT = 0x12345678) * I->T Text <empty> (F = 1, TTT = 0x12345678) @@ -2245,6 +2246,7 @@ typedef struct __attribute__((packed)) iscsi_text_req_packet { * I->T Text <empty> (F = 1, TTT = 0x12345678) * ... * T->I Text <part n> (F = 1, TTT = 0xFFFFFFFF) + * @endverbatim */ uint32_t target_xfer_tag; @@ -2265,16 +2267,16 @@ typedef struct __attribute__((packed)) iscsi_text_req_packet { * * The data lengths of a Text Request MUST NOT exceed the iSCSI target * MaxRecvDataSegmentLength (a parameter that is negotiated per - * connection and per direction). + * connection and per direction).\n * A key=value pair can span Text Request or Text Response boundaries. * A key=value pair can start in one PDU and continue on the next. In * other words, the end of a PDU does not necessarily signal the end of - * a key=value pair. + * a key=value pair.\n * The target responds by sending its response back to the initiator. * The response text format is similar to the request text format. The * Text Response MAY refer to key=value pairs presented in an earlier * Text Request, and the text in the request may refer to earlier - * responses. + * responses.\n * Text operations are usually meant for parameter setting/negotiations * but can also be used to perform some long-lasting operations. */ @@ -2305,11 +2307,11 @@ typedef struct __attribute__((packed)) iscsi_text_req_packet { * the Final Bit set to 1, it indicates that the target has more work to * do (invites a follow-on Text Request). A Text Response with the * F bit set to 1 in response to a Text Request with the F bit set to 0 - * is a protocol error. + * is a protocol error.\n * A Text Response with the F bit set to 1 MUST NOT contain key=value * pairs that may require additional answers from the initiator. * A Text Response with the F bit set to 1 MUST have a Target Transfer - * Tag field set to the reserved value 0xFFFFFFFF. + * Tag field set to the reserved value 0xFFFFFFFF.\n * A Text Response with the F bit set to 0 MUST have a Target Transfer * Tag field set to a value other than the reserved value 0xFFFFFFFF. */ @@ -2352,18 +2354,18 @@ typedef struct __attribute__((packed)) iscsi_text_response_packet { * negotiation) and has enough resources to proceed, it MUST set the * Target Transfer Tag to a value other than the reserved value * 0xFFFFFFFF. Otherwise, the Target Transfer Tag MUST be set to - * 0xFFFFFFFF. + * 0xFFFFFFFF.\n * When the Target Transfer Tag is not 0xFFFFFFFF, the LUN field may be - * significant. + * significant.\n * The initiator MUST copy the Target Transfer Tag and LUN in its next - * request to indicate that it wants the rest of the data. + * request to indicate that it wants the rest of the data.\n * When the target receives a Text Request with the Target Transfer Tag * set to the reserved value 0xFFFFFFFF, it resets its internal * information (resets state) associated with the given Initiator Task - * Tag (restarts the negotiation). + * Tag (restarts the negotiation).\n * When a target cannot finish the operation in a single Text Response * and does not have enough resources to continue, it rejects the Text - * Request with the appropriate Reject code. + * Request with the appropriate Reject code.\n * A target may reset its internal state associated with an Initiator * Task Tag (the current negotiation state) as expressed through the * Target Transfer Tag if the initiator fails to continue the exchange @@ -2392,9 +2394,9 @@ typedef struct __attribute__((packed)) iscsi_text_response_packet { * * The data lengths of a Text Response MUST NOT exceed the iSCSI * initiator MaxRecvDataSegmentLength (a parameter that is negotiated - * per connection and per direction). + * per connection and per direction).\n * The text in the Text Response Data is governed by the same rules as - * the text in the Text Request Data. + * the text in the Text Request Data.\n * Although the initiator is the requesting party and controls the * request-response initiation and termination, the target can offer * key=value pairs of its own as part of a sequence and not only in @@ -2483,20 +2485,22 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Key used during SecurityNegotiation stage of Login Phase: Session type. * + * @verbatim * Use: LO, Declarative, Any-Stage * Senders: Initiator * Scope: SW * SessionType=<Discovery|Normal> * Default is Normal. + * @endverbatim * The initiator indicates the type of session it wants to create. The - * target can either accept it or reject it. + * target can either accept it or reject it.\n * A Discovery session indicates to the target that the only purpose of * this session is discovery. The only requests a target accepts in * this type of session are a Text Request with a SendTargets key and a - * Logout Request with reason "close the session". + * Logout Request with reason "close the session".\n * The Discovery session implies MaxConnections = 1 and overrides both * the default and an explicit setting. ErrorRecoveryLevel MUST be 0 - * (zero) for Discovery sessions. + * (zero) for Discovery sessions.\n * Depending on the type of session, a target may decide on resources to * allocate, the security to enforce, etc., for the session. If the * SessionType key is thus going to be offered as "Discovery", it SHOULD @@ -2507,6 +2511,7 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Key used during SecurityNegotiation stage of Login Phase: Initiator name. * + * @verbatim * Use: IO, Declarative, Any-Stage * Senders: Initiator * Scope: SW @@ -2515,10 +2520,11 @@ typedef struct __attribute__((packed)) iscsi_isid { * InitiatorName=iqn.1992-04.de.uni-freiburg.bwlehrpool:qcow2.5003 * InitiatorName=iqn.2001-02.de.uni-freiburg.matrix:basty.eduroam * InitiatorName=naa.52004567BA64678D + * @endverbatim * The initiator of the TCP connection MUST provide this key to the * remote endpoint at the first login of the Login Phase for every * connection. The InitiatorName key enables the initiator to identify - * itself to the remote endpoint. + * itself to the remote endpoint.\n * The InitiatorName MUST NOT be redeclared within the Login Phase. */ #define ISCSI_LOGIN_AUTH_SECURITY_TEXT_KEY_INITIATOR_NAME "InitiatorName" @@ -2526,6 +2532,7 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Key used during SecurityNegotiation stage of Login Phase: Target name. * + * @verbatim * Use: IO by initiator, FFPO by target - only as response to a * SendTargets, Declarative, Any-Stage * Senders: Initiator and target @@ -2535,12 +2542,13 @@ typedef struct __attribute__((packed)) iscsi_isid { * TargetName=iqn.1993-11.de.uni-freiburg:diskarrays.sn.5003 * TargetName=eui.020000023B040506 * TargetName=naa.62004567BA64678D0123456789ABCDEF + * @endverbatim * The initiator of the TCP connection MUST provide this key to the * remote endpoint in the first Login Request if the initiator is not * establishing a Discovery session. The iSCSI Target Name specifies - * the worldwide unique name of the target. + * the worldwide unique name of the target.\n * The TargetName key may also be returned by the SendTargets Text - * Request (which is its only use when issued by a target). + * Request (which is its only use when issued by a target).\n * The TargetName MUST NOT be redeclared within the Login Phase. */ #define ISCSI_LOGIN_AUTH_SECURITY_TEXT_KEY_TARGET_NAME "TargetName" @@ -2548,24 +2556,28 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Key used during SecurityNegotiation stage of Login Phase: Target address. * + * @verbatim * Use: ALL, Declarative, Any-Stage * Senders: Target * Scope: SW * TargetAddress=domainname[:port][,portal-group-tag] + * @endverbatim * The domainname can be specified as either a DNS host name, a dotted- * decimal IPv4 address, or a bracketed IPv6 address as specified in - * RFC3986. + * RFC3986.\n * If the TCP port is not specified, it is assumed to be the IANA- - * assigned default port for iSCSI. + * assigned default port for iSCSI.\n * If the TargetAddress is returned as the result of a redirect status * in a Login Response, the comma and portal-group-tag MUST be omitted. * If the TargetAddress is returned within a SendTargets response, the - * portal-group-tag MUST be included. + * portal-group-tag MUST be included.\n + * @verbatim * Examples: * TargetAddress=10.0.0.1:5003,1 * TargetAddress=[1080:0:0:0:8:800:200C:417A],65 * TargetAddress=[1080::8:800:200C:417A]:5003,1 * TargetAddress=gitlab.uni-freiburg.de,443 + * @endverbatim * The formats for the port and portal-group-tag are the same as the one * specified in TargetPortalGroupTag. */ @@ -2574,6 +2586,7 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Key used during SecurityNegotiation stage of Login Phase: Initiator alias. * + * @verbatim * Use: ALL, Declarative, Any-Stage * Senders: Initiator * Scope: SW @@ -2582,6 +2595,7 @@ typedef struct __attribute__((packed)) iscsi_isid { * InitiatorAlias=Web Server 5 * InitiatorAlias=matrix.uni-freiburg.de * InitiatorAlias=Matrix Server + * @endverbatim * If an initiator has been configured with a human-readable name or * description, it SHOULD be communicated to the target during a Login * Request PDU. If not, the host name can be used instead. This string @@ -2595,6 +2609,7 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Key used during SecurityNegotiation stage of Login Phase: Target alias. * + * @verbatim * Use: ALL, Declarative, Any-Stage * Senders: Target * Scope: SW @@ -2603,6 +2618,7 @@ typedef struct __attribute__((packed)) iscsi_isid { * TargetAlias=Bob-s Disk * TargetAlias=Database Server 1 Log Disk * TargetAlias=Web Server 3 Disk 20 + * @endverbatim * If a target has been configured with a human-readable name or * description, this name SHOULD be communicated to the initiator during * a Login Response PDU if SessionType=Normal. This string is not used @@ -2615,19 +2631,21 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Key used during SecurityNegotiation stage of Login Phase: Target portal group tag. * + * @verbatim * Use: IO by target, Declarative, Any-Stage * Senders: Target * Scope: SW * TargetPortalGroupTag=<16-bit-binary-value> * Example: * TargetPortalGroupTag=1 + * @endverbatim * The TargetPortalGroupTag key is a 16-bit binary-value that uniquely * identifies a portal group within an iSCSI target node. This key * carries the value of the tag of the portal group that is servicing * the Login Request. The iSCSI target returns this key to the * initiator in the Login Response PDU to the first Login Request PDU * that has the C bit set to 0 when TargetName is given by the - * initiator. + * initiator.\n * SAM2 notes in its informative text that the TPGT value should be * non-zero; note that this is incorrect. A zero value is allowed as a * legal value for the TPGT. This discrepancy currently stands @@ -2638,63 +2656,60 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Key used during SecurityNegotiation stage of Login Phase: Authentication method. * - * // Use: During Login - Security Negotiation + * @verbatim + * Use: During Login - Security Negotiation * Senders: Initiator and target * Scope: connection * AuthMethod = <list-of-values> + * @endverbatim * The main item of security negotiation is the authentication method - * (AuthMethod). + * (AuthMethod).\n * The authentication methods that can be used (appear in the list-of- * values) are either vendor-unique methods or those listed in the * following table: - * +--------------------------------------------------------------+ - * | Name | Description | - * +--------------------------------------------------------------+ - * | KRB5 | Kerberos V5 - defined in RFC4120 | - * +--------------------------------------------------------------+ - * | SRP | Secure Remote Password - | - * | | defined in RFC2945 | - * +--------------------------------------------------------------+ - * | CHAP | Challenge Handshake Authentication Protocol - | - * | | defined in RFC1994 | - * +--------------------------------------------------------------+ - * | None | No authentication | - * +--------------------------------------------------------------+ + * Name | Description + * :--- | :--------------------------------------------------------------- + * KRB5 | Kerberos V5 - defined in RFC4120 + * SRP | Secure Remote Password - defined in RFC2945 + * CHAP | Challenge Handshake Authentication Protocol - defined in RFC1994 + * None | No authentication + * * The AuthMethod selection is followed by an "authentication exchange" - * specific to the authentication method selected. + * specific to the authentication method selected.\n * The authentication method proposal may be made by either the * initiator or the target. However, the initiator MUST make the first * step specific to the selected authentication method as soon as it is * selected. It follows that if the target makes the authentication * method proposal, the initiator sends the first key(s) of the exchange - * together with its authentication method selection. + * together with its authentication method selection.\n * The authentication exchange authenticates the initiator to the target * and, optionally, the target to the initiator. Authentication is * OPTIONAL to use but MUST be supported by the target and initiator. * The initiator and target MUST implement CHAP. All other - * authentication methods are OPTIONAL. + * authentication methods are OPTIONAL.\n * Private or public extension algorithms MAY also be negotiated for * authentication methods. Whenever a private or public extension * algorithm is part of the default offer (the offer made in the absence * of explicit administrative action), the implementer MUST ensure that * CHAP is listed as an alternative in the default offer and "None" is - * not part of the default offer. + * not part of the default offer.\n * Extension authentication methods MUST be named using one of the * following two formats: - * 1) Z-reversed.vendor.dns_name.do_something= - * 2) New public key with no name prefix constraints + * -# Z-reversed.vendor.dns_name.do_something= + * -# New public key with no name prefix constraints + * * Authentication methods named using the Z- format are used as private * extensions. New public keys must be registered with IANA using the * IETF Review process RFC5226. New public extensions for - * authentication methods MUST NOT use the Z# name prefix. + * authentication methods MUST NOT use the Z# name prefix.\n * For all of the public or private extension authentication methods, * the method-specific keys MUST conform to the format specified for - * standard-label. + * standard-label.\n * To identify the vendor for private extension authentication methods, * we suggest using the reversed DNS-name as a prefix to the proper - * digest names. + * digest names.\n * The part of digest-name following Z- MUST conform to the format for - * standard-label. + * standard-label.\n * Support for public or private extension authentication methods is * OPTIONAL. */ @@ -2705,22 +2720,26 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Kerberos V5 (KRB5): KRB_AP_REQ. * * For KRB5 (Kerberos V5) (see RFC4120 and RFC1964), the initiator MUST use: + * @verbatim * KRB_AP_REQ=<KRB_AP_REQ> + * @endverbatim * where KRB_AP_REQ is the client message as defined in RFC4120. * The default principal name assumed by an iSCSI initiator or target * (prior to any administrative configuration action) MUST be the iSCSI * Initiator Name or iSCSI Target Name, respectively, prefixed by the - * string "iscsi/". + * string "iscsi/".\n * If the initiator authentication fails, the target MUST respond with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator has selected the mutual authentication option (by setting * MUTUAL-REQUIRED in the ap-options field of the KRB_AP_REQ), the * target MUST reply with: + * @verbatim * KRB_AP_REP=<KRB_AP_REP> + * @endverbatim * where KRB_AP_REP is the server's response message as defined in - * RFC4120. + * RFC4120.\n * If mutual authentication was selected and target authentication - * fails, the initiator MUST close the connection. + * fails, the initiator MUST close the connection.\n * KRB_AP_REQ and KRB_AP_REP are binary-values, and their binary length * (not the length of the character string that represents them in * encoded form) MUST NOT exceed 65536 bytes. Hex or Base64 encoding @@ -2732,22 +2751,26 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Kerberos V5 (KRB5): KRB_AP_REP. * * For KRB5 (Kerberos V5) (see RFC4120 and RFC1964), the initiator MUST use: + * @verbatim * KRB_AP_REQ=<KRB_AP_REQ> + * @endverbatim * where KRB_AP_REQ is the client message as defined in RFC4120. * The default principal name assumed by an iSCSI initiator or target * (prior to any administrative configuration action) MUST be the iSCSI * Initiator Name or iSCSI Target Name, respectively, prefixed by the - * string "iscsi/". + * string "iscsi/".\n * If the initiator authentication fails, the target MUST respond with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator has selected the mutual authentication option (by setting * MUTUAL-REQUIRED in the ap-options field of the KRB_AP_REQ), the * target MUST reply with: + * @verbatim * KRB_AP_REP=<KRB_AP_REP> + * @endverbatim * where KRB_AP_REP is the server's response message as defined in - * RFC4120. + * RFC4120.\n * If mutual authentication was selected and target authentication - * fails, the initiator MUST close the connection. + * fails, the initiator MUST close the connection.\n * KRB_AP_REQ and KRB_AP_REP are binary-values, and their binary length * (not the length of the character string that represents them in * encoded form) MUST NOT exceed 65536 bytes. Hex or Base64 encoding @@ -2760,36 +2783,48 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Secure Remote Password (SRP): SRP_U. * * For SRP RFC2945, the initiator MUST use: + * @verbatim * SRP_U=<U> TargetAuth=Yes or TargetAuth=No + * @endverbatim * The target MUST answer with a Login reject with the "Authorization * Failure" status or reply with: + * @verbatim * SRP_GROUP=<G1,G2...> SRP_s=<s> + * @endverbatim * where G1,G2... are proposed groups, in order of preference. * The initiator MUST either close the connection or continue with: + * @verbatim * SRP_A=<A> * SRP_GROUP=<G> + * @endverbatim * where G is one of G1,G2... that were proposed by the target. * The target MUST answer with a Login reject with the "Authentication * Failure" status or reply with: + * @verbatim * SRP_B=<B> + * @endverbatim * The initiator MUST close the connection or continue with: + * @verbatim * SRP_M=<M> + * @endverbatim * If the initiator authentication fails, the target MUST answer with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator sent TargetAuth=Yes in the first message (requiring target * authentication), the target MUST reply with: + * @verbatim * SRP_HM=<H(A | M | K)> + * @endverbatim * If the target authentication fails, the initiator MUST close the - * connection: + * connection:\n * where U, s, A, B, M, and H(A | M | K) are defined in RFC2945 (using * the SHA1 hash function, such as SRP-SHA1) and * G,Gn ("Gn" stands for G1,G2...) are identifiers of SRP groups - * specified in RFC3723. + * specified in RFC3723.\n * G, Gn, and U are text strings; s,A,B,M, and H(A | M | K) are * binary-values. The length of s,A,B,M and H(A | M | K) in binary form * (not the length of the character string that represents them in * encoded form) MUST NOT exceed 1024 bytes. Hex or Base64 encoding may - * be used for s,A,B,M and H(A | M | K). + * be used for s,A,B,M and H(A | M | K).\n * For the SRP_GROUP, all the groups specified in RFC3723 up to * 1536 bits (i.e. SRP-768, SRP-1024, SRP-1280, SRP-1536) must be * supported by initiators and targets. To guarantee interoperability, @@ -2801,36 +2836,48 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Secure Remote Password (SRP): SRP_GROUP. * * For SRP RFC2945, the initiator MUST use: + * @verbatim * SRP_U=<U> TargetAuth=Yes or TargetAuth=No + * @endverbatim * The target MUST answer with a Login reject with the "Authorization * Failure" status or reply with: + * @verbatim * SRP_GROUP=<G1,G2...> SRP_s=<s> + * @endverbatim * where G1,G2... are proposed groups, in order of preference. * The initiator MUST either close the connection or continue with: + * @verbatim * SRP_A=<A> * SRP_GROUP=<G> + * @endverbatim * where G is one of G1,G2... that were proposed by the target. * The target MUST answer with a Login reject with the "Authentication * Failure" status or reply with: + * @verbatim * SRP_B=<B> + * @endverbatim * The initiator MUST close the connection or continue with: + * @verbatim * SRP_M=<M> + * @endverbatim * If the initiator authentication fails, the target MUST answer with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator sent TargetAuth=Yes in the first message (requiring target * authentication), the target MUST reply with: + * @verbatim * SRP_HM=<H(A | M | K)> + * @endverbatim * If the target authentication fails, the initiator MUST close the - * connection: + * connection:\n * where U, s, A, B, M, and H(A | M | K) are defined in RFC2945 (using * the SHA1 hash function, such as SRP-SHA1) and * G,Gn ("Gn" stands for G1,G2...) are identifiers of SRP groups - * specified in RFC3723. + * specified in RFC3723.\n * G, Gn, and U are text strings; s,A,B,M, and H(A | M | K) are * binary-values. The length of s,A,B,M and H(A | M | K) in binary form * (not the length of the character string that represents them in * encoded form) MUST NOT exceed 1024 bytes. Hex or Base64 encoding may - * be used for s,A,B,M and H(A | M | K). + * be used for s,A,B,M and H(A | M | K).\n * For the SRP_GROUP, all the groups specified in RFC3723 up to * 1536 bits (i.e. SRP-768, SRP-1024, SRP-1280, SRP-1536) must be * supported by initiators and targets. To guarantee interoperability, @@ -2842,36 +2889,48 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Secure Remote Password (SRP): SRP_A. * * For SRP RFC2945, the initiator MUST use: + * @verbatim * SRP_U=<U> TargetAuth=Yes or TargetAuth=No + * @endverbatim * The target MUST answer with a Login reject with the "Authorization * Failure" status or reply with: + * @verbatim * SRP_GROUP=<G1,G2...> SRP_s=<s> + * @endverbatim * where G1,G2... are proposed groups, in order of preference. * The initiator MUST either close the connection or continue with: + * @verbatim * SRP_A=<A> * SRP_GROUP=<G> + * @endverbatim * where G is one of G1,G2... that were proposed by the target. * The target MUST answer with a Login reject with the "Authentication * Failure" status or reply with: + * @verbatim * SRP_B=<B> + * @endverbatim * The initiator MUST close the connection or continue with: + * @verbatim * SRP_M=<M> + * @endverbatim * If the initiator authentication fails, the target MUST answer with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator sent TargetAuth=Yes in the first message (requiring target * authentication), the target MUST reply with: + * @verbatim * SRP_HM=<H(A | M | K)> + * @endverbatim * If the target authentication fails, the initiator MUST close the - * connection: + * connection:\n * where U, s, A, B, M, and H(A | M | K) are defined in RFC2945 (using * the SHA1 hash function, such as SRP-SHA1) and * G,Gn ("Gn" stands for G1,G2...) are identifiers of SRP groups - * specified in RFC3723. + * specified in RFC3723.\n * G, Gn, and U are text strings; s,A,B,M, and H(A | M | K) are * binary-values. The length of s,A,B,M and H(A | M | K) in binary form * (not the length of the character string that represents them in * encoded form) MUST NOT exceed 1024 bytes. Hex or Base64 encoding may - * be used for s,A,B,M and H(A | M | K). + * be used for s,A,B,M and H(A | M | K).\n * For the SRP_GROUP, all the groups specified in RFC3723 up to * 1536 bits (i.e. SRP-768, SRP-1024, SRP-1280, SRP-1536) must be * supported by initiators and targets. To guarantee interoperability, @@ -2883,36 +2942,48 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Secure Remote Password (SRP): SRP_B. * * For SRP RFC2945, the initiator MUST use: + * @verbatim * SRP_U=<U> TargetAuth=Yes or TargetAuth=No + * @endverbatim * The target MUST answer with a Login reject with the "Authorization * Failure" status or reply with: + * @verbatim * SRP_GROUP=<G1,G2...> SRP_s=<s> + * @endverbatim * where G1,G2... are proposed groups, in order of preference. * The initiator MUST either close the connection or continue with: + * @verbatim * SRP_A=<A> * SRP_GROUP=<G> + * @endverbatim * where G is one of G1,G2... that were proposed by the target. * The target MUST answer with a Login reject with the "Authentication * Failure" status or reply with: + * @verbatim * SRP_B=<B> + * @endverbatim * The initiator MUST close the connection or continue with: + * @verbatim * SRP_M=<M> + * @endverbatim * If the initiator authentication fails, the target MUST answer with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator sent TargetAuth=Yes in the first message (requiring target * authentication), the target MUST reply with: + * @verbatim * SRP_HM=<H(A | M | K)> + * @endverbatim * If the target authentication fails, the initiator MUST close the - * connection: + * connection:\n * where U, s, A, B, M, and H(A | M | K) are defined in RFC2945 (using * the SHA1 hash function, such as SRP-SHA1) and * G,Gn ("Gn" stands for G1,G2...) are identifiers of SRP groups - * specified in RFC3723. + * specified in RFC3723.\n * G, Gn, and U are text strings; s,A,B,M, and H(A | M | K) are * binary-values. The length of s,A,B,M and H(A | M | K) in binary form * (not the length of the character string that represents them in * encoded form) MUST NOT exceed 1024 bytes. Hex or Base64 encoding may - * be used for s,A,B,M and H(A | M | K). + * be used for s,A,B,M and H(A | M | K).\n * For the SRP_GROUP, all the groups specified in RFC3723 up to * 1536 bits (i.e. SRP-768, SRP-1024, SRP-1280, SRP-1536) must be * supported by initiators and targets. To guarantee interoperability, @@ -2924,36 +2995,48 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Secure Remote Password (SRP): SRP_M. * * For SRP RFC2945, the initiator MUST use: + * @verbatim * SRP_U=<U> TargetAuth=Yes or TargetAuth=No + * @endverbatim * The target MUST answer with a Login reject with the "Authorization * Failure" status or reply with: + * @verbatim * SRP_GROUP=<G1,G2...> SRP_s=<s> + * @endverbatim * where G1,G2... are proposed groups, in order of preference. * The initiator MUST either close the connection or continue with: + * @verbatim * SRP_A=<A> * SRP_GROUP=<G> + * @endverbatim * where G is one of G1,G2... that were proposed by the target. * The target MUST answer with a Login reject with the "Authentication * Failure" status or reply with: + * @verbatim * SRP_B=<B> + * @endverbatim * The initiator MUST close the connection or continue with: + * @verbatim * SRP_M=<M> + * @endverbatim * If the initiator authentication fails, the target MUST answer with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator sent TargetAuth=Yes in the first message (requiring target * authentication), the target MUST reply with: + * @verbatim * SRP_HM=<H(A | M | K)> + * @endverbatim * If the target authentication fails, the initiator MUST close the - * connection: + * connection:\n * where U, s, A, B, M, and H(A | M | K) are defined in RFC2945 (using * the SHA1 hash function, such as SRP-SHA1) and * G,Gn ("Gn" stands for G1,G2...) are identifiers of SRP groups - * specified in RFC3723. + * specified in RFC3723.\n * G, Gn, and U are text strings; s,A,B,M, and H(A | M | K) are * binary-values. The length of s,A,B,M and H(A | M | K) in binary form * (not the length of the character string that represents them in * encoded form) MUST NOT exceed 1024 bytes. Hex or Base64 encoding may - * be used for s,A,B,M and H(A | M | K). + * be used for s,A,B,M and H(A | M | K).\n * For the SRP_GROUP, all the groups specified in RFC3723 up to * 1536 bits (i.e. SRP-768, SRP-1024, SRP-1280, SRP-1536) must be * supported by initiators and targets. To guarantee interoperability, @@ -2965,36 +3048,48 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Secure Remote Password (SRP): SRP_HM. * * For SRP RFC2945, the initiator MUST use: + * @verbatim * SRP_U=<U> TargetAuth=Yes or TargetAuth=No + * @endverbatim * The target MUST answer with a Login reject with the "Authorization * Failure" status or reply with: + * @verbatim * SRP_GROUP=<G1,G2...> SRP_s=<s> + * @endverbatim * where G1,G2... are proposed groups, in order of preference. * The initiator MUST either close the connection or continue with: + * @verbatim * SRP_A=<A> * SRP_GROUP=<G> + * @endverbatim * where G is one of G1,G2... that were proposed by the target. * The target MUST answer with a Login reject with the "Authentication * Failure" status or reply with: + * @verbatim * SRP_B=<B> + * @endverbatim * The initiator MUST close the connection or continue with: + * @verbatim * SRP_M=<M> + * @endverbatim * If the initiator authentication fails, the target MUST answer with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator sent TargetAuth=Yes in the first message (requiring target * authentication), the target MUST reply with: + * @verbatim * SRP_HM=<H(A | M | K)> + * @endverbatim * If the target authentication fails, the initiator MUST close the - * connection: + * connection:\n * where U, s, A, B, M, and H(A | M | K) are defined in RFC2945 (using * the SHA1 hash function, such as SRP-SHA1) and * G,Gn ("Gn" stands for G1,G2...) are identifiers of SRP groups - * specified in RFC3723. + * specified in RFC3723.\n * G, Gn, and U are text strings; s,A,B,M, and H(A | M | K) are * binary-values. The length of s,A,B,M and H(A | M | K) in binary form * (not the length of the character string that represents them in * encoded form) MUST NOT exceed 1024 bytes. Hex or Base64 encoding may - * be used for s,A,B,M and H(A | M | K). + * be used for s,A,B,M and H(A | M | K).\n * For the SRP_GROUP, all the groups specified in RFC3723 up to * 1536 bits (i.e. SRP-768, SRP-1024, SRP-1280, SRP-1536) must be * supported by initiators and targets. To guarantee interoperability, @@ -3007,41 +3102,53 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Challenge Handshake Authentication Protocol (CHAP): CHAP_A. * * For CHAP RFC1994, the initiator MUST use: + * @verbatim * CHAP_A=<A1,A2...> + * @endverbatim * where A1,A2... are proposed algorithms, in order of preference. * The target MUST answer with a Login reject with the "Authentication * Failure" status or reply with: + * @verbatim * CHAP_A=<A> * CHAP_I=<I> * CHAP_C=<C> + * @endverbatim * where A is one of A1,A2... that were proposed by the initiator. * The initiator MUST continue with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> + * @endverbatim * or, if it requires target authentication, with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> * CHAP_I=<I> * CHAP_C=<C> + * @endverbatim * If the initiator authentication fails, the target MUST answer with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator required target authentication, the target MUST either * answer with a Login reject with "Authentication Failure" or reply * with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> + * @endverbatim * If the target authentication fails, the initiator MUST close the - * connection: + * connection:\n * where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, * Algorithm, Identifier, Challenge, and Response as defined in - * RFC1994. + * RFC1994.\n * N is a text string; A,A1,A2, and I are numbers; C and R are * binary-values. Their binary length (not the length of the character * string that represents them in encoded form) MUST NOT exceed - * 1024 bytes. Hex or Base64 encoding may be used for C and R. + * 1024 bytes. Hex or Base64 encoding may be used for C and R.\n * For the Algorithm, as stated in [RFC1994], one value is required to * be implemented: + * @verbatim * 5 (CHAP with MD5) + * @endverbatim * To guarantee interoperability, initiators MUST always offer it as one * of the proposed algorithms. */ @@ -3051,41 +3158,53 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Challenge Handshake Authentication Protocol (CHAP): CHAP_I. * * For CHAP RFC1994, the initiator MUST use: + * @verbatim * CHAP_A=<A1,A2...> + * @endverbatim * where A1,A2... are proposed algorithms, in order of preference. * The target MUST answer with a Login reject with the "Authentication * Failure" status or reply with: + * @verbatim * CHAP_A=<A> * CHAP_I=<I> * CHAP_C=<C> + * @endverbatim * where A is one of A1,A2... that were proposed by the initiator. * The initiator MUST continue with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> + * @endverbatim * or, if it requires target authentication, with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> * CHAP_I=<I> * CHAP_C=<C> + * @endverbatim * If the initiator authentication fails, the target MUST answer with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator required target authentication, the target MUST either * answer with a Login reject with "Authentication Failure" or reply * with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> + * @endverbatim * If the target authentication fails, the initiator MUST close the - * connection: + * connection:\n * where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, * Algorithm, Identifier, Challenge, and Response as defined in - * RFC1994. + * RFC1994.\n * N is a text string; A,A1,A2, and I are numbers; C and R are * binary-values. Their binary length (not the length of the character * string that represents them in encoded form) MUST NOT exceed - * 1024 bytes. Hex or Base64 encoding may be used for C and R. + * 1024 bytes. Hex or Base64 encoding may be used for C and R.\n * For the Algorithm, as stated in [RFC1994], one value is required to * be implemented: + * @verbatim * 5 (CHAP with MD5) + * @endverbatim * To guarantee interoperability, initiators MUST always offer it as one * of the proposed algorithms. */ @@ -3095,41 +3214,53 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Challenge Handshake Authentication Protocol (CHAP): CHAP_C. * * For CHAP RFC1994, the initiator MUST use: + * @verbatim * CHAP_A=<A1,A2...> + * @endverbatim * where A1,A2... are proposed algorithms, in order of preference. * The target MUST answer with a Login reject with the "Authentication * Failure" status or reply with: + * @verbatim * CHAP_A=<A> * CHAP_I=<I> * CHAP_C=<C> + * @endverbatim * where A is one of A1,A2... that were proposed by the initiator. * The initiator MUST continue with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> + * @endverbatim * or, if it requires target authentication, with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> * CHAP_I=<I> * CHAP_C=<C> + * @endverbatim * If the initiator authentication fails, the target MUST answer with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator required target authentication, the target MUST either * answer with a Login reject with "Authentication Failure" or reply * with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> + * @endverbatim * If the target authentication fails, the initiator MUST close the - * connection: + * connection:\n * where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, * Algorithm, Identifier, Challenge, and Response as defined in - * RFC1994. + * RFC1994.\n * N is a text string; A,A1,A2, and I are numbers; C and R are * binary-values. Their binary length (not the length of the character * string that represents them in encoded form) MUST NOT exceed - * 1024 bytes. Hex or Base64 encoding may be used for C and R. + * 1024 bytes. Hex or Base64 encoding may be used for C and R.\n * For the Algorithm, as stated in [RFC1994], one value is required to * be implemented: + * @verbatim * 5 (CHAP with MD5) + * @endverbatim * To guarantee interoperability, initiators MUST always offer it as one * of the proposed algorithms. */ @@ -3139,41 +3270,53 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Challenge Handshake Authentication Protocol (CHAP): CHAP_N. * * For CHAP RFC1994, the initiator MUST use: + * @verbatim * CHAP_A=<A1,A2...> + * @endverbatim * where A1,A2... are proposed algorithms, in order of preference. * The target MUST answer with a Login reject with the "Authentication * Failure" status or reply with: + * @verbatim * CHAP_A=<A> * CHAP_I=<I> * CHAP_C=<C> + * @endverbatim * where A is one of A1,A2... that were proposed by the initiator. * The initiator MUST continue with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> + * @endverbatim * or, if it requires target authentication, with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> * CHAP_I=<I> * CHAP_C=<C> + * @endverbatim * If the initiator authentication fails, the target MUST answer with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator required target authentication, the target MUST either * answer with a Login reject with "Authentication Failure" or reply * with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> + * @endverbatim * If the target authentication fails, the initiator MUST close the - * connection: + * connection:\n * where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, * Algorithm, Identifier, Challenge, and Response as defined in - * RFC1994. + * RFC1994.\n * N is a text string; A,A1,A2, and I are numbers; C and R are * binary-values. Their binary length (not the length of the character * string that represents them in encoded form) MUST NOT exceed - * 1024 bytes. Hex or Base64 encoding may be used for C and R. + * 1024 bytes. Hex or Base64 encoding may be used for C and R.\n * For the Algorithm, as stated in [RFC1994], one value is required to * be implemented: + * @verbatim * 5 (CHAP with MD5) + * @endverbatim * To guarantee interoperability, initiators MUST always offer it as one * of the proposed algorithms. */ @@ -3183,41 +3326,53 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Key used during SecurityNegotiation stage of Login Phase: Challenge Handshake Authentication Protocol (CHAP): CHAP_R. * * For CHAP RFC1994, the initiator MUST use: + * @verbatim * CHAP_A=<A1,A2...> + * @endverbatim * where A1,A2... are proposed algorithms, in order of preference. * The target MUST answer with a Login reject with the "Authentication * Failure" status or reply with: + * @verbatim * CHAP_A=<A> * CHAP_I=<I> * CHAP_C=<C> + * @endverbatim * where A is one of A1,A2... that were proposed by the initiator. * The initiator MUST continue with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> + * @endverbatim * or, if it requires target authentication, with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> * CHAP_I=<I> * CHAP_C=<C> + * @endverbatim * If the initiator authentication fails, the target MUST answer with a * Login reject with "Authentication Failure" status. Otherwise, if the * initiator required target authentication, the target MUST either * answer with a Login reject with "Authentication Failure" or reply * with: + * @verbatim * CHAP_N=<N> * CHAP_R=<R> + * @endverbatim * If the target authentication fails, the initiator MUST close the - * connection: + * connection:\n * where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, * Algorithm, Identifier, Challenge, and Response as defined in - * RFC1994. + * RFC1994.\n * N is a text string; A,A1,A2, and I are numbers; C and R are * binary-values. Their binary length (not the length of the character * string that represents them in encoded form) MUST NOT exceed - * 1024 bytes. Hex or Base64 encoding may be used for C and R. + * 1024 bytes. Hex or Base64 encoding may be used for C and R.\n * For the Algorithm, as stated in [RFC1994], one value is required to * be implemented: + * @verbatim * 5 (CHAP with MD5) + * @endverbatim * To guarantee interoperability, initiators MUST always offer it as one * of the proposed algorithms. */ @@ -3262,34 +3417,34 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Header digest. * + * @verbatim * Use: IO * Senders: Initiator and target * Scope: CO * HeaderDigest = <list-of-values> * Default is None for HeaderDigest. + * @endverbatim * Digests enable the checking of end-to-end, non-cryptographic data * integrity beyond the integrity checks provided by the link layers and * the covering of the whole communication path, including all elements * that may change the network-level PDUs, such as routers, switches, - * and proxies. + * and proxies.\n * The following table lists cyclic integrity checksums that can be * negotiated for the digests and MUST be implemented by every iSCSI * initiator and target. These digest options only have error detection * significance. - * +---------------------------------------------+ - * | Name | Description | Generator | - * +---------------------------------------------+ - * | CRC32C | 32-bit CRC |0x11EDC6F41| - * +---------------------------------------------+ - * | None | no digest | - * +---------------------------------------------+ + * Name | Description | Generator + * :----- | :---------- | :---------- + * CRC32C | 32-bit CRC | 0x11EDC6F41 + * None | no digest || + * * The generator polynomial G(x) for this digest is given in hexadecimal * notation (e.g. "0x3b" stands for 0011 1011, and the polynomial is - * x**5 + x**4 + x**3 + x + 1). + * x**5 + x**4 + x**3 + x + 1).\n * When the initiator and target agree on a digest, this digest MUST be - * used for every PDU in the Full Feature Phase. + * used for every PDU in the Full Feature Phase.\n * Padding bytes, when present in a segment covered by a CRC, SHOULD be - * set to 0 and are included in the CRC. + * set to 0 and are included in the CRC.\n * The CRC MUST be calculated by a method that produces the same results * as the following process: * - The PDU bits are considered as the coefficients of a polynomial @@ -3315,26 +3470,28 @@ typedef struct __attribute__((packed)) iscsi_isid { * get the value 0x1c2d19ed as its final remainder (R(x)). This value * is given here in its polynomial form (i.e., not mapped as the * digest word). - * For a discussion about selection criteria for the CRC, see RFC3385. - * For a detailed analysis of the iSCSI polynomial, see Castagnoli93. + * + * For a discussion about selection criteria for the CRC, see RFC3385.\n + * For a detailed analysis of the iSCSI polynomial, see Castagnoli93.\n * Private or public extension algorithms MAY also be negotiated for * digests. Whenever a private or public digest extension algorithm is * part of the default offer (the offer made in the absence of explicit * administrative action), the implementer MUST ensure that CRC32C is * listed as an alternative in the default offer and "None" is not part - * of the default offer. + * of the default offer.\n * Extension digest algorithms MUST be named using one of the following * two formats: - * 1) Y-reversed.vendor.dns_name.do_something= - * 2) New public key with no name prefix constraints + * 1. Y-reversed.vendor.dns_name.do_something= + * 2. New public key with no name prefix constraints + * * Digests named using the Y- format are used for private purposes * (unregistered). New public keys must be registered with IANA using * the IETF Review process (RFC5226). New public extensions for - * digests MUST NOT use the Y# name prefix. + * digests MUST NOT use the Y# name prefix.\n * For private extension digests, to identify the vendor we suggest - * using the reversed DNS-name as a prefix to the proper digest names. + * using the reversed DNS-name as a prefix to the proper digest names.\n * The part of digest-name following Y- MUST conform to the format for - * standard-label specified. + * standard-label specified.\n * Support for public or private extension digests is OPTIONAL. */ #define ISCSI_LOGIN_AUTH_SESSION_TEXT_KEY_HEADER_DIGEST "HeaderDigest" @@ -3342,34 +3499,34 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Data digest. * + * @verbatim * Use: IO * Senders: Initiator and target * Scope: CO * DataDigest = <list-of-values> * Default is None for DataDigest. + * @endverbatim * Digests enable the checking of end-to-end, non-cryptographic data * integrity beyond the integrity checks provided by the link layers and * the covering of the whole communication path, including all elements * that may change the network-level PDUs, such as routers, switches, - * and proxies. + * and proxies.\n * The following table lists cyclic integrity checksums that can be * negotiated for the digests and MUST be implemented by every iSCSI * initiator and target. These digest options only have error detection * significance. - * +---------------------------------------------+ - * | Name | Description | Generator | - * +---------------------------------------------+ - * | CRC32C | 32-bit CRC |0x11EDC6F41| - * +---------------------------------------------+ - * | None | no digest | - * +---------------------------------------------+ + * Name | Description | Generator + * :----- | :---------- | :---------- + * CRC32C | 32-bit CRC | 0x11EDC6F41 + * None | no digest || + * * The generator polynomial G(x) for this digest is given in hexadecimal * notation (e.g. "0x3b" stands for 0011 1011, and the polynomial is - * x**5 + x**4 + x**3 + x + 1). + * x**5 + x**4 + x**3 + x + 1).\n * When the initiator and target agree on a digest, this digest MUST be - * used for every PDU in the Full Feature Phase. + * used for every PDU in the Full Feature Phase.\n * Padding bytes, when present in a segment covered by a CRC, SHOULD be - * set to 0 and are included in the CRC. + * set to 0 and are included in the CRC.\n * The CRC MUST be calculated by a method that produces the same results * as the following process: * - The PDU bits are considered as the coefficients of a polynomial @@ -3395,26 +3552,28 @@ typedef struct __attribute__((packed)) iscsi_isid { * get the value 0x1c2d19ed as its final remainder (R(x)). This value * is given here in its polynomial form (i.e., not mapped as the * digest word). - * For a discussion about selection criteria for the CRC, see RFC3385. - * For a detailed analysis of the iSCSI polynomial, see Castagnoli93. + * + * For a discussion about selection criteria for the CRC, see RFC3385.\n + * For a detailed analysis of the iSCSI polynomial, see Castagnoli93.\n * Private or public extension algorithms MAY also be negotiated for * digests. Whenever a private or public digest extension algorithm is * part of the default offer (the offer made in the absence of explicit * administrative action), the implementer MUST ensure that CRC32C is * listed as an alternative in the default offer and "None" is not part - * of the default offer. + * of the default offer.\n * Extension digest algorithms MUST be named using one of the following * two formats: - * 1) Y-reversed.vendor.dns_name.do_something= - * 2) New public key with no name prefix constraints + * 1. Y-reversed.vendor.dns_name.do_something= + * 2. New public key with no name prefix constraints + * * Digests named using the Y- format are used for private purposes * (unregistered). New public keys must be registered with IANA using * the IETF Review process (RFC5226). New public extensions for - * digests MUST NOT use the Y# name prefix. + * digests MUST NOT use the Y# name prefix.\n * For private extension digests, to identify the vendor we suggest - * using the reversed DNS-name as a prefix to the proper digest names. + * using the reversed DNS-name as a prefix to the proper digest names.\n * The part of digest-name following Y- MUST conform to the format for - * standard-label specified. + * standard-label specified.\n * Support for public or private extension digests is OPTIONAL. */ #define ISCSI_LOGIN_AUTH_SESSION_TEXT_KEY_DATA_DIGEST "DataDigest" @@ -3422,13 +3581,15 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: New connections. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW * Irrelevant when: SessionType=Discovery * MaxConnections=<numerical-value-from-1-to-65535> * Default is 1. - * Result function is Minimum. + * @endverbatim + * Result function is Minimum.\n * The initiator and target negotiate the maximum number of connections * requested/acceptable. */ @@ -3437,40 +3598,43 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Send targets. * + * @verbatim * Use: FFPO * Senders: Initiator * Scope: SW - * The text in this appendix is a normative part of this document. + * @endverbatim + * The text in this appendix is a normative part of this document.\n * To reduce the amount of configuration required on an initiator, iSCSI * provides the SendTargets Text Request. The initiator uses the * SendTargets request to get a list of targets to which it may have * access, as well as the list of addresses (IP address and TCP port) on - * which these targets may be accessed. + * which these targets may be accessed.\n * To make use of SendTargets, an initiator must first establish one of * two types of sessions. If the initiator establishes the session * using the key "SessionType=Discovery", the session is a Discovery * session, and a target name does not need to be specified. Otherwise, * the session is a Normal operational session. The SendTargets command * MUST only be sent during the Full Feature Phase of a Normal or - * Discovery session. + * Discovery session.\n * A system that contains targets MUST support Discovery sessions on * each of its iSCSI IP address-port pairs and MUST support the * SendTargets command on the Discovery session. In a Discovery * session, a target MUST return all path information (IP address-port * pairs and Target Portal Group Tags) for the targets on the target - * Network Entity that the requesting initiator is authorized to access. + * Network Entity that the requesting initiator is authorized to access.\n * A target MUST support the SendTargets command on operational * sessions; these will only return path information about the target to * which the session is connected and do not need to return information * about other target names that may be defined in the responding - * system. - * An initiator MAY make use of the SendTargets command as it sees fit. + * system.\n + * An initiator MAY make use of the SendTargets command as it sees fit.\n * A SendTargets command consists of a single Text Request PDU. This * PDU contains exactly one text key and value. The text key MUST be * SendTargets. The expected response depends upon the value, as well * as whether the session is a Discovery session or an operational - * session. + * session.\n * The value must be one of: + * @verbatim * All * The initiator is requesting that information on all relevant * targets known to the implementation be returned. This value @@ -3488,6 +3652,7 @@ typedef struct __attribute__((packed)) iscsi_isid { * to which the session is logged in. This MUST be supported on * operational sessions and MUST NOT return targets other than the * one to which the session is logged in. + * @endverbatim * The response to this command is a Text Response that contains a list * of zero or more targets and, optionally, their addresses. Each * target is returned as a target record. A target record begins with @@ -3495,63 +3660,72 @@ typedef struct __attribute__((packed)) iscsi_isid { * keys, and bounded by the end of the Text Response or the next * TargetName key, which begins a new record. No text keys other than * TargetName and TargetAddress are permitted within a SendTargets - * response. + * response.\n * A Discovery session MAY respond to a SendTargets request with its * complete list of targets, or with a list of targets that is based on - * the name of the initiator logged in to the session. + * the name of the initiator logged in to the session.\n * A SendTargets response MUST NOT contain target names if there are no - * targets for the requesting initiator to access. + * targets for the requesting initiator to access.\n * Each target record returned includes zero or more TargetAddress - * fields. + * fields.\n * Each target record starts with one text key of the form: + * @verbatim * TargetName=<target-name-goes-here> + * @endverbatim * followed by zero or more address keys of the form: + * @verbatim * TargetAddress=<hostname-or-ipaddress>[:<tcp-port>], * <portal-group-tag> + * @endverbatim * The hostname-or-ipaddress contains a domain name, IPv4 address, or - * IPv6 address (RFC4291), as specified for the TargetAddress key. + * IPv6 address (RFC4291), as specified for the TargetAddress key.\n * A hostname-or-ipaddress duplicated in TargetAddress responses for a * given node (the port is absent or equal) would probably indicate that - * multiple address families are in use at once (IPv6 and IPv4). + * multiple address families are in use at once (IPv6 and IPv4).\n * Each TargetAddress belongs to a portal group, identified by its - * numeric Target Portal Group Tag. The iSCSI Target - * Name, together with this tag, constitutes the SCSI port identifier; - * the tag only needs to be unique within a given target's name list of - * addresses. + * numeric Target Portal Group Tag. The iSCSI Target Name, together with + * this tag, constitutes the SCSI port identifier; the tag only needs to + * be unique within a given target's name list of addresses.\n * Multiple-connection sessions can span iSCSI addresses that belong to - * the same portal group. + * the same portal group.\n * Multiple-connection sessions cannot span iSCSI addresses that belong - * to different portal groups. + * to different portal groups.\n * If a SendTargets response reports an iSCSI address for a target, it * SHOULD also report all other addresses in its portal group in the - * same response. + * same response.\n * A SendTargets Text Response can be longer than a single Text Response - * PDU and makes use of the long Text Responses as specified. + * PDU and makes use of the long Text Responses as specified.\n * After obtaining a list of targets from the Discovery session, an * iSCSI initiator may initiate new sessions to log in to the discovered * targets for full operation. The initiator MAY keep the Discovery * session open and MAY send subsequent SendTargets commands to discover - * new targets. - * Examples: + * new targets.\n + * Examples:\n * This example is the SendTargets response from a single target that - * has no other interface ports. + * has no other interface ports.\n * The initiator sends a Text Request that contains: + * @verbatim * SendTargets=All + * @endverbatim * The target sends a Text Response that contains: + * @verbatim * TargetName=iqn.1993-11.de.uni-freiburg:diskarray.sn.8675309 - * All the target had to return in this simple case was the target name. + * @endverbatim + * All the target had to return in this simple case was the target name.\n * It is assumed by the initiator that the IP address and TCP port for * this target are the same as those used on the current connection to - * the default iSCSI target. + * the default iSCSI target.\n * The next example has two internal iSCSI targets, each accessible via * two different ports with different IP addresses. The following is * the Text Response: + * @verbatim * TargetName=iqn.1993-11.de.uni-freiburg:diskarray.sn.8675309 * TargetAddress=10.1.0.45:5300,1 * TargetAddress=10.1.1.45:5300,2 * TargetName=iqn.1993-11.de.uni-freiburg:diskarray.sn.1234567 * TargetAddress=10.1.0.45:5300,1 * TargetAddress=10.1.1.45:5300,2 + * @endverbatim * Both targets share both addresses; the multiple addresses are likely * used to provide multi-path support. The initiator may connect to * either target name on either address. Each of the addresses has its @@ -3559,24 +3733,26 @@ typedef struct __attribute__((packed)) iscsi_isid { * connection sessions with each other. Keep in mind that the Target * Portal Group Tags for the two named targets are independent of one * another; portal group "1" on the first target is not necessarily the - * same as portal group "1" on the second target. + * same as portal group "1" on the second target.\n * In the above example, a DNS host name or an IPv6 address could have - * been returned instead of an IPv4 address. + * been returned instead of an IPv4 address.\n * The next Text Response shows a target that supports spanning sessions * across multiple addresses and further illustrates the use of the * Target Portal Group Tags: + * @verbatim * TargetName=iqn.1993-11.de.uni-freiburg:diskarray.sn.8675309 * TargetAddress=10.1.0.45:5300,1 * TargetAddress=10.1.1.46:5300,1 * TargetAddress=10.1.0.47:5300,2 * TargetAddress=10.1.1.48:5300,2 * TargetAddress=10.1.1.49:5300,3 + * @endverbatim * In this example, any of the target addresses can be used to reach the * same target. A single-connection session can be established to any * of these TCP addresses. A multiple-connection session could span * addresses .45 and .46 or .47 and .48 but cannot span any other * combination. A TargetAddress with its own tag (.49) cannot be - * combined with any other address within the same session. + * combined with any other address within the same session.\n * This SendTargets response does not indicate whether .49 supports * multiple connections per session; it is communicated via the * MaxConnections text key upon login to the target. @@ -3586,6 +3762,7 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Initial Ready To Transfer. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW @@ -3595,14 +3772,15 @@ typedef struct __attribute__((packed)) iscsi_isid { * I->InitialR2T=No * T->InitialR2T=No * Default is Yes. - * Result function is OR. + * @endverbatim + * Result function is OR.\n * The InitialR2T key is used to turn off the default use of R2T for * unidirectional operations and the output part of bidirectional * commands, thus allowing an initiator to start sending data to a * target as if it has received an initial R2T with Buffer * Offset=Immediate Data Length and Desired Data Transfer * Length=(min(FirstBurstLength, Expected Data Transfer Length) - - * Received Immediate Data Length). + * Received Immediate Data Length).\n * The default action is that R2T is required, unless both the initiator * and the target send this key-pair attribute specifying InitialR2T=No. * Only the first outgoing data burst (immediate data and/or separate @@ -3613,57 +3791,55 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Immediate data. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW * Irrelevant when: SessionType=Discovery * ImmediateData=<boolean-value> * Default is Yes. - * Result function is AND. + * @endverbatim + * Result function is AND.\n * The initiator and target negotiate support for immediate dataTo * turn immediate data off, the initiator or target must state its * desire to do soImmediateData can be turned on if both the - * initiator and target have ImmediateData=Yes. + * initiator and target have ImmediateData=Yes.\n * If ImmediateData is set to Yes and InitialR2T is set to Yes * (default), then only immediate data are accepted in the first burst. * If ImmediateData is set to No and InitialR2T is set to Yes, then the * initiator MUST NOT send unsolicited data and the target MUST reject - * unsolicited data with the corresponding response code. + * unsolicited data with the corresponding response code.\n * If ImmediateData is set to No and InitialR2T is set to No, then the * initiator MUST NOT send unsolicited immediate data but MAY send one - * unsolicited burst of Data-OUT PDUs. + * unsolicited burst of Data-OUT PDUs.\n * If ImmediateData is set to Yes and InitialR2T is set to No, then the * initiator MAY send unsolicited immediate data and/or one unsolicited - * burst of Data-OUT PDUs. + * burst of Data-OUT PDUs.\n * The following table is a summary of unsolicited data options: - * +----------+-------------+------------------+-------------+ - * |InitialR2T|ImmediateData| Unsolicited |ImmediateData| - * | | | Data-Out PDUs | | - * +----------+-------------+------------------+-------------+ - * | No | No | Yes | No | - * +----------+-------------+------------------+-------------+ - * | No | Yes | Yes | Yes | - * +----------+-------------+------------------+-------------+ - * | Yes | No | No | No | - * +----------+-------------+------------------+-------------+ - * | Yes | Yes | No | Yes | - * +----------+-------------+------------------+-------------+ + * InitialR2T | ImmediateData | Unsolicited Data-Out PDUs | ImmediateData + * :--------- | :------------ | :------------------------ | :------------ + * | No | No | Yes | No | + * | No | Yes | Yes | Yes | + * | Yes | No | No | No | + * | Yes | Yes | No | Yes | */ #define ISCSI_LOGIN_AUTH_SESSION_TEXT_KEY_IMMEDIATE_DATA "ImmediateData" /** * @brief Login/Text Operational Session Text Key: Maximum receive DataSegmentLength. * + * @verbatim * Use: ALL, Declarative * Senders: Initiator and target * Scope: CO * MaxRecvDataSegmentLength=<numerical-value-512-to-(2**24 - 1)> * Default is 8192 bytes. + * @endverbatim * The initiator or target declares the maximum data segment length in - * bytes it can receive in an iSCSI PDU. + * bytes it can receive in an iSCSI PDU.\n * The transmitter (initiator or target) is required to send PDUs with a * data segment that does not exceed MaxRecvDataSegmentLength of the - * receiver. + * receiver.\n * A target receiver is additionally limited by MaxBurstLength for * solicited data and FirstBurstLength for unsolicited dataAn * initiator MUST NOT send solicited PDUs exceeding MaxBurstLength nor @@ -3675,13 +3851,15 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Maximum burst length. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW * Irrelevant when: SessionType=Discovery * MaxBurstLength=<numerical-value-512-to-(2**24 - 1)> * Default is 262144 (256 KB). - * Result function is Minimum. + * @endverbatim + * Result function is Minimum.\n * The initiator and target negotiate the maximum SCSI data payload in * bytes in a Data-In or a solicited Data-Out iSCSI sequence. A * sequence consists of one or more consecutive Data-In or Data-Out PDUs @@ -3692,6 +3870,7 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: First burst length. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW @@ -3699,12 +3878,13 @@ typedef struct __attribute__((packed)) iscsi_isid { * Irrelevant when: ( InitialR2T=Yes and ImmediateData=No ) * FirstBurstLength=<numerical-value-512-to-(2**24 - 1)> * Default is 65536 (64 KB). - * Result function is Minimum. + * @endverbatim + * Result function is Minimum.\n * The initiator and target negotiate the maximum amount in bytes of * unsolicited data an iSCSI initiator may send to the target during the * execution of a single SCSI command. This covers the immediate data * (if any) and the sequence of unsolicited Data-Out PDUs (if any) that - * follow the command. + * follow the command.\n * FirstBurstLength MUST NOT exceed MaxBurstLength. */ #define ISCSI_LOGIN_AUTH_SESSION_TEXT_KEY_FIRST_BURST_LEN "FirstBurstLength" @@ -3712,16 +3892,18 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Default time to wait. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW * DefaultTime2Wait=<numerical-value-0-to-3600> * Default is 2. - * Result function is Maximum. + * @endverbatim + * Result function is Maximum.\n * The initiator and target negotiate the minimum time, in seconds, to * wait before attempting an explicit/implicit logout or an active task * reassignment after an unexpected connection termination or a - * connection reset. + * connection reset.\n * A value of 0 indicates that logout or active task reassignment can be * attempted immediately. */ @@ -3730,18 +3912,20 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Default time to retain. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW * DefaultTime2Retain=<numerical-value-0-to-3600> * Default is 20. - * Result function is Minimum. + * @endverbatim + * Result function is Minimum.\n * The initiator and target negotiate the maximum time, in seconds, * after an initial wait (Time2Wait), before which an active task * reassignment is still possible after an unexpected connection - * termination or a connection reset. + * termination or a connection reset.\n * This value is also the session state timeout if the connection in - * question is the last LOGGED_IN connection in the session. + * question is the last LOGGED_IN connection in the session.\n * A value of 0 indicates that connection/task state is immediately * discarded by the target. */ @@ -3750,13 +3934,15 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Maximum outstanding Ready To Transfer. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW * MaxOutstandingR2T=<numerical-value-from-1-to-65535> * Irrelevant when: SessionType=Discovery * Default is 1. - * Result function is Minimum. + * @endverbatim + * Result function is Minimum.\n * The initiator and target negotiate the maximum number of outstanding * R2Ts per task, excluding any implied initial R2T that might be part * of that task. An R2T is considered outstanding until the last data @@ -3768,13 +3954,15 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Data Protocol Data Unit (PDU) in order. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW * Irrelevant when: SessionType=Discovery * DataPDUInOrder=<boolean-value> * Default is Yes. - * Result function is OR. + * @endverbatim + * Result function is OR.\n * "No" is used by iSCSI to indicate that the data PDUs within sequences * can be in any order. "Yes" is used to indicate that data PDUs within * sequences have to be at continuously increasing addresses and @@ -3785,23 +3973,25 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Data sequence in order. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW * Irrelevant when: SessionType=Discovery * DataSequenceInOrder=<boolean-value> * Default is Yes. - * Result function is OR. + * @endverbatim + * Result function is OR.\n * A data sequence is a sequence of Data-In or Data-Out PDUs that end * with a Data-In or Data-Out PDU with the F bit set to 1. A Data-Out - * sequence is sent either unsolicited or in response to an R2T. - * Sequences cover an offset-range. + * sequence is sent either unsolicited or in response to an R2T.\n + * Sequences cover an offset-range.\n * If DataSequenceInOrder is set to No, data PDU sequences may be - * transferred in any order. + * transferred in any order.\n * If DataSequenceInOrder is set to Yes, data sequences MUST be * transferred using continuously non-decreasing sequence offsets (R2T * buffer offset for writes, or the smallest SCSI Data-In buffer offset - * within a read data sequence). + * within a read data sequence).\n * If DataSequenceInOrder is set to Yes, a target may retry at most the * last R2T, and an initiator may at most request retransmission for the * last read data sequence. For this reason, if ErrorRecoveryLevel is @@ -3813,16 +4003,18 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Error recovery level. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW * ErrorRecoveryLevel=<numerical-value-0-to-2> * Default is 0. - * Result function is Minimum. + * @endverbatim + * Result function is Minimum.\n * The initiator and target negotiate the recovery level supported. * Recovery levels represent a combination of recovery capabilities. * Each recovery level includes all the capabilities of the lower - * recovery levels and adds some new ones to them. + * recovery levels and adds some new ones to them.\n * In the description of recovery mechanisms, certain recovery classes * are specified. */ @@ -3831,20 +4023,22 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: X reversed vendor. * + * @verbatim * Use: ALL * Senders: Initiator and target * Scope: specific key dependent * X-reversed.vendor.dns_name.do_something= + * @endverbatim * Keys with this format are used for private extension purposes. These * keys always start with X- if unregistered with IANA (private). New * public keys (if registered with IANA via an IETF Review RFC5226) no * longer have an X# name prefix requirement; implementers may propose - * any intuitive unique name. + * any intuitive unique name.\n * For unregistered keys, to identify the vendor we suggest using the - * reversed DNS-name as a prefix to the key-proper. + * reversed DNS-name as a prefix to the key-proper.\n * The part of key-name following X- MUST conform to the format for - * key-name. - * Vendor-specific keys MUST ONLY be used in Normal sessions. + * key-name.\n + * Vendor-specific keys MUST ONLY be used in Normal sessions.\n * Support for public or private extension keys is OPTIONAL. */ #define ISCSI_LOGIN_AUTH_SESSION_TEXT_KEY_PRIV_EXT_KEY_FMT "X-reversed.vendor" @@ -3852,36 +4046,26 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: Task reporting. * + * @verbatim * Use: LO * Senders: Initiator and target * Scope: SW * Irrelevant when: SessionType=Discovery * TaskReporting=<list-of-values> * Default is RFC3720. + * @endverbatim * This key is used to negotiate the task completion reporting semantics * from the SCSI target. The following table describes the semantics * that an iSCSI target MUST support for respective negotiated key * values. Whenever this key is negotiated, at least the RFC3720 and * ResponseFence values MUST be offered as options by the negotiation * originator. - * +--------------+------------------------------------------+ - * | Name | Description | - * +--------------+------------------------------------------+ - * | RFC3720 | RFC 3720-compliant semantics. Response | - * | | fencing is not guaranteed, and fast | - * | | completion of multi-task aborting is not | - * | | supported. | - * +--------------+------------------------------------------+ - * | ResponseFence| Response Fence | - * | | semantics MUST be supported in reporting | - * | | task completions. | - * +--------------+------------------------------------------+ - * | FastAbort | Updated fast multi-task abort semantics | - * | | defined in MUST be supported. Support | - * | | for the Response. Fence is implied - | - * | | i.e., semantics MUST be supported as | - * | | well. | - * +--------------+------------------------------------------+ + * Name | Description + * :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ + * | RFC3720 | RFC 3720-compliant semantics. Response fencing is not guaranteed, and fast completion of multi-task aborting is not supported. + * | ResponseFence | Response Fence semantics MUST be supported in reporting task completions. + * | FastAbort | Updated fast multi-task abort semantics defined in MUST be supported. Support for the Response. Fence is implied - i.e., semantics MUST be supported as well. + * * When TaskReporting is not negotiated to FastAbort, the * standard multi-task abort semantics MUST be used. */ @@ -3890,6 +4074,7 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: X Node architecture. * + * @verbatim * Use: LO, Declarative * Senders: Initiator and target * Scope: SW @@ -3899,34 +4084,36 @@ typedef struct __attribute__((packed)) iscsi_isid { * X#NodeArchitecture=ExampleOS/v1234,ExampleInc_SW_Initiator/1.05a * X#NodeArchitecture=ExampleInc_HW_Initiator/4010,Firmware/2.0.0.5 * X#NodeArchitecture=ExampleInc_SW_Initiator/2.1,CPU_Arch/i686 + * @endverbatim * This document does not define the structure or content of the list of - * values. + * values.\n * The initiator or target declares the details of its iSCSI node * architecture to the remote endpoint. These details may include, but * are not limited to, iSCSI vendor software, firmware, or hardware * versions; the OS version; or hardware architecture. This key may be - * declared on a Discovery session or a Normal session. + * declared on a Discovery session or a Normal session.\n * The length of the key value (total length of the list-of-values) MUST - * NOT be greater than 255 bytes. - * X#NodeArchitecture MUST NOT be redeclared during the Login Phase. + * NOT be greater than 255 bytes.\n + * X#NodeArchitecture MUST NOT be redeclared during the Login Phase.\n * Functional behavior of the iSCSI node (this includes the iSCSI * protocol logic - the SCSI, iSCSI, and TCP/IP protocols) MUST NOT * depend on the presence, absence, or content of the X#NodeArchitecture * key. The key MUST NOT be used by iSCSI nodes for interoperability or * for exclusion of other nodes. To ensure proper use, key values * SHOULD be set by the node itself, and there SHOULD NOT be provisions - * for the key values to contain user-defined text. + * for the key values to contain user-defined text.\n * Nodes implementing this key MUST choose one of the following - * implementation options: + * implementation options:\n * - only transmit the key, * - only log the key values received from other nodes, or * - both transmit and log the key values. + * * Each node choosing to implement transmission of the key values MUST * be prepared to handle the response of iSCSI nodes that do not - * understand the key. + * understand the key.\n * Nodes that implement transmission and/or logging of the key values * may also implement administrative mechanisms that disable and/or - * change the logging and key transmission details. + * change the logging and key transmission details.\n * Thus, a valid behavior for this key may be that a node is completely * silent (the node does not transmit any key value and simply discards * any key values it receives without issuing a NotUnderstood response). @@ -3936,15 +4123,15 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: IFMarker (obseleted). * - * This document obsoletes the following keys defined in RFC3720: + * This document obsoletes the following keys defined in RFC3720:\n * IFMarker, OFMarker, OFMarkInt, and IFMarkInt. However, iSCSI * mplementations compliant to this document may still receive these - * obsoleted keys - i.e., in a responder role - in a text negotiation. + * obsoleted keys - i.e., in a responder role - in a text negotiation.\n * When an IFMarker or OFMarker key is received, a compliant iSCSI * implementation SHOULD respond with the constant "Reject" value. The - * implementation MAY alternatively respond with a "No" value. + * implementation MAY alternatively respond with a "No" value.\n * However, the implementation MUST NOT respond with a "NotUnderstood" - * value for either of these keys. + * value for either of these keys.\n * When an IFMarkInt or OFMarkInt key is received, a compliant iSCSI * implementation MUST respond with the constant "Reject" value. The * implementation MUST NOT respond with a "NotUnderstood" value for @@ -3955,15 +4142,15 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: OFMarker (obseleted). * - * This document obsoletes the following keys defined in RFC3720: + * This document obsoletes the following keys defined in RFC3720:\n * IFMarker, OFMarker, OFMarkInt, and IFMarkInt. However, iSCSI * mplementations compliant to this document may still receive these - * obsoleted keys - i.e., in a responder role - in a text negotiation. + * obsoleted keys - i.e., in a responder role - in a text negotiation.\n * When an IFMarker or OFMarker key is received, a compliant iSCSI * implementation SHOULD respond with the constant "Reject" value. The - * implementation MAY alternatively respond with a "No" value. + * implementation MAY alternatively respond with a "No" value.\n * However, the implementation MUST NOT respond with a "NotUnderstood" - * value for either of these keys. + * value for either of these keys.\n * When an IFMarkInt or OFMarkInt key is received, a compliant iSCSI * implementation MUST respond with the constant "Reject" value. The * implementation MUST NOT respond with a "NotUnderstood" value for @@ -3974,15 +4161,15 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: OFMarkInt (obseleted). * - * This document obsoletes the following keys defined in RFC3720: + * This document obsoletes the following keys defined in RFC3720:\n * IFMarker, OFMarker, OFMarkInt, and IFMarkInt. However, iSCSI * mplementations compliant to this document may still receive these - * obsoleted keys - i.e., in a responder role - in a text negotiation. + * obsoleted keys - i.e., in a responder role - in a text negotiation.\n * When an IFMarker or OFMarker key is received, a compliant iSCSI * implementation SHOULD respond with the constant "Reject" value. The - * implementation MAY alternatively respond with a "No" value. + * implementation MAY alternatively respond with a "No" value.\n * However, the implementation MUST NOT respond with a "NotUnderstood" - * value for either of these keys. + * value for either of these keys.\n * When an IFMarkInt or OFMarkInt key is received, a compliant iSCSI * implementation MUST respond with the constant "Reject" value. The * implementation MUST NOT respond with a "NotUnderstood" value for @@ -3993,15 +4180,15 @@ typedef struct __attribute__((packed)) iscsi_isid { /** * @brief Login/Text Operational Session Text Key: IFMarkInt (obseleted). * - * This document obsoletes the following keys defined in RFC3720: + * This document obsoletes the following keys defined in RFC3720:\n * IFMarker, OFMarker, OFMarkInt, and IFMarkInt. However, iSCSI * mplementations compliant to this document may still receive these - * obsoleted keys - i.e., in a responder role - in a text negotiation. + * obsoleted keys - i.e., in a responder role - in a text negotiation.\n * When an IFMarker or OFMarker key is received, a compliant iSCSI * implementation SHOULD respond with the constant "Reject" value. The - * implementation MAY alternatively respond with a "No" value. + * implementation MAY alternatively respond with a "No" value.\n * However, the implementation MUST NOT respond with a "NotUnderstood" - * value for either of these keys. + * value for either of these keys.\n * When an IFMarkInt or OFMarkInt key is received, a compliant iSCSI * implementation MUST respond with the constant "Reject" value. The * implementation MUST NOT respond with a "NotUnderstood" value for @@ -4023,7 +4210,7 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Login request flags: Next Stage (NSG): First bit of the two bits. * * The Login negotiation requests and responses are associated - * with a specific stage in the session (SecurityNegotiation, + * with a specific stage in the session (SecurityNegotiation,\n * LoginOperationalNegotiation, FullFeaturePhase) and may indicate the * next stage to which they want to move. The Next Stage value is only * valid when the T bit is 1; otherwise, it is reserved. @@ -4072,7 +4259,7 @@ typedef struct __attribute__((packed)) iscsi_isid { * @brief Login request flags: Transmit. * * (T) When set to 1, this bit indicates that the initiator is ready to - * transit to the next stage. + * transit to the next stage.\n * If the T bit is set to 1 and the NSG is set to FullFeaturePhase, then * this also indicates that the initiator is ready for the Login * Final-Response. @@ -4103,7 +4290,7 @@ typedef struct __attribute__((packed)) iscsi_login_req_packet { * @brief Version-max indicates the maximum version number supported. * * All Login Requests within the Login Phase MUST carry the same - * Version-max. Currently, this is always 0. + * Version-max. Currently, this is always 0.\n * The target MUST use the value presented with the first Login Request. */ uint8_t version_max; @@ -4134,7 +4321,7 @@ typedef struct __attribute__((packed)) iscsi_login_req_packet { * the TSIH sent by the target at the conclusion of the successful login * of the first connection for this session MUST be used. The TSIH * identifies to the target the associated existing session for this new - * connection. + * connection.\n * All Login Requests within a Login Phase MUST carry the same TSIH. * The target MUST check the value presented with the first Login * Request. @@ -4147,9 +4334,9 @@ typedef struct __attribute__((packed)) iscsi_login_req_packet { /** * @brief Connection ID (CID). * - * The CID provides a unique ID for this connection within the session. + * The CID provides a unique ID for this connection within the session.\n * All Login Requests within the Login Phase MUST carry the same CID. - * The target MUST use the value presented with the first Login Request. + * The target MUST use the value presented with the first Login Request.\n * A Login Request with a non-zero TSIH and a CID equal to that of an * existing connection implies a logout of the connection followed by a * login. @@ -4165,7 +4352,7 @@ typedef struct __attribute__((packed)) iscsi_login_req_packet { * The CmdSN is either the initial command sequence number of a session * (for the first Login Request of a session - the "leading" login) or * the command sequence number in the command stream if the login is for - * a new connection in an existing session. + * a new connection in an existing session.\n * Examples: * - Login on a leading connection: If the leading login carries the * CmdSN 123, all other Login Requests in the same Login Phase carry @@ -4177,6 +4364,7 @@ typedef struct __attribute__((packed)) iscsi_login_req_packet { * needed to complete this Login Phase may carry a CmdSN higher than * 500 if non-immediate requests that were issued on other connections * in the same session advance the CmdSN. + * * If the Login Request is a leading Login Request, the target MUST use * the value presented in the CmdSN as the target value for the * ExpCmdSN. @@ -4188,7 +4376,7 @@ typedef struct __attribute__((packed)) iscsi_login_req_packet { * * For the first Login Request on a connection, this is the ExpStatSN * for the old connection, and this field is only valid if the Login - * Request restarts a connection + * Request restarts a connection.\n * For subsequent Login Requests, it is used to acknowledge the Login * Responses with their increasing StatSN values. */ @@ -4270,10 +4458,10 @@ typedef struct __attribute__((packed)) iscsi_login_req_packet { * (T) The T bit is set to 1 as an indicator of the end of the stage. If * the T bit is set to 1 and the NSG is set to FullFeaturePhase, then * this is also the Login Final-Response. A T bit of 0 indicates a - * "partial" response, which means "more negotiation needed". + * "partial" response, which means "more negotiation needed".\n * A Login Response with the T bit set to 1 MUST NOT contain key=value * pairs that may require additional answers from the initiator within - * the same stage. + * the same stage.\n * If the Status-Class is 0, the T bit MUST NOT be set to 1 if the T bit * in the request was set to 0. */ @@ -4283,10 +4471,9 @@ typedef struct __attribute__((packed)) iscsi_login_req_packet { /** * @brief Login response status class: Success. * - * Indicates that the iSCSI target successfully - * received, understood, and accepted the request. The numbering - * fields (StatSN, ExpCmdSN, MaxCmdSN) are only valid if Status- - * Class is 0. + * Indicates that the iSCSI target successfully received, understood, + * and accepted the request. The numbering fields (StatSN, ExpCmdSN, + * MaxCmdSN) are only valid if Status-Class is 0. */ #define ISCSI_LOGIN_RESPONSE_STATUS_CLASS_SUCCESS 0x00 @@ -4340,7 +4527,7 @@ typedef struct __attribute__((packed)) iscsi_login_req_packet { /** * @brief Login response status class: Initiator Error (not a format error). * - * Indicates that the initiator most likely caused the error. + * Indicates that the initiator most likely caused the error.\n * This MAY be due to a request for a resource for which the * initiator does not have permission. The request should * not be tried again. @@ -4432,7 +4619,7 @@ typedef struct __attribute__((packed)) iscsi_login_response_packet { * range specified by the initiator, the target rejects the login and * this field indicates the lowest version supported by the target. * All Login Responses within the Login Phase MUST carry the same - * Version-active. + * Version-active.\n * The initiator MUST use the value presented as a response to the first * Login Request. */ @@ -4507,7 +4694,7 @@ typedef struct __attribute__((packed)) iscsi_login_response_packet { * * The target MUST provide some basic parameters in order to enable the * initiator to determine if it is connected to the correct port and the - * initial text parameters for the security exchange. + * initial text parameters for the security exchange.\n * All the rules specified for Text Responses also hold for Login * Responses. */ @@ -4627,19 +4814,20 @@ typedef struct __attribute__((packed)) iscsi_logout_req_packet { * * A target implicitly terminates the active tasks due to the iSCSI * protocol in the following cases: - * a) When a connection is implicitly or explicitly logged out with + * -# When a connection is implicitly or explicitly logged out with * the reason code "close the connection" and there are active * tasks allegiant to that connection. - * b) When a connection fails and eventually the connection state + * -# When a connection fails and eventually the connection state * times out and there are active tasks allegiant to that * connection - * c) When a successful recovery Logout is performed while there are + * -# When a successful recovery Logout is performed while there are * active tasks allegiant to that connection and those tasks * eventually time out after the Time2Wait and Time2Retain periods * without allegiance reassignment - * d) When a connection is implicitly or explicitly logged out with + * -# When a connection is implicitly or explicitly logged out with * the reason code "close the session" and there are active tasks * in that session + * * If the tasks terminated in any of the above cases are SCSI tasks, * they must be internally terminated as if with CHECK CONDITION status. * This status is only meaningful for appropriately handling the @@ -4739,13 +4927,13 @@ typedef struct __attribute__((packed)) iscsi_logout_response_packet { uint8_t ds_len[3]; /// Reserved for future usage, always MUST be 0. - uint64_t reserved2; // Reserved for future usage + uint64_t reserved2; /// Initiator Task Tag (ITT). uint32_t init_task_tag; /// Reserved for future usage, always MUST be 0. - uint32_t reserved3; // Reserved for future usage + uint32_t reserved3; /// StatSN. uint32_t stat_sn; @@ -4766,11 +4954,11 @@ typedef struct __attribute__((packed)) iscsi_logout_response_packet { * ErrorRecoveryLevel is 2, this is the minimum amount of time, in * seconds, to wait before attempting task reassignment. If the Logout * response code is 0 and the operational ErrorRecoveryLevel is less - * than 2, this field is to be ignored. - * This field is invalid if the Logout response code is 1. + * than 2, this field is to be ignored.\n + * This field is invalid if the Logout response code is 1.\n * If the Logout response code is 2 or 3, this field specifies the * minimum time to wait before attempting a new implicit or explicit - * logout. + * logout.\n * If Time2Wait is 0, the reassignment or a new Logout may be attempted * immediately. */ @@ -4785,14 +4973,14 @@ typedef struct __attribute__((packed)) iscsi_logout_response_packet { * the allegiance reassignment for any active task, after which the task * state is discarded. If the Logout response code is 0 and the * operational ErrorRecoveryLevel is less than 2, this field is to be - * ignored. - * This field is invalid if the Logout response code is 1. + * ignored.\n + * This field is invalid if the Logout response code is 1.\n * If the Logout response code is 2 or 3, this field specifies the * maximum amount of time, in seconds, after the initial wait * (Time2Wait) that the target waits for a new implicit or explicit - * logout. + * logout.\n * If it is the last connection of a session, the whole session state is - * discarded after Time2Retain. + * discarded after Time2Retain.\n * If Time2Retain is 0, the target has already discarded the connection * (and possibly the session) state along with the task states. No * reassignment or Logout is required in this case. @@ -4823,9 +5011,9 @@ typedef struct __attribute__((packed)) iscsi_logout_response_packet { * input sequence, it MUST postpone issuing the SNACK of type DataACK * until the holes are filled. An initiator MAY ignore the A bit if it * deems that the bit is being set aggressively by the target (i.e., - * before the MaxBurstLength limit is reached). + * before the MaxBurstLength limit is reached).\n * The DataACK is used to free resources at the target and not to - * request or imply data retransmission. + * request or imply data retransmission.\n * An initiator MUST NOT request retransmission for any data it had * already acknowledged */ @@ -4836,7 +5024,7 @@ typedef struct __attribute__((packed)) iscsi_logout_response_packet { * * If the initiator MaxRecvDataSegmentLength changed between the * original transmission and the time the initiator requests - * retransmission, the initiator MUST issue a R-Data SNACK. + * retransmission, the initiator MUST issue a R-Data SNACK.\n * With R-Data SNACK, the initiator indicates that it discards all the * unacknowledged data and expects the target to resend it. It also * expects resegmentation. In this case, the retransmitted Data-In PDUs @@ -4844,7 +5032,7 @@ typedef struct __attribute__((packed)) iscsi_logout_response_packet { * changes in MaxRecvDataSegmentLength. Their DataSN starts with the * BegRun of the last DataACK received by the target if any was received; * otherwise, it starts with 0 and is increased by 1 for each resent - * Data-In PDU. + * Data-In PDU.\n * A target that has received a R-Data SNACK MUST return a SCSI Response * that contains a copy of the SNACK Tag field from the R-Data SNACK in * the SCSI Response SNACK Tag field as its last or only Response. For @@ -4855,7 +5043,7 @@ typedef struct __attribute__((packed)) iscsi_logout_response_packet { * must carry the same StatSN. If an initiator attempts to recover a lost * SCSI Response when more than one response has been sent, the * target will send the SCSI Response with the latest content known to - * the target, including the last SNACK Tag for the command. + * the target, including the last SNACK Tag for the command.\n * For considerations in allegiance reassignment of a task to a * connection with a different MaxRecvDataSegmentLength. */ @@ -4938,10 +5126,10 @@ typedef struct __attribute__((packed)) iscsi_snack_req_packet { * For a R-Data SNACK, this field MUST contain a value that is different * from 0 or 0xFFFFFFFF and is unique for the task (identified by the * Initiator Task Tag). This value MUST be copied by the iSCSI target - * in the last or only SCSI Response PDU it issues for the command. + * in the last or only SCSI Response PDU it issues for the command.\n * For DataACK, the Target Transfer Tag MUST contain a copy of the * Target Transfer Tag and LUN provided with the SCSI Data-In PDU with - * the A bit set to 1. + * the A bit set to 1.\n * In all other cases, the Target Transfer Tag field MUST be set to the * reserved value 0xFFFFFFFF. */ @@ -4961,7 +5149,7 @@ typedef struct __attribute__((packed)) iscsi_snack_req_packet { * * This field indicates the DataSN, R2TSN, or StatSN of the first PDU * whose retransmission is requested (Data/R2T and Status SNACK), or the - * next expected DataSN (DataACK SNACK). + * next expected DataSN (DataACK SNACK).\n * A BegRun of 0, when used in conjunction with a RunLength of 0, means * "resend all unacknowledged Data-In, R2T or Response PDUs". * BegRun MUST be 0 for a R-Data SNACK. @@ -4972,10 +5160,10 @@ typedef struct __attribute__((packed)) iscsi_snack_req_packet { * @brief RunLength. * * This field indicates the number of PDUs whose retransmission is - * requested. + * requested.\n * A RunLength of 0 signals that all Data-In, R2T, or Response PDUs * carrying the numbers equal to or greater than BegRun have to be - * resent. + * resent.\n * The RunLength MUST also be 0 for a DataACK SNACK in addition to a * R-Data SNACK. */ @@ -5194,9 +5382,9 @@ typedef struct __attribute__((packed)) iscsi_nop_out_packet { * The NOP-Out MUST have the Initiator Task Tag set to a valid value * only if a response in the form of a NOP-In is requested (i.e., the * NOP-Out is used as a ping request). Otherwise, the Initiator Task - * Tag MUST be set to 0xFFFFFFFF. + * Tag MUST be set to 0xFFFFFFFF.\n * When a target receives the NOP-Out with a valid Initiator Task Tag, - * it MUST respond with a NOP-In Response. + * it MUST respond with a NOP-In Response.\n * If the Initiator Task Tag contains 0xFFFFFFFF, the I bit MUST be set * to 1, and the CmdSN is not advanced after this PDU is sent. */ @@ -5206,11 +5394,11 @@ typedef struct __attribute__((packed)) iscsi_nop_out_packet { * @brief Target Transfer Tag (TTT). * * The Target Transfer Tag is a target-assigned identifier for the - * operation. + * operation.\n * The NOP-Out MUST only have the Target Transfer Tag set if it is * issued in response to a NOP-In with a valid Target Transfer Tag. In - * this case, it copies the Target Transfer Tag from the NOP-In PDU. - * Otherwise, the Target Transfer Tag MUST be set to 0xFFFFFFFF. + * this case, it copies the Target Transfer Tag from the NOP-In PDU.\n + * Otherwise, the Target Transfer Tag MUST be set to 0xFFFFFFFF.\n * When the Target Transfer Tag is set to a value other than 0xFFFFFFFF, * the LUN field MUST also be copied from the NOP-In. */ @@ -5256,9 +5444,9 @@ typedef struct __attribute__((packed)) iscsi_nop_out_packet { * with the same Initiator Task Tag that was provided in the NOP-Out * request. It MUST also duplicate up to the first * MaxRecvDataSegmentLength bytes of the initiator-provided Ping Data. - * For such a response, the Target Transfer Tag MUST be 0xFFFFFFFF. The + * For such a response, the Target Transfer Tag MUST be 0xFFFFFFFF. * - * target SHOULD NOT send a NOP-In in response to any other received + * The target SHOULD NOT send a NOP-In in response to any other received * NOP-Out in order to avoid lengthy sequences of NOP-In and NOP-Out * PDUs sent in response to each other. * @@ -5293,10 +5481,10 @@ typedef struct __attribute__((packed)) iscsi_nop_in_packet { * @brief Target Transfer Tag (TTT). * * If the target is responding to a NOP-Out, this field is set to the - * reserved value 0xFFFFFFFF. + * reserved value 0xFFFFFFFF.\n * If the target is sending a NOP-In as a ping (intending to receive a * corresponding NOP-Out), this field is set to a valid value (not the - * reserved value 0xFFFFFFFF). + * reserved value 0xFFFFFFFF).\n * If the target is initiating a NOP-In without wanting to receive a * corresponding NOP-Out, this field MUST hold the reserved value * 0xFFFFFFFF. |