iPXE - Open Source Boot Firmware

[iscsi] Change default initiator IQN
[ipxe.git] / src / include / ipxe / iscsi.h
1 #ifndef _IPXE_ISCSI_H
2 #define _IPXE_ISCSI_H
3
4 /** @file
5  *
6  * iSCSI protocol
7  *
8  */
9
10 FILE_LICENCE ( GPL2_OR_LATER );
11
12 #include <stdint.h>
13 #include <ipxe/socket.h>
14 #include <ipxe/scsi.h>
15 #include <ipxe/chap.h>
16 #include <ipxe/refcnt.h>
17 #include <ipxe/xfer.h>
18 #include <ipxe/process.h>
19
20 /** Default iSCSI port */
21 #define ISCSI_PORT 3260
22
23 /**
24  * iSCSI segment lengths
25  *
26  * iSCSI uses an icky structure with one one-byte field (a dword
27  * count) and one three-byte field (a byte count).  This structure,
28  * and the accompanying macros, relieve some of the pain.
29  */
30 union iscsi_segment_lengths {
31         struct {
32                 /** The AHS length (measured in dwords) */
33                 uint8_t ahs_len;
34                 /** The data length (measured in bytes), in network
35                  * byte order
36                  */
37                 uint8_t data_len[3];
38         } bytes;
39         /** Ths data length (measured in bytes), in network byte
40          * order, with ahs_len as the first byte.
41          */
42         uint32_t ahs_and_data_len;
43 };
44
45 /** The length of the additional header segment, in dwords */
46 #define ISCSI_AHS_LEN( segment_lengths ) \
47         ( (segment_lengths).bytes.ahs_len )
48
49 /** The length of the data segment, in bytes, excluding any padding */
50 #define ISCSI_DATA_LEN( segment_lengths ) \
51         ( ntohl ( (segment_lengths).ahs_and_data_len ) & 0xffffff )
52
53 /** The padding of the data segment, in bytes */
54 #define ISCSI_DATA_PAD_LEN( segment_lengths ) \
55         ( ( 0 - (segment_lengths).bytes.data_len[2] ) & 0x03 )
56
57 /** Set additional header and data segment lengths */
58 #define ISCSI_SET_LENGTHS( segment_lengths, ahs_len, data_len ) do {    \
59         (segment_lengths).ahs_and_data_len =                            \
60                 htonl ( data_len | ( ahs_len << 24 ) );                 \
61         } while ( 0 )
62
63 /**
64  * iSCSI basic header segment common fields
65  *
66  */
67 struct iscsi_bhs_common {
68         /** Opcode */
69         uint8_t opcode;
70         /** Flags */
71         uint8_t flags;
72         /** Fields specific to the PDU type */
73         uint8_t other_a[2];
74         /** Segment lengths */
75         union iscsi_segment_lengths lengths;
76         /** Fields specific to the PDU type */
77         uint8_t other_b[8];
78         /** Initiator Task Tag */
79         uint32_t itt;
80         /** Fields specific to the PDU type */
81         uint8_t other_c[28];
82 };
83
84 /** Opcode mask */
85 #define ISCSI_OPCODE_MASK 0x3f
86
87 /** Immediate delivery */
88 #define ISCSI_FLAG_IMMEDIATE 0x40
89
90 /** Final PDU of a sequence */
91 #define ISCSI_FLAG_FINAL 0x80
92
93 /** iSCSI tag magic marker */
94 #define ISCSI_TAG_MAGIC 0x18ae0000
95
96 /** iSCSI reserved tag value */
97 #define ISCSI_TAG_RESERVED 0xffffffff
98
99 /**
100  * iSCSI basic header segment common request fields
101  *
102  */
103 struct iscsi_bhs_common_response {
104         /** Opcode */
105         uint8_t opcode;
106         /** Flags */
107         uint8_t flags;
108         /** Fields specific to the PDU type */
109         uint8_t other_a[2];
110         /** Segment lengths */
111         union iscsi_segment_lengths lengths;
112         /** Fields specific to the PDU type */
113         uint8_t other_b[8];
114         /** Initiator Task Tag */
115         uint32_t itt;
116         /** Fields specific to the PDU type */
117         uint8_t other_c[4];
118         /** Status sequence number */
119         uint32_t statsn;
120         /** Expected command sequence number */
121         uint32_t expcmdsn;
122         /** Fields specific to the PDU type */
123         uint8_t other_d[16];
124 };
125
126 /**
127  * iSCSI login request basic header segment
128  *
129  */
130 struct iscsi_bhs_login_request {
131         /** Opcode */
132         uint8_t opcode;
133         /** Flags */
134         uint8_t flags;
135         /** Maximum supported version number */
136         uint8_t version_max;
137         /** Minimum supported version number */
138         uint8_t version_min;
139         /** Segment lengths */
140         union iscsi_segment_lengths lengths;
141         /** Initiator session ID (IANA format) enterprise number and flags */
142         uint32_t isid_iana_en;
143         /** Initiator session ID (IANA format) qualifier */
144         uint16_t isid_iana_qual;
145         /** Target session identifying handle */
146         uint16_t tsih;
147         /** Initiator Task Tag */
148         uint32_t itt;
149         /** Connection ID */
150         uint16_t cid;
151         /** Reserved */
152         uint16_t reserved_a;
153         /** Command sequence number */
154         uint32_t cmdsn;
155         /** Expected status sequence number */
156         uint32_t expstatsn;
157         /** Reserved */
158         uint8_t reserved_b[16];
159 };
160
161 /** Login request opcode */
162 #define ISCSI_OPCODE_LOGIN_REQUEST 0x03
163
164 /** Willingness to transition to next stage */
165 #define ISCSI_LOGIN_FLAG_TRANSITION 0x80
166
167 /** Key=value pairs continued in subsequent request */
168 #define ISCSI_LOGIN_FLAG_CONTINUE 0x40
169
170 /* Current stage values and mask */
171 #define ISCSI_LOGIN_CSG_MASK 0x0c
172 #define ISCSI_LOGIN_CSG_SECURITY_NEGOTIATION 0x00
173 #define ISCSI_LOGIN_CSG_OPERATIONAL_NEGOTIATION 0x04
174 #define ISCSI_LOGIN_CSG_FULL_FEATURE_PHASE 0x0c
175
176 /* Next stage values and mask */
177 #define ISCSI_LOGIN_NSG_MASK 0x03
178 #define ISCSI_LOGIN_NSG_SECURITY_NEGOTIATION 0x00
179 #define ISCSI_LOGIN_NSG_OPERATIONAL_NEGOTIATION 0x01
180 #define ISCSI_LOGIN_NSG_FULL_FEATURE_PHASE 0x03
181
182 /** ISID IANA format marker */
183 #define ISCSI_ISID_IANA 0x40000000
184
185 /** Fen Systems Ltd. IANA enterprise number
186  *
187  * Permission is hereby granted to use Fen Systems Ltd.'s IANA
188  * enterprise number with this iSCSI implementation.
189  */
190 #define IANA_EN_FEN_SYSTEMS 10019
191
192 /**
193  * iSCSI login response basic header segment
194  *
195  */
196 struct iscsi_bhs_login_response {
197         /** Opcode */
198         uint8_t opcode;
199         /** Flags */
200         uint8_t flags;
201         /** Maximum supported version number */
202         uint8_t version_max;
203         /** Minimum supported version number */
204         uint8_t version_min;
205         /** Segment lengths */
206         union iscsi_segment_lengths lengths;
207         /** Initiator session ID (IANA format) enterprise number and flags */
208         uint32_t isid_iana_en;
209         /** Initiator session ID (IANA format) qualifier */
210         uint16_t isid_iana_qual;
211         /** Target session identifying handle */
212         uint16_t tsih;
213         /** Initiator Task Tag */
214         uint32_t itt;
215         /** Reserved */
216         uint32_t reserved_a;
217         /** Status sequence number */
218         uint32_t statsn;
219         /** Expected command sequence number */
220         uint32_t expcmdsn;
221         /** Maximum command sequence number */
222         uint32_t maxcmdsn;
223         /** Status class */
224         uint8_t status_class;
225         /** Status detail */
226         uint8_t status_detail;
227         /** Reserved */
228         uint8_t reserved_b[10];
229 };
230
231 /** Login response opcode */
232 #define ISCSI_OPCODE_LOGIN_RESPONSE 0x23
233
234 /* Login response status codes */
235 #define ISCSI_STATUS_SUCCESS                    0x00
236 #define ISCSI_STATUS_REDIRECT                   0x01
237 #define ISCSI_STATUS_INITIATOR_ERROR            0x02
238 #define ISCSI_STATUS_INITIATOR_ERROR_AUTHENTICATION     0x01
239 #define ISCSI_STATUS_INITIATOR_ERROR_AUTHORISATION      0x02
240 #define ISCSI_STATUS_INITIATOR_ERROR_NOT_FOUND          0x03
241 #define ISCSI_STATUS_INITIATOR_ERROR_REMOVED            0x04
242 #define ISCSI_STATUS_TARGET_ERROR               0x03
243 #define ISCSI_STATUS_TARGET_ERROR_UNAVAILABLE           0x01
244 #define ISCSI_STATUS_TARGET_ERROR_NO_RESOURCES          0x02
245
246 /**
247  * iSCSI SCSI command basic header segment
248  *
249  */
250 struct iscsi_bhs_scsi_command {
251         /** Opcode */
252         uint8_t opcode;
253         /** Flags */
254         uint8_t flags;
255         /** Reserved */
256         uint16_t reserved_a;
257         /** Segment lengths */
258         union iscsi_segment_lengths lengths;
259         /** SCSI Logical Unit Number */
260         struct scsi_lun lun;
261         /** Initiator Task Tag */
262         uint32_t itt;
263         /** Expected data transfer length */
264         uint32_t exp_len;
265         /** Command sequence number */
266         uint32_t cmdsn;
267         /** Expected status sequence number */
268         uint32_t expstatsn;
269         /** SCSI Command Descriptor Block (CDB) */
270         union scsi_cdb cdb;
271 };
272
273 /** SCSI command opcode */
274 #define ISCSI_OPCODE_SCSI_COMMAND 0x01
275
276 /** Command will read data */
277 #define ISCSI_COMMAND_FLAG_READ 0x40
278
279 /** Command will write data */
280 #define ISCSI_COMMAND_FLAG_WRITE 0x20
281
282 /* Task attributes */
283 #define ISCSI_COMMAND_ATTR_UNTAGGED 0x00
284 #define ISCSI_COMMAND_ATTR_SIMPLE 0x01
285 #define ISCSI_COMMAND_ATTR_ORDERED 0x02
286 #define ISCSI_COMMAND_ATTR_HEAD_OF_QUEUE 0x03
287 #define ISCSI_COMMAND_ATTR_ACA 0x04
288
289 /**
290  * iSCSI SCSI response basic header segment
291  *
292  */
293 struct iscsi_bhs_scsi_response {
294         /** Opcode */
295         uint8_t opcode;
296         /** Flags */
297         uint8_t flags;
298         /** Response code */
299         uint8_t response;
300         /** SCSI status code */
301         uint8_t status;
302         /** Segment lengths */
303         union iscsi_segment_lengths lengths;
304         /** Reserved */
305         uint8_t reserved_a[8];
306         /** Initiator Task Tag */
307         uint32_t itt;
308         /** SNACK tag */
309         uint32_t snack;
310         /** Status sequence number */
311         uint32_t statsn;
312         /** Expected command sequence number */
313         uint32_t expcmdsn;
314         /** Maximum command sequence number */
315         uint32_t maxcmdsn;
316         /** Expected data sequence number */
317         uint32_t expdatasn;
318         /** Bidirectional read residual count */
319         uint32_t bidi_residual_count;
320         /** Residual count */
321         uint32_t residual_count;
322 };
323
324 /** SCSI response opcode */
325 #define ISCSI_OPCODE_SCSI_RESPONSE 0x21
326
327 /** SCSI command completed at target */
328 #define ISCSI_RESPONSE_COMMAND_COMPLETE 0x00
329
330 /** SCSI target failure */
331 #define ISCSI_RESPONSE_TARGET_FAILURE 0x01
332
333 /** Data overflow occurred */
334 #define ISCSI_RESPONSE_FLAG_OVERFLOW 0x20
335
336 /** Data underflow occurred */
337 #define ISCSI_RESPONSE_FLAG_UNDERFLOW 0x40
338
339 /**
340  * iSCSI data-in basic header segment
341  *
342  */
343 struct iscsi_bhs_data_in {
344         /** Opcode */
345         uint8_t opcode;
346         /** Flags */
347         uint8_t flags;
348         /** Reserved */
349         uint8_t reserved_a;
350         /** SCSI status code */
351         uint8_t status;
352         /** Segment lengths */
353         union iscsi_segment_lengths lengths;
354         /** Logical Unit Number */
355         struct scsi_lun lun;
356         /** Initiator Task Tag */
357         uint32_t itt;
358         /** Target Transfer Tag */
359         uint32_t ttt;
360         /** Status sequence number */
361         uint32_t statsn;
362         /** Expected command sequence number */
363         uint32_t expcmdsn;
364         /** Maximum command sequence number */
365         uint32_t maxcmdsn;
366         /** Data sequence number */
367         uint32_t datasn;
368         /** Buffer offset */
369         uint32_t offset;
370         /** Residual count */
371         uint32_t residual_count;
372 };
373
374 /** Data-in opcode */
375 #define ISCSI_OPCODE_DATA_IN 0x25
376
377 /** Data requires acknowledgement */
378 #define ISCSI_DATA_FLAG_ACKNOWLEDGE 0x40
379
380 /** Data overflow occurred */
381 #define ISCSI_DATA_FLAG_OVERFLOW 0x04
382
383 /** Data underflow occurred */
384 #define ISCSI_DATA_FLAG_UNDERFLOW 0x02
385
386 /** SCSI status code and overflow/underflow flags are valid */
387 #define ISCSI_DATA_FLAG_STATUS 0x01
388
389 /**
390  * iSCSI data-out basic header segment
391  *
392  */
393 struct iscsi_bhs_data_out {
394         /** Opcode */
395         uint8_t opcode;
396         /** Flags */
397         uint8_t flags;
398         /** Reserved */
399         uint16_t reserved_a;
400         /** Segment lengths */
401         union iscsi_segment_lengths lengths;
402         /** Logical Unit Number */
403         struct scsi_lun lun;
404         /** Initiator Task Tag */
405         uint32_t itt;
406         /** Target Transfer Tag */
407         uint32_t ttt;
408         /** Reserved */
409         uint32_t reserved_b;
410         /** Expected status sequence number */
411         uint32_t expstatsn;
412         /** Reserved */
413         uint32_t reserved_c;
414         /** Data sequence number */
415         uint32_t datasn;
416         /** Buffer offset */
417         uint32_t offset;
418         /** Reserved */
419         uint32_t reserved_d;
420 };
421
422 /** Data-out opcode */
423 #define ISCSI_OPCODE_DATA_OUT 0x05
424
425 /**
426  * iSCSI request to transfer basic header segment
427  *
428  */
429 struct iscsi_bhs_r2t {
430         /** Opcode */
431         uint8_t opcode;
432         /** Flags */
433         uint8_t flags;
434         /** Reserved */
435         uint16_t reserved_a;
436         /** Segment lengths */
437         union iscsi_segment_lengths lengths;
438         /** Logical Unit Number */
439         struct scsi_lun lun;
440         /** Initiator Task Tag */
441         uint32_t itt;
442         /** Target Transfer Tag */
443         uint32_t ttt;
444         /** Status sequence number */
445         uint32_t statsn;
446         /** Expected command sequence number */
447         uint32_t expcmdsn;
448         /** Maximum command sequence number */
449         uint32_t maxcmdsn;
450         /** R2T sequence number */
451         uint32_t r2tsn;
452         /** Buffer offset */
453         uint32_t offset;
454         /** Desired data transfer length */
455         uint32_t len;
456 };
457
458 /** R2T opcode */
459 #define ISCSI_OPCODE_R2T 0x31
460
461 /**
462  * iSCSI NOP-In basic header segment
463  *
464  */
465 struct iscsi_nop_in {
466         /** Opcode */
467         uint8_t opcode;
468         /** Reserved */
469         uint8_t reserved_a[3];
470         /** Segment lengths */
471         union iscsi_segment_lengths lengths;
472         /** Logical Unit Number */
473         struct scsi_lun lun;
474         /** Initiator Task Tag */
475         uint32_t itt;
476         /** Target Transfer Tag */
477         uint32_t ttt;
478         /** Status sequence number */
479         uint32_t statsn;
480         /** Expected command sequence number */
481         uint32_t expcmdsn;
482         /** Maximum command sequence number */
483         uint32_t maxcmdsn;
484         /** Reserved */
485         uint8_t reserved_b[12];
486 };
487
488 /** NOP-In opcode */
489 #define ISCSI_OPCODE_NOP_IN 0x20
490
491 /**
492  * An iSCSI basic header segment
493  */
494 union iscsi_bhs {
495         struct iscsi_bhs_common common;
496         struct iscsi_bhs_common_response common_response;
497         struct iscsi_bhs_login_request login_request;
498         struct iscsi_bhs_login_response login_response;
499         struct iscsi_bhs_scsi_command scsi_command;
500         struct iscsi_bhs_scsi_response scsi_response;
501         struct iscsi_bhs_data_in data_in;
502         struct iscsi_bhs_data_out data_out;
503         struct iscsi_bhs_r2t r2t;
504         struct iscsi_nop_in nop_in;
505         unsigned char bytes[ sizeof ( struct iscsi_bhs_common ) ];
506 };
507
508 /** State of an iSCSI TX engine */
509 enum iscsi_tx_state {
510         /** Nothing to send */
511         ISCSI_TX_IDLE = 0,
512         /** Sending the basic header segment */
513         ISCSI_TX_BHS,
514         /** Sending the additional header segment */
515         ISCSI_TX_AHS,
516         /** Sending the data segment */
517         ISCSI_TX_DATA,
518         /** Sending the data segment padding */
519         ISCSI_TX_DATA_PADDING,
520 };
521
522 /** State of an iSCSI RX engine */
523 enum iscsi_rx_state {
524         /** Receiving the basic header segment */
525         ISCSI_RX_BHS = 0,
526         /** Receiving the additional header segment */
527         ISCSI_RX_AHS,
528         /** Receiving the data segment */
529         ISCSI_RX_DATA,
530         /** Receiving the data segment padding */
531         ISCSI_RX_DATA_PADDING,
532 };
533
534 /** An iSCSI session */
535 struct iscsi_session {
536         /** Reference counter */
537         struct refcnt refcnt;
538
539         /** SCSI command-issuing interface */
540         struct interface control;
541         /** SCSI command interface */
542         struct interface data;
543         /** Transport-layer socket */
544         struct interface socket;
545
546         /** Initiator IQN */
547         char *initiator_iqn;
548         /** Target address */
549         char *target_address;
550         /** Target port */
551         unsigned int target_port;
552         /** Target IQN */
553         char *target_iqn;
554
555         /** Session status
556          *
557          * This is the bitwise-OR of zero or more ISCSI_STATUS_XXX
558          * constants.
559          */
560         int status;
561
562         /** Initiator username (if any) */
563         char *initiator_username;
564         /** Initiator password (if any) */
565         char *initiator_password;
566         /** Target username (if any) */
567         char *target_username;
568         /** Target password (if any) */
569         char *target_password;
570         /** CHAP challenge (for target auth only)
571          *
572          * This is a block of random data; the first byte is used as
573          * the CHAP identifier (CHAP_I) and the remainder as the CHAP
574          * challenge (CHAP_C).
575          */
576         unsigned char chap_challenge[17];
577         /** CHAP response (used for both initiator and target auth) */
578         struct chap_response chap;
579
580         /** Initiator session ID (IANA format) qualifier
581          *
582          * This is part of the ISID.  It is generated randomly
583          * whenever a new connection is opened.
584          */
585         uint16_t isid_iana_qual;
586         /** Initiator task tag
587          *
588          * This is the tag of the current command.  It is incremented
589          * whenever a new command is started.
590          */
591         uint32_t itt;
592         /** Target transfer tag
593          *
594          * This is the tag attached to a sequence of data-out PDUs in
595          * response to an R2T.
596          */
597         uint32_t ttt;
598         /** Transfer offset
599          *
600          * This is the offset for an in-progress sequence of data-out
601          * PDUs in response to an R2T.
602          */
603         uint32_t transfer_offset;
604         /** Transfer length
605          *
606          * This is the length for an in-progress sequence of data-out
607          * PDUs in response to an R2T.
608          */
609         uint32_t transfer_len;
610         /** Command sequence number
611          *
612          * This is the sequence number of the current command, used to
613          * fill out the CmdSN field in iSCSI request PDUs.  It is
614          * updated with the value of the ExpCmdSN field whenever we
615          * receive an iSCSI response PDU containing such a field.
616          */
617         uint32_t cmdsn;
618         /** Status sequence number
619          *
620          * This is the most recent status sequence number present in
621          * the StatSN field of an iSCSI response PDU containing such a
622          * field.  Whenever we send an iSCSI request PDU, we fill out
623          * the ExpStatSN field with this value plus one.
624          */
625         uint32_t statsn;
626         
627         /** Basic header segment for current TX PDU */
628         union iscsi_bhs tx_bhs;
629         /** State of the TX engine */
630         enum iscsi_tx_state tx_state;
631         /** TX process */
632         struct process process;
633
634         /** Basic header segment for current RX PDU */
635         union iscsi_bhs rx_bhs;
636         /** State of the RX engine */
637         enum iscsi_rx_state rx_state;
638         /** Byte offset within the current RX state */
639         size_t rx_offset;
640         /** Length of the current RX state */
641         size_t rx_len;
642         /** Buffer for received data (not always used) */
643         void *rx_buffer;
644
645         /** Current SCSI command, if any */
646         struct scsi_cmd *command;
647
648         /** Target socket address (for boot firmware table) */
649         struct sockaddr target_sockaddr;
650         /** SCSI LUN (for boot firmware table) */
651         struct scsi_lun lun;
652 };
653
654 /** iSCSI session is currently in the security negotiation phase */
655 #define ISCSI_STATUS_SECURITY_NEGOTIATION_PHASE         \
656         ( ISCSI_LOGIN_CSG_SECURITY_NEGOTIATION |        \
657           ISCSI_LOGIN_NSG_OPERATIONAL_NEGOTIATION )
658
659 /** iSCSI session is currently in the operational parameter
660  * negotiation phase
661  */
662 #define ISCSI_STATUS_OPERATIONAL_NEGOTIATION_PHASE      \
663         ( ISCSI_LOGIN_CSG_OPERATIONAL_NEGOTIATION |     \
664           ISCSI_LOGIN_NSG_FULL_FEATURE_PHASE )
665
666 /** iSCSI session is currently in the full feature phase */
667 #define ISCSI_STATUS_FULL_FEATURE_PHASE ISCSI_LOGIN_CSG_FULL_FEATURE_PHASE
668
669 /** Mask for all iSCSI session phases */
670 #define ISCSI_STATUS_PHASE_MASK ( ISCSI_LOGIN_CSG_MASK | ISCSI_LOGIN_NSG_MASK )
671
672 /** iSCSI session needs to send the initial security negotiation strings */
673 #define ISCSI_STATUS_STRINGS_SECURITY 0x0100
674
675 /** iSCSI session needs to send the CHAP_A string */
676 #define ISCSI_STATUS_STRINGS_CHAP_ALGORITHM 0x0200
677
678 /** iSCSI session needs to send the CHAP response */
679 #define ISCSI_STATUS_STRINGS_CHAP_RESPONSE 0x0400
680
681 /** iSCSI session needs to send the mutual CHAP challenge */
682 #define ISCSI_STATUS_STRINGS_CHAP_CHALLENGE 0x0800
683
684 /** iSCSI session needs to send the operational negotiation strings */
685 #define ISCSI_STATUS_STRINGS_OPERATIONAL 0x1000
686
687 /** Mask for all iSCSI "needs to send" flags */
688 #define ISCSI_STATUS_STRINGS_MASK 0xff00
689
690 /** Target has requested forward (initiator) authentication */
691 #define ISCSI_STATUS_AUTH_FORWARD_REQUIRED 0x00010000
692
693 /** Initiator requires target (reverse) authentication */
694 #define ISCSI_STATUS_AUTH_REVERSE_REQUIRED 0x00020000
695
696 /** Target authenticated itself correctly */
697 #define ISCSI_STATUS_AUTH_REVERSE_OK 0x00040000
698
699 /** Default initiator IQN prefix */
700 #define ISCSI_DEFAULT_IQN_PREFIX "iqn.2010-04.org.ipxe"
701
702 #endif /* _IPXE_ISCSI_H */