diff options
Diffstat (limited to 'utils')
| -rw-r--r-- | utils/open-isns/doc/rfc2608.txt | 3027 | ||||
| -rw-r--r-- | utils/open-isns/doc/rfc3279.txt | 1515 | ||||
| -rw-r--r-- | utils/open-isns/doc/rfc3720.txt | 14395 | ||||
| -rw-r--r-- | utils/open-isns/doc/rfc3722.txt | 451 | ||||
| -rw-r--r-- | utils/open-isns/doc/rfc4018.txt | 1291 | ||||
| -rw-r--r-- | utils/open-isns/doc/rfc4171.txt | 6891 |
6 files changed, 0 insertions, 27570 deletions
diff --git a/utils/open-isns/doc/rfc2608.txt b/utils/open-isns/doc/rfc2608.txt deleted file mode 100644 index fa7de62..0000000 --- a/utils/open-isns/doc/rfc2608.txt +++ /dev/null @@ -1,3027 +0,0 @@ - - - - - - -Network Working Group E. Guttman -Request for Comments: 2608 C. Perkins -Updates: 2165 Sun Microsystems -Category: Standards Track J. Veizades - @Home Network - M. Day - Vinca Corporation - June 1999 - - - Service Location Protocol, Version 2 - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (1999). All Rights Reserved. - -Abstract - - The Service Location Protocol provides a scalable framework for the - discovery and selection of network services. Using this protocol, - computers using the Internet need little or no static configuration - of network services for network based applications. This is - especially important as computers become more portable, and users - less tolerant or able to fulfill the demands of network system - administration. - -Table of Contents - - 1. Introduction 3 - 1.1. Applicability Statement . . . . . . . . . . . . . . . 3 - 2. Terminology 4 - 2.1. Notation Conventions . . . . . . . . . . . . . . . . . 4 - 3. Protocol Overview 5 - 4. URLs used with Service Location 8 - 4.1. Service: URLs . . . . . . . . . . . . . . . . . . . . 9 - 4.2. Naming Authorities . . . . . . . . . . . . . . . . . 10 - 4.3. URL Entries . . . . . . . . . . . . . . . . . . . . . 10 - 5. Service Attributes 10 - 6. Required Features 12 - 6.1. Use of Ports, UDP, and Multicast . . . . . . . . . . 13 - - - -Guttman, et al. Standards Track [Page 1] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - 6.2. Use of TCP . . . . . . . . . . . . . . . . . . . . . 14 - 6.3. Retransmission of SLP messages . . . . . . . . . . . 15 - 6.4. Strings in SLP messages . . . . . . . . . . . . . . . 16 - 6.4.1. Scope Lists in SLP . . . . . . . . . . . . . . 16 - 7. Errors 17 - 8. Required SLP Messages 17 - 8.1. Service Request . . . . . . . . . . . . . . . . . . . 19 - 8.2. Service Reply . . . . . . . . . . . . . . . . . . . . 21 - 8.3. Service Registration . . . . . . . . . . . . . . . . . 22 - 8.4. Service Acknowledgment . . . . . . . . . . . . . . . . 23 - 8.5. Directory Agent Advertisement. . . . . . . . . . . . . 24 - 8.6. Service Agent Advertisement. . . . . . . . . . . . . . 25 - 9. Optional Features 26 - 9.1. Service Location Protocol Extensions . . . . . . . . . 27 - 9.2. Authentication Blocks . . . . . . . . . . . . . . . . 28 - 9.2.1. SLP Message Authentication Rules . . . . . . . 29 - 9.2.2. DSA with SHA-1 in Authentication Blocks . . . 30 - 9.3. Incremental Service Registration . . . . . . . . . . 30 - 9.4. Tag Lists . . . . . . . . . . . . . . . . . . . . . . 31 - 10. Optional SLP Messages 32 - 10.1. Service Type Request . . . . . . . . . . . . . . . . 32 - 10.2. Service Type Reply . . . . . . . . . . . . . . . . . 32 - 10.3. Attribute Request . . . . . . . . . . . . . . . . . . 33 - 10.4. Attribute Reply . . . . . . . . . . . . . . . . . . . 34 - 10.5. Attribute Request/Reply Examples . . . . . . . . . . . 34 - 10.6. Service Deregistration . . . . . . . . . . . . . . . 36 - 11. Scopes 37 - 11.1. Scope Rules . . . . . . . . . . . . . . . . . . . . . 37 - 11.2. Administrative and User Selectable Scopes. . . . . . . 38 - 12. Directory Agents 38 - 12.1. Directory Agent Rules . . . . . . . . . . . . . . . . 39 - 12.2. Directory Agent Discovery . . . . . . . . . . . . . . 39 - 12.2.1. Active DA Discovery . . . . . . . . . . . . . 40 - 12.2.2. Passive DA Advertising . . . . . . . . . . . . 40 - 12.3. Reliable Unicast to DAs and SAs. . . . . . . . . . . . 41 - 12.4. DA Scope Configuration . . . . . . . . . . . . . . . 41 - 12.5. DAs and Authentication Blocks. . . . . . . . . . . . . 41 - 13. Protocol Timing Defaults 42 - 14. Optional Configuration 43 - 15. IANA Considerations 44 - 16. Internationalization Considerations 45 - 17. Security Considerations 46 - A. Appendix: Changes to the Service Location Protocol from - v1 to v2 48 - B. Appendix: Service Discovery by Type: Minimal SLPv2 Features 48 - C. Appendix: DAAdverts with arbitrary URLs 49 - D. Appendix: SLP Protocol Extensions 50 - D.1. Required Attribute Missing Option . . . . . . . . . . 50 - - - -Guttman, et al. Standards Track [Page 2] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - E. Acknowledgments 50 - F. References 51 - G. Authors' Addresses 53 - H. Full Copyright Statement 54 - -1. Introduction - - The Service Location Protocol (SLP) provides a flexible and scalable - framework for providing hosts with access to information about the - existence, location, and configuration of networked services. - Traditionally, users have had to find services by knowing the name of - a network host (a human readable text string) which is an alias for a - network address. SLP eliminates the need for a user to know the name - of a network host supporting a service. Rather, the user supplies - the desired type of service and a set of attributes which describe - the service. Based on that description, the Service Location - Protocol resolves the network address of the service for the user. - - SLP provides a dynamic configuration mechanism for applications in - local area networks. Applications are modeled as clients that need - to find servers attached to any of the available networks within an - enterprise. For cases where there are many different clients and/or - services available, the protocol is adapted to make use of nearby - Directory Agents that offer a centralized repository for advertised - services. - - This document updates SLPv1 [RFC 2165], correcting protocol errors, - adding some enhancements and removing some requirements. This - specification has two parts. The first describes the required - features of the protocol. The second describes the extended features - of the protocol which are optional, and allow greater scalability. - -1.1. Applicability Statement - - SLP is intended to function within networks under cooperative - administrative control. Such networks permit a policy to be - implemented regarding security, multicast routing and organization of - services and clients into groups which are not be feasible on the - scale of the Internet as a whole. - - SLP has been designed to serve enterprise networks with shared - services, and it may not necessarily scale for wide-area service - discovery throughout the global Internet, or in networks where there - are hundreds of thousands of clients or tens of thousands of - services. - - - - - - -Guttman, et al. Standards Track [Page 3] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -2. Terminology - - User Agent (UA) - A process working on the user's behalf to establish - contact with some service. The UA retrieves service - information from the Service Agents or Directory Agents. - - Service Agent (SA) A process working on the behalf of one or more - services to advertise the services. - - Directory Agent (DA) A process which collects service - advertisements. There can only be one DA present per - given host. - - Service Type Each type of service has a unique Service Type - string. - - Naming Authority The agency or group which catalogues given - Service Types and Attributes. The default Naming - Authority is IANA. - - Scope A set of services, typically making up a logical - administrative group. - - URL A Universal Resource Locator [8]. - -2.1. Notation Conventions - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in RFC 2119 [9]. - - Syntax Syntax for string based protocols follow the - conventions defined for ABNF [11]. - - Strings All strings are encoded using the UTF-8 [23] - transformation of the Unicode [6] character set and - are NOT null terminated when transmitted. Strings - are preceded by a two byte length field. - - <string-list> A comma delimited list of strings with the - following syntax: - - string-list = string / string `,' string-list - - In format diagrams, any field ending with a \ indicates a variable - length field, given by a prior length field in the protocol. - - - - -Guttman, et al. Standards Track [Page 4] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -3. Protocol Overview - - The Service Location Protocol supports a framework by which client - applications are modeled as 'User Agents' and services are advertised - by 'Service Agents.' A third entity, called a 'Directory Agent' - provides scalability to the protocol. - - The User Agent issues a 'Service Request' (SrvRqst) on behalf of the - client application, specifying the characteristics of the service - which the client requires. The User Agent will receive a Service - Reply (SrvRply) specifying the location of all services in the - network which satisfy the request. - - The Service Location Protocol framework allows the User Agent to - directly issue requests to Service Agents. In this case the request - is multicast. Service Agents receiving a request for a service which - they advertise unicast a reply containing the service's location. - - +------------+ ----Multicast SrvRqst----> +---------------+ - | User Agent | | Service Agent | - +------------+ <----Unicast SrvRply------ +---------------+ - - In larger networks, one or more Directory Agents are used. The - Directory Agent functions as a cache. Service Agents send register - messages (SrvReg) containing all the services they advertise to - Directory Agents and receive acknowledgements in reply (SrvAck). - These advertisements must be refreshed with the Directory Agent or - they expire. User Agents unicast requests to Directory Agents - instead of Service Agents if any Directory Agents are known. - - +-------+ -Unicast SrvRqst-> +-----------+ <-Unicast SrvReg- +--------+ - | User | | Directory | |Service | - | Agent | | Agent | | Agent | - +-------+ <-Unicast SrvRply- +-----------+ -Unicast SrvAck-> +--------+ - - User and Service Agents discover Directory Agents two ways. First, - they issue a multicast Service Request for the 'Directory Agent' - service when they start up. Second, the Directory Agent sends an - unsolicited advertisement infrequently, which the User and Service - Agents listen for. In either case the Agents receive a DA - Advertisement (DAAdvert). - - +---------------+ --Multicast SrvRqst-> +-----------+ - | User or | <--Unicast DAAdvert-- | Directory | - | Service Agent | | Agent | - +---------------+ <-Multicast DAAdvert- +-----------+ - - - - - -Guttman, et al. Standards Track [Page 5] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - Services are grouped together using 'scopes'. These are strings - which identify services which are administratively identified. A - scope could indicate a location, administrative grouping, proximity - in a network topology or some other category. Service Agents and - Directory Agents are always assigned a scope string. - - A User Agent is normally assigned a scope string (in which case the - User Agent will only be able to discover that particular grouping of - services). This allows a network administrator to 'provision' - services to users. Alternatively, the User Agent may be configured - with no scope at all. In that case, it will discover all available - scopes and allow the client application to issue requests for any - service available on the network. - - +---------+ Multicast +-----------+ Unicast +-----------+ - | Service | <--SrvRqst-- | User | --SrvRqst-> | Directory | - | Agent | | Agent | | Agent | - | Scope=X | Unicast | Scope=X,Y | Unicast | Scope=Y | - +---------+ --SrvRply--> +-----------+ <-SrvRply-- +-----------+ - - In the above illustration, the User Agent is configured with scopes X - and Y. If a service is sought in scope X, the request is multicast. - If it is sought in scope Y, the request is unicast to the DA. - Finally, if the request is to be made in both scopes, the request - must be both unicast and multicast. - - Service Agents and User Agents may verify digital signatures provided - with DAAdverts. User Agents and Directory Agents may verify service - information registered by Service Agents. The keying material to use - to verify digital signatures is identified using a SLP Security - Parameter Index, or SLP SPI. - - Every host configured to generate a digital signature includes the - SLP SPI used to verify it in the Authentication Block it transmits. - Every host which can verify a digital signature must be configured - with keying material and other parameters corresponding with the SLP - SPI such that it can perform verifying calculations. - - SAs MUST accept multicast service requests and unicast service - requests. SAs MAY accept other requests (Attribute and Service Type - Requests). SAs MUST listen for multicast DA Advertisements. - - The features described up to this point are required to implement. A - minimum implementation consists of a User Agent, Service Agent or - both. - - There are several optional features in the protocol. Note that DAs - MUST support all these message types, but DA support is itself - - - -Guttman, et al. Standards Track [Page 6] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - optional to deploy on networks using SLP. UAs and SAs MAY support - these message types. These operations are primarily for interactive - use (browsing or selectively updating service registrations.) UAs - and SAs either support them or not depending on the requirements and - constraints of the environment where they will be used. - - Service Type Request A request for all types of service on the - network. This allows generic service browsers - to be built. - - Service Type Reply A reply to a Service Type Request. - - Attribute Request A request for attributes of a given type of - service or attributes of a given service. - - Attribute Reply A reply to an Attribute Request. - - Service Deregister A request to deregister a service or some - attributes of a service. - - Service Update A subsequent SrvRqst to an advertisement. - This allows individual dynamic attributes to - be updated. - - SA Advertisement In the absence of Directory Agents, a User - agent may request Service Agents in order - to discover their scope configuration. The - User Agent may use these scopes in requests. - - In the absence of Multicast support, Broadcast MAY be used. The - location of DAs may be staticly configured, discovered using SLP as - described above, or configured using DHCP. If a message is too large, - it may be unicast using TCP. - - A SLPv2 implementation SHOULD support SLPv1 [22]. This support - includes: - - 1. SLPv2 DAs are deployed, phasing out SLPv1 DAs. - - 2. Unscoped SLPv1 requests are considered to be of DEFAULT scope. - SLPv1 UAs MUST be reconfigured to have a scope if possible. - - 3. There is no way for an SLPv2 DA to behave as an unscoped SLPv1 - DA. SLPv1 SAs MUST be reconfigured to have a scope if possible. - - 4. SLPv2 DAs answer SLPv1 requests with SLPv1 replies and SLPv2 - requests with SLPv2 replies. - - - - -Guttman, et al. Standards Track [Page 7] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - 5. SLPv2 DAs use registrations from SLPv1 and SLPv2 in the same - way. That is, incoming requests from agents using either version - of the protocol will be matched against this common set of - registered services. - - 6. SLPv2 registrations which use Language Tags which are greater - than 2 characters long will be inaccessible to SLPv1 UAs. - - 7. SLPv2 DAs MUST return only service type strings in SrvTypeRply - messages which conform to SLPv1 service type string syntax, ie. - they MUST NOT return Service Type strings for abstract service - types. - - 8. SLPv1 SrvRqsts and AttrRqsts by Service Type do not match Service - URLs with abstract service types. They only match Service URLs - with concrete service types. - - SLPv1 UAs will not receive replies from SLPv2 SAs and SLPv2 UAs will - not receive replies from SLPv1 SAs. In order to interoperate UAs and - SAs of different versions require a SLPv2 DA to be present on the - network which supports both protocols. - - The use of abstract service types in SLPv2 presents a backward - compatibility issue for SLPv1. It is possible that a SLPv1 UA will - request a service type which is actually an abstract service type. - Based on the rules above, the SLPv1 UA will never receive an abstract - Service URL reply. For example, the service type 'service:x' in a - SLPv1 AttrRqst will not return the attributes of 'service:x:y://orb'. - If the request was made with SLPv2, it would return the attributes of - this service. - -4. URLs used with Service Location - - A Service URL indicates the location of a service. This URL may be - of the service: scheme [13] (reviewed in section 4.1), or any other - URL scheme conforming to the URI standard [8], except that URLs - without address specifications SHOULD NOT be advertised by SLP. The - service type for an 'generic' URL is its scheme name. For example, - the service type string for "http://www.srvloc.org" would be "http". - - Reserved characters in URLs follow the rules in RFC 2396 [8]. - - - - - - - - - - -Guttman, et al. Standards Track [Page 8] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -4.1. Service: URLs - - Service URL syntax and semantics are defined in [13]. Any network - service may be encoded in a Service URL. - - This section provides an introduction to Service URLs and an example - showing a simple application of them, representing standard network - services. - - A Service URL may be of the form: - - "service:"<srvtype>"://"<addrspec> - - The Service Type of this service: URL is defined to be the string up - to (but not including) the final `:' before <addrspec>, the address - specification. - - <addrspec> is a hostname (which should be used if possible) or dotted - decimal notation for a hostname, followed by an optional `:' and - port number. - - A service: scheme URL may be formed with any standard protocol name - by concatenating "service:" and the reserved port [1] name. For - example, "service:tftp://myhost" would indicate a tftp service. A - tftp service on a nonstandard port could be - "service:tftp://bad.glad.org:8080". - - Service Types SHOULD be defined by a "Service Template" [13], which - provides expected attributes, values and protocol behavior. An - abstract service type (also described in [13]) has the form - - "service:<abstract-type>:<concrete-type>". - - The service type string "service:<abstract-type>" matches all - services of that abstract type. If the concrete type is included - also, only these services match the request. For example: a SrvRqst - or AttrRqst which specifies "service:printer" as the Service Type - will match the URL service:printer:lpr://hostname and - service:printer:http://hostname. If the requests specified - "service:printer:http" they would match only the latter URL. - - An optional substring MAY follow the last `.' character in the - <srvtype> (or <abstract-type> in the case of an abstract service type - URL). This substring is the Naming Authority, as described in Section - 9.6. Service types with different Naming Authorities are quite - distinct. In other words, service:x.one and service:x.two are - different service types, as are service:abstract.one:y and - service:abstract.two:y. - - - -Guttman, et al. Standards Track [Page 9] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -4.2. Naming Authorities - - A Naming Authority MAY optionally be included as part of the Service - Type string. The Naming Authority of a service defines the meaning - of the Service Types and attributes registered with and provided by - Service Location. The Naming Authority itself is typically a string - which uniquely identifies an organization. IANA is the implied - Naming Authority when no string is appended. "IANA" itself MUST NOT - be included explicitly. - - Naming Authorities may define Service Types which are experimental, - proprietary or for private use. Using a Naming Authority, one may - either simply ignore attributes upon registration or create a local- - use only set of attributes for one's site. The procedure to use is - to create a 'unique' Naming Authority string and then specify the - Standard Attribute Definitions as described above. This Naming - Authority will accompany registration and queries, as described in - Sections 8.1 and 8.3. Service Types SHOULD be registered with IANA - to allow for Internet-wide interoperability. - -4.3. URL Entries - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Reserved | Lifetime | URL Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |URL len, contd.| URL (variable length) \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |# of URL auths | Auth. blocks (if any) \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - SLP stores URLs in protocol elements called URL Entries, which - associate a length, a lifetime, and possibly authentication - information along with the URL. URL Entries, defined as shown above, - are used in Service Replies and Service Registrations. - -5. Service Attributes - - A service advertisement is often accompanied by Service Attributes. - These attributes are used by UAs in Service Requests to select - appropriate services. - - The allowable attributes which may be used are typically specified by - a Service Template [13] for a particular service type. Services - which are advertised according to a standard template MUST register - all service attributes which the standard template requires. URLs - with schemes other than "service:" MAY be registered with attributes. - - - -Guttman, et al. Standards Track [Page 10] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - Non-standard attribute names SHOULD begin with "x-", because no - standard attribute name will ever have those initial characters. - - An attribute list is a string encoding of the attributes of a - service. The following ABNF [11] grammar defines attribute lists: - - attr-list = attribute / attribute `,' attr-list - attribute = `(' attr-tag `=' attr-val-list `)' / attr-tag - attr-val-list = attr-val / attr-val `,' attr-val-list - attr-tag = 1*safe-tag - attr-val = intval / strval / boolval / opaque - intval = [-]1*DIGIT - strval = 1*safe-val - boolval = "true" / "false" - opaque = "\FF" 1*escape-val - safe-val = ; Any character except reserved. - safe-tag = ; Any character except reserved, star and bad-tag. - reserved = `(' / `)' / `,' / `\' / `!' / `<' / `=' / `>' / `~' / CTL - escape-val = `\' HEXDIG HEXDIG - bad-tag = CR / LF / HTAB / `_' - star = `*' - - The <attr-list>, if present, MUST be scanned prior to evaluation for - all occurrences of the escape character `\'. Reserved characters - MUST be escaped (other characters MUST NOT be escaped). All escaped - characters must be restored to their value before attempting string - matching. For Opaque values, escaped characters are not converted - - they are interpreted as bytes. - - Boolean Strings which have the form "true" or "false" can - only take one value and may only be compared with - '='. Booleans are case insensitive when compared. - - Integer Strings which take the form [-] 1*<digit> and fall - in the range "-2147483648" to "2147483647" are - considered to be Integers. These are compared using - integer comparison. - - String All other Strings are matched using strict lexical - ordering (see Section 6.4). - - Opaque Opaque values are sequences of bytes. These are - distinguished from Strings since they begin with - the sequence "\FF". This, unescaped, is an illegal - UTF-8 encoding, indicating that what follows is a - sequence of bytes expressed in escape notation which - constitute the binary value. For example, a '0' byte - is encoded "\FF\00". - - - -Guttman, et al. Standards Track [Page 11] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - A string which contains escaped values other than from the reserved - set of characters is illegal. If such a string is included in an - <attr-list>, <tag-list> or search filter, the SA or DA which receives - it MUST return a PARSE_ERROR to the message. - - A keyword has only an <attr-tag>, and no values. Attributes can have - one or multiple values. All values are expressed as strings. - - When values have been advertised by a SA or are registered in a DA, - they can take on implicit typing rules for matching incoming - requests. - - Stored values must be consistent, i.e., x=4,true,sue,\ff\00\00 is - disallowed. A DA or SA receiving such an <attr-list> MUST return an - INVALID_REGISTRATION error. - -6. Required Features - - This section defines the minimal implementation requirements for SAs - and UAs as well as their interaction with DAs. A DA is not required - for SLP to function, but if it is present, the UA and SA MUST - interact with it as defined below. - - A minimal implementation may consist of either a UA or SA or both. - The only required features of a UA are that it can issue SrvRqsts - according to the rules below and interpret DAAdverts, SAAdverts and - SrvRply messages. The UA MUST issue requests to DAs as they are - discovered. An SA MUST reply to appropriate SrvRqsts with SrvRply or - SAAdvert messages. The SA MUST also register with DAs as they are - discovered. - - UAs perform discovery by issuing Service Request messages. SrvRqst - messages are issued, using UDP, following these prioritized rules: - - 1. A UA issues a request to a DA which it has been configured with - by DHCP. - - 2. A UA issues requests to DAs which it has been statically - configured with. - - 3. UA uses multicast/convergence SrvRqsts to discover DAs, then uses - that set of DAs. A UA that does not know of any DAs SHOULD retry - DA discovery, increasing the waiting interval between subsequent - attempts exponentially (doubling the wait interval each time.) - The recommended minimum waiting interval is CONFIG_DA_FIND - seconds. - - - - - -Guttman, et al. Standards Track [Page 12] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - 4. A UA with no knowledge of DAs sends requests using multicast - convergence to SAs. SAs unicast replies to UAs according to the - multicast convergence algorithm. - - UAs and SAs are configured with a list of scopes to use according to - these prioritized rules: - - 1. With DHCP. - - 2. With static configuration. The static configuration may be - explicitly set to NO SCOPE for UAs, if the User Selectable Scope - model is used. See section 11.2. - - 3. In the absence of configuration, the agent's scope is "DEFAULT". - - A UA MUST issue requests with one or more of the scopes it has been - configured to use. - - A UA which has been statically configured with NO SCOPE LIST will use - DA or SA discovery to determine its scope list dynamically. In this - case it uses an empty scope list to discover DAs and possibly SAs. - Then it uses the scope list it obtains from DAAdverts and possibly - SAAdverts in subsequent requests. - - The SA MUST register all its services with any DA it discovers, if - the DA advertises any of the scopes it has been configured with. A - SA obtains information about DAs as a UA does. In addition, the SA - MUST listen for multicast unsolicited DAAdverts. The SA registers by - sending SrvReg messages to DAs, which reply with SrvReg messages to - indicate success. SAs register in ALL the scopes they were - configured to use. - -6.1. Use of Ports, UDP, and Multicast - - DAs MUST accept unicast requests and multicast directory agent - discovery service requests (for the service type "service:directory- - agent"). - - SAs MUST accept multicast requests and unicast requests both. The SA - can distinguish between them by whether the REQUEST MCAST flag is set - in the SLP Message header. - - The Service Location Protocol uses multicast for discovering DAs and - for issuing requests to SAs by default. - - The reserved listening port for SLP is 427. This is the destination - port for all SLP messages. SLP messages MAY be transmitted on an - ephemeral port. Replies and acknowledgements are sent to the port - - - -Guttman, et al. Standards Track [Page 13] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - from which the request was issued. The default maximum transmission - unit for UDP messages is 1400 bytes excluding UDP and other headers. - - If a SLP message does not fit into a UDP datagram it MUST be - truncated to fit, and the OVERFLOW flag is set in the reply message. - A UA which receives a truncated message MAY open a TCP connection - (see section 6.2) with the DA or SA and retransmit the request, using - the same XID. It MAY also attempt to make use of the truncated reply - or reformulate a more restrictive request which will result in a - smaller reply. - - SLP Requests messages are multicast to The Administratively Scoped - SLP Multicast [17] address, which is 239.255.255.253. The default - TTL to use for multicast is 255. - - In isolated networks, broadcasts will work in place of multicast. To - that end, SAs SHOULD and DAs MUST listen for broadcast Service - Location messages at port 427. This allows UAs which do not support - multicast the use of Service Location on isolated networks. - - Setting multicast TTL to less than 255 (the default) limits the range - of SLP discovery in a network, and localizes service information in - the network. - -6.2. Use of TCP - - A SrvReg or SrvDeReg may be too large to fit into a datagram. To - send such large SLP messages, a TCP (unicast) connection MUST be - established. - - To avoid the need to implement TCP, one MUST insure that: - - - UAs never issue requests larger than the Path MTU. SAs can omit - TCP support only if they never have to receive unicast requests - longer than the path MTU. - - - UAs can accept replies with the 'OVERFLOW' flag set, and make use - of the first result included, or reformulate the request. - - - Ensure that a SA can send a SrvRply, SrvReg, or SrvDeReg in - a single datagram. This means limiting the size of URLs, - the number of attributes and the number of authenticators - transmitted. - - DAs MUST be able to respond to UDP and TCP requests, as well as - multicast DA Discovery SrvRqsts. SAs MUST be able to respond to TCP - unless the SA will NEVER receive a request or send a reply which will - exceed a datagram in size (e.g., some embedded systems). - - - -Guttman, et al. Standards Track [Page 14] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - A TCP connection MAY be used for a single SLP transaction, or for - multiple transactions. Since there are length fields in the message - headers, SLP Agents can send multiple requests along a connection and - read the return stream for acknowledgments and replies. - - The initiating agent SHOULD close the TCP connection. The DA SHOULD - wait at least CONFIG_CLOSE_CONN seconds before closing an idle - connection. DAs and SAs SHOULD close an idle TCP connection after - CONFIG_CLOSE_CONN seconds to ensure robust operation, even when the - initiating agent neglects to close it. See Section 13 for timing - rules. - -6.3. Retransmission of SLP messages - - Requests which fail to elicit a response are retransmitted. The - initial retransmission occurs after a CONFIG_RETRY wait period. - Retransmissions MUST be made with exponentially increasing wait - intervals (doubling the wait each time). This applies to unicast as - well as multicast SLP requests. - - Unicast requests to a DA or SA should be retransmitted until either a - response (which might be an error) has been obtained, or for - CONFIG_RETRY_MAX seconds. - - Multicast requests SHOULD be reissued over CONFIG_MC_MAX seconds - until a result has been obtained. UAs need only wait till they - obtain the first reply which matches their request. That is, - retransmission is not required if the requesting agent is prepared to - use the 'first reply' instead of 'as many replies as possible within - a bounded time interval.' - - When SLP SrvRqst, SrvTypeRqst, and AttrRqst messages are multicast, - they contain a <PRList> of previous responders. Initially the - <PRList> is empty. When these requests are unicast, the <PRList> is - always empty. - - Any DA or SA which sees its address in the <PRList> MUST NOT respond - to the request. - - The message SHOULD be retransmitted until the <PRList> causes no - further responses to be elicited or the previous responder list and - the request will not fit into a single datagram or until - CONFIG_MC_MAX seconds elapse. - - UAs which retransmit a request use the same XID. This allows a DA or - SA to cache its reply to the original request and then send it again, - should a duplicate request arrive. This cached information should - only be held very briefly. XIDs SHOULD be randomly chosen to avoid - - - -Guttman, et al. Standards Track [Page 15] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - duplicate XIDs in requests if UAs restart frequently. - -6.4. Strings in SLP messages - - The escape character is a backslash (UTF-8 0x5c) followed by the two - hexadecimal digits of the escaped character. Only reserved - characters are escaped. For example, a comma (UTF-8 0x29) is escaped - as `\29', and a backslash `\' is escaped as `\5c'. String lists used - in SLP define the comma to be the delimiter between list elements, so - commas in data strings must be escaped in this manner. Backslashes - are the escape character so they also must always be escaped when - included in a string literally. - - String comparison for order and equality in SLP MUST be case - insensitive inside the 0x00-0x7F subrange of UTF-8 (which corresponds - to ASCII character encoding). Case insensitivity SHOULD be supported - throughout the entire UTF-8 encoded Unicode [6] character set. - - The case insensitivity rule applies to all string matching in SLPv2, - including Scope strings, SLP SPI strings, service types, attribute - tags and values in query handling, language tags, previous responder - lists. Comparisons of URL strings, however, is case sensitive. - - White space (SPACE, CR, LF, TAB) internal to a string value is folded - to a single SPACE character for the sake of string comparisons. - White space preceding or following a string value is ignored for the - purposes of string comparison. For example, " Some String " - matches "SOME STRING". - - String comparisons (using comparison operators such as `<=' or `>=') - are done using lexical ordering in UTF-8 encoded characters, not - using any language specific rules. - - The reserved character `*' may precede, follow or be internal to a - string value in order to indicate substring matching. The query - including this character matches any character sequence which - conforms to the letters which are not wildcarded. - -6.4.1. Scope Lists in SLP - - Scope Lists in SLPv2 have the following grammar: - - scope-list = scope-val / scope-val `,' scope-list - scope-val = 1*safe - safe = ; Any character except reserved. - reserved = `(' / `)' / `,' / `\' / `!' / `<' / `=' / `>' / `~' / CTL - / `;' / `*' / `+' - escape-val = `\' HEXDIG HEXDIG - - - -Guttman, et al. Standards Track [Page 16] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - Scopes which include any reserved characters must replace the escaped - character with the escaped-val format. - -7. Errors - - If the Error Code in a SLP reply message is nonzero, the rest of the - message MAY be truncated. No data is necessarily transmitted or - should be expected after the header and the error code, except - possibly for some optional extensions to clarify the error, for - example as in section D.1. - - Errors are only returned for unicast requests. Multicast requests - are silently discarded if they result in an error. - - LANGUAGE_NOT_SUPPORTED = 1: There is data for the service type in - the scope in the AttrRqst or SrvRqst, but not in the requested - language. - PARSE_ERROR = 2: The message fails to obey SLP syntax. - INVALID_REGISTRATION = 3: The SrvReg has problems -- e.g., a zero - lifetime or an omitted Language Tag. - SCOPE_NOT_SUPPORTED = 4: The SLP message did not include a scope in - its <scope-list> supported by the SA or DA. - AUTHENTICATION_UNKNOWN = 5: The DA or SA receives a request for an - unsupported SLP SPI. - AUTHENTICATION_ABSENT = 6: The DA expected URL and ATTR - authentication in the SrvReg and did not receive it. - AUTHENTICATION_FAILED = 7: The DA detected an authentication error in - an Authentication block. - VER_NOT_SUPPORTED = 9: Unsupported version number in message header. - INTERNAL_ERROR = 10: The DA (or SA) is too sick to respond. - DA_BUSY_NOW = 11: UA or SA SHOULD retry, using exponential back off. - OPTION_NOT_UNDERSTOOD = 12: The DA (or SA) received an unknown option - from the mandatory range (see section 9.1). - INVALID_UPDATE = 13: The DA received a SrvReg without FRESH set, for - an unregistered service or with inconsistent Service Types. - MSG_NOT_SUPPORTED = 14: The SA received an AttrRqst or SrvTypeRqst - and does not support it. - REFRESH_REJECTED = 15: The SA sent a SrvReg or partial SrvDereg to a - DA more frequently than the DA's min-refresh-interval. - -8. Required SLP Messages - - All length fields in SLP messages are in network byte order. Where ' - tuples' are defined, these are sequences of bytes, in the precise - order listed, in network byte order. - - SLP messages all begin with the following header: - - - - -Guttman, et al. Standards Track [Page 17] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Version | Function-ID | Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length, contd.|O|F|R| reserved |Next Ext Offset| - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Next Extension Offset, contd.| XID | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Language Tag Length | Language Tag \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Message Type Abbreviation Function-ID - - Service Request SrvRqst 1 - Service Reply SrvRply 2 - Service Registration SrvReg 3 - Service Deregister SrvDeReg 4 - Service Acknowledge SrvAck 5 - Attribute Request AttrRqst 6 - Attribute Reply AttrRply 7 - DA Advertisement DAAdvert 8 - Service Type Request SrvTypeRqst 9 - Service Type Reply SrvTypeRply 10 - SA Advertisement SAAdvert 11 - - SAs and UAs MUST support SrvRqst, SrvRply and DAAdvert. SAs MUST - also support SrvReg, SAAdvert and SrvAck. For UAs and SAs, support - for other messages are OPTIONAL. - - - Length is the length of the entire SLP message, header included. - - The flags are: OVERFLOW (0x80) is set when a message's length - exceeds what can fit into a datagram. FRESH (0x40) is set on - every new SrvReg. REQUEST MCAST (0x20) is set when multicasting - or broadcasting requests. Reserved bits MUST be 0. - - Next Extension Offset is set to 0 unless extensions are used. - The first extension begins at 'offset' bytes, from the message's - beginning. It is placed after the SLP message data. See - Section 9.1 for how to interpret unrecognized SLP Extensions. - - XID is set to a unique value for each unique request. If the - request is retransmitted, the same XID is used. Replies set - the XID to the same value as the xid in the request. Only - unsolicited DAAdverts are sent with an XID of 0. - - Lang Tag Length is the length in bytes of the Language Tag field. - - Language Tag conforms to [7]. The Language Tag in a reply MUST - be the same as the Language Tag in the request. This field must - be encoded 1*8ALPHA *("-" 1*8ALPHA). - - - - -Guttman, et al. Standards Track [Page 18] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - If an option is specified, and not included in the message, the - receiver MUST respond with a PARSE_ERROR. - -8.1. Service Request - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Service Location header (function = SrvRqst = 1) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of <PRList> | <PRList> String \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of <service-type> | <service-type> String \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of <scope-list> | <scope-list> String \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of predicate string | Service Request <predicate> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of <SLP SPI> string | <SLP SPI> String \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - In order for a Service to match a SrvRqst, it must belong to at least - one requested scope, support the requested service type, and match - the predicate. If the predicate is present, the language of the - request (ignoring the dialect part of the Language Tag) must match - the advertised service. - - <PRList> is the Previous Responder List. This <string-list> contains - dotted decimal notation IP (v4) addresses, and is iteratively - multicast to obtain all possible results (see Section 6.3). UAs - SHOULD implement this discovery algorithm. SAs MUST use this to - discover all available DAs in their scope, if they are not already - configured with DA addresses by some other means. - - A SA silently drops all requests which include the SA's address in - the <PRList>. An SA which has multiple network interfaces MUST check - if any of the entries in the <PRList> equal any of its interfaces. - An entry in the PRList which does not conform to an IPv4 dotted - decimal address is ignored: The rest of the <PRList> is processed - normally and an error is not returned. - - Once a <PRList> plus the request exceeds the path MTU, multicast - convergence stops. This algorithm is not intended to find all - instances; it finds 'enough' to provide useful results. - - The <scope-list> is a <string-list> of configured scope names. SAs - and DAs which have been configured with any of the scopes in this - list will respond. DAs and SAs MUST reply to unicast requests with a - - - -Guttman, et al. Standards Track [Page 19] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - SCOPE_NOT_SUPPORTED error if the <scope-list> is omitted or fails to - include a scope they support (see Section 11). The only exceptions - to this are described in Section 11.2. - - The <service-type> string is discussed in Section 4. Normally, a - SrvRqst elicits a SrvRply. There are two exceptions: If the - <service-type> is set to "service:directory-agent", DAs respond to - the SrvRqst with a DAAdvert (see Section 8.5.) If set to - "service:service-agent", SAs respond with a SAAdvert (see Section - 8.6.) If this field is omitted, a PARSE_ERROR is returned - as this - field is REQUIRED. - - The <predicate> is a LDAPv3 search filter [14]. This field is - OPTIONAL. Services may be discovered simply by type and scope. - Otherwise, services are discovered which satisfy the <predicate>. If - present, it is compared to each registered service. If the attribute - in the filter has been registered with multiple values, the filter is - compared to each value and the results are ORed together, i.e., - "(x=3)" matches a registration of (x=1,2,3); "(!(Y=0))" matches - (y=0,1) since Y can be nonzero. Note the matching is case - insensitive. Keywords (i.e., attributes without values) are matched - with a "presence" filter, as in "(keyword=*)". - - An incoming request term MUST have the same type as the attribute in - a registration in order to match. Thus, "(x=33)" will not match ' - x=true', etc. while "(y=foo)" will match 'y=FOO'. - "(|(x=33)(y=foo))" will be satisfied, even though "(x=33)" cannot be - satisfied, because of the `|' (boolean disjunction). - - Wildcard matching MUST be done with the '=' filter. In any other - case, a PARSE_ERROR is returned. Request terms which include - wildcards are interpreted to be Strings. That is, (x=34*) would - match 'x=34foo', but not 'x=3432' since the first value is a String - while the second value is an Integer; Strings don't match Integers. - - Examples of Predicates follow. <t> indicates the service type of the - SrvRqst, <s> gives the <scope-list> and <p> is the predicate string. - - <t>=service:http <s>=DEFAULT <p>= (empty string) - This is a minimal request string. It matches all http - services advertised with the default scope. - - <t>=service:pop3 <s>=SALES,DEFAULT <p>=(user=wump) - This is a request for all pop3 services available in - the SALES or DEFAULT scope which serve mail to the user - `wump'. - - - - - -Guttman, et al. Standards Track [Page 20] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - <t>=service:backup <s>=BLDG 32 <p>=(&(q<=3)(speed>=1000)) - This returns the backup service which has a queue length - less than 3 and a speed greater than 1000. It will - return this only for services registered with the BLDG 32 - scope. - - <t>=service:directory-agent <s>=DEFAULT <p>= - This returns DAAdverts for all DAs in the DEFAULT scope. - - DAs are discovered by sending a SrvRqst with the service type set to - "service:directory-agent". If a predicate is included in the - SrvRqst, the DA SHOULD respond only if the predicate can be satisfied - with the DA's attributes. The <scope-list> MUST contain all scopes - configured for the UA or SA which is discovering DAs. - - The <SLP SPI> string indicates a SLP SPI that the requester has been - configured with. If this string is omitted, the responder does not - include any Authentication Blocks in its reply. If it is included, - the responder MUST return a reply which has an associated - authentication block with the SLP SPI in the SrvRqst. If no replies - may be returned because the SLP SPI is not supported, the responder - returns an AUTHENTICATION_UNKNOWN error. - -8.2. Service Reply - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Service Location header (function = SrvRply = 2) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Error Code | URL Entry count | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | <URL Entry 1> ... <URL Entry N> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The service reply contains zero or more URL entries (see Section - 4.3). A service reply with zero URL entries MUST be returned in - response to a unicast Service Request, if no matching URLs are - present. A service reply with zero URL entries MUST NOT be sent in - response to a multicast or broadcast service request (instead, if - there was no match found or an error processing the request, the - service reply should not be generated at all). - - If the reply overflows, the UA MAY simply use the first URL Entry in - the list. A URL obtained by SLP may not be cached longer than - Lifetime seconds, unless there is a URL Authenticator block present. - - - - - -Guttman, et al. Standards Track [Page 21] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - In that case, the cache lifetime is indicated by the Timestamp in the - URL Authenticator (see Section 9.2). - - An authentication block is returned in the URL Entries, including the - SLP SPI in the SrvRqst. If no SLP SPI was included in the request, - no Authentication Blocks are returned in the reply. URL - Authentication Blocks are defined in Section 9.2.1. - - If a SrvRply is sent by UDP, a URL Entry MUST NOT be included unless - it fits entirely without truncation. - -8.3. Service Registration - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Service Location header (function = SrvReg = 3) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | <URL-Entry> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of service type string | <service-type> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of <scope-list> | <scope-list> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of attr-list string | <attr-list> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |# of AttrAuths |(if present) Attribute Authentication Blocks...\ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The <entry> is a URL Entry (see section 4.3). The Lifetime defines - how long a DA can cache the registration. SAs SHOULD reregister - before this lifetime expires (but SHOULD NOT more often than once per - second). The Lifetime MAY be set to any value between 0 and 0xffff - (maximum, around 18 hours). Long-lived registrations remain stale - longer if the service fails and the SA does not deregister the - service. - - The <service-type> defines the service type of the URL to be - registered, regardless of the scheme of the URL. The <scope-list> - MUST contain the names of all scopes configured for the SA, which the - DA it is registering with supports. The default value for the - <scope-list> is "DEFAULT" (see Section 11). - - The SA MUST register consistently with all DAs. If a SA is - configured with scopes X and Y and there are three DAs, whose scopes - are "X", "Y" and "X,Y" respectively, the SA will register the with - all three DAs in their respective scopes. All future updates and - deregistrations of the service must be sent to the same set of DAs in - - - -Guttman, et al. Standards Track [Page 22] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - the same scopes the service was initially registered in. - - The <attr-list>, if present, specifies the attributes and values to - be associated with the URL by the DA (see Section 5). - - A SA configured with the ability to sign service registrations MUST - sign each of the URLs and Attribute Lists using each of the keys it - is configured to use, and the DA it is registering with accepts. - (The SA MUST acquire DAAdverts for all DAs it will register with to - obtain the DA's SLP SPI list and attributes, as described in Section - 8.5). The SA supplies a SLP SPI in each authentication block - indicating the SLP SPI configuration required to verify the digital - signature. The format of the digital signatures used is defined in - section 9.2.1. - - Subsequent registrations of previously registered services MUST - contain the same list of SLP SPIs as previous ones or else DAs will - reject them, replying with an AUTHENTICATION_ABSENT error. - - A registration with the FRESH flag set will replace *entirely* any - previous registration for the same URL in the same language. If the - FRESH flag is not set, the registration is an "incremental" - registration (see Section 9.3). - -8.4. Service Acknowledgment - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Service Location header (function = SrvAck = 5) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Error Code | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - A DA returns a SrvAck to an SA after a SrvReg. It carries only a two - byte Error Code (see Section 7). - - - - - - - - - - - - - - - -Guttman, et al. Standards Track [Page 23] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -8.5. Directory Agent Advertisement - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Service Location header (function = DAAdvert = 8) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Error Code | DA Stateless Boot Timestamp | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |DA Stateless Boot Time,, contd.| Length of URL | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - \ URL \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length of <scope-list> | <scope-list> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length of <attr-list> | <attr-list> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length of <SLP SPI List> | <SLP SPI List> String \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | # Auth Blocks | Authentication block (if any) \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The Error Code is set to 0 when the DAAdvert is multicast. If the - DAAdvert is being returned due to a unicast SrvRqst (ie. a request - without the REQUEST MCAST flag set) the DA returns the same errors a - SrvRply would. - - The <scope-list> of the SrvRqst must either be omitted or include a - scope which the DA supports. The DA Stateless Boot Timestamp - indicates the state of the DA (see section 12.1). - - The DA MAY include a list of its attributes in the DAAdvert. This - list SHOULD be kept short, as the DAAdvert must fit into a datagram - in order to be multicast. - - A potential scaling problem occurs in SLPv2 if SAs choose too low a - Lifetime. In this case, an onerous amount of reregistration occurs - as more services are deployed. SLPv2 allows DAs to control SAs - frequency of registration. A DA MAY reissue a DAAdvert with a new - set of attributes at any time, to change the reregistration behavior - of SAs. These apply only to subsequent registrations; existing - service registrations with the DA retain their registered lifetimes. - - If the DAAdvert includes the attribute "min-refresh-interval" it MUST - be set to a single Integer value indicating a number of seconds. If - this attribute is present SAs MUST NOT refresh any particular service - advertisement more frequently than this value. If SrvReg with the - FRESH FLAG not set or SrvDereg with a non-empty tag list updating a - - - -Guttman, et al. Standards Track [Page 24] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - particular service are received more often than the value for the - DA's advertised "min-refresh-interval" attribute the DA SHOULD reject - the message and return a REFRESH_REJECTED error in the SrvAck. - - The URL is "service:directory-agent://"<addr> of the DA, where <addr> - is the dotted decimal numeric address of the DA. The <scope-list> of - the DA MUST NOT be NULL. - - The SLP SPI List is the list of SPIs that the DA is capable of - verifying. SAs MUST NOT register services with authentication blocks - for those SLP SPIs which are not on the list. DAs will reject - service registrations which they cannot verify, returning an - AUTHENTICATION_UNKNOWN error. - - The format of DAAdvert signatures is defined in Section 9.2.1. - - The SLP SPI which is used to verify the DAAdvert is included in the - Authentication Block. When DAAdverts are multicast, they may have to - transmit multiple DAAdvert Authentication Blocks. If the DA is - configured to be able to generate signatures for more than one SPI, - the DA MUST include one Authentication Block for each SPI. If all - these Authentication Blocks do not fit in a single datagram (to - multicast or broadcast) the DA MUST send separate DAAdverts so that - Authentication Blocks for all the SPIs the DA is capable of - generating are sent. - - If the DAAdvert is being sent in response to a SrvRqst, the DAAdvert - contains only the authentication block with the SLP SPI in the - SrvRqst, if the DA is configured to be able to produce digital - signatures using that SLP SPI. If the SrvRqst is unicast to the DA - (the REQUEST MCAST flag in the header is not set) and an unsupported - SLP SPI is included, the DA replies with a DAAdvert with the Error - Code set to an AUTHENTICATION_UNKNOWN error. - - UAs SHOULD be configured with SLP SPIs that will allow them to verify - DA Advertisements. If the UA is configured with SLP SPIs and - receives a DAAdvert which fails to be verified using one of them, the - UA MUST discard it. - -8.6. Service Agent Advertisement - - User Agents MUST NOT solicit SA Advertisements if they have been - configured to use a particular DA, if they have been configured with - a <scope-list> or if DAs have been discovered. UAs solicit SA - Advertisements only when they are explicitly configured to use User - Selectable scopes (see Section 11.2) in order to discover the scopes - that SAs support. This allows UAs without scope configuration to - make use of either DAs or SAs without any functional difference - - - -Guttman, et al. Standards Track [Page 25] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - except performance. - - A SA MAY be configured with attributes, and SHOULD support the - attribute 'service-type' whose value is all the service types of - services represented by the SA. SAs MUST NOT respond if the SrvRqst - predicate is not satisfied. For example, only SAs offering 'nfs' - services SHOULD respond with a SAAdvert to a SrvRqst for service type - "service:service-agent" which includes a predicate "(service- - type=nfs)". - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Service Location header (function = SAAdvert = 11) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length of URL | URL \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length of <scope-list> | <scope-list> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length of <attr-list> | <attr-list> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | # auth blocks | authentication block (if any) \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The SA responds only to multicast SA discovery requests which either - include no <scope-list> or a scope which they are configured to use. - - The SAAdvert MAY include a list of attributes the SA supports. This - attribute list SHOULD be kept short so that the SAAdvert will not - exceed the path MTU in size. - - The URL is "service:service-agent://"<addr> of the SA, where <addr> - is the dotted decimal numeric address of the SA. The <scope-list> of - the SA MUST NOT be null. - - The SAAdvert contains one SAAdvert Authentication block for each SLP - SPI the SA can produce Authentication Blocks for. If the UA can - verify the Authentication Block of the SAAdvert, and the SAAdvert - fails to be verified, the UA MUST discard it. - -9. Optional Features - - The features described in this section are not mandatory. Some are - useful for interactive use of SLP (where a user rather than a program - will select services, using a browsing interface for example) and for - scalability of SLP to larger networks. - - - - - -Guttman, et al. Standards Track [Page 26] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -9.1. Service Location Protocol Extensions - - The format of a Service Location Extension is: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Extension ID | Next Extension Offset | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Offset, contd.| Extension Data \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Extension IDs are assigned in the following way: - - 0x0000-0x3FFF Standardized. Optional to implement. Ignore if - unrecognized. - 0x4000-0x7FFF Standardized. Mandatory to implement. A UA or SA - which receives this option in a reply and does not understand - it MUST silently discard the reply. A DA or SA which receives - this option in a request and does not understand it MUST return - an OPTION_NOT_UNDERSTOOD error. - 0x8000-0x8FFF For private use (not standardized). Optional to - implement. Ignore if unrecognized. - 0x9000-0xFFFF Reserved. - - The three byte offset to next extension indicates the position of the - next extension as offset from the beginning of the SLP message. - - The offset value is 0 if there are no extensions following the - current extension. - - If the offset is 0, the length of the current Extension Data is - determined by subtracting total length of the SLP message as given in - the SLP message header minus the offset of the current extension. - - Extensions defined in this document are in Section D. See section 15 - for procedures that are required when specifying new SLP extensions. - - - - - - - - - - - - - - -Guttman, et al. Standards Track [Page 27] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -9.2. Authentication Blocks - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Block Structure Descriptor | Authentication Block Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Timestamp | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | SLP SPI String Length | SLP SPI String \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Structured Authentication Block ... \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Authentication blocks are returned with certain SLP messages to - verify that the contents have not been modified, and have been - transmitted by an authorized agent. The authentication data - (contained in the Structured Authentication Block) is typically case - sensitive. Even though SLP registration data (e.g., attribute - values) are typically are not case sensitive, the case of the - registration data has to be preserved by the registering DA so that - UAs will be able to verify the data used for calculating digital - signature data. - - The Block Structure Descriptor (BSD) identifies the format of the - Authenticator which follows. BSDs 0x0000-0x7FFF will be maintained - by IANA. BSDs 0x8000-0x8FFF are for private use. - - The Authentication Block Length is the length of the entire block, - starting with the BSD. - - The Timestamp is the time that the authenticator expires (to prevent - replay attacks.) The Timestamp is a 32-bit unsigned fixed-point - number of seconds relative to 0h on 1 January 1970. SAs use this - value to indicate when the validity of the digital signature expires. - This Timestamp will wrap back to 0 in the year 2106. Once the value - of the Timestamp wraps, the time at which the Timestamp is relative - to resets. For example, after 06h28 and 16 seconds 5 February 2106, - all Timestamp values will be relative to that epoch date. - - The SLP Security Parameters Index (SPI) string identifies the key - length, algorithm parameters and keying material to be used by agents - to verify the signature data in the Structured Authentication Block. - The SLP SPI string has the same grammar as the <scope-val> defined in - Section 6.4.1. - - Reserved characters in SLP SPI strings must be escaped using the same - convention as used throughout SLPv2. - - - -Guttman, et al. Standards Track [Page 28] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - SLP SPIs deployed in a site MUST be unique. An SLP SPI used for - BSD=0x0002 must not be the same as used for some other BSD. - - All SLP agents MUST implement DSA [20] (BSD=0x0002). SAs MUST - register services with DSA authentication blocks, and they MAY - register them with other authentication blocks using other - algorithms. SAs MUST use DSA authentication blocks in SrvDeReg - messages and DAs MUST use DSA authentication blocks in unsolicited - DAAdverts. - -9.2.1. SLP Message Authentication Rules - - The sections below define how to calculate the value to apply to the - algorithm identified by the BSD value. The components listed are - used as if they were a contiguous single byte aligned buffer in the - order given. - - URL - 16-bit Length of SLP SPI String, SLP SPI String. - 16-bit Length of URL, URL, - 32-bit Timestamp. - - Attribute List - 16-bit Length of SLP SPI String, SLP SPI String, - 16-bit length of <attr-list>, <attr-list>, - 32-bit Timestamp. - - DAAdvert - 16-bit Length of SLP SPI String, SLP SPI String, - 32-bit DA Stateless Boot Timestamp, - 16-bit Length of URL, URL, - 16-bit Length of <attr-list>, <attr-list>, - 16-bit Length of DA's <scope-list>, DA's <scope-list>, - 16-bit Length of DA's <SLP SPI List>, DA's <SLP SPI List>, - 32-bit Timestamp. - - The first SLP SPI is the SLP SPI in the Authentication - Block. This SLP SPI indicates the keying material and other - parameters to use to verify the DAAdvert. The SLP SPI List is - the list of SLP SPIs the DA itself supports, and is able to - verify. - - SAAdvert - 16-bit Length of SLP SPI String, SLP SPI String, - 16-bit Length of URL, URL, - 16-bit Length of <attr-list>, <attr-list>, - 16-bit Length of <scope-list>, <scope-list>, - 32-bit Timestamp. - - - -Guttman, et al. Standards Track [Page 29] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -9.2.2 DSA with SHA-1 in Authentication Blocks - - BSD=0x0002 is defined to be DSA with SHA-1. The signature - calculation is defined by [20]. The signature format conforms to - that in the X.509 v3 certificate: - - 1. The signature algorithm identifier (an OID) - 2. The signature value (an octet string) - 3. The certificate path. - - All data is represented in ASN.1 encoding: - - id-dsa-with-sha1 ID ::= { - iso(1) member-body(2) us(840) x9-57 (10040) - x9cm(4) 3 } - - i.e., the ASN.1 encoding of 1.2.840.10040.4.3 followed immediately - by: - - Dss-Sig-Value ::= SEQUENCE { - r INTEGER, - s INTEGER } - - i.e., the binary ASN.1 encoding of r and s computed using DSA and - SHA-1. This is followed by a certificate path, as defined by X.509 - [10], [2], [3], [4], [5]. - - Authentication Blocks for BSD=0x0002 have the following format. In - the future, BSDs may be assigned which have different formats. - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | ASN.1 encoded DSA signature \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - -9.3. Incremental Service Registration - - Incremental registrations update attribute values for a previously - registered service. Incremental service registrations are useful - when only a single attribute has changed, for instance. In an - incremental registration, the FRESH flag in the SrvReg header is NOT - set. - - The new registration's attributes replace the previous - registration's, but do not affect attributes which were included - previously and are not present in the update. - - - - -Guttman, et al. Standards Track [Page 30] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - For example, suppose service:x://a.org has been registered with - attributes A=1, B=2, C=3. If an incremental registration comes for - service:x://a.org with attributes C=30, D=40, then the attributes for - the service after the update are A=1, B=2, C=30, D=40. - - Incremental registrations MUST NOT be performed for services - registered with Authentication Blocks. These must be registered with - ALL attributes, with the FRESH flag in the SrvReg header set. DAs - which receive such registration messages return an - AUTHENTICATION_FAILED error. - - If the FRESH flag is not set and the DA does not have a prior - registration for the service, the incremental registration fails with - error code INVALID_UPDATE. - - The SA MUST use the same <scope-list> in an update message as was - used in the prior registration. If this is not done, the DA returns - a SCOPE_NOT_SUPPORTED error. In order to change the scope of a - service advertisement it MUST be deregistered first and reregistered - with a new <scope-list>. - - The SA MUST use the same <service-type> in an update message as was - used in a prior registration of the same URL. If this is not done, - the DA returns an INVALID_UPDATE error. - -9.4. Tag Lists - - Tag lists are used in SrvDeReg and AttrReq messages. The syntax of a - <tag-list> item is: - - tag-filter = simple-tag / substring - simple-tag = 1*filt-char - substring = [initial] any [final] - initial = 1*filt-char - any = `*' *(filt-char `*') - final = 1*filt-char - filt-char = Any character excluding <reserved> and <bad-tag> (see - grammar in Section 5). - - Wild card characters in a <tag-list> item match arbitrary sequences - of characters. For instance "*bob*" matches "some bob I know", - "bigbob", "bobby" and "bob". - - - - - - - - - -Guttman, et al. Standards Track [Page 31] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -10. Optional SLP Messages - - The additional requests provide features for user interaction and for - efficient updating of service advertisements with dynamic attributes. - -10.1. Service Type Request - - The Service Type Request (SrvTypeRqst) allows a UA to discover all - types of service on a network. This is useful for general purpose - service browsers. - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Service Location header (function = SrvTypeRqst = 9) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of PRList | <PRList> String \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of Naming Authority | <Naming Authority String> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of <scope-list> | <scope-list> String \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The <PRList> list and <scope-list> are interpreted as in Section 8.1. - - The Naming Authority string, if present in the request, will limit - the reply to Service Type strings with the specified Naming - Authority. If the Naming Authority string is absent, the IANA - registered service types will be returned. If the length of the - Naming Authority is set to 0xFFFF, the Naming Authority string is - omitted and ALL Service Types are returned, regardless of Naming - Authority. - -10.2. Service Type Reply - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Service Location header (function = SrvTypeRply = 10) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Error Code | length of <srvType-list> | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | <srvtype--list> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The service-type Strings (as described in Section 4.1) are provided - in <srvtype-list>, which is a <string-list>. - - - - -Guttman, et al. Standards Track [Page 32] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - If a service type has a Naming Authority other than IANA it MUST be - returned following the service type string and a `.' character. - Service types with the IANA Naming Authority do not include a Naming - Authority string. - -10.3. Attribute Request - - The Attribute Request (AttrRqst) allows a UA to discover attributes - of a given service (by supplying its URL) or for an entire service - type. The latter feature allows the UA to construct a query for an - available service by selecting desired features. The UA may request - that all attributes are returned, or only a subset of them. - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Service Location header (function = AttrRqst = 6) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of PRList | <PRList> String \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of URL | URL \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of <scope-list> | <scope-list> string \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of <tag-list> string | <tag-list> string \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | length of <SLP SPI> string | <SLP SPI> string \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The <PRList>, <scope-list> and <SLP SPI> string are interpreted as in - Section 8.1. - - The URL field can take two forms. It can simply be a Service Type - (see Section 4.1), such as "http" or "service:tftp". In this case, - all attributes and the full range of values for each attribute of all - services of the given Service Type is returned. - - The URL field may alternatively be a full URL, such as - "service:printer:lpr://igore.wco.ftp.com:515/draft" or - "nfs://max.net/znoo". In this, only the registered attributes for - the specified URL are returned. - - The <tag-list> field is a <string-list> of attribute tags, as defined - in Section 9.4 which indicates the attributes to return in the - AttrRply. If <tag-list> is omitted, all attributes are returned. - <tag-list> MUST be omitted and a full URL MUST be included when - attributes when a SLP SPI List string is included, otherwise the DA - will reply with an AUTHENTICATION_FAILED error. - - - -Guttman, et al. Standards Track [Page 33] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -10.4. Attribute Reply - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Service Location header (function = AttrRply = 7) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Error Code | length of <attr-list> | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | <attr-list> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |# of AttrAuths | Attribute Authentication Block (if present) \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The format of the <attr-list> and the Authentication Block is as - specified for SrvReg (see Section 9.2.1). - - Attribute replies SHOULD be returned with the original case of the - string registration intact, as they are likely to be human readable. - In the case where the AttrRqst was by service type, all attributes - defined for the service type, and all their values are returned. - - Although white space is folded for string matching, attribute tags - and values MUST be returned with their original white space - preserved. - - Only one copy of each attribute tag or String value should be - returned, arbitrarily choosing one version (with respect to upper and - lower case and white space internal to the strings): Duplicate - attributes and values SHOULD be removed. An arbitrary version of the - string value and tag name is chosen for the merge. For example: - "(A=a a,b)" merged with "(a=A A,B)" may yield "(a=a a,B)". - -10.5. Attribute Request/Reply Examples - - Suppose that printer services have been registered as follows: - - Registered Service: - URL = service:printer:lpr://igore.wco.ftp.com/draft - scope-list = Development - Lang. Tag = en - Attributes = (Name=Igore),(Description=For developers only), - (Protocol=LPR),(location-description=12th floor), - (Operator=James Dornan \3cdornan@monster\3e), - (media-size=na-letter),(resolution=res-600),x-OK - - URL = service:printer:lpr://igore.wco.ftp.com/draft - scope-list = Development - - - -Guttman, et al. Standards Track [Page 34] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - Lang. Tag = de - Attributes = (Name=Igore),(Description=Nur fuer Entwickler), - (Protocol=LPR),(location-description=13te Etage), - (Operator=James Dornan \3cdornan@monster\3e), - (media-size=na-letter),(resolution=res-600),x-OK - - URL = service:printer:http://not.wco.ftp.com/cgi-bin/pub-prn - scope-list = Development - Lang. Tag = en - Attributes = (Name=Not),(Description=Experimental IPP printer), - (Protocol=http),(location-description=QA bench), - (media-size=na-letter),(resolution=other),x-BUSY - - Notice the first printer, "Igore" is registered in both English and - German. The `<' and `>' characters in the Operator attribute value - which are part of the Email address had to be escaped, as they are - reserved characters for values. - - Attribute tags are not translated, though attribute values may be, - see [13]. - - The attribute Request: - - URL = service:printer:lpr://igore.wco.ftp.com/draft - scope-list = Development - Lang. Tag = de - tag-list = resolution,loc* - - receives the Attribute Reply: - - (location-description=13te Etage),(resolution=res-600) - - The attribute Request: - - URL = service:printer - scope-list = Development - Lang. Tag = en - tag-list = x-*,resolution,protocol - - receives an Attribute Reply containing: - - (protocols=http,LPR),(resolution=res-600,other),x-OK,x-BUSY - - The first request is by service instance and returns the requested - values, in German. The second request is by abstract service type - (see Section 4) and returns values from both "Igore" and "Not". - - - - - -Guttman, et al. Standards Track [Page 35] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - An attribute Authentication Block is returned if an authentication - block with the SLP SPI in the AttrRqst can be returned. Note that - the <attr-list> returned from a DA with an Authentication Block MUST - be identical to the <attr-list> registered by a SA, in order for the - authentication verification calculations to be possible. - - A SA or DA only returns an Attribute Authentication Block if the - AttrRqst included a full URL in the request and no tag list. - - If an SLP SPI is specified in a unicast request (the REQUEST MCAST - flag in the header is not set) and the SA or DA cannot return an - Authentication Block with that SLP SPI, an AUTHENTICATION_UNKNOWN - error is returned. The # of Attr Auths field is set to 0 if there no - Authentication Block is included, or 1 if an Authentication Block - follows. - -10.6. Service Deregistration - - A DA deletes a service registration when its Lifetime expires. - Services SHOULD be deregistered when they are no longer available, - rather than leaving the registrations to time out. - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Service Location header (function = SrvDeReg = 4) | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length of <scope-list> | <scope-list> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | URL Entry \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Length of <tag-list> | <tag-list> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The <scope-list> is a <string-list> (see section 2.1). - - The SA MUST retry if there is no response from the DA, see Section - 12.3. The DA acknowledges a SrvDeReg with a SrvAck. Once the SA - receives an acknowledgment indicating success, the service and/or - attributes are no longer advertised by the DA. The DA deregisters the - service or service attributes from every scope specified in the - SrvDeReg which it was previously registered in. - - The SA MUST deregister all services with the same scope list used to - register the service with a DA. If this is not done in the SrvDeReg - message, the DA returns a SCOPE_NOT_SUPPORTED error. The Lifetime - field in the URL Entry is ignored for the purposes of the SrvDeReg. - - - - -Guttman, et al. Standards Track [Page 36] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - The <tag-list> is a <string-list> of attribute tags to deregister as - defined in Section 9.4. If no <tag-list> is present, the SrvDeReg - deregisters the service in all languages it has been registered in. - If the <tag-list> is present, the SrvDeReg deregisters the attributes - whose tags are listed in the tag spec. Services registered with - Authentication Blocks MUST NOT include a <tag-list> in a SrvDeReg - message: A DA will respond with an AUTHENTICATION_FAILED error in - this case. - - If the service to be deregistered was registered with an - authentication block or blocks, a URL authentication block for each - of the SLP SPIs registered must be included in the SrvDeReg. - Otherwise, the DA returns an AUTHENTICATION_ABSENT error. If the - message fails to be verified by the DA, an AUTHENTICATION_FAILED - error is returned by the DA. - -11. Scopes - - Scopes are sets of services. The primary use of Scopes is to provide - the ability to create administrative groupings of services. A set of - services may be assigned a scope by network administrators. A client - seeking services is configured to use one or more scopes. The user - will only discover those services which have been configured for him - or her to use. By configuring UAs and SAs with scopes, - administrators may provision services. Scopes strings are case - insensitive. The default SCOPE string is "DEFAULT". - - Scopes are the primary means an administrator has to scale SLP - deployments to larger networks. When DAs with NON-DEFAULT scopes are - present on the network, further gains can be had by configuring UAs - and SAs to have a predefined non-default scope. These agents can - then perform DA discovery and make requests using their scope. This - will limit the number of replies. - -11.1. Scope Rules - - SLP messages which fail to contain a scope that the receiving Agent - is configured to use are dropped (if the request was multicast) or a - SCOPE_NOT_SUPPORTED error is returned (if the request was unicast). - Every SrvRqst (except for DA and SA discovery requests), SrvReg, - AttrRqst, SrvTypeRqst, DAAdvert, and SAAdvert message MUST include a - <scope-list>. - - A UA MUST unicast its SLP messages to a DA which supports the desired - scope, in preference to multicasting a request to SAs. A UA MAY - multicast the request if no DA is available in the scope it is - configured to use. - - - - -Guttman, et al. Standards Track [Page 37] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -11.2. Administrative and User Selectable Scopes - - All requests and services are scoped. The two exceptions are - SrvRqsts for "service:directory-agent" and "service:service-agent". - These MAY have a zero-length <scope-list> when used to enable the - user to make scope selections. In this case UAs obtain their scope - list from DAAdverts (or if DAs are not available, from SAAdverts.) - - Otherwise, if SAs and UAs are to use any scope other than the default - (i.e., "DEFAULT"), the UAs and SAs are configured with lists of - scopes to use by system administrators, perhaps automatically by way - of DHCP option 78 or 79 [21]. Such administrative scoping allows - services to be provisioned, so that users will only see services they - are intended to see. - - User configurable scopes allow a user to discover any service, but - require them to do their own selection of scope. This is similar to - the way AppleTalk [12] and SMB [19] networking allow user selection - of AppleTalk Zone or workgroups. - - Note that the two configuration choices are not compatible. One - model allows administrators control over service provision. The - other delegates this to users (who may not be prepared to do any - configuration of their system). - -12. Directory Agents - - DAs cache service location and attribute information. They exist to - enhance the performance and scalability of SLP. Multiple DAs provide - further scalability and robustness of operation, since they can each - store service information for the same SAs, in case one of the DAs - fails. - - A DA provides a centralized store for service information. This is - useful in a network with several subnets or with many SLP Agents. - The DA address can be dynamically configured with UAs and SAs using - DHCP, or by using static configuration. - - SAs configured to use DAs with DHCP or static configuration MUST - unicast a SrvRqst to the DA, when the SA is initialized. The SrvRqst - omits the scope list and sets the service type of the request to - "service:directory-agent". The DA will return a DAAdvert with its - attributes, SLP SPI list, and other parameters which are essential - for proper SA to DA communication. - - Passive detection of DAs by SAs enables services to be advertised - consistently among DAs of the same scope. Advertisements expire if - not renewed, leaving only transient stale registrations in DAs, even - - - -Guttman, et al. Standards Track [Page 38] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - in the case of a failure of a SA. - - A single DA can support many UAs. UAs send the same requests to DAs - that they would send to SAs and expect the same results. DAs reduce - the load on SAs, making simpler implementations of SAs possible. - - UAs MUST be prepared for the possibility that the service information - they obtain from DAs is stale. - -12.1. Directory Agent Rules - - When DAs are present, each SA MUST register its services with DAs - that support one or more of its scope(s). - - UAs MUST unicast requests directly to a DA (when scoping rules - allow), hence avoiding using the multicast convergence algorithm, to - obtain service information. This decreases network utilization and - increases the speed at which UAs can obtain service information. - - DAs MUST flush service advertisements once their lifetime expires or - their URL Authentication Block "Timestamp" of expiration is past. - - DAAdverts MUST include DA Stateless Boot Timestamp, in the same - format as the Authentication Block (see Section 9.2). The Timestamp - in the Authentication Block indicates the time at which all previous - registrations were lost (i.e., the last stateless reboot). The - Timestamp is set to 0 in a DAAdvert to notify UAs and SAs that the DA - is going down. DAs MUST NOT use equal or lesser Boot Timestamps to - previous ones, if they go down and restart without service - registration state. This would mislead SAs to not reregister with - the DA. - - DAs which receive a multicast SrvRqst for the service type - "service:directory-agent" MUST silently discard it if the <scope- - list> is (a) not omitted and (b) does not include a scope they are - configured to use. Otherwise the DA MUST respond with a DAAdvert. - - DAs MUST respond to AttrRqst and SrvTypeRqst messages (these are - OPTIONAL only for SAs, not DAs.) - -12.2. Directory Agent Discovery - - UAs can discover DAs using static configuration, DHCP options 78 and - 79, or by multicasting (or broadcasting) Service Requests using the - convergence algorithm in Section 6.3. - - - - - - -Guttman, et al. Standards Track [Page 39] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - See Section 6 regarding unsolicited DAAdverts. Section 12.2.2 - describes how SAs may reduce the number of times they must reregister - with DAs in response to unsolicited DAAdverts. - - DAs MUST send unsolicited DAAdverts once per CONFIG_DA_BEAT. An - unsolicited DAAdvert has an XID of 0. SAs MUST listen for DAAdverts, - passively, as described in Section 8.5. UAs MAY do this. If they do - not listen for unsolicited DAAdverts, however, they will not discover - DAs as they become available. UAs SHOULD, in this case, do periodic - active DA discovery, see Section 6. - - A URL with the scheme "service:directory-agent" indicates the DA's - location as defined in Section 8.5. For example: - "service:directory-agent://foobawooba.org". - - The following sections suggest timing algorithms which enhance the - scalability of SLP. - -12.2.1. Active DA Discovery - - After a UA or SA restarts, its initial DA discovery request SHOULD be - delayed for some random time uniformly distributed from 0 to - CONFIG_START_WAIT seconds. - - The UA or SA sends the DA Discovery request using a SrvRqst, as - described in Section 8.1. DA Discovery requests MUST include a - Previous Responder List. SrvRqsts for Active DA Discovery SHOULD NOT - be sent more than once per CONFIG_DA_FIND seconds. - - After discovering a new DA, a SA MUST wait a random time between 0 - and CONFIG_REG_ACTIVE seconds before registering their services. - -12.2.2. Passive DA Advertising - - A DA MUST multicast (or broadcast) an unsolicited DAAdvert every - CONFIG_DA_BEAT seconds. CONFIG_DA_BEAT SHOULD be specified to - prevent DAAdverts from using more than 1% of the available bandwidth. - - All UAs and SAs which receive the unsolicited DAAdvert SHOULD examine - its DA stateless Boot Timestamp. If it is set to 0, the DA is going - down and no further messages should be sent to it. - - If a SA detects a DA it has never encountered (with a nonzero - timestamp,) the SA must register with it. SAs MUST examine the - DAAdvert's timestamp to determine if the DA has had a stateless - reboot since the SA last registered with it. If so it registers with - the DA. SAs MUST wait a random interval between 0 and - CONFIG_REG_PASSIVE before beginning DA registration. - - - -Guttman, et al. Standards Track [Page 40] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -12.3. Reliable Unicast to DAs and SAs - - If a DA or SA fails to respond to a unicast UDP message in - CONFIG_RETRY seconds, the message should be retried. The wait - interval for each subsequent retransmission MUST exponentially - increase, doubling each time. If a DA or SA fails to respond after - CONFIG_RETRY_MAX seconds, the sender should consider the receiver to - have gone down. The UA should use a different DA. If no such DA - responds, DA discovery should be used to find a new DA. If no DA is - available, multicast requests to SAs are used. - -12.4. DA Scope Configuration - - By default, DAs are configured with the "DEFAULT" scope. - Administrators may add other configured scopes, in order to support - UAs and SAs in non default scopes. The default configuration MUST - NOT be removed from the DA unless: - - - There are other DAs which support the "DEFAULT" scope, or - - - All UAs and SAs have been configured with non-default scopes. - - Non-default scopes can be phased-in as the SLP deployment grows. - Default scopes should be phased out only when the non-default scopes - are universally configured. - - If a DA and SA are coresident on a host (quite possibly implemented - by the same process), configuration of the host is considerably - simplified if the SA supports only scopes also supported by the DA. - That is, the SA SHOULD NOT advertise services in any scopes which are - not supported by the coresident DA. This means that incoming requests - can be answered by a single data store; the SA and DA registrations - do not need to be kept separately. - -12.5. DAs and Authentication Blocks - - DAs are not configured to sign service registrations or attribute - lists. They simply cache services registered by Service Agents. DAs - MUST NOT accept registrations including authentication blocks for SLP - SPIs which it is not configured with, see Section 8.5. - - A DA protects registrations which are made with authentication blocks - using SLP SPIs it is configured to use. If a service S is - registered, a subsequent registration (which will replace the - adertisement) or a deregistration (which will remove it) MUST include - an Authentication Block with the corresponding SLP SPI, see Section - 8.3 and Section 10.6. - - - - -Guttman, et al. Standards Track [Page 41] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - Example: - - A DA is configured to be able to verify Authentication Blocks with - SLP SPIs "X,Y", that is X and Y. - - An SA registers a service with an Authentication Block with SPI "Z". - The DA stores the registration, but discards the Authentication - Block. If a UA requests a service with an SLP SPI string "Z", the DA - will respond with an AUTHENTICATION_UNKNOWN error. - - An SA registers a service S with Authentication Blocks including SLP - SPIs "X" and "Y". If a UA requests a service with an SLP SPI string - "X" the DA will be able to return S (if the service type, language, - scope and predicate of the SrvRqst match S) The DA will also return - the Authentication Block with SLP SPI set to "X". If the DA receives - a subsequent SrvDeReg for S (which will remove the advertisement) or - a subsequent SrvReg for S (which will replace it), the message must - include two URL Authentication Blocks, one each for SPIs "X" and "Y". - If either of these were absent, the DA would return an - AUTHENTICATION_ABSENT error. - -13. Protocol Timing Defaults - -Interval name Section Default Value Meaning -------------------- ------- ------------- ------------------------ -CONFIG_MC_MAX 6.3 15 seconds Max time to wait for a - complete multicast query - response (all values.) -CONFIG_START_WAIT 12.2.1 3 seconds Wait to perform DA - discovery on reboot. -CONFIG_RETRY 12.3 2 seconds Wait interval before - initial retransmission - of multicast or unicast - requests. -CONFIG_RETRY_MAX 12.3 15 seconds Give up on unicast - request retransmission. -CONFIG_DA_BEAT 12.2.2 3 hours DA Heartbeat, so that SAs - passively detect new DAs. -CONFIG_DA_FIND 12.3 900 seconds Minimum interval to wait - before repeating Active - DA discovery. -CONFIG_REG_PASSIVE 12.2 1-3 seconds Wait to register services - on passive DA discovery. -CONFIG_REG_ACTIVE 8.3 1-3 seconds Wait to register services - on active DA discovery. -CONFIG_CLOSE_CONN 6.2 5 minutes DAs and SAs close idle - connections. - - - - -Guttman, et al. Standards Track [Page 42] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -14. Optional Configuration - - Broadcast Only - Any SLP agent SHOULD be configurable to use broadcast - only. See Sections 6.1 and 12.2. - - Predefined DA - A UA or SA SHOULD be configurable to use a predefined DA. - - No DA Discovery - The UA or SA SHOULD be configurable to ONLY use - predefined and DHCP-configured DAs and perform no active - or passive DA discovery. - - Multicast TTL - The default multicast TTL is 255. Agents SHOULD be - configurable to use other values. A lower value will - focus the multicast convergence algorithm on smaller - subnetworks, decreasing the number of responses and - increases the performance of service location. This - may result in UAs obtaining different results for the - identical requests depending on where they are connected - to the network. - - Timing Values - Time values other than the default MAY be configurable. - See Section 13. - - Scopes - A UA MAY be configurable to support User Selectable - scopes by omitting all predefined scopes. See - Section 11.2. A UA or SA MUST be configurable to use - specific scopes by default. Additionally, a UA or SA - MUST be configurable to use specific scopes for requests - for and registrations of specific service types. The - scope or scopes of a DA MUST be configurable. The - default value for a DA is to have the scope "DEFAULT" if - not otherwise configured. - - DHCP Configuration - DHCP options 78 and 79 may be used to configure SLP. If - DA locations are configured using DHCP, these SHOULD - be used in preference to DAs discovered actively or - passively. One or more of the scopes configured using - DHCP MUST be used in requests. The entire configured - <scope-list> MUST be used in registration and DA - configuration messages. - - - - -Guttman, et al. Standards Track [Page 43] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - Service Template - UAs and SAs MAY be configured by using Service Templates. - Besides simplifying the specification of attribute - values, this also allows them to enforce the inclusion - of 'required' attributes in SrvRqst, SrvReg and SrvDeReg - messages. DAs MAY be configured with templates to - allow them to WARN UAs and SAs in these cases. See - Section 10.4. - - SLP SPI for service discovery - Agents SHOULD be configurable to support SLP SPIs using - the following parameters: BSD=2 (DSA with SHA-1) and - a public key identified by the SLP SPI String. In - the future, when a Public Key Infrastructure exists, - SLP Agents may be able to obtain public keys and - cryptographic parameters corresponding to the names used - in SLP SPI Strings. - - Note that if the SLP SPI string chosen is identical - to a scope string, it is effectively the same as a - Protected Scope in SLPv1. Namely, every SA advertising - in that scope would be configured with the same Private - Key. Every DA and UA of that scope would be configured - with the appropriate Public Key to verify signatures - produced by those SAs. This is a convenient way to - configure SLP deployments in the absence of a Public Key - Infrastructure. Currently, it would be too difficult to - manage the keying of UAs and DAs if each SA had its own - key. - - SLP SPI for Directory Agent discovery - Agents SHOULD be configurable to support SLP SPIs as - above, to be used when discovering DAs. This SPI SHOULD - be sent in SrvRqsts to discover DAs and be used to verify - multicast DAAdvert messages. - - SA and DA Private Key - SAs and DAs which can generate digital signatures require - a Private Key and a corresponding SLP SPI indentifier - to include in the Authentication Block. The SLP SPI - identifies the Public Key to use to verify the digital - signature in the Authentication Block. - -15. IANA Considerations - - SLP includes four sets of identifiers which may be registered with - IANA. The policies for these registrations (See [18]) are noted in - each case. - - - -Guttman, et al. Standards Track [Page 44] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - The Block Structure Descriptor (BSD) identifies the format of the - Authenticator which follows. BSDs 0x8000-0x8FFF are for Private Use. - - Further Block Structured Descriptor (BSD) values, from the range - 0x0003-0x7FFF may be standardized in the future by submitting a - document which describes: - - - The data format of the Structured Authenticator block. - - - Which cryptographic algorithm to use (including a reference - to a technical specification of the algorithm.) - - - The format of any keying material required for - preconfiguring UAs, DAs and SAs. Also include any - considerations regarding key distribution. - - - Security considerations to alert others to the strengths and - weaknesses of the approach. - - The IANA will assign Cryptographic BSD numbers on the basis of IETF - Consenus. - - New function-IDs, in the range 12-255, may be standardized by the - method of IETF Consensus. - - New SLP Extensions with types in the range 2-65535 may be registered - following review by a Designated Expert. - - New error numbers in the range 15-65535 are assigned on the basis of - a Standards Action. - - Protocol elements used with Service Location Protocol may also - require IANA registration actions. SLP is used in conjunction with - "service:" URLs and Service Templates [13]. These are standardized - by review of a Designated Expert and a mailing list (See [13].) - -16. Internationalization Considerations - - SLP messages support the use of multiple languages by providing a - Language Tag field in the common message header (see Section 8). - - Services MAY be registered in multiple languages. This provides - attributes so that users with different language skills may select - services interactively. - - Attribute tags are not translated. Attribute values may be - translated unless the Service Template [13] defines the attribute - values to be 'literal'. - - - -Guttman, et al. Standards Track [Page 45] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - A service which is registered in multiple languages may be queried in - multiple languages. The language of the SrvRqst or AttrRqst is used - to satisfy the request. If the requested language is not supported, - a LANGUAGE_NOT_SUPPORTED error is returned. SrvRply and AttrRply - messages are always in the same language of the request. - - A DA or SA MAY be configured with translations of Service Templates - [13] for the same service type. This will allow the DA or SA to - translate a request (say in Italian) to the language of the service - advertisement (say in English) and then translate the reply back to - Italian. Similarly, a UA MAY use templates to translate outgoing - requests and incoming replies. - - The dialect field in the Language Tag MAY be used: Requests which - can be fulfilled by matching a language and dialect will be preferred - to those which match only the language portion. Otherwise, dialects - have no effect on matching requests. - -17. Security Considerations - - SLP provides for authentication of service URLs and service - attributes. This provides UAs and DAs with knowledge of the - integrity of service URLs and attributes included in SLP messages. - The only systems which can generate digital signatures are those - which have been configured by administrators in advance. Agents - which verify signed data may assume it is 'trustworthy' inasmuch as - administrators have ensured the cryptographic keying of SAs and DAs - reflects 'trustworthiness.' - - Service Location does not provide confidentiality. Because the - objective of this protocol is to advertise services to a community of - users, confidentiality might not generally be needed when this - protocol is used in non-sensitive environments. Specialized schemes - might be able to provide confidentiality, if needed in the future. - Sites requiring confidentiality should implement the IP Encapsulating - Security Payload (ESP) [3] to provide confidentiality for Service - Location messages. - - If Agents are not configured to generate Authentication Blocks and - Agents are not configured to verify them, an adversary might easily - use this protocol to advertise services on servers controlled by the - adversary and thereby gain access to users' private information. - Further, an adversary using this protocol will find it much easier to - engage in selective denial of service attacks. Sites that are in - potentially hostile environments (e.g., are directly connected to the - Internet) should consider the advantages of distributing keys - associated with SLP SPIs prior to deploying the sensitive directory - agents or service agents. - - - -Guttman, et al. Standards Track [Page 46] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - SLP is useful as a bootstrap protocol. It may be used in - environments in which no preconfiguration is possible. In such - situations, a certain amount of "blind faith" is required: Without - any prior configuration it is impossible to use any of the security - mechanisms described above. SLP will make use of the mechanisms - provided by the Security Area of the IETF for key distribution as - they become available. At this point it would only be possible to - gain the benefits associated with the use of Authentication Blocks if - cryptographic information and SLP SPIs can be preconfigured with the - end systems before they use SLP. - - SLPv2 enables a number of security policies with the mechanisms it - includes. A SLPv2 UA could, for instance, reject any SLP message - which did not carry an authentication block which it could verify. - This is not the only policy which is possible to implement. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Guttman, et al. Standards Track [Page 47] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -A. Appendix: Changes to the Service Location Protocol from v1 to v2 - - SLP version 2 (SLPv2) corrects race conditions present in SLPv1 [22]. - In addition, authentication has been reworked to provide more - flexibility and protection (especially for DA Advertisements). SLPv2 - also changes the formats and definition of many flags and values and - reduces the number of 'required features.' SLPv2 clarifies and - changes the use of 'Scopes', eliminating support for 'unscoped - directory agents' and 'unscoped requests'. SLPv2 uses LDAPv3 - compatible string encodings of attributes and search filters. Other - changes (such as Language and Character set handling) adopt practices - recommended by the Internet Engineering Steering Group. - - Effort has been made to make SLPv2 operate the same whether DAs are - present or not. For this reason, a new message (the SAAdvert) has - been added. This allows UAs to discover scope information in the - absence of administrative configuration and DAs. This was not - possible in SLPv1. - - SLPv2 is incompatible in some respects with SLPv1. If a DA which - supports both SLPv1 and SLPv2 with the same scope is present, - services advertised by SAs using either version of the protocol will - be available to both SLPv1 and SLPv2 UAs. SLPv1 DAs SHOULD be phased - out and replace with SLPv2 DAs which support both versions of the - protocol. - - SLPv1 allows services to be advertised and requested without a scope. - Further, DAs can be configured without a scope. This is incompatible - with SLPv2 and presents scalability problems. To facilitate this - forward migration, SLPv1 agents MUST use scopes for all registrations - and requests. SLPv1 DAs MUST be configured with a scope list. This - constitutes a revision of RFC 2165 [22]. - -B. Appendix: Service Discovery by Type: Minimal SLPv2 Features - - Service Agents may advertise services without attributes. This will - enable only discovery of services by type. Service types discovered - this way will have a Service Template [13] defined which specifies - explicitly that no attributes are associated with the service - advertisement. Service types associated with Service Templates which - specify attributes MUST NOT be advertised by SAs which do not support - attributes. - - While discovery of service by service type is a subset of the - features possible using SLPv2 this form of discovery is consistent - with the current generation of products that allow simple browsing of - all services in a 'zone' or 'workgroup' by type. In some cases, - attribute discovery, security and feature negotiation is handled by - - - -Guttman, et al. Standards Track [Page 48] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - application layer protocols - all that is required is the basic - discovery of services that support a certain service. - - UAs requesting only service of that service type would only need to - support service type and scope fields of the Service Request. UAs - would still perform DA discovery and unicast SLPv2 SrvRqst messages - to DAs in their scope once they were discovered instead of - multicasting them. - - SAs would also perform DA discovery and use a SLPv2 SrvReg to - register all their advertised services with SLPv2 DAs in their scope. - These advertisements would needless to say contain no attribute - string. - - These minimal SAs could ignore the Language Tag in requests since - SrvRqst messages would contain no attributes, hence no strings would - be internationalized. Further, any non-null predicate string would - fail to match a service advertisement with no attributes, so these - SAs would not have to parse and interpret search filters. Overflow - will never occur in SrvRqst, SrvRply or SrvReg messages so TCP - message handling would not have to be implemented. Finally, all - AttrRqst messages could be dropped by the SA, since no attributes are - supported. - -C. Appendix: DAAdverts with arbitrary URLs - - Using Active DA Discovery, a SrvRqst with its service type field set - to "service:directory-agent". DAs will respond with a DAAdvert - containing a URL with the "service:directory-agent:" scheme. This is - the same DAAdvert that such a DA would multicast in unsolicited DA - advertisements. - - A UA or SA which receives an unsolicited DAAdvert MUST examine the - URL to determine if it has a recognized scheme. If the UA or SA does - not recognize the DAAdvert's URL scheme, the DAAdvert is silently - discarded. This document specifies only how to use URLs with the - "service:directory-agent:" scheme. - - This provides the possibility for forward compatibility with future - versions of SLP and enables other services to advertise their ability - to serve as a clearinghouse for service location information. - - For example, if LDAPv3 [15] is used for service registration and - discovery by a set of end systems, they could interpret a LDAP URL - [16] to passively discover the LDAP server to use for this purpose. - This document does not specify how this is done: SLPv2 agents - without further support would simply discard this DAAdvert. - - - - -Guttman, et al. Standards Track [Page 49] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -D. Appendix: SLP Protocol Extensions - -D.1. Required Attribute Missing Option - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Extension Type = 0x0001 | Extension Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Template IDVer Length | Template IDVer String \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - |Required Attr <tag-list> Length| Required Attr <tag-list> \ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - Required attributes and the format of the IDVer string are defined by - [13]. - - If a SA or DA receives a SrvRqst or a SrvReg which fails to include a - Required Attribute for the requested Service Type (according to the - Service Template), it MAY return the Required Attribute Extension in - addition to the reply corresponding to the message. The sender - SHOULD reissue the message with a search filter including the - attributes listed in the returned Required Attribute Extension. - Similarly, the Required Attribute Extension may be returned in - response to a SrvDereg message that contains a required attribute - tag. - - The Template IDVer String is the name and version number string of - the Service Template which defines the given attribute as required. - It SHOULD be included, but can be omitted if a given SA or DA has - been individually configured to have 'required attributes.' - - The Required Attribute <tag-list> MUST NOT include wild cards. - -E. Acknowledgments - - This document incorporates ideas from work on several discovery - protocols, including RDP by Perkins and Harjono, and PDS by Michael - Day. We are grateful for contributions by Ye Gu and Peter Ford. - John Veizades was instrumental in the standardization of the Service - Location Protocol. Implementors at Novell, Axis Communications and - Sun Microsystems have contributed significantly to make this a much - clearer and more consistent document. - - - - - - - - -Guttman, et al. Standards Track [Page 50] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -F. References - - [1] Port numbers, July 1997. - ftp://ftp.isi.edu/in-notes/iana/assignments/port-numbers. - - [2] ISO/IEC JTC1/SC 21. Certificate Extensions. Draft Amendment - DAM 4 to ISO/IEC 9594-2, December 1996. - - [3] ISO/IEC JTC1/SC 21. Certificate Extensions. Draft Amendment - DAM 2 to ISO/IEC 9594-6, December 1996. - - [4] ISO/IEC JTC1/SC 21. Certificate Extensions. Draft Amendment - DAM 1 to ISO/IEC 9594-7, December 1996. - - [5] ISO/IEC JTC1/SC 21. Certificate Extensions. Draft Amendment - DAM 1 to ISO/IEC 9594-8, December 1996. - - [6] Unicode Technical Report #8. The Unicode Standard, version 2.1. - Technical report, The Unicode Consortium, 1998. - - [7] Alvestrand, H., "Tags for the Identification of Languages", - RFC 1766, March 1995. - - [8] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform - Resource Identifiers (URI): Generic Syntax", RFC 2396, - August 1998. - - [9] Bradner, S., "Key Words for Use in RFCs to Indicate Requirement - Levels", BCP 14, RFC 2119, March 1997. - - [10] CCITT. The Directory Authentication Framework. Recommendation - X.509, 1988. - - [11] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 2234, November 1997. - - [12] S. Gursharan, R. Andrews, and A. Oppenheimer. Inside AppleTalk. - Addison-Wesley, 1990. - - [13] Guttman, E., Perkins, C. and J. Kempf, "Service Templates and - service: Schemes", RFC 2609, June 1999. - - [14] Howes, T., "The String Representation of LDAP Search Filters", - RFC 2254, December 1997. - - [15] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory - Access Protocol (v3)", RFC 2251, December 1997. - - - - -Guttman, et al. Standards Track [Page 51] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - - [16] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, - December 1997. - - [17] Meyer, D., "Administratively Scoped IP Multicast", RFC 2365, - July 1998. - - [18] Narten, T. and H. Alvestrand, "Guidelines for Writing - an IANA Considerations Section in RFCs, BCP 26, RFC 2434, - October 1998. - - [19] Microsoft Networks. SMB File Sharing Protocol Extensions 3.0, - Document Version 1.09, November 1989. - - [20] National Institute of Standards and Technology. Digital - signature standard. Technical Report NIST FIPS PUB 186, U.S. - Department of Commerce, May 1994. - - [21] Perkins, C. and E. Guttman, "DHCP Options for Service Location - Protocol", RFC 2610, June 1999. - - [22] Veizades, J., Guttman, E., Perkins, C. and S. Kaplan, "Service - Location Protocol", RFC 2165, July 1997. - - [23] Yergeau, F., "UTF-8, a transformation format of ISO 10646", - RFC 2279, January 1998. - - - - - - - - - - - - - - - - - - - - - - - - - - -Guttman, et al. Standards Track [Page 52] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -G. Authors' Addresses - - Erik Guttman - Sun Microsystems - Bahnstr. 2 - 74915 Waibstadt - Germany - - Phone: +49 7263 911 701 - EMail: Erik.Guttman@sun.com - - - Charles Perkins - Sun Microsystems - 901 San Antonio Road - Palo Alto, CA 94040 - USA - - Phone: +1 650 786 6464 - EMail: cperkins@sun.com - - - John Veizades - @Home Network - 425 Broadway - Redwood City, CA 94043 - USA - - Phone: +1 650 569 5243 - EMail: veizades@home.net - - - Michael Day - Vinca Corporation. - 1201 North 800 East - Orem, Utah 84097 USA - - Phone: +1 801 376-5083 - EMail: mday@vinca.com - - - - - - - - - - - - -Guttman, et al. Standards Track [Page 53] - -RFC 2608 Service Location Protocol, Version 2 June 1999 - - -H. Full Copyright Statement - - Copyright (C) The Internet Society (1999). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Guttman, et al. Standards Track [Page 54] - diff --git a/utils/open-isns/doc/rfc3279.txt b/utils/open-isns/doc/rfc3279.txt deleted file mode 100644 index 04e7b07..0000000 --- a/utils/open-isns/doc/rfc3279.txt +++ /dev/null @@ -1,1515 +0,0 @@ - - - - - - -Network Working Group W. Polk -Request for Comments: 3279 NIST -Obsoletes: 2528 R. Housley -Category: Standards Track RSA Laboratories - L. Bassham - NIST - April 2002 - - Algorithms and Identifiers for the - Internet X.509 Public Key Infrastructure - Certificate and Certificate Revocation List (CRL) Profile - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2002). All Rights Reserved. - -Abstract - - This document specifies algorithm identifiers and ASN.1 encoding - formats for digital signatures and subject public keys used in the - Internet X.509 Public Key Infrastructure (PKI). Digital signatures - are used to sign certificates and certificate revocation list (CRLs). - Certificates include the public key of the named subject. - -Table of Contents - - 1 Introduction . . . . . . . . . . . . . . . . . . . . . . 2 - 2 Algorithm Support . . . . . . . . . . . . . . . . . . . . 3 - 2.1 One-Way Hash Functions . . . . . . . . . . . . . . . . 3 - 2.1.1 MD2 One-Way Hash Functions . . . . . . . . . . . . . 3 - 2.1.2 MD5 One-Way Hash Functions . . . . . . . . . . . . . 4 - 2.1.3 SHA-1 One-Way Hash Functions . . . . . . . . . . . . 4 - 2.2 Signature Algorithms . . . . . . . . . . . . . . . . . 4 - 2.2.1 RSA Signature Algorithm . . . . . . . . . . . . . . . 5 - 2.2.2 DSA Signature Algorithm . . . . . . . . . . . . . . . 6 - 2.2.3 Elliptic Curve Digital Signature Algorithm . . . . . 7 - 2.3 Subject Public Key Algorithms . . . . . . . . . . . . . 7 - 2.3.1 RSA Keys . . . . . . . . . . . . . . . . . . . . . . 8 - 2.3.2 DSA Signature Keys . . . . . . . . . . . . . . . . . 9 - 2.3.3 Diffie-Hellman Key Exchange Keys . . . . . . . . . . 10 - - - -Polk, et al. Standards Track [Page 1] - -RFC 3279 Algorithms and Identifiers April 2002 - - - 2.3.4 KEA Public Keys . . . . . . . . . . . . . . . . . . . 11 - 2.3.5 ECDSA and ECDH Public Keys . . . . . . . . . . . . . 13 - 3 ASN.1 Module . . . . . . . . . . . . . . . . . . . . . . 18 - 4 References . . . . . . . . . . . . . . . . . . . . . . . 24 - 5 Security Considerations . . . . . . . . . . . . . . . . . 25 - 6 Intellectual Property Rights . . . . . . . . . . . . . . 26 - 7 Author Addresses . . . . . . . . . . . . . . . . . . . . 26 - 8 Full Copyright Statement . . . . . . . . . . . . . . . . 27 - -1 Introduction - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in [RFC 2119]. - - This document specifies algorithm identifiers and ASN.1 [X.660] - encoding formats for digital signatures and subject public keys used - in the Internet X.509 Public Key Infrastructure (PKI). This - specification supplements [RFC 3280], "Internet X.509 Public Key - Infrastructure: Certificate and Certificate Revocation List (CRL) - Profile." Implementations of this specification MUST also conform to - RFC 3280. - - This specification defines the contents of the signatureAlgorithm, - signatureValue, signature, and subjectPublicKeyInfo fields within - Internet X.509 certificates and CRLs. - - This document identifies one-way hash functions for use in the - generation of digital signatures. These algorithms are used in - conjunction with digital signature algorithms. - - This specification describes the encoding of digital signatures - generated with the following cryptographic algorithms: - - * Rivest-Shamir-Adelman (RSA); - * Digital Signature Algorithm (DSA); and - * Elliptic Curve Digital Signature Algorithm (ECDSA). - - This document specifies the contents of the subjectPublicKeyInfo - field in Internet X.509 certificates. For each algorithm, the - appropriate alternatives for the the keyUsage extension are provided. - This specification describes encoding formats for public keys used - with the following cryptographic algorithms: - - * Rivest-Shamir-Adelman (RSA); - * Digital Signature Algorithm (DSA); - * Diffie-Hellman (DH); - * Key Encryption Algorithm (KEA); - - - -Polk, et al. Standards Track [Page 2] - -RFC 3279 Algorithms and Identifiers April 2002 - - - * Elliptic Curve Digital Signature Algorithm (ECDSA); and - * Elliptic Curve Diffie-Hellman (ECDH). - -2 Algorithm Support - - This section describes cryptographic algorithms which may be used - with the Internet X.509 certificate and CRL profile [RFC 3280]. This - section describes one-way hash functions and digital signature - algorithms which may be used to sign certificates and CRLs, and - identifies object identifiers (OIDs) for public keys contained in a - certificate. - - Conforming CAs and applications MUST, at a minimum, support digital - signatures and public keys for one of the specified algorithms. When - using any of the algorithms identified in this specification, - conforming CAs and applications MUST support them as described. - -2.1 One-way Hash Functions - - This section identifies one-way hash functions for use in the - Internet X.509 PKI. One-way hash functions are also called message - digest algorithms. SHA-1 is the preferred one-way hash function for - the Internet X.509 PKI. However, PEM uses MD2 for certificates [RFC - 1422] [RFC 1423] and MD5 is used in other legacy applications. For - these reasons, MD2 and MD5 are included in this profile. The data - that is hashed for certificate and CRL signing is fully described in - [RFC 3280]. - -2.1.1 MD2 One-way Hash Function - - MD2 was developed by Ron Rivest for RSA Security. RSA Security has - recently placed the MD2 algorithm in the public domain. Previously, - RSA Data Security had granted license for use of MD2 for non- - commercial Internet Privacy-Enhanced Mail (PEM). MD2 may continue to - be used with PEM certificates, but SHA-1 is preferred. MD2 produces - a 128-bit "hash" of the input. MD2 is fully described in [RFC 1319]. - - At the Selected Areas in Cryptography '95 conference in May 1995, - Rogier and Chauvaud presented an attack on MD2 that can nearly find - collisions [RC95]. Collisions occur when one can find two different - messages that generate the same message digest. A checksum operation - in MD2 is the only remaining obstacle to the success of the attack. - For this reason, the use of MD2 for new applications is discouraged. - It is still reasonable to use MD2 to verify existing signatures, as - the ability to find collisions in MD2 does not enable an attacker to - find new messages having a previously computed hash value. - - - - - -Polk, et al. Standards Track [Page 3] - -RFC 3279 Algorithms and Identifiers April 2002 - - -2.1.2 MD5 One-way Hash Function - - MD5 was developed by Ron Rivest for RSA Security. RSA Security has - placed the MD5 algorithm in the public domain. MD5 produces a 128- - bit "hash" of the input. MD5 is fully described in [RFC 1321]. - - Den Boer and Bosselaers [DB94] have found pseudo-collisions for MD5, - but there are no other known cryptanalytic results. The use of MD5 - for new applications is discouraged. It is still reasonable to use - MD5 to verify existing signatures. - -2.1.3 SHA-1 One-way Hash Function - - SHA-1 was developed by the U.S. Government. SHA-1 produces a 160-bit - "hash" of the input. SHA-1 is fully described in [FIPS 180-1]. RFC - 3174 [RFC 3174] also describes SHA-1, and it provides an - implementation of the algorithm. - -2.2 Signature Algorithms - - Certificates and CRLs conforming to [RFC 3280] may be signed with any - public key signature algorithm. The certificate or CRL indicates the - algorithm through an algorithm identifier which appears in the - signatureAlgorithm field within the Certificate or CertificateList. - This algorithm identifier is an OID and has optionally associated - parameters. This section identifies algorithm identifiers and - parameters that MUST be used in the signatureAlgorithm field in a - Certificate or CertificateList. - - Signature algorithms are always used in conjunction with a one-way - hash function. - - This section identifies OIDS for RSA, DSA, and ECDSA. The contents - of the parameters component for each algorithm vary; details are - provided for each algorithm. - - The data to be signed (e.g., the one-way hash function output value) - is formatted for the signature algorithm to be used. Then, a private - key operation (e.g., RSA encryption) is performed to generate the - signature value. This signature value is then ASN.1 encoded as a BIT - STRING and included in the Certificate or CertificateList in the - signature field. - - - - - - - - - -Polk, et al. Standards Track [Page 4] - -RFC 3279 Algorithms and Identifiers April 2002 - - -2.2.1 RSA Signature Algorithm - - The RSA algorithm is named for its inventors: Rivest, Shamir, and - Adleman. This profile includes three signature algorithms based on - the RSA asymmetric encryption algorithm. The signature algorithms - combine RSA with either the MD2, MD5, or the SHA-1 one-way hash - functions. - - The signature algorithm with SHA-1 and the RSA encryption algorithm - is implemented using the padding and encoding conventions described - in PKCS #1 [RFC 2313]. The message digest is computed using the - SHA-1 hash algorithm. - - The RSA signature algorithm, as specified in PKCS #1 [RFC 2313] - includes a data encoding step. In this step, the message digest and - the OID for the one-way hash function used to compute the digest are - combined. When performing the data encoding step, the md2, md5, and - id-sha1 OIDs MUST be used to specify the MD2, MD5, and SHA-1 one-way - hash functions, respectively: - - md2 OBJECT IDENTIFIER ::= { - iso(1) member-body(2) US(840) rsadsi(113549) - digestAlgorithm(2) 2 } - - md5 OBJECT IDENTIFIER ::= { - iso(1) member-body(2) US(840) rsadsi(113549) - digestAlgorithm(2) 5 } - - id-sha1 OBJECT IDENTIFIER ::= { - iso(1) identified-organization(3) oiw(14) secsig(3) - algorithms(2) 26 } - - The signature algorithm with MD2 and the RSA encryption algorithm is - defined in PKCS #1 [RFC 2313]. As defined in PKCS #1 [RFC 2313], the - ASN.1 OID used to identify this signature algorithm is: - - md2WithRSAEncryption OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) - pkcs-1(1) 2 } - - The signature algorithm with MD5 and the RSA encryption algorithm is - defined in PKCS #1 [RFC 2313]. As defined in PKCS #1 [RFC 2313], the - ASN.1 OID used to identify this signature algorithm is: - - md5WithRSAEncryption OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) - pkcs-1(1) 4 } - - - - -Polk, et al. Standards Track [Page 5] - -RFC 3279 Algorithms and Identifiers April 2002 - - - The ASN.1 object identifier used to identify this signature algorithm - is: - - sha-1WithRSAEncryption OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) - pkcs-1(1) 5 } - - When any of these three OIDs appears within the ASN.1 type - AlgorithmIdentifier, the parameters component of that type SHALL be - the ASN.1 type NULL. - - The RSA signature generation process and the encoding of the result - is described in detail in PKCS #1 [RFC 2313]. - -2.2.2 DSA Signature Algorithm - - The Digital Signature Algorithm (DSA) is defined in the Digital - Signature Standard (DSS). DSA was developed by the U.S. Government, - and DSA is used in conjunction with the SHA-1 one-way hash function. - DSA is fully described in [FIPS 186]. The ASN.1 OID used to identify - this signature algorithm is: - - id-dsa-with-sha1 OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) x9-57 (10040) - x9cm(4) 3 } - - When the id-dsa-with-sha1 algorithm identifier appears as the - algorithm field in an AlgorithmIdentifier, the encoding SHALL omit - the parameters field. That is, the AlgorithmIdentifier SHALL be a - SEQUENCE of one component: the OBJECT IDENTIFIER id-dsa-with-sha1. - - The DSA parameters in the subjectPublicKeyInfo field of the - certificate of the issuer SHALL apply to the verification of the - signature. - - When signing, the DSA algorithm generates two values. These values - are commonly referred to as r and s. To easily transfer these two - values as one signature, they SHALL be ASN.1 encoded using the - following ASN.1 structure: - - Dss-Sig-Value ::= SEQUENCE { - r INTEGER, - s INTEGER } - - - - - - - - -Polk, et al. Standards Track [Page 6] - -RFC 3279 Algorithms and Identifiers April 2002 - - -2.2.3 ECDSA Signature Algorithm - - The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in - [X9.62]. The ASN.1 object identifiers used to identify ECDSA are - defined in the following arc: - - ansi-X9-62 OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) 10045 } - - id-ecSigType OBJECT IDENTIFIER ::= { - ansi-X9-62 signatures(4) } - - ECDSA is used in conjunction with the SHA-1 one-way hash function. - The ASN.1 object identifier used to identify ECDSA with SHA-1 is: - - ecdsa-with-SHA1 OBJECT IDENTIFIER ::= { - id-ecSigType 1 } - - When the ecdsa-with-SHA1 algorithm identifier appears as the - algorithm field in an AlgorithmIdentifier, the encoding MUST omit the - parameters field. That is, the AlgorithmIdentifier SHALL be a - SEQUENCE of one component: the OBJECT IDENTIFIER ecdsa-with-SHA1. - - The elliptic curve parameters in the subjectPublicKeyInfo field of - the certificate of the issuer SHALL apply to the verification of the - signature. - - When signing, the ECDSA algorithm generates two values. These values - are commonly referred to as r and s. To easily transfer these two - values as one signature, they MUST be ASN.1 encoded using the - following ASN.1 structure: - - Ecdsa-Sig-Value ::= SEQUENCE { - r INTEGER, - s INTEGER } - -2.3 Subject Public Key Algorithms - - Certificates conforming to [RFC 3280] may convey a public key for any - public key algorithm. The certificate indicates the algorithm - through an algorithm identifier. This algorithm identifier is an OID - and optionally associated parameters. - - This section identifies preferred OIDs and parameters for the RSA, - DSA, Diffie-Hellman, KEA, ECDSA, and ECDH algorithms. Conforming CAs - MUST use the identified OIDs when issuing certificates containing - - - - - -Polk, et al. Standards Track [Page 7] - -RFC 3279 Algorithms and Identifiers April 2002 - - - public keys for these algorithms. Conforming applications supporting - any of these algorithms MUST, at a minimum, recognize the OID - identified in this section. - -2.3.1 RSA Keys - - The OID rsaEncryption identifies RSA public keys. - - pkcs-1 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840) - rsadsi(113549) pkcs(1) 1 } - - rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1} - - The rsaEncryption OID is intended to be used in the algorithm field - of a value of type AlgorithmIdentifier. The parameters field MUST - have ASN.1 type NULL for this algorithm identifier. - - The RSA public key MUST be encoded using the ASN.1 type RSAPublicKey: - - RSAPublicKey ::= SEQUENCE { - modulus INTEGER, -- n - publicExponent INTEGER } -- e - - where modulus is the modulus n, and publicExponent is the public - exponent e. The DER encoded RSAPublicKey is the value of the BIT - STRING subjectPublicKey. - - This OID is used in public key certificates for both RSA signature - keys and RSA encryption keys. The intended application for the key - MAY be indicated in the key usage field (see [RFC 3280]). The use of - a single key for both signature and encryption purposes is not - recommended, but is not forbidden. - - If the keyUsage extension is present in an end entity certificate - which conveys an RSA public key, any combination of the following - values MAY be present: - - digitalSignature; - nonRepudiation; - keyEncipherment; and - dataEncipherment. - - If the keyUsage extension is present in a CA or CRL issuer - certificate which conveys an RSA public key, any combination of the - following values MAY be present: - - digitalSignature; - nonRepudiation; - - - -Polk, et al. Standards Track [Page 8] - -RFC 3279 Algorithms and Identifiers April 2002 - - - keyEncipherment; - dataEncipherment; - keyCertSign; and - cRLSign. - - However, this specification RECOMMENDS that if keyCertSign or cRLSign - is present, both keyEncipherment and dataEncipherment SHOULD NOT be - present. - -2.3.2 DSA Signature Keys - - The Digital Signature Algorithm (DSA) is defined in the Digital - Signature Standard (DSS) [FIPS 186]. The DSA OID supported by this - profile is: - - id-dsa OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) x9-57(10040) x9cm(4) 1 } - - The id-dsa algorithm syntax includes optional domain parameters. - These parameters are commonly referred to as p, q, and g. When - omitted, the parameters component MUST be omitted entirely. That is, - the AlgorithmIdentifier MUST be a SEQUENCE of one component: the - OBJECT IDENTIFIER id-dsa. - - If the DSA domain parameters are present in the subjectPublicKeyInfo - AlgorithmIdentifier, the parameters are included using the following - ASN.1 structure: - - Dss-Parms ::= SEQUENCE { - p INTEGER, - q INTEGER, - g INTEGER } - - The AlgorithmIdentifier within subjectPublicKeyInfo is the only place - within a certificate where the parameters may be used. If the DSA - algorithm parameters are omitted from the subjectPublicKeyInfo - AlgorithmIdentifier and the CA signed the subject certificate using - DSA, then the certificate issuer's DSA parameters apply to the - subject's DSA key. If the DSA domain parameters are omitted from the - SubjectPublicKeyInfo AlgorithmIdentifier and the CA signed the - subject certificate using a signature algorithm other than DSA, then - the subject's DSA domain parameters are distributed by other means. - If the subjectPublicKeyInfo AlgorithmIdentifier field omits the - parameters component, the CA signed the subject with a signature - algorithm other than DSA, and the subject's DSA parameters are not - available through other means, then clients MUST reject the - certificate. - - - - -Polk, et al. Standards Track [Page 9] - -RFC 3279 Algorithms and Identifiers April 2002 - - - The DSA public key MUST be ASN.1 DER encoded as an INTEGER; this - encoding shall be used as the contents (i.e., the value) of the - subjectPublicKey component (a BIT STRING) of the SubjectPublicKeyInfo - data element. - - DSAPublicKey ::= INTEGER -- public key, Y - - If the keyUsage extension is present in an end entity certificate - which conveys a DSA public key, any combination of the following - values MAY be present: - - digitalSignature; - nonRepudiation; - - If the keyUsage extension is present in a CA or CRL issuer - certificate which conveys a DSA public key, any combination of the - following values MAY be present: - - digitalSignature; - nonRepudiation; - keyCertSign; and - cRLSign. - -2.3.3 Diffie-Hellman Key Exchange Keys - - The Diffie-Hellman OID supported by this profile is defined in - [X9.42]. - - dhpublicnumber OBJECT IDENTIFIER ::= { iso(1) member-body(2) - us(840) ansi-x942(10046) number-type(2) 1 } - - The dhpublicnumber OID is intended to be used in the algorithm field - of a value of type AlgorithmIdentifier. The parameters field of that - type, which has the algorithm-specific syntax ANY DEFINED BY - algorithm, have the ASN.1 type DomainParameters for this algorithm. - - DomainParameters ::= SEQUENCE { - p INTEGER, -- odd prime, p=jq +1 - g INTEGER, -- generator, g - q INTEGER, -- factor of p-1 - j INTEGER OPTIONAL, -- subgroup factor - validationParms ValidationParms OPTIONAL } - - ValidationParms ::= SEQUENCE { - seed BIT STRING, - pgenCounter INTEGER } - - - - - -Polk, et al. Standards Track [Page 10] - -RFC 3279 Algorithms and Identifiers April 2002 - - - The fields of type DomainParameters have the following meanings: - - p identifies the prime p defining the Galois field; - - g specifies the generator of the multiplicative subgroup of order - g; - - q specifies the prime factor of p-1; - - j optionally specifies the value that satisfies the equation - p=jq+1 to support the optional verification of group parameters; - - seed optionally specifies the bit string parameter used as the - seed for the domain parameter generation process; and - - pgenCounter optionally specifies the integer value output as part - of the of the domain parameter prime generation process. - - If either of the domain parameter generation components (pgenCounter - or seed) is provided, the other MUST be present as well. - - The Diffie-Hellman public key MUST be ASN.1 encoded as an INTEGER; - this encoding shall be used as the contents (i.e., the value) of the - subjectPublicKey component (a BIT STRING) of the SubjectPublicKeyInfo - data element. - - DHPublicKey ::= INTEGER -- public key, y = g^x mod p - - If the keyUsage extension is present in a certificate which conveys a - DH public key, the following values may be present: - - keyAgreement; - encipherOnly; and - decipherOnly. - - If present, the keyUsage extension MUST assert keyAgreement and MAY - assert either encipherOnly and decipherOnly. The keyUsage extension - MUST NOT assert both encipherOnly and decipherOnly. - -2.3.4 KEA Public Keys - - This section identifies the preferred OID and parameters for the - inclusion of a KEA public key in a certificate. The Key Exchange - Algorithm (KEA) is a key agreement algorithm. Two parties may - generate a "pairwise key" if and only if they share the same KEA - parameters. The KEA parameters are not included in a certificate; - instead a domain identifier is supplied in the parameters field. - - - - -Polk, et al. Standards Track [Page 11] - -RFC 3279 Algorithms and Identifiers April 2002 - - - When the SubjectPublicKeyInfo field contains a KEA key, the algorithm - identifier and parameters SHALL be as defined in [SDN.701r]: - - id-keyExchangeAlgorithm OBJECT IDENTIFIER ::= - { 2 16 840 1 101 2 1 1 22 } - - KEA-Parms-Id ::= OCTET STRING - - CAs MUST populate the parameters field of the AlgorithmIdentifier - within the SubjectPublicKeyInfo field of each certificate containing - a KEA public key with an 80-bit parameter identifier (OCTET STRING), - also known as the domain identifier. The domain identifier is - computed in three steps: - - (1) the KEA domain parameters (p, q, and g) are DER encoded using - the Dss-Parms structure; - - (2) a 160-bit SHA-1 hash is generated from the parameters; and - - (3) the 160-bit hash is reduced to 80-bits by performing an - "exclusive or" of the 80 high order bits with the 80 low order - bits. - - The resulting value is encoded such that the most significant byte of - the 80-bit value is the first octet in the octet string. The Dss- - Parms is provided above in Section 2.3.2. - - A KEA public key, y, is conveyed in the subjectPublicKey BIT STRING - such that the most significant bit (MSB) of y becomes the MSB of the - BIT STRING value field and the least significant bit (LSB) of y - becomes the LSB of the BIT STRING value field. This results in the - following encoding: - - BIT STRING tag; - BIT STRING length; - 0 (indicating that there are zero unused bits in the final octet - of y); and - BIT STRING value field including y. - - The key usage extension may optionally appear in a KEA certificate. - If a KEA certificate includes the keyUsage extension, only the - following values may be asserted: - - keyAgreement; - encipherOnly; and - decipherOnly. - - - - - -Polk, et al. Standards Track [Page 12] - -RFC 3279 Algorithms and Identifiers April 2002 - - - If present, the keyUsage extension MUST assert keyAgreement and MAY - assert either encipherOnly and decipherOnly. The keyUsage extension - MUST NOT assert both encipherOnly and decipherOnly. - -2.3.5 ECDSA and ECDH Keys - - This section identifies the preferred OID and parameter encoding for - the inclusion of an ECDSA or ECDH public key in a certificate. The - Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in - [X9.62]. ECDSA is the elliptic curve mathematical analog of the - Digital Signature Algorithm [FIPS 186]. The Elliptic Curve Diffie - Hellman (ECDH) algorithm is a key agreement algorithm defined in - [X9.63]. - - ECDH is the elliptic curve mathematical analog of the Diffie-Hellman - key agreement algorithm as specified in [X9.42]. The ECDSA and ECDH - specifications use the same OIDs and parameter encodings. The ASN.1 - object identifiers used to identify these public keys are defined in - the following arc: - - ansi-X9-62 OBJECT IDENTIFIER ::= - { iso(1) member-body(2) us(840) 10045 } - - When certificates contain an ECDSA or ECDH public key, the - id-ecPublicKey algorithm identifier MUST be used. The id-ecPublicKey - algorithm identifier is defined as follows: - - id-public-key-type OBJECT IDENTIFIER ::= { ansi-X9.62 2 } - - id-ecPublicKey OBJECT IDENTIFIER ::= { id-publicKeyType 1 } - - This OID is used in public key certificates for both ECDSA signature - keys and ECDH encryption keys. The intended application for the key - may be indicated in the key usage field (see [RFC 3280]). The use of - a single key for both signature and encryption purposes is not - recommended, but is not forbidden. - - ECDSA and ECDH require use of certain parameters with the public key. - The parameters may be inherited from the issuer, implicitly included - through reference to a "named curve," or explicitly included in the - certificate. - - EcpkParameters ::= CHOICE { - ecParameters ECParameters, - namedCurve OBJECT IDENTIFIER, - implicitlyCA NULL } - - - - - -Polk, et al. Standards Track [Page 13] - -RFC 3279 Algorithms and Identifiers April 2002 - - - When the parameters are inherited, the parameters field SHALL contain - implictlyCA, which is the ASN.1 value NULL. When parameters are - specified by reference, the parameters field SHALL contain the - named-Curve choice, which is an object identifier. When the - parameters are explicitly included, they SHALL be encoded in the - ASN.1 structure ECParameters: - - ECParameters ::= SEQUENCE { - version ECPVer, -- version is always 1 - fieldID FieldID, -- identifies the finite field over - -- which the curve is defined - curve Curve, -- coefficients a and b of the - -- elliptic curve - base ECPoint, -- specifies the base point P - -- on the elliptic curve - order INTEGER, -- the order n of the base point - cofactor INTEGER OPTIONAL -- The integer h = #E(Fq)/n - } - - ECPVer ::= INTEGER {ecpVer1(1)} - - Curve ::= SEQUENCE { - a FieldElement, - b FieldElement, - seed BIT STRING OPTIONAL } - - FieldElement ::= OCTET STRING - - ECPoint ::= OCTET STRING - - The value of FieldElement SHALL be the octet string representation of - a field element following the conversion routine in [X9.62], Section - 4.3.3. The value of ECPoint SHALL be the octet string representation - of an elliptic curve point following the conversion routine in - [X9.62], Section 4.3.6. Note that this octet string may represent an - elliptic curve point in compressed or uncompressed form. - - Implementations that support elliptic curve according to this - specification MUST support the uncompressed form and MAY support the - compressed form. - - The components of type ECParameters have the following meanings: - - version specifies the version number of the elliptic curve - parameters. It MUST have the value 1 (ecpVer1). - - - - - - -Polk, et al. Standards Track [Page 14] - -RFC 3279 Algorithms and Identifiers April 2002 - - - fieldID identifies the finite field over which the elliptic curve - is defined. Finite fields are represented by values of the - parameterized type FieldID, constrained to the values of the - objects defined in the information object set FieldTypes. - Additional detail regarding fieldID is provided below. - - curve specifies the coefficients a and b of the elliptic curve E. - Each coefficient is represented as a value of type FieldElement, - an OCTET STRING. seed is an optional parameter used to derive the - coefficients of a randomly generated elliptic curve. - - base specifies the base point P on the elliptic curve. The base - point is represented as a value of type ECPoint, an OCTET STRING. - - order specifies the order n of the base point. - - cofactor is the integer h = #E(Fq)/n. This parameter is specified - as OPTIONAL. However, the cofactor MUST be included in ECDH - public key parameters. The cofactor is not required to support - ECDSA, except in parameter validation. The cofactor MAY be - included to support parameter validation for ECDSA keys. - Parameter validation is not required by this specification. - - The AlgorithmIdentifier within SubjectPublicKeyInfo is the only place - within a certificate where the parameters may be used. If the - elliptic curve parameters are specified as implicitlyCA in the - SubjectPublicKeyInfo AlgorithmIdentifier and the CA signed the - subject certificate using ECDSA, then the certificate issuer's ECDSA - parameters apply to the subject's ECDSA key. If the elliptic curve - parameters are specified as implicitlyCA in the SubjectPublicKeyInfo - AlgorithmIdentifier and the CA signed the certificate using a - signature algorithm other than ECDSA, then clients MUST not make use - of the elliptic curve public key. - - FieldID ::= SEQUENCE { - fieldType OBJECT IDENTIFIER, - parameters ANY DEFINED BY fieldType } - - FieldID is a SEQUENCE of two components, fieldType and parameters. - The fieldType contains an object identifier value that uniquely - identifies the type contained in the parameters. - - The object identifier id-fieldType specifies an arc containing the - object identifiers of each field type. It has the following value: - - id-fieldType OBJECT IDENTIFIER ::= { ansi-X9-62 fieldType(1) } - - - - - -Polk, et al. Standards Track [Page 15] - -RFC 3279 Algorithms and Identifiers April 2002 - - - The object identifiers prime-field and characteristic-two-field name - the two kinds of fields defined in this Standard. They have the - following values: - - prime-field OBJECT IDENTIFIER ::= { id-fieldType 1 } - - Prime-p ::= INTEGER -- Field size p (p in bits) - - characteristic-two-field OBJECT IDENTIFIER ::= { id-fieldType 2 } - - Characteristic-two ::= SEQUENCE { - m INTEGER, -- Field size 2^m - basis OBJECT IDENTIFIER, - parameters ANY DEFINED BY basis } - - The object identifier id-characteristic-two-basis specifies an arc - containing the object identifiers for each type of basis for the - characteristic-two finite fields. It has the following value: - - id-characteristic-two-basis OBJECT IDENTIFIER ::= { - characteristic-two-field basisType(1) } - - The object identifiers gnBasis, tpBasis and ppBasis name the three - kinds of basis for characteristic-two finite fields defined by - [X9.62]. They have the following values: - - gnBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 1 } - - -- for gnBasis, the value of the parameters field is NULL - - tpBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 2 } - - -- type of parameters field for tpBasis is Trinomial - - Trinomial ::= INTEGER - - ppBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 3 } - - -- type of parameters field for ppBasis is Pentanomial - - Pentanomial ::= SEQUENCE { - k1 INTEGER, - k2 INTEGER, - k3 INTEGER } - - - - - - - -Polk, et al. Standards Track [Page 16] - -RFC 3279 Algorithms and Identifiers April 2002 - - - The elliptic curve public key (an ECPoint which is an OCTET STRING) - is mapped to a subjectPublicKey (a BIT STRING) as follows: the most - significant bit of the OCTET STRING becomes the most significant bit - of the BIT STRING, and the least significant bit of the OCTET STRING - becomes the least significant bit of the BIT STRING. Note that this - octet string may represent an elliptic curve point in compressed or - uncompressed form. Implementations that support elliptic curve - according to this specification MUST support the uncompressed form - and MAY support the compressed form. - - If the keyUsage extension is present in a CA or CRL issuer - certificate which conveys an elliptic curve public key, any - combination of the following values MAY be present: - - digitalSignature; - nonRepudiation; and - keyAgreement. - - If the keyAgreement value is present, either of the following values - MAY be present: - - encipherOnly; and - decipherOnly. - - The keyUsage extension MUST NOT assert both encipherOnly and - decipherOnly. - - If the keyUsage extension is present in a CA certificate which - conveys an elliptic curve public key, any combination of the - following values MAY be present: - - digitalSignature; - nonRepudiation; - keyAgreement; - keyCertSign; and - cRLSign. - - As above, if the keyUsage extension asserts keyAgreement then it MAY - assert either encipherOnly and decipherOnly. However, this - specification RECOMMENDS that if keyCertSign or cRLSign is present, - keyAgreement, encipherOnly, and decipherOnly SHOULD NOT be present. - - - - - - - - - - -Polk, et al. Standards Track [Page 17] - -RFC 3279 Algorithms and Identifiers April 2002 - - -3 ASN.1 Module - - PKIX1Algorithms88 { iso(1) identified-organization(3) dod(6) - internet(1) security(5) mechanisms(5) pkix(7) id-mod(0) - id-mod-pkix1-algorithms(17) } - - DEFINITIONS EXPLICIT TAGS ::= BEGIN - - -- EXPORTS All; - - -- IMPORTS NONE; - - -- - -- One-way Hash Functions - -- - - md2 OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) rsadsi(113549) - digestAlgorithm(2) 2 } - - md5 OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) rsadsi(113549) - digestAlgorithm(2) 5 } - - id-sha1 OBJECT IDENTIFIER ::= { - iso(1) identified-organization(3) oiw(14) secsig(3) - algorithms(2) 26 } - - -- - -- DSA Keys and Signatures - -- - - -- OID for DSA public key - - id-dsa OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) x9-57(10040) x9algorithm(4) 1 } - - -- encoding for DSA public key - - DSAPublicKey ::= INTEGER -- public key, y - - Dss-Parms ::= SEQUENCE { - p INTEGER, - q INTEGER, - g INTEGER } - - - - - - -Polk, et al. Standards Track [Page 18] - -RFC 3279 Algorithms and Identifiers April 2002 - - - -- OID for DSA signature generated with SHA-1 hash - - id-dsa-with-sha1 OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) x9-57 (10040) x9algorithm(4) 3 } - - -- encoding for DSA signature generated with SHA-1 hash - - Dss-Sig-Value ::= SEQUENCE { - r INTEGER, - s INTEGER } - - -- - -- RSA Keys and Signatures - -- - - -- arc for RSA public key and RSA signature OIDs - - pkcs-1 OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) 1 } - - -- OID for RSA public keys - - rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1 } - - -- OID for RSA signature generated with MD2 hash - - md2WithRSAEncryption OBJECT IDENTIFIER ::= { pkcs-1 2 } - - -- OID for RSA signature generated with MD5 hash - - md5WithRSAEncryption OBJECT IDENTIFIER ::= { pkcs-1 4 } - - -- OID for RSA signature generated with SHA-1 hash - - sha1WithRSAEncryption OBJECT IDENTIFIER ::= { pkcs-1 5 } - - -- encoding for RSA public key - - RSAPublicKey ::= SEQUENCE { - modulus INTEGER, -- n - publicExponent INTEGER } -- e - - - - - - - - - - -Polk, et al. Standards Track [Page 19] - -RFC 3279 Algorithms and Identifiers April 2002 - - - -- - -- Diffie-Hellman Keys - -- - - dhpublicnumber OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) ansi-x942(10046) - number-type(2) 1 } - - -- encoding for DSA public key - - DHPublicKey ::= INTEGER -- public key, y = g^x mod p - - DomainParameters ::= SEQUENCE { - p INTEGER, -- odd prime, p=jq +1 - g INTEGER, -- generator, g - q INTEGER, -- factor of p-1 - j INTEGER OPTIONAL, -- subgroup factor, j>= 2 - validationParms ValidationParms OPTIONAL } - - ValidationParms ::= SEQUENCE { - seed BIT STRING, - pgenCounter INTEGER } - - -- - -- KEA Keys - -- - - id-keyExchangeAlgorithm OBJECT IDENTIFIER ::= - { 2 16 840 1 101 2 1 1 22 } - - KEA-Parms-Id ::= OCTET STRING - - -- - -- Elliptic Curve Keys, Signatures, and Curves - -- - - ansi-X9-62 OBJECT IDENTIFIER ::= { - iso(1) member-body(2) us(840) 10045 } - - FieldID ::= SEQUENCE { -- Finite field - fieldType OBJECT IDENTIFIER, - parameters ANY DEFINED BY fieldType } - - -- Arc for ECDSA signature OIDS - - id-ecSigType OBJECT IDENTIFIER ::= { ansi-X9-62 signatures(4) } - - - - - -Polk, et al. Standards Track [Page 20] - -RFC 3279 Algorithms and Identifiers April 2002 - - - -- OID for ECDSA signatures with SHA-1 - - ecdsa-with-SHA1 OBJECT IDENTIFIER ::= { id-ecSigType 1 } - - -- OID for an elliptic curve signature - -- format for the value of an ECDSA signature value - - ECDSA-Sig-Value ::= SEQUENCE { - r INTEGER, - s INTEGER } - - -- recognized field type OIDs are defined in the following arc - - id-fieldType OBJECT IDENTIFIER ::= { ansi-X9-62 fieldType(1) } - - -- where fieldType is prime-field, the parameters are of type Prime-p - - prime-field OBJECT IDENTIFIER ::= { id-fieldType 1 } - - Prime-p ::= INTEGER -- Finite field F(p), where p is an odd prime - - -- where fieldType is characteristic-two-field, the parameters are - -- of type Characteristic-two - - characteristic-two-field OBJECT IDENTIFIER ::= { id-fieldType 2 } - - Characteristic-two ::= SEQUENCE { - m INTEGER, -- Field size 2^m - basis OBJECT IDENTIFIER, - parameters ANY DEFINED BY basis } - - -- recognized basis type OIDs are defined in the following arc - - id-characteristic-two-basis OBJECT IDENTIFIER ::= { - characteristic-two-field basisType(3) } - - -- gnbasis is identified by OID gnBasis and indicates - -- parameters are NULL - - gnBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 1 } - - -- parameters for this basis are NULL - - -- trinomial basis is identified by OID tpBasis and indicates - -- parameters of type Pentanomial - - tpBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 2 } - - - - -Polk, et al. Standards Track [Page 21] - -RFC 3279 Algorithms and Identifiers April 2002 - - - -- Trinomial basis representation of F2^m - -- Integer k for reduction polynomial xm + xk + 1 - - Trinomial ::= INTEGER - - -- for pentanomial basis is identified by OID ppBasis and indicates - -- parameters of type Pentanomial - - ppBasis OBJECT IDENTIFIER ::= { id-characteristic-two-basis 3 } - - -- Pentanomial basis representation of F2^m - -- reduction polynomial integers k1, k2, k3 - -- f(x) = x**m + x**k3 + x**k2 + x**k1 + 1 - - Pentanomial ::= SEQUENCE { - k1 INTEGER, - k2 INTEGER, - k3 INTEGER } - - -- The object identifiers gnBasis, tpBasis and ppBasis name - -- three kinds of basis for characteristic-two finite fields - - FieldElement ::= OCTET STRING -- Finite field element - - ECPoint ::= OCTET STRING -- Elliptic curve point - - -- Elliptic Curve parameters may be specified explicitly, - -- specified implicitly through a "named curve", or - -- inherited from the CA - - EcpkParameters ::= CHOICE { - ecParameters ECParameters, - namedCurve OBJECT IDENTIFIER, - implicitlyCA NULL } - - ECParameters ::= SEQUENCE { -- Elliptic curve parameters - version ECPVer, - fieldID FieldID, - curve Curve, - base ECPoint, -- Base point G - order INTEGER, -- Order n of the base point - cofactor INTEGER OPTIONAL } -- The integer h = #E(Fq)/n - - ECPVer ::= INTEGER {ecpVer1(1)} - - - - - - - -Polk, et al. Standards Track [Page 22] - -RFC 3279 Algorithms and Identifiers April 2002 - - - Curve ::= SEQUENCE { - a FieldElement, -- Elliptic curve coefficient a - b FieldElement, -- Elliptic curve coefficient b - seed BIT STRING OPTIONAL } - - id-publicKeyType OBJECT IDENTIFIER ::= { ansi-X9-62 keyType(2) } - - id-ecPublicKey OBJECT IDENTIFIER ::= { id-publicKeyType 1 } - - -- Named Elliptic Curves in ANSI X9.62. - - ellipticCurve OBJECT IDENTIFIER ::= { ansi-X9-62 curves(3) } - - c-TwoCurve OBJECT IDENTIFIER ::= { - ellipticCurve characteristicTwo(0) } - - c2pnb163v1 OBJECT IDENTIFIER ::= { c-TwoCurve 1 } - c2pnb163v2 OBJECT IDENTIFIER ::= { c-TwoCurve 2 } - c2pnb163v3 OBJECT IDENTIFIER ::= { c-TwoCurve 3 } - c2pnb176w1 OBJECT IDENTIFIER ::= { c-TwoCurve 4 } - c2tnb191v1 OBJECT IDENTIFIER ::= { c-TwoCurve 5 } - c2tnb191v2 OBJECT IDENTIFIER ::= { c-TwoCurve 6 } - c2tnb191v3 OBJECT IDENTIFIER ::= { c-TwoCurve 7 } - c2onb191v4 OBJECT IDENTIFIER ::= { c-TwoCurve 8 } - c2onb191v5 OBJECT IDENTIFIER ::= { c-TwoCurve 9 } - c2pnb208w1 OBJECT IDENTIFIER ::= { c-TwoCurve 10 } - c2tnb239v1 OBJECT IDENTIFIER ::= { c-TwoCurve 11 } - c2tnb239v2 OBJECT IDENTIFIER ::= { c-TwoCurve 12 } - c2tnb239v3 OBJECT IDENTIFIER ::= { c-TwoCurve 13 } - c2onb239v4 OBJECT IDENTIFIER ::= { c-TwoCurve 14 } - c2onb239v5 OBJECT IDENTIFIER ::= { c-TwoCurve 15 } - c2pnb272w1 OBJECT IDENTIFIER ::= { c-TwoCurve 16 } - c2pnb304w1 OBJECT IDENTIFIER ::= { c-TwoCurve 17 } - c2tnb359v1 OBJECT IDENTIFIER ::= { c-TwoCurve 18 } - c2pnb368w1 OBJECT IDENTIFIER ::= { c-TwoCurve 19 } - c2tnb431r1 OBJECT IDENTIFIER ::= { c-TwoCurve 20 } - - primeCurve OBJECT IDENTIFIER ::= { ellipticCurve prime(1) } - - prime192v1 OBJECT IDENTIFIER ::= { primeCurve 1 } - prime192v2 OBJECT IDENTIFIER ::= { primeCurve 2 } - prime192v3 OBJECT IDENTIFIER ::= { primeCurve 3 } - prime239v1 OBJECT IDENTIFIER ::= { primeCurve 4 } - prime239v2 OBJECT IDENTIFIER ::= { primeCurve 5 } - prime239v3 OBJECT IDENTIFIER ::= { primeCurve 6 } - prime256v1 OBJECT IDENTIFIER ::= { primeCurve 7 } - - END - - - -Polk, et al. Standards Track [Page 23] - -RFC 3279 Algorithms and Identifiers April 2002 - - -4 References - - [FIPS 180-1] Federal Information Processing Standards Publication - (FIPS PUB) 180-1, Secure Hash Standard, 17 April 1995. - [Supersedes FIPS PUB 180 dated 11 May 1993.] - - [FIPS 186-2] Federal Information Processing Standards Publication - (FIPS PUB) 186, Digital Signature Standard, 27 January - 2000. [Supersedes FIPS PUB 186-1 dated 15 December - 1998.] - - [P1363] IEEE P1363, "Standard Specifications for Public-Key - Cryptography", 2001. - - [RC95] Rogier, N. and Chauvaud, P., "The compression function - of MD2 is not collision free," Presented at Selected - Areas in Cryptography '95, May 1995. - - [RFC 1034] Mockapetris, P., "Domain Names - Concepts and - Facilities", STD 13, RFC 1034, November 1987. - - [RFC 1319] Kaliski, B., "The MD2 Message-Digest Algorithm", RFC - 1319, April 1992. - - [RFC 1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC - 1321, April 1992. - - [RFC 1422] Kent, S., "Privacy Enhancement for Internet Electronic - Mail: Part II: Certificate-Based Key Management", RFC - 1422, February 1993. - - [RFC 1423] Balenson, D., "Privacy Enhancement for Internet - Electronic Mail: Part III: Algorithms, Modes, and - Identifiers", RFC 1423, February 1993. - - [RFC 2119] Bradner, S., "Key Words for Use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC 2313] Kaliski, B., "PKCS #1: RSA Encryption Version 1.5", - RFC 2313, March 1998. - - [RFC 2459] Housley, R., Ford, W., Polk, W. and D. Solo "Internet - X.509 Public Key Infrastructure: Certificate and CRL - Profile", RFC 2459, January, 1999. - - [RFC 3174] Eastlake, D. and P. Jones, "US Secure Hash Algorithm 1 - (SHA1)", RFC 3174, September 2001. - - - - -Polk, et al. Standards Track [Page 24] - -RFC 3279 Algorithms and Identifiers April 2002 - - - [RFC 3280] Housley, R., Polk, W., Ford, W. and D. Solo, "Internet - X.509 Public Key Infrastructure Certificate and - Certificate Revocation List (CRL) Profile", RFC 3280, - April 2002. - - [SDN.701r] SDN.701, "Message Security Protocol 4.0", Revision A - 1997-02-06. - - [X.208] CCITT Recommendation X.208: Specification of Abstract - Syntax Notation One (ASN.1), 1988. - - [X.660] ITU-T Recommendation X.660 Information Technology - - ASN.1 encoding rules: Specification of Basic Encoding - Rules (BER), Canonical Encoding Rules (CER) and - Distinguished Encoding Rules (DER), 1997. - - [X9.42] ANSI X9.42-2000, "Public Key Cryptography for The - Financial Services Industry: Agreement of Symmetric - Keys Using Discrete Logarithm Cryptography", December, - 1999. - - [X9.62] X9.62-1998, "Public Key Cryptography For The Financial - Services Industry: The Elliptic Curve Digital - Signature Algorithm (ECDSA)", January 7, 1999. - - [X9.63] ANSI X9.63-2001, "Public Key Cryptography For The - Financial Services Industry: Key Agreement and Key - Transport Using Elliptic Curve Cryptography", Work in - Progress. - -5 Security Considerations - - This specification does not constrain the size of public keys or - their parameters for use in the Internet PKI. However, the key size - selected impacts the strength achieved when implementing - cryptographic services. Selection of appropriate key sizes is - critical to implementing appropriate security. - - This specification does not identify particular elliptic curves for - use in the Internet PKI. However, the particular curve selected - impact the strength of the digital signatures. Some curves are - cryptographically stronger than others! - - In general, use of "well-known" curves, such as the "named curves" - from ANSI X9.62, is a sound strategy. For additional information, - refer to X9.62 Appendix H.1.3, "Key Length Considerations" and - Appendix A.1, "Avoiding Cryptographically Weak Keys". - - - - -Polk, et al. Standards Track [Page 25] - -RFC 3279 Algorithms and Identifiers April 2002 - - - This specification supplements RFC 3280. The security considerations - section of that document applies to this specification as well. - -6 Intellectual Property Rights - - The IETF has been notified of intellectual property rights claimed in - regard to some or all of the specification contained in this - document. For more information consult the online list of claimed - rights. - - The IETF takes no position regarding the validity or scope of any - intellectual property or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards- related documentation can be found in BCP-11. Copies of - claims of rights made available for publication and any assurances of - licenses to be made available, or the result of an attempt made to - obtain a general license or permission for the use of such - proprietary rights by implementors or users of this specification can - be obtained from the IETF Secretariat. - -7 Author Addresses: - - Tim Polk - NIST - 100 Bureau Drive, Stop 8930 - Gaithersburg, MD 20899-8930 - USA - EMail: tim.polk@nist.gov - - Russell Housley - RSA Laboratories - 918 Spring Knoll Drive - Herndon, VA 20170 - USA - EMail: rhousley@rsasecurity.com - - Larry Bassham - NIST - 100 Bureau Drive, Stop 8930 - Gaithersburg, MD 20899-8930 - USA - EMail: lbassham@nist.gov - - - - - -Polk, et al. Standards Track [Page 26] - -RFC 3279 Algorithms and Identifiers April 2002 - - -8. Full Copyright Statement - - Copyright (C) The Internet Society (2002). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Polk, et al. Standards Track [Page 27] - diff --git a/utils/open-isns/doc/rfc3720.txt b/utils/open-isns/doc/rfc3720.txt deleted file mode 100644 index 2041f93..0000000 --- a/utils/open-isns/doc/rfc3720.txt +++ /dev/null @@ -1,14395 +0,0 @@ - - - - - - -Network Working Group J. Satran -Request for Comments: 3720 K. Meth -Category: Standards Track IBM - C. Sapuntzakis - Cisco Systems - M. Chadalapaka - Hewlett-Packard Co. - E. Zeidner - IBM - April 2004 - - - Internet Small Computer Systems Interface (iSCSI) - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - This document describes a transport protocol for Internet Small - Computer Systems Interface (iSCSI) that works on top of TCP. The - iSCSI protocol aims to be fully compliant with the standardized SCSI - architecture model. - - SCSI is a popular family of protocols that enable systems to - communicate with I/O devices, especially storage devices. SCSI - protocols are request/response application protocols with a common - standardized architecture model and basic command set, as well as - standardized command sets for different device classes (disks, tapes, - media-changers etc.). - - As system interconnects move from the classical bus structure to a - network structure, SCSI has to be mapped to network transport - protocols. IP networks now meet the performance requirements of fast - system interconnects and as such are good candidates to "carry" SCSI. - - - - - - - -Satran, et al. Standards Track [Page 1] - -RFC 3720 iSCSI April 2004 - - -Table of Contents - - 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 9 - 2. Definitions and Acronyms. . . . . . . . . . . . . . . . . . . 10 - 2.1. Definitions. . . . . . . . . . . . . . . . . . . . . . 10 - 2.2. Acronyms . . . . . . . . . . . . . . . . . . . . . . . 14 - 2.3. Conventions. . . . . . . . . . . . . . . . . . . . . . 16 - 2.3.1. Word Rule. . . . . . . . . . . . . . . . . . 16 - 2.3.2. Half-Word Rule . . . . . . . . . . . . . . . 17 - 2.3.3. Byte Rule. . . . . . . . . . . . . . . . . . 17 - 3. Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . 17 - 3.1. SCSI Concepts. . . . . . . . . . . . . . . . . . . . . 17 - 3.2. iSCSI Concepts and Functional Overview . . . . . . . . 18 - 3.2.1. Layers and Sessions. . . . . . . . . . . . . 19 - 3.2.2. Ordering and iSCSI Numbering . . . . . . . . 19 - 3.2.2.1. Command Numbering and - Acknowledging . . . . . . . . . . 20 - 3.2.2.2. Response/Status Numbering and - Acknowledging . . . . . . . . . . 23 - 3.2.2.3. Data Sequencing . . . . . . . . 24 - 3.2.3. iSCSI Login. . . . . . . . . . . . . . . . . 24 - 3.2.4. iSCSI Full Feature Phase . . . . . . . . . . 25 - 3.2.4.1. Command Connection Allegiance . . 26 - 3.2.4.2. Data Transfer Overview. . . . . . 27 - 3.2.4.3. Tags and Integrity Checks . . . . 28 - 3.2.4.4. Task Management . . . . . . . . . 28 - 3.2.5. iSCSI Connection Termination . . . . . . . . 29 - 3.2.6. iSCSI Names. . . . . . . . . . . . . . . . . 29 - 3.2.6.1. iSCSI Name Properties . . . . . . 30 - 3.2.6.2. iSCSI Name Encoding . . . . . . . 31 - 3.2.6.3. iSCSI Name Structure. . . . . . . 32 - 3.2.6.3.1. Type "iqn." (iSCSI - Qualified Name) . . . 32 - 3.2.6.3.2. Type "eui." (IEEE - EUI-64 format). . . . 34 - 3.2.7. Persistent State . . . . . . . . . . . . . . 34 - 3.2.8. Message Synchronization and Steering . . . . 35 - 3.2.8.1. Sync/Steering and iSCSI PDU - Length . . . . . . . . . . . . . 36 - 3.3. iSCSI Session Types. . . . . . . . . . . . . . . . . . 36 - 3.4. SCSI to iSCSI Concepts Mapping Model . . . . . . . . . 37 - 3.4.1. iSCSI Architecture Model . . . . . . . . . . 37 - 3.4.2. SCSI Architecture Model. . . . . . . . . . . 39 - 3.4.3. Consequences of the Model. . . . . . . . . . 41 - 3.4.3.1. I_T Nexus State . . . . . . . . . 42 - 3.5. Request/Response Summary . . . . . . . . . . . . . . . 42 - 3.5.1. Request/Response Types Carrying SCSI Payload 43 - 3.5.1.1. SCSI-Command . . . . . . . . . . 43 - - - -Satran, et al. Standards Track [Page 2] - -RFC 3720 iSCSI April 2004 - - - 3.5.1.2. SCSI-Response . . . . . . . . . 43 - 3.5.1.3. Task Management Function Request. 44 - 3.5.1.4. Task Management Function Response 44 - 3.5.1.5. SCSI Data-Out and SCSI Data-In. . 44 - 3.5.1.6. Ready To Transfer (R2T) . . . . . 45 - 3.5.2. Requests/Responses carrying SCSI and iSCSI - Payload. . . . . . . . . . . . . . . . . . . 46 - 3.5.2.1. Asynchronous Message. . . . . . . 46 - 3.5.3. Requests/Responses Carrying iSCSI Only - Payload. . . . . . . . . . . . . . . . . . . 46 - 3.5.3.1. Text Request and Text Response. . 46 - 3.5.3.2. Login Request and Login Response. 47 - 3.5.3.3. Logout Request and Response . . . 47 - 3.5.3.4. SNACK Request . . . . . . . . . . 48 - 3.5.3.5. Reject. . . . . . . . . . . . . . 48 - 3.5.3.6. NOP-Out Request and NOP-In - Response . . . . . . . . . . . . 48 - 4. SCSI Mode Parameters for iSCSI. . . . . . . . . . . . . . . . 48 - 5. Login and Full Feature Phase Negotiation. . . . . . . . . . . 48 - 5.1. Text Format. . . . . . . . . . . . . . . . . . . . . . 50 - 5.2. Text Mode Negotiation. . . . . . . . . . . . . . . . . 53 - 5.2.1. List negotiations. . . . . . . . . . . . . . 56 - 5.2.2. Simple-value Negotiations. . . . . . . . . . 56 - 5.3. Login Phase. . . . . . . . . . . . . . . . . . . . . . 57 - 5.3.1. Login Phase Start. . . . . . . . . . . . . . 60 - 5.3.2. iSCSI Security Negotiation . . . . . . . . . 62 - 5.3.3. Operational Parameter Negotiation During - the Login Phase. . . . . . . . . . . . . . . 63 - 5.3.4. Connection Reinstatement . . . . . . . . . . 64 - 5.3.5. Session Reinstatement, Closure, and Timeout. 64 - 5 5.3.5.1. Loss of Nexus - Notification. . . . . 65 - 5.3.6. Session Continuation and Failure . . . . . . 65 - 5.4. Operational Parameter Negotiation Outside the Login - Phase. . . . . . . . . . . . . . . . . . . . . . . . . 66 - 6. iSCSI Error Handling and Recovery . . . . . . . . . . . . . . 67 - 6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 67 - 6.1.1. Background . . . . . . . . . . . . . . . . . 67 - 6.1.2. Goals. . . . . . . . . . . . . . . . . . . . 67 - 6.1.3. Protocol Features and State Expectations . . 68 - 6.1.4. Recovery Classes . . . . . . . . . . . . . . 69 - 6.1.4.1. Recovery Within-command . . . . . 69 - 6.1.4.2. Recovery Within-connection. . . . 70 - 6.1.4.3. Connection Recovery . . . . . . . 71 - 6.1.4.4. Session Recovery. . . . . . . . . 72 - 6.1.5. Error Recovery Hierarchy . . . . . . . . . . . 72 - 6.2. Retry and Reassign in Recovery . . . . . . . . . . . . 74 - 6.2.1. Usage of Retry . . . . . . . . . . . . . . . 74 - - - -Satran, et al. Standards Track [Page 3] - -RFC 3720 iSCSI April 2004 - - - 6.2.2. Allegiance Reassignment. . . . . . . . . . . 75 - 6.3. Usage Of Reject PDU in Recovery. . . . . . . . . . . . 76 - 6.4. Connection Timeout Management. . . . . . . . . . . . . 76 - 6.4.1. Timeouts on Transport Exception Events . . . 77 - 6.4.2. Timeouts on Planned Decommissioning. . . . . 77 - 6.5. Implicit Termination of Tasks. . . . . . . . . . . . . 77 - 6.6. Format Errors. . . . . . . . . . . . . . . . . . . . . 78 - 6.7. Digest Errors. . . . . . . . . . . . . . . . . . . . . 78 - 6.8. Sequence Errors. . . . . . . . . . . . . . . . . . . . 80 - 6.9. SCSI Timeouts. . . . . . . . . . . . . . . . . . . . . 81 - 6.10. Negotiation Failures . . . . . . . . . . . . . . . . . 81 - 6.11. Protocol Errors. . . . . . . . . . . . . . . . . . . . 82 - 6.12. Connection Failures. . . . . . . . . . . . . . . . . . 82 - 6.13. Session Errors . . . . . . . . . . . . . . . . . . . . 83 - 7. State Transitions . . . . . . . . . . . . . . . . . . . . . . 84 - 7.1. Standard Connection State Diagrams . . . . . . . . . . 84 - 7.1.1. State Descriptions for Initiators and - Targets. . . . . . . . . . . . . . . . . . . 84 - 7.1.2. State Transition Descriptions for Initiators - and Targets. . . . . . . . . . . . . . . . . 85 - 7.1.3. Standard Connection State Diagram for an - Initiator. . . . . . . . . . . . . . . . . . 88 - 7.1.4. Standard Connection State Diagram for a - Target . . . . . . . . . . . . . . . . . . . 90 - 7.2. Connection Cleanup State Diagram for Initiators and - Targets. . . . . . . . . . . . . . . . . . . . . . . . 92 - 7.2.1. State Descriptions for Initiators and - Targets. . . . . . . . . . . . . . . . . . . 94 - 7.2.2. State Transition Descriptions for Initiators - and Targets. . . . . . . . . . . . . . . . . 94 - 7.3. Session State Diagrams . . . . . . . . . . . . . . . . 95 - 7.3.1. Session State Diagram for an Initiator . . . 95 - 7.3.2. Session State Diagram for a Target . . . . . 96 - 7.3.3. State Descriptions for Initiators and - Targets. . . . . . . . . . . . . . . . . . . 97 - 7.3.4. State Transition Descriptions for Initiators - and Targets. . . . . . . . . . . . . . . . . 98 - 8. Security Considerations . . . . . . . . . . . . . . . . . . . 99 - 8.1. iSCSI Security Mechanisms. . . . . . . . . . . . . . . 100 - 8.2. In-band Initiator-Target Authentication. . . . . . . . 100 - 8.2.1. CHAP Considerations. . . . . . . . . . . . . 101 - 8.2.2. SRP Considerations . . . . . . . . . . . . . 103 - 8.3. IPsec. . . . . . . . . . . . . . . . . . . . . . . . . 104 - 8.3.1. Data Integrity and Authentication. . . . . . 104 - 8.3.2. Confidentiality. . . . . . . . . . . . . . . 105 - 8.3.3. Policy, Security Associations, and - Cryptographic Key Management . . . . . . . . 105 - 9. Notes to Implementers . . . . . . . . . . . . . . . . . . . . 106 - - - -Satran, et al. Standards Track [Page 4] - -RFC 3720 iSCSI April 2004 - - - 9.1. Multiple Network Adapters. . . . . . . . . . . . . . . 106 - 9.1.1. Conservative Reuse of ISIDs. . . . . . . . . 107 - 9.1.2. iSCSI Name, ISID, and TPGT Use . . . . . . . 107 - 9.2. Autosense and Auto Contingent Allegiance (ACA) . . . . 109 - 9.3. iSCSI Timeouts . . . . . . . . . . . . . . . . . . . . 109 - 9.4. Command Retry and Cleaning Old Command Instances . . . 110 - 9.5. Synch and Steering Layer and Performance . . . . . . . 110 - 9.6. Considerations for State-dependent Devices and - Long-lasting SCSI Operations . . . . . . . . . . . . . 111 - 9.6.1. Determining the Proper ErrorRecoveryLevel. . 112 - 10. iSCSI PDU Formats . . . . . . . . . . . . . . . . . . . . . . 112 - 10.1. iSCSI PDU Length and Padding . . . . . . . . . . . . . 113 - 10.2. PDU Template, Header, and Opcodes. . . . . . . . . . . 113 - 10.2.1. Basic Header Segment (BHS) . . . . . . . . . 114 - 10.2.1.1. I . . . . . . . . . . . . . . . . 115 - 10.2.1.2. Opcode. . . . . . . . . . . . . . 115 - 10.2.1.3. Final (F) bit . . . . . . . . . . 116 - 10.2.1.4. Opcode-specific Fields. . . . . . 116 - 10.2.1.5. TotalAHSLength. . . . . . . . . . 116 - 10.2.1.6. DataSegmentLength . . . . . . . . 116 - 10.2.1.7. LUN . . . . . . . . . . . . . . . 116 - 10.2.1.8. Initiator Task Tag. . . . . . . . 117 - 10.2.2. Additional Header Segment (AHS) . . . . . . . 117 - 10.2.2.1. AHSType . . . . . . . . . . . . . 117 - 10.2.2.2. AHSLength . . . . . . . . . . . . 117 - 10.2.2.3. Extended CDB AHS. . . . . . . . . 118 - 10.2.2.4. Bidirectional Expected Read-Data - Length AHS. . . . . . . . . . . . 118 - 10.2.3. Header Digest and Data Digest. . . . . . . . 118 - 10.2.4. Data Segment . . . . . . . . . . . . . . . . 119 - 10.3. SCSI Command . . . . . . . . . . . . . . . . . . . . . 119 - 10.3.1. Flags and Task Attributes (byte 1) . . . . . 120 - 10.3.2. CmdSN - Command Sequence Number. . . . . . . 120 - 10.3.3. ExpStatSN. . . . . . . . . . . . . . . . . . 120 - 10.3.4. Expected Data Transfer Length. . . . . . . . 121 - 10.3.5. CDB - SCSI Command Descriptor Block. . . . . 121 - 10.3.6. Data Segment - Command Data. . . . . . . . . 121 - 10.4. SCSI Response. . . . . . . . . . . . . . . . . . . . . 122 - 10.4.1. Flags (byte 1) . . . . . . . . . . . . . . . 123 - 10.4.2. Status . . . . . . . . . . . . . . . . . . . 123 - 10.4.3. Response . . . . . . . . . . . . . . . . . . 124 - 10.4.4. SNACK Tag. . . . . . . . . . . . . . . . . . 125 - 10.4.5. Residual Count . . . . . . . . . . . . . . . 125 - 10.4.6. Bidirectional Read Residual Count. . . . . . 125 - 10.4.7. Data Segment - Sense and Response Data - Segment. . . . . . . . . . . . . . . . . . . 125 - 10.4.7.1. SenseLength . . . . . . . . . . . 126 - 10.4.7.2. Sense Data. . . . . . . . . . . . 126 - - - -Satran, et al. Standards Track [Page 5] - -RFC 3720 iSCSI April 2004 - - - 10.4.8. ExpDataSN. . . . . . . . . . . . . . . . . . 127 - 10.4.9. StatSN - Status Sequence Number. . . . . . . 127 - 10.4.10. ExpCmdSN - Next Expected CmdSN from this - Initiator. . . . . . . . . . . . . . . . . . 128 - 10.4.11. MaxCmdSN - Maximum CmdSN from this Initiator 128 - 10.5. Task Management Function Request . . . . . . . . . . . 129 - 10.5.1. Function . . . . . . . . . . . . . . . . . . 129 - 10.5.2. TotalAHSLength and DataSegmentLength . . . . 132 - 10.5.3. LUN. . . . . . . . . . . . . . . . . . . . . 132 - 10.5.4. Referenced Task Tag. . . . . . . . . . . . . 132 - 10.5.5. RefCmdSN . . . . . . . . . . . . . . . . . . 132 - 10.5.6. ExpDataSN. . . . . . . . . . . . . . . . . . 133 - 10.6. Task Management Function Response. . . . . . . . . . . 134 - 10.6.1. Response . . . . . . . . . . . . . . . . . . 134 - 10.6.2. Task Management Actions on Task Sets . . . . 136 - 10.6.3. TotalAHSLength and DataSegmentLength . . . . 137 - 10.7. SCSI Data-Out & SCSI Data-In . . . . . . . . . . . . . 137 - 10.7.1. F (Final) Bit. . . . . . . . . . . . . . . . 139 - 10.7.2. A (Acknowledge) Bit. . . . . . . . . . . . . 139 - 10.7.3. Flags (byte 1) . . . . . . . . . . . . . . . 140 - 10.7.4. Target Transfer Tag and LUN. . . . . . . . . 140 - 10.7.5. DataSN . . . . . . . . . . . . . . . . . . . 141 - 10.7.6. Buffer Offset. . . . . . . . . . . . . . . . 141 - 10.7.7. DataSegmentLength. . . . . . . . . . . . . . 141 - 10.8. Ready To Transfer (R2T). . . . . . . . . . . . . . . . 142 - 10.8.1. TotalAHSLength and DataSegmentLength . . . . 143 - 10.8.2. R2TSN. . . . . . . . . . . . . . . . . . . . 143 - 10.8.3. StatSN . . . . . . . . . . . . . . . . . . . 144 - 10.8.4. Desired Data Transfer Length and Buffer - Offset . . . . . . . . . . . . . . . . . . . 144 - 10.8.5. Target Transfer Tag. . . . . . . . . . . . . 144 - 10.9. Asynchronous Message . . . . . . . . . . . . . . . . . 145 - 10.9.1. AsyncEvent . . . . . . . . . . . . . . . . . 146 - 10.9.2. AsyncVCode . . . . . . . . . . . . . . . . . 147 - 10.9.3. LUN. . . . . . . . . . . . . . . . . . . . . 147 - 10.9.4. Sense Data and iSCSI Event Data. . . . . . . 148 - 10.9.4.1. SenseLength . . . . . . . . . . . 148 - 10.10. Text Request . . . . . . . . . . . . . . . . . . . . . 149 - 10.10.1. F (Final) Bit. . . . . . . . . . . . . . . . 150 - 10.10.2. C (Continue) Bit . . . . . . . . . . . . . . 150 - 10.10.3. Initiator Task Tag . . . . . . . . . . . . . 150 - 10.10.4. Target Transfer Tag. . . . . . . . . . . . . 150 - 10.10.5. Text . . . . . . . . . . . . . . . . . . . . 151 - 10.11. Text Response. . . . . . . . . . . . . . . . . . . . . 152 - 10.11.1. F (Final) Bit. . . . . . . . . . . . . . . . 152 - 10.11.2. C (Continue) Bit . . . . . . . . . . . . . . 153 - 10.11.3. Initiator Task Tag . . . . . . . . . . . . . 153 - 10.11.4. Target Transfer Tag. . . . . . . . . . . . . 153 - - - -Satran, et al. Standards Track [Page 6] - -RFC 3720 iSCSI April 2004 - - - 10.11.5. StatSN . . . . . . . . . . . . . . . . . . . 154 - 10.11.6. Text Response Data . . . . . . . . . . . . . 154 - 10.12. Login Request. . . . . . . . . . . . . . . . . . . . . 154 - 10.12.1. T (Transit) Bit. . . . . . . . . . . . . . . 155 - 10.12.2. C (Continue) Bit . . . . . . . . . . . . . . 155 - 10.12.3. CSG and NSG. . . . . . . . . . . . . . . . . 156 - 10.12.4. Version. . . . . . . . . . . . . . . . . . . 156 - 10.12.4.1. Version-max. . . . . . . . . . . 156 - 10.12.4.2. Version-min. . . . . . . . . . . 156 - 10.12.5. ISID . . . . . . . . . . . . . . . . . . . . 157 - 10.12.6. TSIH . . . . . . . . . . . . . . . . . . . . 158 - 10.12.7. Connection ID - CID. . . . . . . . . . . . . 158 - 10.12.8. CmdSN. . . . . . . . . . . . . . . . . . . . 159 - 10.12.9. ExpStatSN. . . . . . . . . . . . . . . . . . 159 - 10.12.10. Login Parameters . . . . . . . . . . . . . . 159 - 10.13. Login Response . . . . . . . . . . . . . . . . . . . . 160 - 10.13.1. Version-max. . . . . . . . . . . . . . . . . 160 - 10.13.2. Version-active . . . . . . . . . . . . . . . 161 - 10.13.3. TSIH . . . . . . . . . . . . . . . . . . . . 161 - 10.13.4. StatSN . . . . . . . . . . . . . . . . . . . 161 - 10.13.5. Status-Class and Status-Detail . . . . . . . 161 - 10.13.6. T (Transit) Bit. . . . . . . . . . . . . . . 164 - 10.13.7. C (Continue) Bit . . . . . . . . . . . . . . 164 - 10.13.8. Login Parameters . . . . . . . . . . . . . . 164 - 10.14. Logout Request . . . . . . . . . . . . . . . . . . . . 165 - 10.14.1. Reason Code. . . . . . . . . . . . . . . . . 167 - 10.14.2. TotalAHSLength and DataSegmentLength . . . . 168 - 10.14.3. CID. . . . . . . . . . . . . . . . . . . . . 168 - 10.14.4. ExpStatSN. . . . . . . . . . . . . . . . . . 168 - 10.14.5. Implicit termination of tasks. . . . . . . . 168 - 10.15. Logout Response. . . . . . . . . . . . . . . . . . . . 169 - 10.15.1. Response . . . . . . . . . . . . . . . . . . 170 - 10.15.2. TotalAHSLength and DataSegmentLength . . . . 170 - 10.15.3. Time2Wait. . . . . . . . . . . . . . . . . . 170 - 10.15.4. Time2Retain. . . . . . . . . . . . . . . . . 170 - 10.16. SNACK Request. . . . . . . . . . . . . . . . . . . . . 171 - 10.16.1. Type . . . . . . . . . . . . . . . . . . . . 172 - 10.16.2. Data Acknowledgement . . . . . . . . . . . . 173 - 10.16.3. Resegmentation . . . . . . . . . . . . . . . 173 - 10.16.4. Initiator Task Tag . . . . . . . . . . . . . 174 - 10.16.5. Target Transfer Tag or SNACK Tag . . . . . . 174 - 10.16.6. BegRun . . . . . . . . . . . . . . . . . . . 174 - 10.16.7. RunLength. . . . . . . . . . . . . . . . . . 174 - 10.17. Reject . . . . . . . . . . . . . . . . . . . . . . . . 175 - 10.17.1. Reason . . . . . . . . . . . . . . . . . . . 176 - 10.17.2. DataSN/R2TSN . . . . . . . . . . . . . . . . 177 - 10.17.3. StatSN, ExpCmdSN and MaxCmdSN. . . . . . . . 177 - 10.17.4. Complete Header of Bad PDU . . . . . . . . . 177 - - - -Satran, et al. Standards Track [Page 7] - -RFC 3720 iSCSI April 2004 - - - 10.18. NOP-Out. . . . . . . . . . . . . . . . . . . . . . . . 178 - 10.18.1. Initiator Task Tag . . . . . . . . . . . . . 179 - 10.18.2. Target Transfer Tag. . . . . . . . . . . . . 179 - 10.18.3. Ping Data. . . . . . . . . . . . . . . . . . 179 - 10.19. NOP-In . . . . . . . . . . . . . . . . . . . . . . . . 180 - 10.19.1. Target Transfer Tag. . . . . . . . . . . . . 181 - 10.19.2. StatSN . . . . . . . . . . . . . . . . . . . 181 - 10.19.3. LUN. . . . . . . . . . . . . . . . . . . . . 181 - 11. iSCSI Security Text Keys and Authentication Methods . . . . . 181 - 11.1. AuthMethod . . . . . . . . . . . . . . . . . . . . . . 182 - 11.1.1. Kerberos . . . . . . . . . . . . . . . . . . 184 - 11.1.2. Simple Public-Key Mechanism (SPKM) . . . . . 184 - 11.1.3. Secure Remote Password (SRP) . . . . . . . . 185 - 11.1.4. Challenge Handshake Authentication Protocol - (CHAP) . . . . . . . . . . . . . . . . . . . 186 - 12. Login/Text Operational Text Keys. . . . . . . . . . . . . . . 187 - 12.1. HeaderDigest and DataDigest. . . . . . . . . . . . . . 188 - 12.2. MaxConnections . . . . . . . . . . . . . . . . . . . . 190 - 12.3. SendTargets. . . . . . . . . . . . . . . . . . . . . . 191 - 12.4. TargetName . . . . . . . . . . . . . . . . . . . . . . 191 - 12.5. InitiatorName. . . . . . . . . . . . . . . . . . . . . 192 - 12.6. TargetAlias. . . . . . . . . . . . . . . . . . . . . . 192 - 12.7. InitiatorAlias . . . . . . . . . . . . . . . . . . . . 193 - 12.8. TargetAddress. . . . . . . . . . . . . . . . . . . . . 193 - 12.9. TargetPortalGroupTag . . . . . . . . . . . . . . . . . 194 - 12.10. InitialR2T . . . . . . . . . . . . . . . . . . . . . . 194 - 12.11. ImmediateData. . . . . . . . . . . . . . . . . . . . . 195 - 12.12. MaxRecvDataSegmentLength . . . . . . . . . . . . . . . 196 - 12.13. MaxBurstLength . . . . . . . . . . . . . . . . . . . . 196 - 12.14. FirstBurstLength . . . . . . . . . . . . . . . . . . . 197 - 12.15. DefaultTime2Wait . . . . . . . . . . . . . . . . . . . 197 - 12.16. DefaultTime2Retain . . . . . . . . . . . . . . . . . . 198 - 12.17. MaxOutstandingR2T. . . . . . . . . . . . . . . . . . . 198 - 12.18. DataPDUInOrder . . . . . . . . . . . . . . . . . . . . 198 - 12.19. DataSequenceInOrder. . . . . . . . . . . . . . . . . . 199 - 12.20. ErrorRecoveryLevel . . . . . . . . . . . . . . . . . . 199 - 12.21. SessionType. . . . . . . . . . . . . . . . . . . . . . 200 - 12.22. The Private or Public Extension Key Format . . . . . . 200 - 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 201 - 13.1. Naming Requirements. . . . . . . . . . . . . . . . . . 203 - 13.2. Mechanism Specification Requirements . . . . . . . . . 203 - 13.3. Publication Requirements . . . . . . . . . . . . . . . 203 - 13.4. Security Requirements. . . . . . . . . . . . . . . . . 203 - 13.5. Registration Procedure . . . . . . . . . . . . . . . . 204 - 13.5.1. Present the iSCSI extension item to the - Community. . . . . . . . . . . . . . . . . . 204 - 13.5.2. iSCSI extension item review and IESG - approval . . . . . . . . . . . . . . . . . . 204 - - - -Satran, et al. Standards Track [Page 8] - -RFC 3720 iSCSI April 2004 - - - 13.5.3. IANA Registration. . . . . . . . . . . . . . 204 - 13.5.4. Standard iSCSI extension item-label format . 204 - 13.6. IANA Procedures for Registering iSCSI extension items. 205 - References. . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 - Appendix A. Sync and Steering with Fixed Interval Markers . . . . 209 - A.1. Markers At Fixed Intervals . . . . . . . . . . . . . . 209 - A.2. Initial Marker-less Interval . . . . . . . . . . . . . 210 - A.3. Negotiation. . . . . . . . . . . . . . . . . . . . . . 210 - A.3.1. OFMarker, IFMarker . . . . . . . . . . . . . 210 - A.3.2. OFMarkInt, IFMarkInt . . . . . . . . . . . . 211 - Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 212 - B.1. Read Operation Example . . . . . . . . . . . . . . . . 212 - B.2. Write Operation Example. . . . . . . . . . . . . . . . 213 - B.3. R2TSN/DataSN Use Examples. . . . . . . . . . . . . . . 214 - B.4. CRC Examples . . . . . . . . . . . . . . . . . . . . . 217 - Appendix C. Login Phase Examples . . . . . . . . . . . . . . . . 219 - Appendix D. SendTargets Operation. . . . . . . . . . . . . . . . 229 - Appendix E. Algorithmic Presentation of Error Recovery Classes . 233 - E.1. General Data Structure and Procedure Description . . . 233 - E.2. Within-command Error Recovery Algorithms . . . . . . . 234 - E.2.1. Procedure Descriptions . . . . . . . . . . . 234 - E.2.2. Initiator Algorithms . . . . . . . . . . . . 235 - E.2.3. Target Algorithms. . . . . . . . . . . . . . 237 - E.3. Within-connection Recovery Algorithms. . . . . . . . . 240 - E.3.1. Procedure Descriptions . . . . . . . . . . . 240 - E.3.2. Initiator Algorithms . . . . . . . . . . . . 241 - E.3.3. Target Algorithms. . . . . . . . . . . . . . 243 - E.4. Connection Recovery Algorithms . . . . . . . . . . . . 243 - E.4.1. Procedure Descriptions . . . . . . . . . . . 243 - E.4.2. Initiator Algorithms . . . . . . . . . . . . 244 - E.4.3. Target Algorithms. . . . . . . . . . . . . . 246 - Appendix F. Clearing Effects of Various Events on Targets. . . . 249 - F.1. Clearing Effects on iSCSI Objects. . . . . . . . . . . 249 - F.2. Clearing Effects on SCSI Objects . . . . . . . . . . . 253 - Acknowledgements. . . . . . . . . . . . . . . . . . . . . . . . . 254 - Authors' Addresses. . . . . . . . . . . . . . . . . . . . . . . . 256 - Full Copyright Statement. . . . . . . . . . . . . . . . . . . . . 257 - -1. Introduction - - The Small Computer Systems Interface (SCSI) is a popular family of - protocols for communicating with I/O devices, especially storage - devices. SCSI is a client-server architecture. Clients of a SCSI - interface are called "initiators". Initiators issue SCSI "commands" - to request services from components, logical units of a server known - as a "target". A "SCSI transport" maps the client-server SCSI - protocol to a specific interconnect. An Initiator is one endpoint of - a SCSI transport and a target is the other endpoint. - - - -Satran, et al. Standards Track [Page 9] - -RFC 3720 iSCSI April 2004 - - - The SCSI protocol has been mapped over various transports, including - Parallel SCSI, IPI, IEEE-1394 (firewire) and Fibre Channel. These - transports are I/O specific and have limited distance capabilities. - - The iSCSI protocol defined in this document describes a means of - transporting SCSI packets over TCP/IP (see [RFC791], [RFC793], - [RFC1035], [RFC1122]), providing for an interoperable solution which - can take advantage of existing Internet infrastructure, Internet - management facilities, and address distance limitations. - -2. Definitions and Acronyms - -2.1. Definitions - - - Alias: An alias string can also be associated with an iSCSI Node. - The alias allows an organization to associate a user-friendly - string with the iSCSI Name. However, the alias string is not a - substitute for the iSCSI Name. - - - CID (Connection ID): Connections within a session are identified by - a connection ID. It is a unique ID for this connection within the - session for the initiator. It is generated by the initiator and - presented to the target during login requests and during logouts - that close connections. - - - Connection: A connection is a TCP connection. Communication - between the initiator and target occurs over one or more TCP - connections. The TCP connections carry control messages, SCSI - commands, parameters, and data within iSCSI Protocol Data Units - (iSCSI PDUs). - - - iSCSI Device: A SCSI Device using an iSCSI service delivery - subsystem. Service Delivery Subsystem is defined by [SAM2] as a - transport mechanism for SCSI commands and responses. - - - iSCSI Initiator Name: The iSCSI Initiator Name specifies the - worldwide unique name of the initiator. - - - iSCSI Initiator Node: The "initiator". The word "initiator" has - been appropriately qualified as either a port or a device in the - rest of the document when the context is ambiguous. All - unqualified usages of "initiator" refer to an initiator port (or - device) depending on the context. - - - iSCSI Layer: This layer builds/receives iSCSI PDUs and - relays/receives them to/from one or more TCP connections that form - an initiator-target "session". - - - - -Satran, et al. Standards Track [Page 10] - -RFC 3720 iSCSI April 2004 - - - - iSCSI Name: The name of an iSCSI initiator or iSCSI target. - - - iSCSI Node: The iSCSI Node represents a single iSCSI initiator or - iSCSI target. There are one or more iSCSI Nodes within a Network - Entity. The iSCSI Node is accessible via one or more Network - Portals. An iSCSI Node is identified by its iSCSI Name. The - separation of the iSCSI Name from the addresses used by and for the - iSCSI Node allows multiple iSCSI Nodes to use the same address, and - the same iSCSI Node to use multiple addresses. - - - iSCSI Target Name: The iSCSI Target Name specifies the worldwide - unique name of the target. - - - iSCSI Target Node: The "target". - - - iSCSI Task: An iSCSI task is an iSCSI request for which a response - is expected. - - - iSCSI Transfer Direction: The iSCSI transfer direction is defined - with regard to the initiator. Outbound or outgoing transfers are - transfers from the initiator to the target, while inbound or - incoming transfers are from the target to the initiator. - - - ISID: The initiator part of the Session Identifier. It is - explicitly specified by the initiator during Login. - - - I_T nexus: According to [SAM2], the I_T nexus is a relationship - between a SCSI Initiator Port and a SCSI Target Port. For iSCSI, - this relationship is a session, defined as a relationship between - an iSCSI Initiator's end of the session (SCSI Initiator Port) and - the iSCSI Target's Portal Group. The I_T nexus can be identified - by the conjunction of the SCSI port names; that is, the I_T nexus - identifier is the tuple (iSCSI Initiator Name + ',i,'+ ISID, iSCSI - Target Name + ',t,'+ Portal Group Tag). - - - Network Entity: The Network Entity represents a device or gateway - that is accessible from the IP network. A Network Entity must have - one or more Network Portals, each of which can be used to gain - access to the IP network by some iSCSI Nodes contained in that - Network Entity. - - - Network Portal: The Network Portal is a component of a Network - Entity that has a TCP/IP network address and that may be used by an - iSCSI Node within that Network Entity for the connection(s) within - one of its iSCSI sessions. A Network Portal in an initiator is - identified by its IP address. A Network Portal in a target is - identified by its IP address and its listening TCP port. - - - - -Satran, et al. Standards Track [Page 11] - -RFC 3720 iSCSI April 2004 - - - - Originator: In a negotiation or exchange, the party that initiates - the negotiation or exchange. - - - PDU (Protocol Data Unit): The initiator and target divide their - communications into messages. The term "iSCSI protocol data unit" - (iSCSI PDU) is used for these messages. - - - Portal Groups: iSCSI supports multiple connections within the same - session; some implementations will have the ability to combine - connections in a session across multiple Network Portals. A Portal - Group defines a set of Network Portals within an iSCSI Network - Entity that collectively supports the capability of coordinating a - session with connections spanning these portals. Not all Network - Portals within a Portal Group need participate in every session - connected through that Portal Group. One or more Portal Groups may - provide access to an iSCSI Node. Each Network Portal, as utilized - by a given iSCSI Node, belongs to exactly one portal group within - that node. - - - Portal Group Tag: This 16-bit quantity identifies a Portal Group - within an iSCSI Node. All Network Portals with the same portal - group tag in the context of a given iSCSI Node are in the same - Portal Group. - - - Recovery R2T: An R2T generated by a target upon detecting the loss - of one or more Data-Out PDUs through one of the following means: a - digest error, a sequence error, or a sequence reception timeout. A - recovery R2T carries the next unused R2TSN, but requests all or - part of the data burst that an earlier R2T (with a lower R2TSN) had - already requested. - - - Responder: In a negotiation or exchange, the party that responds to - the originator of the negotiation or exchange. - - - SCSI Device: This is the SAM2 term for an entity that contains one - or more SCSI ports that are connected to a service delivery - subsystem and supports a SCSI application protocol. For example, a - SCSI Initiator Device contains one or more SCSI Initiator Ports and - zero or more application clients. A Target Device contains one or - more SCSI Target Ports and one or more device servers and - associated logical units. For iSCSI, the SCSI Device is the - component within an iSCSI Node that provides the SCSI - functionality. As such, there can be at most, one SCSI Device - within a given iSCSI Node. Access to the SCSI Device can only be - achieved in an iSCSI normal operational session. The SCSI Device - Name is defined to be the iSCSI Name of the node. - - - - - -Satran, et al. Standards Track [Page 12] - -RFC 3720 iSCSI April 2004 - - - - SCSI Layer: This builds/receives SCSI CDBs (Command Descriptor - Blocks) and relays/receives them with the remaining command execute - [SAM2] parameters to/from the iSCSI Layer. - - - Session: The group of TCP connections that link an initiator with a - target form a session (loosely equivalent to a SCSI I-T nexus). - TCP connections can be added and removed from a session. Across - all connections within a session, an initiator sees one and the - same target. - - - SCSI Initiator Port: This maps to the endpoint of an iSCSI normal - operational session. An iSCSI normal operational session is - negotiated through the login process between an iSCSI initiator - node and an iSCSI target node. At successful completion of this - process, a SCSI Initiator Port is created within the SCSI Initiator - Device. The SCSI Initiator Port Name and SCSI Initiator Port - Identifier are both defined to be the iSCSI Initiator Name together - with (a) a label that identifies it as an initiator port - name/identifier and (b) the ISID portion of the session identifier. - - - SCSI Port: This is the SAM2 term for an entity in a SCSI Device - that provides the SCSI functionality to interface with a service - delivery subsystem. For iSCSI, the definition of the SCSI - Initiator Port and the SCSI Target Port are different. - - - SCSI Port Name: A name made up as UTF-8 [RFC2279] characters and - includes the iSCSI Name + 'i' or 't' + ISID or Portal Group Tag. - - - - SCSI Target Port: This maps to an iSCSI Target Portal Group. - - - SCSI Target Port Name and SCSI Target Port Identifier: These are - both defined to be the iSCSI Target Name together with (a) a label - that identifies it as a target port name/identifier and (b) the - portal group tag. - - - SSID (Session ID): A session between an iSCSI initiator and an - iSCSI target is defined by a session ID that is a tuple composed of - an initiator part (ISID) and a target part (Target Portal Group - Tag). The ISID is explicitly specified by the initiator at session - establishment. The Target Portal Group Tag is implied by the - initiator through the selection of the TCP endpoint at connection - establishment. The TargetPortalGroupTag key must also be returned - by the target as a confirmation during connection establishment - when TargetName is given. - - - Target Portal Group Tag: A numerical identifier (16-bit) for an - iSCSI Target Portal Group. - - - -Satran, et al. Standards Track [Page 13] - -RFC 3720 iSCSI April 2004 - - - - TSIH (Target Session Identifying Handle): A target assigned tag for - a session with a specific named initiator. The target generates it - during session establishment. Its internal format and content are - not defined by this protocol, except for the value 0 that is - reserved and used by the initiator to indicate a new session. It - is given to the target during additional connection establishment - for the same session. - -2.2. Acronyms - - Acronym Definition - ------------------------------------------------------------ - 3DES Triple Data Encryption Standard - ACA Auto Contingent Allegiance - AEN Asynchronous Event Notification - AES Advanced Encryption Standard - AH Additional Header (not the IPsec AH!) - AHS Additional Header Segment - API Application Programming Interface - ASC Additional Sense Code - ASCII American Standard Code for Information Interchange - ASCQ Additional Sense Code Qualifier - BHS Basic Header Segment - CBC Cipher Block Chaining - CD Compact Disk - CDB Command Descriptor Block - CHAP Challenge Handshake Authentication Protocol - CID Connection ID - CO Connection Only - CRC Cyclic Redundancy Check - CRL Certificate Revocation List - CSG Current Stage - CSM Connection State Machine - DES Data Encryption Standard - DNS Domain Name Server - DOI Domain of Interpretation - DVD Digital Versatile Disk - ESP Encapsulating Security Payload - EUI Extended Unique Identifier - FFP Full Feature Phase - FFPO Full Feature Phase Only - FIM Fixed Interval Marker - Gbps Gigabits per Second - HBA Host Bus Adapter - HMAC Hashed Message Authentication Code - I_T Initiator_Target - I_T_L Initiator_Target_LUN - IANA Internet Assigned Numbers Authority - - - -Satran, et al. Standards Track [Page 14] - -RFC 3720 iSCSI April 2004 - - - ID Identifier - IDN Internationalized Domain Name - IEEE Institute of Electrical & Electronics Engineers - IETF Internet Engineering Task Force - IKE Internet Key Exchange - I/O Input - Output - IO Initialize Only - IP Internet Protocol - IPsec Internet Protocol Security - IPv4 Internet Protocol Version 4 - IPv6 Internet Protocol Version 6 - IQN iSCSI Qualified Name - ISID Initiator Session ID - ITN iSCSI Target Name - ITT Initiator Task Tag - KRB5 Kerberos V5 - LFL Lower Functional Layer - LTDS Logical-Text-Data-Segment - LO Leading Only - LU Logical Unit - LUN Logical Unit Number - MAC Message Authentication Codes - NA Not Applicable - NIC Network Interface Card - NOP No Operation - NSG Next Stage - OS Operating System - PDU Protocol Data Unit - PKI Public Key Infrastructure - R2T Ready To Transfer - R2TSN Ready To Transfer Sequence Number - RDMA Remote Direct Memory Access - RFC Request For Comments - SAM SCSI Architecture Model - SAM2 SCSI Architecture Model - 2 - SAN Storage Area Network - SCSI Small Computer Systems Interface - SN Sequence Number - SNACK Selective Negative Acknowledgment - also - Sequence Number Acknowledgement for data - SPKM Simple Public-Key Mechanism - SRP Secure Remote Password - SSID Session ID - SW Session Wide - TCB Task Control Block - TCP Transmission Control Protocol - TPGT Target Portal Group Tag - TSIH Target Session Identifying Handle - - - -Satran, et al. Standards Track [Page 15] - -RFC 3720 iSCSI April 2004 - - - TTT Target Transfer Tag - UFL Upper Functional Layer - ULP Upper Level Protocol - URN Uniform Resource Names [RFC2396] - UTF Universal Transformation Format - WG Working Group - -2.3. Conventions - - In examples, "I->" and "T->" show iSCSI PDUs sent by the initiator - and target respectively. - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in BCP 14 [RFC2119]. - - iSCSI messages - PDUs - are represented by diagrams as in the - following example: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0| Basic Header Segment (BHS) | - +---------------+---------------+---------------+---------------+ - ---------- - +| | - +---------------+---------------+---------------+---------------+ - - The diagrams include byte and bit numbering. - - The following representation and ordering rules are observed in this - document: - - - Word Rule - - Half-word Rule - - Byte Rule - -2.3.1. Word Rule - - A word holds four consecutive bytes. Whenever a word has numeric - content, it is considered an unsigned number in base 2 positional - representation with the lowest numbered byte (e.g., byte 0) bit 0 - representing 2**31 and bit 1 representing 2**30 through lowest - numbered byte + 3 (e.g., byte 3) bit 7 representing 2**0. - - Decimal and hexadecimal representation of word values map this - representation to decimal or hexadecimal positional notation. - - - -Satran, et al. Standards Track [Page 16] - -RFC 3720 iSCSI April 2004 - - -2.3.2. Half-Word Rule - - A half-word holds two consecutive bytes. Whenever a half-word has - numeric content it is considered an unsigned number in base 2 - positional representation with the lowest numbered byte (e.g., byte - 0), bit 0 representing 2**15 and bit 1 representing 2**14 through - lowest numbered byte + 1 (e.g., byte 1), bit 7 representing 2**0. - - Decimal and hexadecimal representation of half-word values map this - representation to decimal or hexadecimal positional notation. - -2.3.3. Byte Rule - - For every PDU, bytes are sent and received in increasing numbered - order (network order). - - Whenever a byte has numerical content, it is considered an unsigned - number in base 2 positional representation with bit 0 representing - 2**7 and bit 1 representing 2**6 through bit 7 representing 2**0. - -3. Overview - -3.1. SCSI Concepts - - The SCSI Architecture Model-2 [SAM2] describes in detail the - architecture of the SCSI family of I/O protocols. This section - provides a brief background of the SCSI architecture and is intended - to familiarize readers with its terminology. - - At the highest level, SCSI is a family of interfaces for requesting - services from I/O devices, including hard drives, tape drives, CD and - DVD drives, printers, and scanners. In SCSI terminology, an - individual I/O device is called a "logical unit" (LU). - - SCSI is a client-server architecture. Clients of a SCSI interface - are called "initiators". Initiators issue SCSI "commands" to request - services from components, logical units, of a server known as a - "target". The "device server" on the logical unit accepts SCSI - commands and processes them. - - A "SCSI transport" maps the client-server SCSI protocol to a specific - interconnect. Initiators are one endpoint of a SCSI transport. The - "target" is the other endpoint. A target can contain multiple - Logical Units (LUs). Each Logical Unit has an address within a - target called a Logical Unit Number (LUN). - - A SCSI task is a SCSI command or possibly a linked set of SCSI - commands. Some LUs support multiple pending (queued) tasks, but the - - - -Satran, et al. Standards Track [Page 17] - -RFC 3720 iSCSI April 2004 - - - queue of tasks is managed by the logical unit. The target uses an - initiator provided "task tag" to distinguish between tasks. Only one - command in a task can be outstanding at any given time. - - Each SCSI command results in an optional data phase and a required - response phase. In the data phase, information can travel from the - initiator to target (e.g., WRITE), target to initiator (e.g., READ), - or in both directions. In the response phase, the target returns the - final status of the operation, including any errors. - - Command Descriptor Blocks (CDB) are the data structures used to - contain the command parameters that an initiator sends to a target. - The CDB content and structure is defined by [SAM2] and device-type - specific SCSI standards. - -3.2. iSCSI Concepts and Functional Overview - - The iSCSI protocol is a mapping of the SCSI remote procedure - invocation model (see [SAM2]) over the TCP protocol. SCSI commands - are carried by iSCSI requests and SCSI responses and status are - carried by iSCSI responses. iSCSI also uses the request response - mechanism for iSCSI protocol mechanisms. - - For the remainder of this document, the terms "initiator" and - "target" refer to "iSCSI initiator node" and "iSCSI target node", - respectively (see Section 3.4.1 iSCSI Architecture Model) unless - otherwise qualified. - - In keeping with similar protocols, the initiator and target divide - their communications into messages. This document uses the term - "iSCSI protocol data unit" (iSCSI PDU) for these messages. - - For performance reasons, iSCSI allows a "phase-collapse". A command - and its associated data may be shipped together from initiator to - target, and data and responses may be shipped together from targets. - - The iSCSI transfer direction is defined with respect to the - initiator. Outbound or outgoing transfers are transfers from an - initiator to a target, while inbound or incoming transfers are from a - target to an initiator. - - An iSCSI task is an iSCSI request for which a response is expected. - - In this document "iSCSI request", "iSCSI command", request, or - (unqualified) command have the same meaning. Also, unless otherwise - specified, status, response, or numbered response have the same - meaning. - - - - -Satran, et al. Standards Track [Page 18] - -RFC 3720 iSCSI April 2004 - - -3.2.1. Layers and Sessions - - The following conceptual layering model is used to specify initiator - and target actions and the way in which they relate to transmitted - and received Protocol Data Units: - - a) the SCSI layer builds/receives SCSI CDBs (Command Descriptor - Blocks) and passes/receives them with the remaining command - execute parameters ([SAM2]) to/from - - b) the iSCSI layer that builds/receives iSCSI PDUs and - relays/receives them to/from one or more TCP connections; the - group of connections form an initiator-target "session". - - Communication between the initiator and target occurs over one or - more TCP connections. The TCP connections carry control messages, - SCSI commands, parameters, and data within iSCSI Protocol Data Units - (iSCSI PDUs). The group of TCP connections that link an initiator - with a target form a session (loosely equivalent to a SCSI I_T nexus, - see Section 3.4.2 SCSI Architecture Model). A session is defined by - a session ID that is composed of an initiator part and a target part. - TCP connections can be added and removed from a session. Each - connection within a session is identified by a connection ID (CID). - - Across all connections within a session, an initiator sees one - "target image". All target identifying elements, such as LUN, are - the same. A target also sees one "initiator image" across all - connections within a session. Initiator identifying elements, such - as the Initiator Task Tag, are global across the session regardless - of the connection on which they are sent or received. - - iSCSI targets and initiators MUST support at least one TCP connection - and MAY support several connections in a session. For error recovery - purposes, targets and initiators that support a single active - connection in a session SHOULD support two connections during - recovery. - -3.2.2. Ordering and iSCSI Numbering - - iSCSI uses Command and Status numbering schemes and a Data sequencing - scheme. - - Command numbering is session-wide and is used for ordered command - delivery over multiple connections. It can also be used as a - mechanism for command flow control over a session. - - - - - - -Satran, et al. Standards Track [Page 19] - -RFC 3720 iSCSI April 2004 - - - Status numbering is per connection and is used to enable missing - status detection and recovery in the presence of transient or - permanent communication errors. - - Data sequencing is per command or part of a command (R2T triggered - sequence) and is used to detect missing data and/or R2T PDUs due to - header digest errors. - - Typically, fields in the iSCSI PDUs communicate the Sequence Numbers - between the initiator and target. During periods when traffic on a - connection is unidirectional, iSCSI NOP-Out/In PDUs may be utilized - to synchronize the command and status ordering counters of the target - and initiator. - - The iSCSI session abstraction is equivalent to the SCSI I_T nexus, - and the iSCSI session provides an ordered command delivery from the - SCSI initiator to the SCSI target. For detailed design - considerations that led to the iSCSI session model as it is defined - here and how it relates the SCSI command ordering features defined in - SCSI specifications to the iSCSI concepts see [CORD]. - -3.2.2.1. Command Numbering and Acknowledging - - iSCSI performs ordered command delivery within a session. All - commands (initiator-to-target PDUs) in transit from the initiator to - the target are numbered. - - iSCSI considers a task to be instantiated on the target in response - to every request issued by the initiator. A set of task management - operations including abort and reassign (see Section 10.5 Task - Management Function Request) may be performed on any iSCSI task. - - Some iSCSI tasks are SCSI tasks, and many SCSI activities are related - to a SCSI task ([SAM2]). In all cases, the task is identified by the - Initiator Task Tag for the life of the task. - - The command number is carried by the iSCSI PDU as CmdSN - (Command Sequence Number). The numbering is session-wide. Outgoing - iSCSI PDUs carry this number. The iSCSI initiator allocates CmdSNs - with a 32-bit unsigned counter (modulo 2**32). Comparisons and - arithmetic on CmdSN use Serial Number Arithmetic as defined in - [RFC1982] where SERIAL_BITS = 32. - - Commands meant for immediate delivery are marked with an immediate - delivery flag; they MUST also carry the current CmdSN. CmdSN does - not advance after a command marked for immediate delivery is sent. - - - - - -Satran, et al. Standards Track [Page 20] - -RFC 3720 iSCSI April 2004 - - - Command numbering starts with the first login request on the first - connection of a session (the leading login on the leading connection) - and command numbers are incremented by 1 for every non-immediate - command issued afterwards. - - If immediate delivery is used with task management commands, these - commands may reach the target before the tasks on which they are - supposed to act. However their CmdSN serves as a marker of their - position in the stream of commands. The initiator and target must - ensure that the task management commands act as specified by [SAM2]. - For example, both commands and responses appear as if delivered in - order. Whenever CmdSN for an outgoing PDU is not specified by an - explicit rule, CmdSN will carry the current value of the local CmdSN - variable (see later in this section). - - The means by which an implementation decides to mark a PDU for - immediate delivery or by which iSCSI decides by itself to mark a PDU - for immediate delivery are beyond the scope of this document. - - The number of commands used for immediate delivery is not limited and - their delivery for execution is not acknowledged through the - numbering scheme. Immediate commands MAY be rejected by the iSCSI - target layer due to a lack of resources. An iSCSI target MUST be - able to handle at least one immediate task management command and one - immediate non-task-management iSCSI command per connection at any - time. - - In this document, delivery for execution means delivery to the SCSI - execution engine or an iSCSI protocol specific execution engine - (e.g., for text requests with public or private extension keys - involving an execution component). With the exception of the - commands marked for immediate delivery, the iSCSI target layer MUST - deliver the commands for execution in the order specified by CmdSN. - Commands marked for immediate delivery may be delivered by the iSCSI - target layer for execution as soon as detected. iSCSI may avoid - delivering some commands to the SCSI target layer if required by a - prior SCSI or iSCSI action (e.g., CLEAR TASK SET Task Management - request received before all the commands on which it was supposed to - act). - - On any connection, the iSCSI initiator MUST send the commands in - increasing order of CmdSN, except for commands that are retransmitted - due to digest error recovery and connection recovery. - - For the numbering mechanism, the initiator and target maintain the - following three variables for each session: - - - - - -Satran, et al. Standards Track [Page 21] - -RFC 3720 iSCSI April 2004 - - - - CmdSN - the current command Sequence Number, advanced by 1 on - each command shipped except for commands marked for immediate - delivery. CmdSN always contains the number to be assigned to - the next Command PDU. - - ExpCmdSN - the next expected command by the target. The target - acknowledges all commands up to, but not including, this - number. The initiator treats all commands with CmdSN less than - ExpCmdSN as acknowledged. The target iSCSI layer sets the - ExpCmdSN to the largest non-immediate CmdSN that it can deliver - for execution plus 1 (no holes in the CmdSN sequence). - - MaxCmdSN - the maximum number to be shipped. The queuing - capacity of the receiving iSCSI layer is MaxCmdSN - ExpCmdSN + - 1. - - The initiator's ExpCmdSN and MaxCmdSN are derived from - target-to-initiator PDU fields. Comparisons and arithmetic on - ExpCmdSN and MaxCmdSN MUST use Serial Number Arithmetic as defined in - [RFC1982] where SERIAL_BITS = 32. - - The target MUST NOT transmit a MaxCmdSN that is less than - ExpCmdSN-1. For non-immediate commands, the CmdSN field can take any - value from ExpCmdSN to MaxCmdSN inclusive. The target MUST silently - ignore any non-immediate command outside of this range or non- - immediate duplicates within the range. The CmdSN carried by - immediate commands may lie outside the ExpCmdSN to MaxCmdSN range. - For example, if the initiator has previously sent a non-immediate - command carrying the CmdSN equal to MaxCmdSN, the target window is - closed. For group task management commands issued as immediate - commands, CmdSN indicates the scope of the group action (e.g., on - ABORT TASK SET indicates which commands are aborted). - - MaxCmdSN and ExpCmdSN fields are processed by the initiator as - follows: - - - If the PDU MaxCmdSN is less than the PDU ExpCmdSN-1 (in Serial - Arithmetic Sense), they are both ignored. - - If the PDU MaxCmdSN is greater than the local MaxCmdSN (in - Serial Arithmetic Sense), it updates the local MaxCmdSN; - otherwise, it is ignored. - - If the PDU ExpCmdSN is greater than the local ExpCmdSN (in - Serial Arithmetic Sense), it updates the local ExpCmdSN; - otherwise, it is ignored. - - This sequence is required because updates may arrive out of order - (e.g., the updates are sent on different TCP connections). - - iSCSI initiators and targets MUST support the command numbering - scheme. - - - -Satran, et al. Standards Track [Page 22] - -RFC 3720 iSCSI April 2004 - - - A numbered iSCSI request will not change its allocated CmdSN, - regardless of the number of times and circumstances in which it is - reissued (see Section 6.2.1 Usage of Retry). At the target, CmdSN is - only relevant when the command has not created any state related to - its execution (execution state); afterwards, CmdSN becomes - irrelevant. Testing for the execution state (represented by - identifying the Initiator Task Tag) MUST precede any other action at - the target. If no execution state is found, it is followed by - ordering and delivery. If an execution state is found, it is - followed by delivery. - - If an initiator issues a command retry for a command with CmdSN R on - a connection when the session CmdSN value is Q, it MUST NOT advance - the CmdSN past R + 2**31 -1 unless the connection is no longer - operational (i.e., it has returned to the FREE state, see Section - 7.1.3 Standard Connection State Diagram for an Initiator), the - connection has been reinstated (see Section 5.3.4 Connection - Reinstatement), or a non-immediate command with CmdSN equal or - greater than Q was issued subsequent to the command retry on the same - connection and the reception of that command is acknowledged by the - target (see Section 9.4 Command Retry and Cleaning Old Command - Instances). - - A target MUST NOT issue a command response or Data-In PDU with status - before acknowledging the command. However, the acknowledgement can - be included in the response or Data-In PDU. - -3.2.2.2. Response/Status Numbering and Acknowledging - - Responses in transit from the target to the initiator are numbered. - The StatSN (Status Sequence Number) is used for this purpose. StatSN - is a counter maintained per connection. ExpStatSN is used by the - initiator to acknowledge status. The status sequence number space is - 32-bit unsigned-integers and the arithmetic operations are the - regular mod(2**32) arithmetic. - - Status numbering starts with the Login response to the first Login - request of the connection. The Login response includes an initial - value for status numbering (any initial value is valid). - - To enable command recovery, the target MAY maintain enough state - information for data and status recovery after a connection failure. - A target doing so can safely discard all of the state information - maintained for recovery of a command after the delivery of the status - for the command (numbered StatSN) is acknowledged through ExpStatSN. - - A large absolute difference between StatSN and ExpStatSN may indicate - a failed connection. Initiators MUST undertake recovery actions if - - - -Satran, et al. Standards Track [Page 23] - -RFC 3720 iSCSI April 2004 - - - the difference is greater than an implementation defined constant - that MUST NOT exceed 2**31-1. - - Initiators and Targets MUST support the response-numbering scheme. - -3.2.2.3. Data Sequencing - - Data and R2T PDUs transferred as part of some command execution MUST - be sequenced. The DataSN field is used for data sequencing. For - input (read) data PDUs, DataSN starts with 0 for the first data PDU - of an input command and advances by 1 for each subsequent data PDU. - For output data PDUs, DataSN starts with 0 for the first data PDU of - a sequence (the initial unsolicited sequence or any data PDU sequence - issued to satisfy an R2T) and advances by 1 for each subsequent data - PDU. R2Ts are also sequenced per command. For example, the first - R2T has an R2TSN of 0 and advances by 1 for each subsequent R2T. For - bidirectional commands, the target uses the DataSN/R2TSN to sequence - Data-In and R2T PDUs in one continuous sequence (undifferentiated). - Unlike command and status, data PDUs and R2Ts are not acknowledged by - a field in regular outgoing PDUs. Data-In PDUs can be acknowledged - on demand by a special form of the SNACK PDU. Data and R2T PDUs are - implicitly acknowledged by status for the command. The DataSN/R2TSN - field enables the initiator to detect missing data or R2T PDUs. - - For any read or bidirectional command, a target MUST issue less than - 2**32 combined R2T and Data-In PDUs. Any output data sequence MUST - contain less than 2**32 Data-Out PDUs. - -3.2.3. iSCSI Login - - The purpose of the iSCSI login is to enable a TCP connection for - iSCSI use, authentication of the parties, negotiation of the - session's parameters and marking of the connection as belonging to an - iSCSI session. - - A session is used to identify to a target all the connections with a - given initiator that belong to the same I_T nexus. (For more details - on how a session relates to an I_T nexus, see Section 3.4.2 SCSI - Architecture Model). - - The targets listen on a well-known TCP port or other TCP port for - incoming connections. The initiator begins the login process by - connecting to one of these TCP ports. - - As part of the login process, the initiator and target SHOULD - authenticate each other and MAY set a security association protocol - for the session. This can occur in many different ways and is - subject to negotiation. - - - -Satran, et al. Standards Track [Page 24] - -RFC 3720 iSCSI April 2004 - - - To protect the TCP connection, an IPsec security association MAY be - established before the Login request. For information on using IPsec - security for iSCSI see Chapter 8 and [RFC3723]. - - The iSCSI Login Phase is carried through Login requests and - responses. Once suitable authentication has occurred and operational - parameters have been set, the session transitions to the Full Feature - Phase and the initiator may start to send SCSI commands. The - security policy for whether, and by what means, a target chooses to - authorize an initiator is beyond the scope of this document. For a - more detailed description of the Login Phase, see Chapter 5. - - The login PDU includes the ISID part of the session ID (SSID). The - target portal group that services the login is implied by the - selection of the connection endpoint. For a new session, the TSIH is - zero. As part of the response, the target generates a TSIH. - - During session establishment, the target identifies the SCSI - initiator port (the "I" in the "I_T nexus") through the value pair - (InitiatorName, ISID). We describe InitiatorName later in this - section. Any persistent state (e.g., persistent reservations) on the - target that is associated with a SCSI initiator port is identified - based on this value pair. Any state associated with the SCSI target - port (the "T" in the "I_T nexus") is identified externally by the - TargetName and portal group tag (see Section 3.4.1 iSCSI Architecture - Model). ISID is subject to reuse restrictions because it is used to - identify a persistent state (see Section 3.4.3 Consequences of the - Model). - - Before the Full Feature Phase is established, only Login Request and - Login Response PDUs are allowed. Login requests and responses MUST - be used exclusively during Login. On any connection, the login phase - MUST immediately follow TCP connection establishment and a subsequent - Login Phase MUST NOT occur before tearing down a connection. - - A target receiving any PDU except a Login request before the Login - phase is started MUST immediately terminate the connection on which - the PDU was received. Once the Login phase has started, if the - target receives any PDU except a Login request, it MUST send a Login - reject (with Status "invalid during login") and then disconnect. If - the initiator receives any PDU except a Login response, it MUST - immediately terminate the connection. - -3.2.4. iSCSI Full Feature Phase - - Once the initiator is authorized to do so, the iSCSI session is in - the iSCSI Full Feature Phase. A session is in Full Feature Phase - after successfully finishing the Login Phase on the first (leading) - - - -Satran, et al. Standards Track [Page 25] - -RFC 3720 iSCSI April 2004 - - - connection of a session. A connection is in Full Feature Phase if - the session is in Full Feature Phase and the connection login has - completed successfully. An iSCSI connection is not in Full Feature - Phase - - a) when it does not have an established transport connection, - - OR - - b) when it has a valid transport connection, but a successful - login was not performed or the connection is currently logged - out. - - In a normal Full Feature Phase, the initiator may send SCSI commands - and data to the various LUs on the target by encapsulating them in - iSCSI PDUs that go over the established iSCSI session. - -3.2.4.1. Command Connection Allegiance - - For any iSCSI request issued over a TCP connection, the corresponding - response and/or other related PDU(s) MUST be sent over the same - connection. We call this "connection allegiance". If the original - connection fails before the command is completed, the connection - allegiance of the command may be explicitly reassigned to a different - transport connection as described in detail in Section 6.2 Retry and - Reassign in Recovery. - - Thus, if an initiator issues a READ command, the target MUST send the - requested data, if any, followed by the status to the initiator over - the same TCP connection that was used to deliver the SCSI command. - If an initiator issues a WRITE command, the initiator MUST send the - data, if any, for that command over the same TCP connection that was - used to deliver the SCSI command. The target MUST return Ready To - Transfer (R2T), if any, and the status over the same TCP connection - that was used to deliver the SCSI command. Retransmission requests - (SNACK PDUs) and the data and status that they generate MUST also use - the same connection. - - However, consecutive commands that are part of a SCSI linked - command-chain task (see [SAM2]) MAY use different connections. - Connection allegiance is strictly per-command and not per-task. - During the iSCSI Full Feature Phase, the initiator and target MAY - interleave unrelated SCSI commands, their SCSI Data, and responses - over the session. - - - - - - - -Satran, et al. Standards Track [Page 26] - -RFC 3720 iSCSI April 2004 - - -3.2.4.2. Data Transfer Overview - - Outgoing SCSI data (initiator to target user data or command - parameters) is sent as either solicited data or unsolicited data. - Solicited data are sent in response to R2T PDUs. Unsolicited data - can be sent as part of an iSCSI command PDU ("immediate data") or in - separate iSCSI data PDUs. - - Immediate data are assumed to originate at offset 0 in the initiator - SCSI write-buffer (outgoing data buffer). All other Data PDUs have - the buffer offset set explicitly in the PDU header. - - An initiator may send unsolicited data up to FirstBurstLength as - immediate (up to the negotiated maximum PDU length), in a separate - PDU sequence or both. All subsequent data MUST be solicited. The - maximum length of an individual data PDU or the immediate-part of the - first unsolicited burst MAY be negotiated at login. - - The maximum amount of unsolicited data that can be sent with a - command is negotiated at login through the FirstBurstLength key. A - target MAY separately enable immediate data (through the - ImmediateData key) without enabling the more general (separate data - PDUs) form of unsolicited data (through the InitialR2T key). - - Unsolicited data on write are meant to reduce the effect of latency - on throughput (no R2T is needed to start sending data). In addition, - immediate data is meant to reduce the protocol overhead (both - bandwidth and execution time). - - An iSCSI initiator MAY choose not to send unsolicited data, only - immediate data or FirstBurstLength bytes of unsolicited data with a - command. If any non-immediate unsolicited data is sent, the total - unsolicited data MUST be either FirstBurstLength, or all of the data - if the total amount is less than the FirstBurstLength. - - It is considered an error for an initiator to send unsolicited data - PDUs to a target that operates in R2T mode (only solicited data are - allowed). It is also an error for an initiator to send more - unsolicited data, whether immediate or as separate PDUs, than - FirstBurstLength. - - An initiator MUST honor an R2T data request for a valid outstanding - command (i.e., carrying a valid Initiator Task Tag) and deliver all - the requested data provided the command is supposed to deliver - outgoing data and the R2T specifies data within the command bounds. - The initiator action is unspecified for receiving an R2T request that - specifies data, all or part, outside of the bounds of the command. - - - - -Satran, et al. Standards Track [Page 27] - -RFC 3720 iSCSI April 2004 - - - A target SHOULD NOT silently discard data and then request - retransmission through R2T. Initiators SHOULD NOT keep track of the - data transferred to or from the target (scoreboarding). SCSI targets - perform residual count calculation to check how much data was - actually transferred to or from the device by a command. This may - differ from the amount the initiator sent and/or received for reasons - such as retransmissions and errors. Read or bidirectional commands - implicitly solicit the transmission of the entire amount of data - covered by the command. SCSI data packets are matched to their - corresponding SCSI commands by using tags specified in the protocol. - - In addition, iSCSI initiators and targets MUST enforce some ordering - rules. When unsolicited data is used, the order of the unsolicited - data on each connection MUST match the order in which the commands on - that connection are sent. Command and unsolicited data PDUs may be - interleaved on a single connection as long as the ordering - requirements of each are maintained (e.g., command N+1 MAY be sent - before the unsolicited Data-Out PDUs for command N, but the - unsolicited Data-Out PDUs for command N MUST precede the unsolicited - Data-Out PDUs of command N+1). A target that receives data out of - order MAY terminate the session. - -3.2.4.3. Tags and Integrity Checks - - Initiator tags for pending commands are unique initiator-wide for a - session. Target tags are not strictly specified by the protocol. It - is assumed that target tags are used by the target to tag (alone or - in combination with the LUN) the solicited data. Target tags are - generated by the target and "echoed" by the initiator. These - mechanisms are designed to accomplish efficient data delivery along - with a large degree of control over the data flow. - - As the Initiator Task Tag is used to identify a task during its - execution, the iSCSI initiator and target MUST verify that all other - fields used in task-related PDUs have values that are consistent with - the values used at the task instantiation based on the Initiator Task - Tag (e.g., the LUN used in an R2T PDU MUST be the same as the one - used in the SCSI command PDU used to instantiate the task). Using - inconsistent field values is considered a protocol error. - -3.2.4.4. Task Management - - SCSI task management assumes that individual tasks and task groups - can be aborted solely based on the task tags (for individual tasks) - or the timing of the task management command (for task groups), and - that the task management action is executed synchronously - i.e., no - message involving an aborted task will be seen by the SCSI initiator - after receiving the task management response. In iSCSI initiators - - - -Satran, et al. Standards Track [Page 28] - -RFC 3720 iSCSI April 2004 - - - and targets interact asynchronously over several connections. iSCSI - specifies the protocol mechanism and implementation requirements - needed to present a synchronous view while using an asynchronous - infrastructure. - -3.2.5. iSCSI Connection Termination - - An iSCSI connection may be terminated by use of a transport - connection shutdown or a transport reset. Transport reset is assumed - to be an exceptional event. - - Graceful TCP connection shutdowns are done by sending TCP FINs. A - graceful transport connection shutdown SHOULD only be initiated by - either party when the connection is not in iSCSI Full Feature Phase. - A target MAY terminate a Full Feature Phase connection on internal - exception events, but it SHOULD announce the fact through an - Asynchronous Message PDU. Connection termination with outstanding - commands may require recovery actions. - - If a connection is terminated while in Full Feature Phase, connection - cleanup (see section 7) is required prior to recovery. By doing - connection cleanup before starting recovery, the initiator and target - will avoid receiving stale PDUs after recovery. - -3.2.6. iSCSI Names - - Both targets and initiators require names for the purpose of - identification. In addition, names enable iSCSI storage resources to - be managed regardless of location (address). An iSCSI node name is - also the SCSI device name of an iSCSI device. The iSCSI name of a - SCSI device is the principal object used in authentication of targets - to initiators and initiators to targets. This name is also used to - identify and manage iSCSI storage resources. - - iSCSI names must be unique within the operational domain of the end - user. However, because the operational domain of an IP network is - potentially worldwide, the iSCSI name formats are architected to be - worldwide unique. To assist naming authorities in the construction - of worldwide unique names, iSCSI provides two name formats for - different types of naming authorities. - - iSCSI names are associated with iSCSI nodes, and not iSCSI network - adapter cards, to ensure that the replacement of network adapter - cards does not require reconfiguration of all SCSI and iSCSI resource - allocation information. - - - - - - -Satran, et al. Standards Track [Page 29] - -RFC 3720 iSCSI April 2004 - - - Some SCSI commands require that protocol-specific identifiers be - communicated within SCSI CDBs. See Section 3.4.2 SCSI Architecture - Model for the definition of the SCSI port name/identifier for iSCSI - ports. - - An initiator may discover the iSCSI Target Names to which it has - access, along with their addresses, using the SendTargets text - request, or other techniques discussed in [RFC3721]. - -3.2.6.1. iSCSI Name Properties - - Each iSCSI node, whether an initiator or target, MUST have an iSCSI - name. - - Initiators and targets MUST support the receipt of iSCSI names of up - to the maximum length of 223 bytes. - - The initiator MUST present both its iSCSI Initiator Name and the - iSCSI Target Name to which it wishes to connect in the first login - request of a new session or connection. The only exception is if a - discovery session (see Section 2.3 iSCSI Session Types) is to be - established. In this case, the iSCSI Initiator Name is still - required, but the iSCSI Target Name MAY be omitted. - - iSCSI names have the following properties: - - a) iSCSI names are globally unique. No two initiators or targets - can have the same name. - b) iSCSI names are permanent. An iSCSI initiator node or target - node has the same name for its lifetime. - c) iSCSI names do not imply a location or address. An iSCSI - initiator or target can move, or have multiple addresses. A - change of address does not imply a change of name. - d) iSCSI names do not rely on a central name broker; the naming - authority is distributed. - e) iSCSI names support integration with existing unique naming - schemes. - f) iSCSI names rely on existing naming authorities. iSCSI does - not create any new naming authority. - - The encoding of an iSCSI name has the following properties: - - a) iSCSI names have the same encoding method regardless of the - underlying protocols. - b) iSCSI names are relatively simple to compare. The algorithm - for comparing two iSCSI names for equivalence does not rely on - an external server. - - - - -Satran, et al. Standards Track [Page 30] - -RFC 3720 iSCSI April 2004 - - - c) iSCSI names are composed only of displayable characters. iSCSI - names allow the use of international character sets but are not - case sensitive. No whitespace characters are used in iSCSI - names. - d) iSCSI names may be transported using both binary and - ASCII-based protocols. - - An iSCSI name really names a logical software entity, and is not tied - to a port or other hardware that can be changed. For instance, an - initiator name should name the iSCSI initiator node, not a particular - NIC or HBA. When multiple NICs are used, they should generally all - present the same iSCSI initiator name to the targets, because they - are simply paths to the same SCSI layer. In most operating systems, - the named entity is the operating system image. - - Similarly, a target name should not be tied to hardware interfaces - that can be changed. A target name should identify the logical - target and must be the same for the target regardless of the physical - portion being addressed. This assists iSCSI initiators in - determining that the two targets it has discovered are really two - paths to the same target. - - The iSCSI name is designed to fulfill the functional requirements for - Uniform Resource Names (URN) [RFC1737]. For example, it is required - that the name have a global scope, be independent of address or - location, and be persistent and globally unique. Names must be - extensible and scalable with the use of naming authorities. The name - encoding should be both human and machine readable. See [RFC1737] - for further requirements. - -3.2.6.2. iSCSI Name Encoding - - An iSCSI name MUST be a UTF-8 encoding of a string of Unicode - characters with the following properties: - - - It is in Normalization Form C (see "Unicode Normalization - Forms" [UNICODE]). - - It only contains characters allowed by the output of the iSCSI - stringprep template (described in [RFC3722]). - - The following characters are used for formatting iSCSI names: - - - dash ('-'=U+002d) - - dot ('.'=U+002e) - - colon (':'=U+003a) - - - The UTF-8 encoding of the name is not larger than 223 bytes. - - - - - -Satran, et al. Standards Track [Page 31] - -RFC 3720 iSCSI April 2004 - - - The stringprep process is described in [RFC3454]; iSCSI's use of the - stringprep process is described in [RFC3722]. Stringprep is a method - designed by the Internationalized Domain Name (IDN) working group to - translate human-typed strings into a format that can be compared as - opaque strings. Strings MUST NOT include punctuation, spacing, - diacritical marks, or other characters that could get in the way of - readability. The stringprep process also converts strings into - equivalent strings of lower-case characters. - - The stringprep process does not need to be implemented if the names - are only generated using numeric and lower-case (any character set) - alphabetic characters. - - Once iSCSI names encoded in UTF-8 are "normalized" they may be safely - compared byte-for-byte. - -3.2.6.3. iSCSI Name Structure - - An iSCSI name consists of two parts--a type designator followed by a - unique name string. - - The iSCSI name does not define any new naming authorities. Instead, - it supports two existing ways of designating naming authorities: an - iSCSI-Qualified Name, using domain names to identify a naming - authority, and the EUI format, where the IEEE Registration Authority - assists in the formation of worldwide unique names (EUI-64 format). - - The type designator strings currently defined are: - - iqn. - iSCSI Qualified name - eui. - Remainder of the string is an IEEE EUI-64 - identifier, in ASCII-encoded hexadecimal. - - These two naming authority designators were considered sufficient at - the time of writing this document. The creation of additional naming - type designators for iSCSI may be considered by the IETF and detailed - in separate RFCs. - -3.2.6.3.1. Type "iqn." (iSCSI Qualified Name) - - This iSCSI name type can be used by any organization that owns a - domain name. This naming format is useful when an end user or - service provider wishes to assign iSCSI names for targets and/or - initiators. - - To generate names of this type, the person or organization generating - the name must own a registered domain name. This domain name does - not have to be active, and does not have to resolve to an address; it - - - -Satran, et al. Standards Track [Page 32] - -RFC 3720 iSCSI April 2004 - - - just needs to be reserved to prevent others from generating iSCSI - names using the same domain name. - - Since a domain name can expire, be acquired by another entity, or may - be used to generate iSCSI names by both owners, the domain name must - be additionally qualified by a date during which the naming authority - owned the domain name. For this reason, a date code is provided as - part of the "iqn." format. - - The iSCSI qualified name string consists of: - - - The string "iqn.", used to distinguish these names from "eui." - formatted names. - - A date code, in yyyy-mm format. This date MUST be a date - during which the naming authority owned the domain name used in - this format, and SHOULD be the first month in which the domain - name was owned by this naming authority at 00:01 GMT of the - first day of the month. This date code uses the Gregorian - calendar. All four digits in the year must be present. Both - digits of the month must be present, with January == "01" and - December == "12". The dash must be included. - - A dot "." - - The reversed domain name of the naming authority (person or - organization) creating this iSCSI name. - - An optional, colon (:) prefixed, string within the character - set and length boundaries that the owner of the domain name - deems appropriate. This may contain product types, serial - numbers, host identifiers, or software keys (e.g., it may - include colons to separate organization boundaries). With the - exception of the colon prefix, the owner of the domain name can - assign everything after the reversed domain name as desired. - It is the responsibility of the entity that is the naming - authority to ensure that the iSCSI names it assigns are - worldwide unique. For example, "Example Storage Arrays, Inc.", - might own the domain name "example.com". - - The following are examples of iSCSI qualified names that might be - generated by "EXAMPLE Storage Arrays, Inc." - - Naming String defined by - Type Date Auth "example.com" naming authority - +--++-----+ +---------+ +--------------------------------+ - | || | | | | | - - iqn.2001-04.com.example:storage:diskarrays-sn-a8675309 - iqn.2001-04.com.example - iqn.2001-04.com.example:storage.tape1.sys1.xyz - iqn.2001-04.com.example:storage.disk2.sys1.xyz - - - -Satran, et al. Standards Track [Page 33] - -RFC 3720 iSCSI April 2004 - - - -3.2.6.3.2. Type "eui." (IEEE EUI-64 format) - - The IEEE Registration Authority provides a service for assigning - globally unique identifiers [EUI]. The EUI-64 format is used to - build a global identifier in other network protocols. For example, - Fibre Channel defines a method of encoding it into a WorldWideName. - For more information on registering for EUI identifiers, see [OUI]. - - The format is "eui." followed by an EUI-64 identifier (16 - ASCII-encoded hexadecimal digits). - - Example iSCSI name: - - Type EUI-64 identifier (ASCII-encoded hexadecimal) - +--++--------------+ - | || | - eui.02004567A425678D - - The IEEE EUI-64 iSCSI name format might be used when a manufacturer - is already registered with the IEEE Registration Authority and uses - EUI-64 formatted worldwide unique names for its products. - - More examples of name construction are discussed in [RFC3721]. - -3.2.7. Persistent State - - iSCSI does not require any persistent state maintenance across - sessions. However, in some cases, SCSI requires persistent - identification of the SCSI initiator port name (See Section 3.4.2 - SCSI Architecture Model and Section 3.4.3 Consequences of the Model). - - iSCSI sessions do not persist through power cycles and boot - operations. - - All iSCSI session and connection parameters are re-initialized upon - session and connection creation. - - Commands persist beyond connection termination if the session - persists and command recovery within the session is supported. - However, when a connection is dropped, command execution, as - perceived by iSCSI (i.e., involving iSCSI protocol exchanges for the - affected task), is suspended until a new allegiance is established by - the 'task reassign' task management function. (See Section 10.5 Task - Management Function Request.) - - - - - - -Satran, et al. Standards Track [Page 34] - -RFC 3720 iSCSI April 2004 - - -3.2.8. Message Synchronization and Steering - - iSCSI presents a mapping of the SCSI protocol onto TCP. This - encapsulation is accomplished by sending iSCSI PDUs of varying - lengths. Unfortunately, TCP does not have a built-in mechanism for - signaling message boundaries at the TCP layer. iSCSI overcomes this - obstacle by placing the message length in the iSCSI message header. - This serves to delineate the end of the current message as well as - the beginning of the next message. - - In situations where IP packets are delivered in order from the - network, iSCSI message framing is not an issue and messages are - processed one after the other. In the presence of IP packet - reordering (i.e., frames being dropped), legacy TCP implementations - store the "out of order" TCP segments in temporary buffers until the - missing TCP segments arrive, upon which the data must be copied to - the application buffers. In iSCSI, it is desirable to steer the SCSI - data within these out of order TCP segments into the pre-allocated - SCSI buffers rather than store them in temporary buffers. This - decreases the need for dedicated reassembly buffers as well as the - latency and bandwidth related to extra copies. - - Relying solely on the "message length" information from the iSCSI - message header may make it impossible to find iSCSI message - boundaries in subsequent TCP segments due to the loss of a TCP - segment that contains the iSCSI message length. The missing TCP - segment(s) must be received before any of the following segments can - be steered to the correct SCSI buffers (due to the inability to - determine the iSCSI message boundaries). Since these segments cannot - be steered to the correct location, they must be saved in temporary - buffers that must then be copied to the SCSI buffers. - - Different schemes can be used to recover synchronization. To make - these schemes work, iSCSI implementations have to make sure that the - appropriate protocol layers are provided with enough information to - implement a synchronization and/or data steering mechanism. One of - these schemes is detailed in Appendix A. - Sync and Steering with - Fixed Interval Markers -. - - The Fixed Interval Markers (FIM) scheme works by inserting markers in - the payload stream at fixed intervals that contain the offset for the - start of the next iSCSI PDU. - - Under normal circumstances (no PDU loss or data reception out of - order), iSCSI data steering can be accomplished by using the - identifying tag and the data offset fields in the iSCSI header in - addition to the TCP sequence number from the TCP header. The - - - - -Satran, et al. Standards Track [Page 35] - -RFC 3720 iSCSI April 2004 - - - identifying tag helps associate the PDU with a SCSI buffer address - while the data offset and TCP sequence number are used to determine - the offset within the buffer. - - When the part of the TCP data stream containing an iSCSI PDU header - is delayed or lost, markers may be used to minimize the damage as - follows: - - - Markers indicate where the next iSCSI PDU starts and enable - continued processing when iSCSI headers have to be dropped due to - data errors discovered at the iSCSI level (e.g., iSCSI header CRC - errors). - - - Markers help minimize the amount of data that has to be kept by - the TCP/iSCSI layer while waiting for a late TCP packet arrival - or recovery, because later they might help find iSCSI PDU headers - and use the information contained in those to steer data to SCSI - buffers. - -3.2.8.1. Sync/Steering and iSCSI PDU Length - - When a large iSCSI message is sent, the TCP segment(s) that contain - the iSCSI header may be lost. The remaining TCP segment(s), up to - the next iSCSI message, must be buffered (in temporary buffers) - because the iSCSI header that indicates to which SCSI buffers the - data are to be steered was lost. To minimize the amount of - buffering, it is recommended that the iSCSI PDU length be restricted - to a small value (perhaps a few TCP segments in length). During - login, each end of the iSCSI session specifies the maximum iSCSI PDU - length it will accept. - -3.3. iSCSI Session Types - - iSCSI defines two types of sessions: - - a) Normal operational session - an unrestricted session. - b) Discovery-session - a session only opened for target - discovery. The target MUST ONLY accept text requests with the - SendTargets key and a logout request with the reason "close - the session". All other requests MUST be rejected. - - The session type is defined during login with the key=value parameter - in the login command. - - - - - - - - -Satran, et al. Standards Track [Page 36] - -RFC 3720 iSCSI April 2004 - - -3.4. SCSI to iSCSI Concepts Mapping Model - - The following diagram shows an example of how multiple iSCSI Nodes - (targets in this case) can coexist within the same Network Entity and - can share Network Portals (IP addresses and TCP ports). Other more - complex configurations are also possible. For detailed descriptions - of the components of these diagrams, see Section 3.4.1 iSCSI - Architecture Model. - - +-----------------------------------+ - | Network Entity (iSCSI Client) | - | | - | +-------------+ | - | | iSCSI Node | | - | | (Initiator) | | - | +-------------+ | - | | | | - | +--------------+ +--------------+ | - | |Network Portal| |Network Portal| | - | | 10.1.30.4 | | 10.1.40.6 | | - +-+--------------+-+--------------+-+ - | | - | IP Networks | - | | - +-+--------------+-+--------------+-+ - | |Network Portal| |Network Portal| | - | | 10.1.30.21 | | 10.1.40.3 | | - | | TCP Port 3260| | TCP Port 3260| | - | +--------------+ +--------------+ | - | | | | - | ----------------- | - | | | | - | +-------------+ +--------------+ | - | | iSCSI Node | | iSCSI Node | | - | | (Target) | | (Target) | | - | +-------------+ +--------------+ | - | | - | Network Entity (iSCSI Server) | - +-----------------------------------+ - -3.4.1. iSCSI Architecture Model - - This section describes the part of the iSCSI architecture model that - has the most bearing on the relationship between iSCSI and the SCSI - Architecture Model. - - - - - - -Satran, et al. Standards Track [Page 37] - -RFC 3720 iSCSI April 2004 - - - a) Network Entity - represents a device or gateway that is - accessible from the IP network. A Network Entity must have - one or more Network Portals (see item d), each of which can be - used by some iSCSI Nodes (see item (b)) contained in that - Network Entity to gain access to the IP network. - - b) iSCSI Node - represents a single iSCSI initiator or iSCSI - target. There are one or more iSCSI Nodes within a Network - Entity. The iSCSI Node is accessible via one or more Network - Portals (see item d). An iSCSI Node is identified by its - iSCSI Name (see Section 3.2.6 iSCSI Names and Chapter 12). - The separation of the iSCSI Name from the addresses used by - and for the iSCSI node allows multiple iSCSI nodes to use the - same addresses, and the same iSCSI node to use multiple - addresses. - - c) An alias string may also be associated with an iSCSI Node. - The alias allows an organization to associate a user friendly - string with the iSCSI Name. However, the alias string is not - a substitute for the iSCSI Name. - - d) Network Portal - a component of a Network Entity that has a - TCP/IP network address and that may be used by an iSCSI Node - within that Network Entity for the connection(s) within one of - its iSCSI sessions. In an initiator, it is identified by its - IP address. In a target, it is identified by its IP address - and its listening TCP port. - - e) Portal Groups - iSCSI supports multiple connections within the - same session; some implementations will have the ability to - combine connections in a session across multiple Network - Portals. A Portal Group defines a set of Network Portals - within an iSCSI Node that collectively supports the capability - of coordinating a session with connections that span these - portals. Not all Network Portals within a Portal Group need - to participate in every session connected through that Portal - Group. One or more Portal Groups may provide access to an - iSCSI Node. Each Network Portal, as utilized by a given iSCSI - Node, belongs to exactly one portal group within that node. - Portal Groups are identified within an iSCSI Node by a portal - group tag, a simple unsigned-integer between 0 and 65535 (see - Section 12.3 SendTargets). All Network Portals with the same - portal group tag in the context of a given iSCSI Node are in - the same Portal Group. - - - - - - - -Satran, et al. Standards Track [Page 38] - -RFC 3720 iSCSI April 2004 - - - Both iSCSI Initiators and iSCSI Targets have portal groups, - though only the iSCSI Target Portal Groups are used directly - in the iSCSI protocol (e.g., in SendTargets). For references - to the initiator Portal Groups, see Section 9.1.1 Conservative - Reuse of ISIDs. - - f) Portals within a Portal Group should support similar session - parameters, because they may participate in a common session. - - The following diagram shows an example of one such configuration on a - target and how a session that shares Network Portals within a Portal - Group may be established. - - ----------------------------IP Network--------------------- - | | | - +----|---------------|-----+ +----|---------+ - | +---------+ +---------+ | | +---------+ | - | | Network | | Network | | | | Network | | - | | Portal | | Portal | | | | Portal | | - | +--|------+ +---------+ | | +---------+ | - | | | | | | | - | | Portal | | | | Portal | - | | Group 1 | | | | Group 2 | - +--------------------------+ +--------------+ - | | | - +--------|---------------|--------------------|--------------------+ - | | | | | - | +----------------------------+ +-----------------------------+ | - | | iSCSI Session (Target side)| | iSCSI Session (Target side) | | - | | | | | | - | | (TSIH = 56) | | (TSIH = 48) | | - | +----------------------------+ +-----------------------------+ | - | | - | iSCSI Target Node | - | (within Network Entity, not shown) | - +------------------------------------------------------------------+ - -3.4.2. SCSI Architecture Model - - This section describes the relationship between the SCSI Architecture - Model [SAM2] and the constructs of the SCSI device, SCSI port and I_T - nexus, and the iSCSI constructs described in Section 3.4.1 iSCSI - Architecture Model. - - This relationship implies implementation requirements in order to - conform to the SAM2 model and other SCSI operational functions. - These requirements are detailed in Section 3.4.3 Consequences of the - Model. - - - -Satran, et al. Standards Track [Page 39] - -RFC 3720 iSCSI April 2004 - - - The following list outlines mappings of SCSI architectural elements - to iSCSI. - - a) SCSI Device - the SAM2 term for an entity that contains one or - more SCSI ports that are connected to a service delivery - subsystem and supports a SCSI application protocol. For - example, a SCSI Initiator Device contains one or more SCSI - Initiator Ports and zero or more application clients. A SCSI - Target Device contains one or more SCSI Target Ports and one - or more logical units. For iSCSI, the SCSI Device is the - component within an iSCSI Node that provides the SCSI - functionality. As such, there can be one SCSI Device, at - most, within an iSCSI Node. Access to the SCSI Device can - only be achieved in an iSCSI normal operational session (see - Section 3.3 iSCSI Session Types). The SCSI Device Name is - defined to be the iSCSI Name of the node and MUST be used in - the iSCSI protocol. - - b) SCSI Port - the SAM2 term for an entity in a SCSI Device that - provides the SCSI functionality to interface with a service - delivery subsystem or transport. For iSCSI, the definition of - SCSI Initiator Port and SCSI Target Port are different. - - SCSI Initiator Port: This maps to one endpoint of an iSCSI - normal operational session (see Section 3.3 iSCSI Session - Types). An iSCSI normal operational session is negotiated - through the login process between an iSCSI initiator node and - an iSCSI target node. At successful completion of this - process, a SCSI Initiator Port is created within the SCSI - Initiator Device. The SCSI Initiator Port Name and SCSI - Initiator Port Identifier are both defined to be the iSCSI - Initiator Name together with (a) a label that identifies it as - an initiator port name/identifier and (b) the ISID portion of - the session identifier. - - SCSI Target Port: This maps to an iSCSI Target Portal Group. - The SCSI Target Port Name and the SCSI Target Port Identifier - are both defined to be the iSCSI Target Name together with (a) - a label that identifies it as a target port name/identifier - and (b) the portal group tag. - - The SCSI Port Name MUST be used in iSCSI. When used in SCSI - parameter data, the SCSI port name MUST be encoded as: - - The iSCSI Name in UTF-8 format, followed by - - a comma separator (1 byte), followed by - - the ASCII character 'i' (for SCSI Initiator Port) or the - ASCII character 't' (for SCSI Target Port) (1 byte), - followed by - - - -Satran, et al. Standards Track [Page 40] - -RFC 3720 iSCSI April 2004 - - - - a comma separator (1 byte), followed by - - a text encoding as a hex-constant (see Section 5.1 Text - Format) of the ISID (for SCSI initiator port) or the portal - group tag (for SCSI target port) including the initial 0X - or 0x and the terminating null (15 bytes). - - The ASCII character 'i' or 't' is the label that identifies - this port as either a SCSI Initiator Port or a SCSI Target - Port. - - c) I_T nexus - a relationship between a SCSI Initiator Port and a - SCSI Target Port, according to [SAM2]. For iSCSI, this - relationship is a session, defined as a relationship between - an iSCSI Initiator's end of the session (SCSI Initiator Port) - and the iSCSI Target's Portal Group. The I_T nexus can be - identified by the conjunction of the SCSI port names or by the - iSCSI session identifier SSID. iSCSI defines the I_T nexus - identifier to be the tuple (iSCSI Initiator Name + 'i' + ISID, - iSCSI Target Name + 't' + Portal Group Tag). - - NOTE: The I_T nexus identifier is not equal to the session - identifier (SSID). - -3.4.3. Consequences of the Model - - This section describes implementation and behavioral requirements - that result from the mapping of SCSI constructs to the iSCSI - constructs defined above. Between a given SCSI initiator port and a - given SCSI target port, only one I_T nexus (session) can exist. No - more than one nexus relationship (parallel nexus) is allowed by - [SAM2]. Therefore, at any given time, only one session can exist - between a given iSCSI initiator node and an iSCSI target node, with - the same session identifier (SSID). - - These assumptions lead to the following conclusions and requirements: - - ISID RULE: Between a given iSCSI Initiator and iSCSI Target Portal - Group (SCSI target port), there can only be one session with a given - value for ISID that identifies the SCSI initiator port. See Section - 10.12.5 ISID. - - The structure of the ISID that contains a naming authority component - (see Section 10.12.5 ISID and [RFC3721]) provides a mechanism to - facilitate compliance with the ISID rule. (See Section 9.1.1 - Conservative Reuse of ISIDs.) - - - - - - -Satran, et al. Standards Track [Page 41] - -RFC 3720 iSCSI April 2004 - - - The iSCSI Initiator Node should manage the assignment of ISIDs prior - to session initiation. The "ISID RULE" does not preclude the use of - the same ISID from the same iSCSI Initiator with different Target - Portal Groups on the same iSCSI target or on other iSCSI targets (see - Section 9.1.1 Conservative Reuse of ISIDs). Allowing this would be - analogous to a single SCSI Initiator Port having relationships - (nexus) with multiple SCSI target ports on the same SCSI target - device or SCSI target ports on other SCSI target devices. It is also - possible to have multiple sessions with different ISIDs to the same - Target Portal Group. Each such session would be considered to be - with a different initiator even when the sessions originate from the - same initiator device. The same ISID may be used by a different - iSCSI initiator because it is the iSCSI Name together with the ISID - that identifies the SCSI Initiator Port. - - NOTE: A consequence of the ISID RULE and the specification for the - I_T nexus identifier is that two nexus with the same identifier - should never exist at the same time. - - TSIH RULE: The iSCSI Target selects a non-zero value for the TSIH at - session creation (when an initiator presents a 0 value at Login). - After being selected, the same TSIH value MUST be used whenever the - initiator or target refers to the session and a TSIH is required. - -3.4.3.1. I_T Nexus State - - Certain nexus relationships contain an explicit state (e.g., - initiator-specific mode pages) that may need to be preserved by the - device server [SAM2] in a logical unit through changes or failures in - the iSCSI layer (e.g., session failures). In order for that state to - be restored, the iSCSI initiator should reestablish its session - (re-login) to the same Target Portal Group using the previous ISID. - That is, it should perform session recovery as described in Chapter - 6. This is because the SCSI initiator port identifier and the SCSI - target port identifier (or relative target port) form the datum that - the SCSI logical unit device server uses to identify the I_T nexus. - -3.5. Request/Response Summary - - This section lists and briefly describes all the iSCSI PDU types - (request and responses). - - All iSCSI PDUs are built as a set of one or more header segments - (basic and auxiliary) and zero or one data segments. The header - group and the data segment may each be followed by a CRC (digest). - - The basic header segment has a fixed length of 48 bytes. - - - - -Satran, et al. Standards Track [Page 42] - -RFC 3720 iSCSI April 2004 - - -3.5.1. Request/Response Types Carrying SCSI Payload - -3.5.1.1. SCSI-Command - - This request carries the SCSI CDB and all the other SCSI execute - command procedure call (see [SAM2]) IN arguments such as task - attributes, Expected Data Transfer Length for one or both transfer - directions (the latter for bidirectional commands), and Task Tag (as - part of the I_T_L_x nexus). The I_T_L nexus is derived by the - initiator and target from the LUN field in the request and the I_T - nexus is implicit in the session identification. - - In addition, the SCSI-command PDU carries information required for - the proper operation of the iSCSI protocol - the command sequence - number (CmdSN) for the session and the expected status number - (ExpStatSN) for the connection. - - All or part of the SCSI output (write) data associated with the SCSI - command may be sent as part of the SCSI-Command PDU as a data - segment. - -3.5.1.2. SCSI-Response - - The SCSI-Response carries all the SCSI execute-command procedure call - (see [SAM2]) OUT arguments and the SCSI execute-command procedure - call return value. - - The SCSI-Response contains the residual counts from the operation, if - any, an indication of whether the counts represent an overflow or an - underflow, and the SCSI status if the status is valid or a response - code (a non-zero return value for the execute-command procedure call) - if the status is not valid. - - For a valid status that indicates that the command has been - processed, but resulted in an exception (e.g., a SCSI CHECK - CONDITION), the PDU data segment contains the associated sense data. - The use of Autosense ([SAM2]) is REQUIRED by iSCSI. - - Some data segment content may also be associated (in the data - segment) with a non-zero response code. - - In addition, the SCSI-Response PDU carries information required for - the proper operation of the iSCSI protocol: - - - The number of Data-In PDUs that a target has sent (to enable - the initiator to check that all have arrived). - - StatSN - the Status Sequence Number on this connection. - - - - -Satran, et al. Standards Track [Page 43] - -RFC 3720 iSCSI April 2004 - - - - ExpCmdSN - the next Expected Command Sequence Number at the - target. - - MaxCmdSN - the maximum CmdSN acceptable at the target from - this initiator. - -3.5.1.3 Task Management Function Request - - The Task Management function request provides an initiator with a way - to explicitly control the execution of one or more SCSI Tasks or - iSCSI functions. The PDU carries a function identifier (which task - management function to perform) and enough information to - unequivocally identify the task or task-set on which to perform the - action, even if the task(s) to act upon has not yet arrived or has - been discarded due to an error. - - The referenced tag identifies an individual task if the function - refers to an individual task. - - The I_T_L nexus identifies task sets. In iSCSI the I_T_L nexus is - identified by the LUN and the session identification (the session - identifies an I_T nexus). - - For task sets, the CmdSN of the Task Management function request - helps identify the tasks upon which to act, namely all tasks - associated with a LUN and having a CmdSN preceding the Task - Management function request CmdSN. - - For a Task Management function, the coordination between responses to - the tasks affected and the Task Management function response is done - by the target. - -3.5.1.4. Task Management Function Response - - The Task Management function response carries an indication of - function completion for a Task Management function request including - how it was completed (response and qualifier) and additional - information for failure responses. - - After the Task Management response indicates Task Management function - completion, the initiator will not receive any additional responses - from the affected tasks. - -3.5.1.5. SCSI Data-Out and SCSI Data-In - - SCSI Data-Out and SCSI Data-In are the main vehicles by which SCSI - data payload is carried between initiator and target. Data payload - is associated with a specific SCSI command through the Initiator Task - Tag. For target convenience, outgoing solicited data also carries a - - - -Satran, et al. Standards Track [Page 44] - -RFC 3720 iSCSI April 2004 - - - Target Transfer Tag (copied from R2T) and the LUN. Each PDU contains - the payload length and the data offset relative to the buffer address - contained in the SCSI execute command procedure call. - - In each direction, the data transfer is split into "sequences". An - end-of-sequence is indicated by the F bit. - - An outgoing sequence is either unsolicited (only the first sequence - can be unsolicited) or consists of all the Data-Out PDUs sent in - response to an R2T. - - Input sequences are built to enable the direction switching for - bidirectional commands. - - For input, the target may request positive acknowledgement of input - data. This is limited to sessions that support error recovery and is - implemented through the A bit in the SCSI Data-In PDU header. - - Data-In and Data-Out PDUs also carry the DataSN to enable the - initiator and target to detect missing PDUs (discarded due to an - error). - - In addition, StatSN is carried by the Data-In PDUs. - - To enable a SCSI command to be processed while involving a minimum - number of messages, the last SCSI Data-In PDU passed for a command - may also contain the status if the status indicates termination with - no exceptions (no sense or response involved). - -3.5.1.6. Ready To Transfer (R2T) - - R2T is the mechanism by which the SCSI target "requests" the - initiator for output data. R2T specifies to the initiator the offset - of the requested data relative to the buffer address from the execute - command procedure call and the length of the solicited data. - - To help the SCSI target associate the resulting Data-Out with an R2T, - the R2T carries a Target Transfer Tag that will be copied by the - initiator in the solicited SCSI Data-Out PDUs. There are no protocol - specific requirements with regard to the value of these tags, but it - is assumed that together with the LUN, they will enable the target to - associate data with an R2T. - - - - - - - - - -Satran, et al. Standards Track [Page 45] - -RFC 3720 iSCSI April 2004 - - - R2T also carries information required for proper operation of the - iSCSI protocol, such as: - - - R2TSN (to enable an initiator to detect a missing R2T) - - StatSN - - ExpCmdSN - - MaxCmdSN - -3.5.2. Requests/Responses carrying SCSI and iSCSI Payload - -3.5.2.1. Asynchronous Message - - Asynchronous Messages are used to carry SCSI asynchronous events - (AEN) and iSCSI asynchronous messages. - - When carrying an AEN, the event details are reported as sense data in - the data segment. - -3.5.3. Requests/Responses Carrying iSCSI Only Payload - -3.5.3.1. Text Request and Text Response - - Text requests and responses are designed as a parameter negotiation - vehicle and as a vehicle for future extension. - - In the data segment, Text Requests/Responses carry text information - using a simple "key=value" syntax. - - Text Request/Responses may form extended sequences using the same - Initiator Task Tag. The initiator uses the F (Final) flag bit in the - text request header to indicate its readiness to terminate a - sequence. The target uses the F (Final) flag bit in the text - response header to indicate its consent to sequence termination. - - Text Request and Responses also use the Target Transfer Tag to - indicate continuation of an operation or a new beginning. A target - that wishes to continue an operation will set the Target Transfer Tag - in a Text Response to a value different from the default 0xffffffff. - An initiator willing to continue will copy this value into the Target - Transfer Tag of the next Text Request. If the initiator wants to - restart the current target negotiation (start fresh) will set the - Target Transfer Tag to 0xffffffff. - - Although a complete exchange is always started by the initiator, - specific parameter negotiations may be initiated by the initiator or - target. - - - - - -Satran, et al. Standards Track [Page 46] - -RFC 3720 iSCSI April 2004 - - -3.5.3.2. Login Request and Login Response - - Login Requests and Responses are used exclusively during the Login - Phase of each connection to set up the session and connection - parameters. (The Login Phase consists of a sequence of login - requests and responses carrying the same Initiator Task Tag.) - - A connection is identified by an arbitrarily selected connection-ID - (CID) that is unique within a session. - - Similar to the Text Requests and Responses, Login Requests/Responses - carry key=value text information with a simple syntax in the data - segment. - - The Login Phase proceeds through several stages (security - negotiation, operational parameter negotiation) that are selected - with two binary coded fields in the header -- the "current stage" - (CSG) and the "next stage" (NSG) with the appearance of the latter - being signaled by the "transit" flag (T). - - The first Login Phase of a session plays a special role, called the - leading login, which determines some header fields (e.g., the version - number, the maximum number of connections, and the session - identification). - - The CmdSN initial value is also set by the leading login. - - StatSN for each connection is initiated by the connection login. - - A login request may indicate an implied logout (cleanup) of the - connection to be logged in (a connection restart) by using the same - Connection ID (CID) as an existing connection, as well as the same - session identifying elements of the session to which the old - connection was associated. - -3.5.3.3. Logout Request and Response - - Logout Requests and Responses are used for the orderly closing of - connections for recovery or maintenance. The logout request may be - issued following a target prompt (through an asynchronous message) or - at an initiators initiative. When issued on the connection to be - logged out, no other request may follow it. - - The Logout Response indicates that the connection or session cleanup - is completed and no other responses will arrive on the connection (if - received on the logging out connection). In addition, the Logout - Response indicates how long the target will continue to hold - resources for recovery (e.g., command execution that continues on a - - - -Satran, et al. Standards Track [Page 47] - -RFC 3720 iSCSI April 2004 - - - new connection) in the text key Time2Retain and how long the - initiator must wait before proceeding with recovery in the text key - Time2Wait. - -3.5.3.4. SNACK Request - - With the SNACK Request, the initiator requests retransmission of - numbered-responses or data from the target. A single SNACK request - covers a contiguous set of missing items, called a run, of a given - type of items. The type is indicated in a type field in the PDU - header. The run is composed of an initial item (StatSN, DataSN, - R2TSN) and the number of missed Status, Data, or R2T PDUs. For long - Data-In sequences, the target may request (at predefined minimum - intervals) a positive acknowledgement for the data sent. A SNACK - request with a type field that indicates ACK and the number of - Data-In PDUs acknowledged conveys this positive acknowledgement. - -3.5.3.5. Reject - - Reject enables the target to report an iSCSI error condition (e.g., - protocol, unsupported option) that uses a Reason field in the PDU - header and includes the complete header of the bad PDU in the Reject - PDU data segment. - -3.5.3.6. NOP-Out Request and NOP-In Response - - This request/response pair may be used by an initiator and target as - a "ping" mechanism to verify that a connection/session is still - active and all of its components are operational. Such a ping may be - triggered by the initiator or target. The triggering party indicates - that it wants a reply by setting a value different from the default - 0xffffffff in the corresponding Initiator/Target Transfer Tag. - - NOP-In/NOP-Out may also be used "unidirectional" to convey to the - initiator/target command, status or data counter values when there is - no other "carrier" and there is a need to update the initiator/ - target. - -4. SCSI Mode Parameters for iSCSI - - There are no iSCSI specific mode pages. - -5. Login and Full Feature Phase Negotiation - - iSCSI parameters are negotiated at session or connection - establishment by using Login Requests and Responses (see Section - 3.2.3 iSCSI Login) and during the Full Feature Phase (Section 3.2.4 - iSCSI Full Feature Phase) by using Text Requests and Responses. In - - - -Satran, et al. Standards Track [Page 48] - -RFC 3720 iSCSI April 2004 - - - both cases the mechanism used is an exchange of iSCSI-text-key=value - pairs. For brevity iSCSI-text-keys are called just keys in the rest - of this document. - - Keys are either declarative or require negotiation and the key - description indicates if the key is declarative or requires - negotiation. - - For the declarative keys, the declaring party sets a value for the - key. The key specification indicates if the key can be declared by - the initiator, target or both. - - For the keys that require negotiation one of the parties (the - proposing party) proposes a value or set of values by including the - key=value in the data part of a Login or Text Request or Response - PDUs. The other party (the accepting party) makes a selection based - on the value or list of values proposed and includes the selected - value in a key=value in the data part of one of the following Login - or Text Response or Request PDUs. For most of the keys both the - initiator and target can be proposing parties. - - The login process proceeds in two stages - the security negotiation - stage and the operational parameter negotiation stage. Both stages - are optional but at least one of them has to be present to enable the - setting of some mandatory parameters. - - If present, the security negotiation stage precedes the operational - parameter negotiation stage. - - Progression from stage to stage is controlled by the T (Transition) - bit in the Login Request/Response PDU header. Through the T bit set - to 1, the initiator indicates that it would like to transition. The - target agrees to the transition (and selects the next stage) when - ready. A field in the Login PDU header indicates the current stage - (CSG) and during transition, another field indicates the next stage - (NSG) proposed (initiator) and selected (target). - - The text negotiation process is used to negotiate or declare - operational parameters. The negotiation process is controlled by the - F (final) bit in the PDU header. During text negotiations, the F bit - is used by the initiator to indicate that it is ready to finish the - negotiation and by the Target to acquiesce the end of negotiation. - - Since some key=value pairs may not fit entirely in a single PDU, the - C (continuation) bit is used (both in Login and Text) to indicate - that "more follows". - - - - - -Satran, et al. Standards Track [Page 49] - -RFC 3720 iSCSI April 2004 - - - The text negotiation uses an additional mechanism by which a target - may deliver larger amounts of data to an enquiring initiator. The - target sets a Target Task Tag to be used as a bookmark that when - returned by the initiator, means "go on". If reset to a "neutral - value", it means "forget about the rest". - - This chapter details types of keys and values used, the syntax rules - for parameter formation, and the negotiation schemes to be used with - different types of parameters. - -5.1. Text Format - - The initiator and target send a set of key=value pairs encoded in - UTF-8 Unicode. All the text keys and text values specified in this - document are to be presented and interpreted in the case in which - they appear in this document. They are case sensitive. - - The following character symbols are used in this document for text - items (the hexadecimal values represent Unicode code points): - - (a-z, A-Z) - letters - (0-9) - digits - " " (0x20) - space - "." (0x2e) - dot - "-" (0x2d) - minus - "+" (0x2b) - plus - "@" (0x40) - commercial at - "_" (0x5f) - underscore - "=" (0x3d) - equal - ":" (0x3a) - colon - "/" (0x2f) - solidus or slash - "[" (0x5b) - left bracket - "]" (0x5d) - right bracket - null (0x00) - null separator - "," (0x2c) - comma - "~" (0x7e) - tilde - - Key=value pairs may span PDU boundaries. An initiator or target that - sends partial key=value text within a PDU indicates that more text - follows by setting the C bit in the Text or Login Request or Text or - Login Response to 1. Data segments in a series of PDUs that have the - C bit set to 1 and end with a PDU that have the C bit set to 0, or - include a single PDU that has the C bit set to 0, have to be - considered as forming a single logical-text-data-segment (LTDS). - - Every key=value pair, including the last or only pair in a LTDS, MUST - be followed by one null (0x00) delimiter. - - - - -Satran, et al. Standards Track [Page 50] - -RFC 3720 iSCSI April 2004 - - - A key-name is whatever precedes the first "=" in the key=value pair. - The term key is used frequently in this document in place of - key-name. - - A value is whatever follows the first "=" in the key=value pair up to - the end of the key=value pair, but not including the null delimiter. - - The following definitions will be used in the rest of this document: - - standard-label: A string of one or more characters that consist of - letters, digits, dot, minus, plus, commercial at, or underscore. - A standard-label MUST begin with a capital letter and must not - exceed 63 characters. - - key-name: A standard-label. - - text-value: A string of zero or more characters that consist of - letters, digits, dot, minus, plus, commercial at, underscore, - slash, left bracket, right bracket, or colon. - - iSCSI-name-value: A string of one or more characters that consist - of minus, dot, colon, or any character allowed by the output of - the iSCSI string-prep template as specified in [RFC3722] (see - also Section 3.2.6.2 iSCSI Name Encoding). - - iSCSI-local-name-value: A UTF-8 string; no null characters are - allowed in the string. This encoding is to be used for localized - (internationalized) aliases. - - boolean-value: The string "Yes" or "No". - - hex-constant: A hexadecimal constant encoded as a string that - starts with "0x" or "0X" followed by one or more digits or the - letters a, b, c, d, e, f, A, B, C, D, E, or F. Hex-constants are - used to encode numerical values or binary strings. When used to - encode numerical values, the excessive use of leading 0 digits is - discouraged. The string following 0X (or 0x) represents a base16 - number that starts with the most significant base16 digit, - followed by all other digits in decreasing order of significance - and ending with the least-significant base16 digit. When used to - encode binary strings, hexadecimal constants have an implicit - byte-length that includes four bits for every hexadecimal digit - of the constant, including leading zeroes. For example, a - hex-constant of n hexadecimal digits has a byte-length of (the - integer part of) (n+1)/2. - - - - - - -Satran, et al. Standards Track [Page 51] - -RFC 3720 iSCSI April 2004 - - - decimal-constant: An unsigned decimal number with the digit 0 or a - string of one or more digits that start with a non-zero digit. - Decimal-constants are used to encode numerical values or binary - strings. Decimal constants can only be used to encode binary - strings if the string length is explicitly specified. There is - no implicit length for decimal strings. Decimal-constant MUST - NOT be used for parameter values if the values can be equal or - greater than 2**64 (numerical) or for binary strings that can be - longer than 64 bits. - - base64-constant: base64 constant encoded as a string that starts - with "0b" or "0B" followed by 1 or more digits or letters or plus - or slash or equal. The encoding is done according to [RFC2045] - and each character, except equal, represents a base64 digit or a - 6-bit binary string. Base64-constants are used to encode - numerical-values or binary strings. When used to encode - numerical values, the excessive use of leading 0 digits (encoded - as A) is discouraged. The string following 0B (or 0b) represents - a base64 number that starts with the most significant base64 - digit, followed by all other digits in decreasing order of - significance and ending with the least-significant base64 digit; - the least significant base64 digit may be optionally followed by - pad digits (encoded as equal) that are not considered as part of - the number. When used to encode binary strings, base64-constants - have an implicit - byte-length that includes six bits for every character of the - constant, excluding trailing equals (i.e., a base64-constant of n - base64 characters excluding the trailing equals has a byte-length - of ((the integer part of) (n*3/4)). Correctly encoded base64 - strings cannot have n values of 1, 5 ... k*4+1. - - numerical-value: An unsigned integer always less than 2**64 encoded - as a decimal-constant or a hex-constant. Unsigned integer - arithmetic applies to numerical-values. - - large-numerical-value: An unsigned integer that can be larger than - or equal to 2**64 encoded as a hex constant, or - base64-constant. Unsigned integer arithmetic applies to - large-numeric-values. - - numeric-range: Two numerical-values separated by a tilde where the - value to the right of tilde must not be lower than the value to - the left. - - regular-binary-value: A binary string not longer than 64 bits - encoded as a decimal constant, hex constant, or base64-constant. - The length of the string is either specified by the key - definition or is the implicit byte-length of the encoded string. - - - -Satran, et al. Standards Track [Page 52] - -RFC 3720 iSCSI April 2004 - - - large-binary-value: A binary string longer than 64 bits encoded as - a hex-constant or base64-constant. The length of the string is - either specified by the key definition or is the implicit - byte-length of the encoded string. - - binary-value: A regular-binary-value or a large-binary-value. - Operations on binary values are key specific. - - simple-value: Text-value, iSCSI-name-value, boolean-value, - numeric-value, a numeric-range, or a binary-value. - - list-of-values: A sequence of text-values separated by a comma. - - If not otherwise specified, the maximum length of a simple-value (not - its encoded representation) is 255 bytes, not including the delimiter - (comma or zero byte). - - Any iSCSI target or initiator MUST support receiving at least 8192 - bytes of key=value data in a negotiation sequence. When proposing or - accepting authentication methods that explicitly require support for - very long authentication items, the initiator and target MUST support - receiving of at least 64 kilobytes of key=value data (see Appendix - 11.1.2 - Simple Public-Key Mechanism (SPKM) - that require support - for public key certificates). - -5.2. Text Mode Negotiation - - During login, and thereafter, some session or connection parameters - are either declared or negotiated through an exchange of textual - information. - - The initiator starts the negotiation and/or declaration through a - Text or Login Request and indicates when it is ready for completion - (by setting the F bit to 1 and keeping it to 1 in a Text Request or - the T bit in the Login Request). As negotiation text may span PDU - boundaries, a Text or Login Request or Text or Login Response PDU - that has the C bit set to 1 MUST NOT have the F/T bit set to 1. - - A target receiving a Text or Login Request with the C bit set to 1 - MUST answer with a Text or Login Response with no data segment - (DataSegmentLength 0). An initiator receiving a Text or Login - Response with the C bit set to 1 MUST answer with a Text or Login - Request with no data segment (DataSegmentLength 0). - - A target or initiator SHOULD NOT use a Text or Login Response or Text - or Login Request with no data segment (DataSegmentLength 0) unless - explicitly required by a general or a key-specific negotiation rule. - - - - -Satran, et al. Standards Track [Page 53] - -RFC 3720 iSCSI April 2004 - - - The format of a declaration is: - - Declarer-> <key>=<valuex> - - The general format of text negotiation is: - - Proposer-> <key>=<valuex> - Acceptor-> <key>={<valuey>|NotUnderstood|Irrelevant|Reject} - - Thus a declaration is a one-way textual exchange while a negotiation - is a two-way exchange. - - The proposer or declarer can either be the initiator or the target, - and the acceptor can either be the target or initiator, respectively. - Targets are not limited to respond to key=value pairs as proposed by - the initiator. The target may propose key=value pairs of its own. - - All negotiations are explicit (i.e., the result MUST only be based on - newly exchanged or declared values). There are no implicit - proposals. If a proposal is not made, then a reply cannot be - expected. Conservative design also requires that default values - should not be relied upon when use of some other value has serious - consequences. - - The value proposed or declared can be a numerical-value, a - numerical-range defined by lower and upper values with both integers - separated by a tilde, a binary value, a text-value, an - iSCSI-name-value, an iSCSI-local-name-value, a boolean-value (Yes or - No), or a list of comma separated text-values. A range, a - large-numerical-value, an iSCSI-name-value and an - iSCSI-local-name-value MAY ONLY be used if it is explicitly allowed. - An accepted value can be a numerical-value, a large-numerical-value, - a text-value, or a boolean-value. - - If a specific key is not relevant for the current negotiation, the - acceptor may answer with the constant "Irrelevant" for all types of - negotiation. However the negotiation is not considered as failed if - the answer is "Irrelevant". The "Irrelevant" answer is meant for - those cases in which several keys are presented by a proposing party - but the selection made by the acceptor for one of the keys makes - other keys irrelevant. The following example illustrates the use of - "Irrelevant": - - I->T OFMarker=Yes,OFMarkInt=2048~8192 - T->I OFMarker=No,OFMarkInt=Irrelevant - - I->T X#vkey1=(bla,alb,None),X#vkey2=(bla,alb) - T->I X#vkey1=None,X#vkey2=Irrelevant - - - -Satran, et al. Standards Track [Page 54] - -RFC 3720 iSCSI April 2004 - - - - Any key not understood by the acceptor may be ignored by the acceptor - without affecting the basic function. However, the answer for a key - not understood MUST be key=NotUnderstood. - - The constants "None", "Reject", "Irrelevant", and "NotUnderstood" are - reserved and MUST ONLY be used as described here. Violation of this - rule is a protocol error (in particular the use of "Reject", - "Irrelevant", and "NotUnderstood" as proposed values). - - Reject or Irrelevant are legitimate negotiation options where allowed - but their excessive use is discouraged. A negotiation is considered - complete when the acceptor has sent the key value pair even if the - value is "Reject", "Irrelevant", or "NotUnderstood. Sending the key - again would be a re-negotiation and is forbidden for many keys. - - If the acceptor sends "Reject" as an answer the negotiated key is - left at its current value (or default if no value was set). If the - current value is not acceptable to the proposer on the connection or - to the session it is sent, the proposer MAY choose to terminate the - connection or session. - - All keys in this document, except for the X extension formats, MUST - be supported by iSCSI initiators and targets when used as specified - here. If used as specified, these keys MUST NOT be answered with - NotUnderstood. - - Implementers may introduce new keys by prefixing them with - "X-", followed by their (reversed) domain name, or with new keys - registered with IANA prefixing them with X#. For example, the entity - owning the domain example.com can issue: - - X-com.example.bar.foo.do_something=3 - - or a new registered key may be used as in: - - X#SuperCalyPhraGilistic=Yes - - Implementers MAY also introduce new values, but ONLY for new keys or - authentication methods (see Section 11 iSCSI Security Text Keys and - Authentication Methods), or digests (see Section 12.1 HeaderDigest - and DataDigest). - - Whenever parameter action or acceptance is dependent on other - parameters, the dependency rules and parameter sequence must be - specified with the parameters. - - - - - -Satran, et al. Standards Track [Page 55] - -RFC 3720 iSCSI April 2004 - - - In the Login Phase (see Section 5.3 Login Phase), every stage is a - separate negotiation. In the FullFeaturePhase, a Text Request - Response sequence is a negotiation. Negotiations MUST be handled as - atomic operations. For example, all negotiated values go into effect - after the negotiation concludes in agreement or are ignored if the - negotiation fails. - - Some parameters may be subject to integrity rules (e.g., parameter-x - must not exceed parameter-y or parameter-u not 1 implies parameter-v - be Yes). Whenever required, integrity rules are specified with the - keys. Checking for compliance with the integrity rule must only be - performed after all the parameters are available (the existent and - the newly negotiated). An iSCSI target MUST perform integrity - checking before the new parameters take effect. An initiator MAY - perform integrity checking. - - An iSCSI initiator or target MAY terminate a negotiation that does - not end within a reasonable time or number of exchanges. - -5.2.1. List negotiations - - In list negotiation, the originator sends a list of values (which may - include "None") in its order of preference. - - The responding party MUST respond with the same key and the first - value that it supports (and is allowed to use for the specific - originator) selected from the originator list. - - The constant "None" MUST always be used to indicate a missing - function. However, "None" is only a valid selection if it is - explicitly proposed. - - If an acceptor does not understand any particular value in a list, it - MUST ignore it. If an acceptor does not support, does not - understand, or is not allowed to use any of the proposed options with - a specific originator, it may use the constant "Reject" or terminate - the negotiation. The selection of a value not proposed MUST be - handled as a protocol error. - -5.2.2. Simple-value Negotiations - - For simple-value negotiations, the accepting party MUST answer with - the same key. The value it selects becomes the negotiation result. - - Proposing a value not admissible (e.g., not within the specified - bounds) MAY be answered with the constant "Reject" or the acceptor - MAY select an admissible value. - - - - -Satran, et al. Standards Track [Page 56] - -RFC 3720 iSCSI April 2004 - - - The selection by the acceptor, of a value not admissible under the - selection rules is considered a protocol error. The selection rules - are key-specific. - - For a numerical range, the value selected must be an integer within - the proposed range or "Reject" (if the range is unacceptable). - - In Boolean negotiations (i.e., those that result in keys taking the - values Yes or No), the accepting party MUST answer with the same key - and the result of the negotiation when the received value does not - determine that result by itself. The last value transmitted becomes - the negotiation result. The rules for selecting the value to answer - with are expressed as Boolean functions of the value received, and - the value that the accepting party would have selected if given a - choice. - - Specifically, the two cases in which answers are OPTIONAL are: - - - The Boolean function is "AND" and the value "No" is received. - The outcome of the negotiation is "No". - - The Boolean function is "OR" and the value "Yes" is received. - The outcome of the negotiation is "Yes". - - Responses are REQUIRED in all other cases, and the value chosen and - sent by the acceptor becomes the outcome of the negotiation. - -5.3. Login Phase - - The Login Phase establishes an iSCSI connection between an initiator - and a target; it also creates a new session or associates the - connection to an existing session. The Login Phase sets the iSCSI - protocol parameters, security parameters, and authenticates the - initiator and target to each other. - - The Login Phase is only implemented via Login Request and Responses. - The whole Login Phase is considered as a single task and has a single - Initiator Task Tag (similar to the linked SCSI commands). - - The default MaxRecvDataSegmentLength is used during Login. - - The Login Phase sequence of requests and responses proceeds as - follows: - - - Login initial request - - Login partial response (optional) - - More Login Requests and Responses (optional) - - Login Final-Response (mandatory) - - - - -Satran, et al. Standards Track [Page 57] - -RFC 3720 iSCSI April 2004 - - - The initial Login Request of any connection MUST include the - InitiatorName key=value pair. The initial Login Request of the first - connection of a session MAY also include the SessionType key=value - pair. For any connection within a session whose type is not - "Discovery", the first Login Request MUST also include the TargetName - key=value pair. - - The Login Final-response accepts or rejects the Login Request. - - The Login Phase MAY include a SecurityNegotiation stage and a - LoginOperationalNegotiation stage or both, but MUST include at least - one of them. The included stage MAY be empty except for the - mandatory names. - - The Login Requests and Responses contain a field (CSG) that indicates - the current negotiation stage (SecurityNegotiation or - LoginOperationalNegotiation). If both stages are used, the - SecurityNegotiation MUST precede the LoginOperationalNegotiation. - - Some operational parameters can be negotiated outside the login - through Text Requests and Responses. - - Security MUST be completely negotiated within the Login Phase. The - use of underlying IPsec security is specified in Chapter 8 and in - [RFC3723]. iSCSI support for security within the protocol only - consists of authentication in the Login Phase. - - In some environments, a target or an initiator is not interested in - authenticating its counterpart. It is possible to bypass - authentication through the Login Request and Response. - - The initiator and target MAY want to negotiate iSCSI authentication - parameters. Once this negotiation is completed, the channel is - considered secure. - - Most of the negotiation keys are only allowed in a specific stage. - The SecurityNegotiation keys appear in Chapter 11 and the - LoginOperationalNegotiation keys appear in Chapter 12. Only a - limited set of keys (marked as Any-Stage in Chapter 12) may be used - in any of the two stages. - - Any given Login Request or Response belongs to a specific stage; this - determines the negotiation keys allowed with the request or response. - It is considered to be a protocol error to send a key that is not - allowed in the current stage. - - - - - - -Satran, et al. Standards Track [Page 58] - -RFC 3720 iSCSI April 2004 - - - Stage transition is performed through a command exchange (request/ - response) that carries the T bit and the same CSG code. During this - exchange, the next stage is selected by the target through the "next - stage" code (NSG). The selected NSG MUST NOT exceed the value stated - by the initiator. The initiator can request a transition whenever it - is ready, but a target can only respond with a transition after one - is proposed by the initiator. - - In a negotiation sequence, the T bit settings in one pair of Login - Request-Responses have no bearing on the T bit settings of the next - pair. An initiator that has a T bit set to 1 in one pair and is - answered with a T bit setting of 0, may issue the next request with - the T bit set to 0. - - When a transition is requested by the initiator and acknowledged by - the target, both the initiator and target switch to the selected - stage. - - Targets MUST NOT submit parameters that require an additional - initiator Login Request in a Login Response with the T bit set to 1. - - Stage transitions during login (including entering and exit) are only - possible as outlined in the following table: - - +-----------------------------------------------------------+ - |From To -> | Security | Operational | FullFeature | - | | | | | | - | V | | | | - +-----------------------------------------------------------+ - | (start) | yes | yes | no | - +-----------------------------------------------------------+ - | Security | no | yes | yes | - +-----------------------------------------------------------+ - | Operational | no | no | yes | - +-----------------------------------------------------------+ - - The Login Final-Response that accepts a Login Request can only come - as a response to a Login Request with the T bit set to 1, and both - the request and response MUST indicate FullFeaturePhase as the next - phase via the NSG field. - - Neither the initiator nor the target should attempt to declare or - negotiate a parameter more than once during login except for - responses to specific keys that explicitly allow repeated key - declarations (e.g., TargetAddress). An attempt to - renegotiate/redeclare parameters not specifically allowed MUST be - detected by the initiator and target. If such an attempt is detected - - - - -Satran, et al. Standards Track [Page 59] - -RFC 3720 iSCSI April 2004 - - - by the target, the target MUST respond with Login reject (initiator - error); if detected by the initiator, the initiator MUST drop the - connection. - -5.3.1. Login Phase Start - - The Login Phase starts with a Login Request from the initiator to the - target. The initial Login Request includes: - - - Protocol version supported by the initiator. - - iSCSI Initiator Name and iSCSI Target Name - - ISID, TSIH, and connection Ids - - Negotiation stage that the initiator is ready to enter. - - A login may create a new session or it may add a connection to an - existing session. Between a given iSCSI Initiator Node (selected - only by an InitiatorName) and a given iSCSI target defined by an - iSCSI TargetName and a Target Portal Group Tag, the login results are - defined by the following table: - - - +------------------------------------------------------------------+ - |ISID | TSIH | CID | Target action | - +------------------------------------------------------------------+ - |new | non-zero | any | fail the login | - | | | | ("session does not exist") | - +------------------------------------------------------------------+ - |new | zero | any | instantiate a new session | - +------------------------------------------------------------------+ - |existing | zero | any | do session reinstatement | - | | | | (see section 5.3.5) | - +------------------------------------------------------------------+ - |existing | non-zero | new | add a new connection to | - | | existing | | the session | - +------------------------------------------------------------------+ - |existing | non-zero |existing| do connection reinstatement| - | | existing | | (see section 5.3.4) | - +------------------------------------------------------------------+ - |existing | non-zero | any | fail the login | - | | new | | ("session does not exist") | - +------------------------------------------------------------------+ - - Determination of "existing" or "new" are made by the target. - - - - - - - - -Satran, et al. Standards Track [Page 60] - -RFC 3720 iSCSI April 2004 - - - Optionally, the Login Request may include: - - - Security parameters - OR - - iSCSI operational parameters - AND/OR - - The next negotiation stage that the initiator is ready to - enter. - - The target can answer the login in the following ways: - - - Login Response with Login reject. This is an immediate rejection - from the target that causes the connection to terminate and the - session to terminate if this is the first (or only) connection of - a new session. The T bit and the CSG and NSG fields are - reserved. - - Login Response with Login Accept as a final response (T bit set - to 1 and the NSG in both request and response are set to - FullFeaturePhase). The response includes the protocol version - supported by the target and the session ID, and may include iSCSI - operational or security parameters (that depend on the current - stage). - - Login Response with Login Accept as a partial response (NSG not - set to FullFeaturePhase in both request and response) that - indicates the start of a negotiation sequence. The response - includes the protocol version supported by the target and either - security or iSCSI parameters (when no security mechanism is - chosen) supported by the target. - - If the initiator decides to forego the SecurityNegotiation stage, it - issues the Login with the CSG set to LoginOperationalNegotiation and - the target may reply with a Login Response that indicates that it is - unwilling to accept the connection (see Section 10.13 Login Response) - without SecurityNegotiation and will terminate the connection with a - response of Authentication failure (see Section 10.13.5 Status-Class - and Status-Detail). - - If the initiator is willing to negotiate iSCSI security, but is - unwilling to make the initial parameter proposal and may accept a - connection without iSCSI security, it issues the Login with the T bit - set to 1, the CSG set to SecurityNegotiation, and the NSG set to - LoginOperationalNegotiation. If the target is also ready to skip - security, the Login Response only contains the TargetPortalGroupTag - key (see Section 12.9 TargetPortalGroupTag), the T bit set to 1, the - CSG set to SecurityNegotiation, and the NSG set to - LoginOperationalNegotiation. - - - - - -Satran, et al. Standards Track [Page 61] - -RFC 3720 iSCSI April 2004 - - - An initiator that chooses to operate without iSCSI security, with all - the operational parameters taking the default values, issues the - Login with the T bit set to 1, the CSG set to - LoginOperationalNegotiation, and the NSG set to FullFeaturePhase. If - the target is also ready to forego security and can finish its - LoginOperationalNegotiation, the Login Response has T bit set to 1, - the CSG set to LoginOperationalNegotiation, and the NSG set to - FullFeaturePhase in the next stage. - - During the Login Phase the iSCSI target MUST return the - TargetPortalGroupTag key with the first Login Response PDU with which - it is allowed to do so (i.e., the first Login Response issued after - the first Login Request with the C bit set to 0) for all session - types when TargetName is given and the response is not a redirection. - The TargetPortalGroupTag key value indicates the iSCSI portal group - servicing the Login Request PDU. If the reconfiguration of iSCSI - portal groups is a concern in a given environment, the iSCSI - initiator should use this key to ascertain that it had indeed - initiated the Login Phase with the intended target portal group. - -5.3.2. iSCSI Security Negotiation - - The security exchange sets the security mechanism and authenticates - the initiator user and the target to each other. The exchange - proceeds according to the authentication method chosen in the - negotiation phase and is conducted using the Login Requests' and - responses' key=value parameters. - - An initiator directed negotiation proceeds as follows: - - - The initiator sends a Login Request with an ordered list of the - options it supports (authentication algorithm). The options are - listed in the initiator's order of preference. The initiator MAY - also send private or public extension options. - - - The target MUST reply with the first option in the list it - supports and is allowed to use for the specific initiator unless - it does not support any, in which case it MUST answer with - "Reject" (see Section 5.2 Text Mode Negotiation). The parameters - are encoded in UTF8 as key=value. For security parameters, see - Chapter 11. - - - When the initiator considers that it is ready to conclude the - SecurityNegotiation stage, it sets the T bit to 1 and the NSG to - what it would like the next stage to be. The target will then - set the T bit to 1 and set the NSG to the next stage in the Login - Response when it finishes sending its security keys. The next - - - - -Satran, et al. Standards Track [Page 62] - -RFC 3720 iSCSI April 2004 - - - stage selected will be the one the target selected. If the next - stage is FullFeaturePhase, the target MUST respond with a Login - Response with the TSIH value. - - If the security negotiation fails at the target, then the target MUST - send the appropriate Login Response PDU. If the security negotiation - fails at the initiator, the initiator SHOULD close the connection. - - It should be noted that the negotiation might also be directed by the - target if the initiator does support security, but is not ready to - direct the negotiation (propose options). - -5.3.3. Operational Parameter Negotiation During the Login Phase - - Operational parameter negotiation during the login MAY be done: - - - Starting with the first Login Request if the initiator does not - propose any security/integrity option. - - - Starting immediately after the security negotiation if the - initiator and target perform such a negotiation. - - Operational parameter negotiation MAY involve several Login - Request-Response exchanges started and terminated by the initiator. - The initiator MUST indicate its intent to terminate the negotiation - by setting the T bit to 1; the target sets the T bit to 1 on the last - response. - - If the target responds to a Login Request that has the T bit set to 1 - with a Login Response that has the T bit set to 0, the initiator - should keep sending the Login Request (even empty) with the T bit set - to 1, while it still wants to switch stage, until it receives the - Login Response that has the T bit set to 1 or it receives a key that - requires it to set the T bit to 0. - - Some session specific parameters can only be specified during the - Login Phase of the first connection of a session (i.e., begun by a - Login Request that contains a zero-valued TSIH) - the leading Login - Phase (e.g., the maximum number of connections that can be used for - this session). - - A session is operational once it has at least one connection in - FullFeaturePhase. New or replacement connections can only be added - to a session after the session is operational. - - For operational parameters, see Chapter 12. - - - - - -Satran, et al. Standards Track [Page 63] - -RFC 3720 iSCSI April 2004 - - -5.3.4. Connection Reinstatement - - Connection reinstatement is the process of an initiator logging in - with an ISID-TSIH-CID combination that is possibly active from the - target's perspective, which causes the implicit logging out of the - connection corresponding to the CID, and reinstating a new Full - Feature Phase iSCSI connection in its place (with the same CID). - Thus, the TSIH in the Login PDU MUST be non-zero and the CID does not - change during a connection reinstatement. The Login Request performs - the logout function of the old connection if an explicit logout was - not performed earlier. In sessions with a single connection, this - may imply the opening of a second connection with the sole purpose of - cleaning up the first. Targets MUST support opening a second - connection even when they do not support multiple connections in Full - Feature Phase if ErrorRecoveryLevel is 2 and SHOULD support opening a - second connection if ErrorRecoveryLevel is less than 2. - - If the operational ErrorRecoveryLevel is 2, connection reinstatement - enables future task reassignment. If the operational - ErrorRecoveryLevel is less than 2, connection reinstatement is the - replacement of the old CID without enabling task reassignment. In - this case, all the tasks that were active on the old CID must be - immediately terminated without further notice to the initiator. - - The initiator connection state MUST be CLEANUP_WAIT (section 7.1.3) - when the initiator attempts a connection reinstatement. - - In practical terms, in addition to the implicit logout of the old - connection, reinstatement is equivalent to a new connection login. - -5.3.5. Session Reinstatement, Closure, and Timeout - - Session reinstatement is the process of the initiator logging in with - an ISID that is possibly active from the target's perspective. Thus - implicitly logging out the session that corresponds to the ISID and - reinstating a new iSCSI session in its place (with the same ISID). - Therefore, the TSIH in the Login PDU MUST be zero to signal session - reinstatement. Session reinstatement causes all the tasks that were - active on the old session to be immediately terminated by the target - without further notice to the initiator. - - The initiator session state MUST be FAILED (Section 7.3 Session State - Diagrams) when the initiator attempts a session reinstatement. - - - - - - - - -Satran, et al. Standards Track [Page 64] - -RFC 3720 iSCSI April 2004 - - - Session closure is an event defined to be one of the following: - - - A successful "session close" logout. - - A successful "connection close" logout for the last Full Feature - Phase connection when no other connection in the session is - waiting for cleanup (Section 7.2 Connection Cleanup State Diagram - for Initiators and Targets) and no tasks in the session are - waiting for reassignment. - - Session timeout is an event defined to occur when the last connection - state timeout expires and no tasks are waiting for reassignment. - This takes the session to the FREE state (N6 transition in the - session state diagram). - -5.3.5.1. Loss of Nexus Notification - - The iSCSI layer provides the SCSI layer with the "I_T nexus loss" - notification when any one of the following events happens: - - a) Successful completion of session reinstatement. - b) Session closure event. - c) Session timeout event. - - Certain SCSI object clearing actions may result due to the - notification in the SCSI end nodes, as documented in Appendix F. - - Clearing Effects of Various Events on Targets -. - -5.3.6. Session Continuation and Failure - - Session continuation is the process by which the state of a - preexisting session continues to be used by connection reinstatement - (Section 5.3.4 Connection Reinstatement), or by adding a connection - with a new CID. Either of these actions associates the new transport - connection with the session state. - - Session failure is an event where the last Full Feature Phase - connection reaches the CLEANUP_WAIT state (Section 7.2 Connection - Cleanup State Diagram for Initiators and Targets), or completes a - successful recovery logout, thus causing all active tasks (that are - formerly allegiant to the connection) to start waiting for task - reassignment. - - - - - - - - - - -Satran, et al. Standards Track [Page 65] - -RFC 3720 iSCSI April 2004 - - -5.4. Operational Parameter Negotiation Outside the Login Phase - - Some operational parameters MAY be negotiated outside (after) the - Login Phase. - - Parameter negotiation in Full Feature Phase is done through Text - requests and responses. Operational parameter negotiation MAY - involve several Text request-response exchanges, which the initiator - always starts and terminates using the same Initiator Task Tag. The - initiator MUST indicate its intent to terminate the negotiation by - setting the F bit to 1; the target sets the F bit to 1 on the last - response. - - If the target responds to a Text request with the F bit set to 1 and - with a Text response with the F bit set to 0, the initiator should - keep sending the Text request (even empty) with the F bit set to 1, - while it still wants to finish the negotiation, until it receives the - Text response with the F bit set to 1. Responding to a Text request - with the F bit set to 1 with an empty (no key=value pairs) response - with the F bit set to 0 is discouraged. - - Targets MUST NOT submit parameters that require an additional - initiator Text request in a Text response with the F bit set to 1. - - In a negotiation sequence, the F bit settings in one pair of Text - request-responses have no bearing on the F bit settings of the next - pair. An initiator that has the F bit set to 1 in a request and is - being answered with an F bit setting of 0 may issue the next request - with the F bit set to 0. - - Whenever the target responds with the F bit set to 0, it MUST set the - Target Transfer Tag to a value other than the default 0xffffffff. - - An initiator MAY reset an operational parameter negotiation by - issuing a Text request with the Target Transfer Tag set to the value - 0xffffffff after receiving a response with the Target Transfer Tag - set to a value other than 0xffffffff. A target may reset an - operational parameter negotiation by answering a Text request with a - Reject PDU. - - Neither the initiator nor the target should attempt to declare or - negotiate a parameter more than once during any negotiation sequence - without an intervening operational parameter negotiation reset, - except for responses to specific keys that explicitly allow repeated - key declarations (e.g., TargetAddress). If detected by the target, - this MUST result in a Reject PDU with a reason of "protocol error". - The initiator MUST reset the negotiation as outlined above. - - - - -Satran, et al. Standards Track [Page 66] - -RFC 3720 iSCSI April 2004 - - - Parameters negotiated by a text exchange negotiation sequence only - become effective after the negotiation sequence is completed. - -6. iSCSI Error Handling and Recovery - -6.1. Overview - -6.1.1. Background - - The following two considerations prompted the design of much of the - error recovery functionality in iSCSI: - - i) An iSCSI PDU may fail the digest check and be dropped, despite - being received by the TCP layer. The iSCSI layer must - optionally be allowed to recover such dropped PDUs. - ii) A TCP connection may fail at any time during the data - transfer. All the active tasks must optionally be allowed to - continue on a different TCP connection within the same - session. - - Implementations have considerable flexibility in deciding what degree - of error recovery to support, when to use it and by which mechanisms - to achieve the required behavior. Only the externally visible - actions of the error recovery mechanisms must be standardized to - ensure interoperability. - - This chapter describes a general model for recovery in support of - interoperability. See Appendix E. - Algorithmic Presentation of - Error Recovery Classes - for further detail on how the described - model may be implemented. Compliant implementations do not have to - match the implementation details of this model as presented, but the - external behavior of such implementations must correspond to the - externally observable characteristics of the presented model. - -6.1.2. Goals - - The major design goals of the iSCSI error recovery scheme are as - follows: - - a) Allow iSCSI implementations to meet different requirements by - defining a collection of error recovery mechanisms that - implementations may choose from. - b) Ensure interoperability between any two implementations - supporting different sets of error recovery capabilities. - c) Define the error recovery mechanisms to ensure command - ordering even in the face of errors, for initiators that - demand ordering. - - - - -Satran, et al. Standards Track [Page 67] - -RFC 3720 iSCSI April 2004 - - - d) Do not make additions in the fast path, but allow moderate - complexity in the error recovery path. - e) Prevent both the initiator and target from attempting to - recover the same set of PDUs at the same time. For example, - there must be a clear "error recovery functionality - distribution" between the initiator and target. - -6.1.3. Protocol Features and State Expectations - - The initiator mechanisms defined in connection with error recovery - are: - - a) NOP-OUT to probe sequence numbers of the target (section - 10.18) - b) Command retry (section 6.2.1) - c) Recovery R2T support (section 6.7) - d) Requesting retransmission of status/data/R2T using the SNACK - facility (section 10.16) - e) Acknowledging the receipt of the data (section 10.16) - f) Reassigning the connection allegiance of a task to a different - TCP connection (section 6.2.2) - g) Terminating the entire iSCSI session to start afresh (section - 6.1.4.4) - - The target mechanisms defined in connection with error recovery are: - - a) NOP-IN to probe sequence numbers of the initiator (section - 10.19) - b) Requesting retransmission of data using the recovery R2T - feature (section 6.7) - c) SNACK support (section 10.16) d) Requesting that parts of - read data be acknowledged (section 10.7.2) - e) Allegiance reassignment support (section 6.2.2) - f) Terminating the entire iSCSI session to force the initiator to - start over (section 6.1.4.4) - - For any outstanding SCSI command, it is assumed that iSCSI, in - conjunction with SCSI at the initiator, is able to keep enough - information to be able to rebuild the command PDU, and that outgoing - data is available (in host memory) for retransmission while the - command is outstanding. It is also assumed that at the target, - incoming data (read data) MAY be kept for recovery or it can be - reread from a device server. - - It is further assumed that a target will keep the "status & sense" - for a command it has executed if it supports status retransmission. - A target that agrees to support data retransmission is expected to be - prepared to retransmit the outgoing data (i.e., Data-In) on request - - - -Satran, et al. Standards Track [Page 68] - -RFC 3720 iSCSI April 2004 - - - until either the status for the completed command is acknowledged, or - the data in question has been separately acknowledged. - -6.1.4. Recovery Classes - - iSCSI enables the following classes of recovery (in the order of - increasing scope of affected iSCSI tasks): - - - Within a command (i.e., without requiring command restart). - - Within a connection (i.e., without requiring the connection to - be rebuilt, but perhaps requiring command restart). - - Connection recovery (i.e., perhaps requiring connections to be - rebuilt and commands to be reissued). - - Session recovery. - - The recovery scenarios detailed in the rest of this section are - representative rather than exclusive. In every case, they detail the - lowest class recovery that MAY be attempted. The implementer is left - to decide under which circumstances to escalate to the next recovery - class and/or what recovery classes to implement. Both the iSCSI - target and initiator MAY escalate the error handling to an error - recovery class, which impacts a larger number of iSCSI tasks in any - of the cases identified in the following discussion. - - In all classes, the implementer has the choice of deferring errors to - the SCSI initiator (with an appropriate response code), in which case - the task, if any, has to be removed from the target and all the side - effects, such as ACA, must be considered. - - Use of within-connection and within-command recovery classes MUST NOT - be attempted before the connection is in Full Feature Phase. - - In the detailed description of the recovery classes, the mandating - terms (MUST, SHOULD, MAY, etc.) indicate normative actions to be - executed if the recovery class is supported and used. - -6.1.4.1. Recovery Within-command - - At the target, the following cases lend themselves to - within-command recovery: - - - Lost data PDU - realized through one of the following: - - a) Data digest error - dealt with as specified in Section 6.7 - Digest Errors, using the option of a recovery R2T. - - - - - - -Satran, et al. Standards Track [Page 69] - -RFC 3720 iSCSI April 2004 - - - b) Sequence reception timeout (no data or - partial-data-and-no-F-bit) - considered an implicit sequence - error and dealt with as specified in Section 6.8 Sequence - Errors, using the option of a recovery R2T. - c) Header digest error, which manifests as a sequence reception - timeout or a sequence error - dealt with as specified in - Section 6.8 Sequence Errors, using the option of a recovery - R2T. - - At the initiator, the following cases lend themselves to - within-command recovery: - - Lost data PDU or lost R2T - realized through one of the - following: - - a) Data digest error - dealt with as specified in Section 6.7 - Digest Errors, using the option of a SNACK. - b) Sequence reception timeout (no status) or response reception - timeout - dealt with as specified in Section 6.8 Sequence - Errors, using the option of a SNACK. - c) Header digest error, which manifests as a sequence reception - timeout or a sequence error - dealt with as specified in - Section 6.8 Sequence Errors, using the option of a SNACK. - - To avoid a race with the target, which may already have a recovery - R2T or a termination response on its way, an initiator SHOULD NOT - originate a SNACK for an R2T based on its internal timeouts (if any). - Recovery in this case is better left to the target. - - The timeout values used by the initiator and target are outside the - scope of this document. Sequence reception timeout is generally a - large enough value to allow the data sequence transfer to be - complete. - -6.1.4.2. Recovery Within-connection - - At the initiator, the following cases lend themselves to - within-connection recovery: - - - Requests not acknowledged for a long time. Requests are - acknowledged explicitly through ExpCmdSN or implicitly by - receiving data and/or status. The initiator MAY retry - non-acknowledged commands as specified in Section 6.2 Retry and - Reassign in Recovery. - - - - - - - -Satran, et al. Standards Track [Page 70] - -RFC 3720 iSCSI April 2004 - - - - Lost iSCSI numbered Response. It is recognized by either - identifying a data digest error on a Response PDU or a Data-In - PDU carrying the status, or by receiving a Response PDU with a - higher StatSN than expected. In the first case, digest error - handling is done as specified in Section 6.7 Digest Errors using - the option of a SNACK. In the second case, sequence error - handling is done as specified in Section 6.8 Sequence Errors, - using the option of a SNACK. - - At the target, the following cases lend themselves to - within-connection recovery: - - - Status/Response not acknowledged for a long time. The target MAY - issue a NOP-IN (with a valid Target Transfer Tag or otherwise) - that carries the next status sequence number it is going to use - in the StatSN field. This helps the initiator detect any missing - StatSN(s) and issue a SNACK for the status. - - The timeout values used by the initiator and the target are outside - the scope of this document. - -6.1.4.3. Connection Recovery - - At an iSCSI initiator, the following cases lend themselves to - connection recovery: - - - TCP connection failure: The initiator MUST close the connection. - It then MUST either implicitly or explicitly logout the failed - connection with the reason code "remove the connection for - recovery" and reassign connection allegiance for all commands - still in progress associated with the failed connection on one or - more connections (some or all of which MAY be newly established - connections) using the "Task reassign" task management function - (see Section 10.5.1 Function). For an initiator, a command is in - progress as long as it has not received a response or a Data-In - PDU including status. - - Note: The logout function is mandatory. However, a new connection - establishment is only mandatory if the failed connection was the - last or only connection in the session. - - - Receiving an Asynchronous Message that indicates one or all - connections in a session has been dropped. The initiator MUST - handle it as a TCP connection failure for the connection(s) - referred to in the Message. - - - - - - -Satran, et al. Standards Track [Page 71] - -RFC 3720 iSCSI April 2004 - - - At an iSCSI target, the following cases lend themselves to connection - recovery: - - - TCP connection failure. The target MUST close the connection and, - if more than one connection is available, the target SHOULD send - an Asynchronous Message that indicates it has dropped the - connection. Then, the target will wait for the initiator to - continue recovery. - -6.1.4.4. Session Recovery - - Session recovery should be performed when all other recovery attempts - have failed. Very simple initiators and targets MAY perform session - recovery on all iSCSI errors and rely on recovery on the SCSI layer - and above. - - Session recovery implies the closing of all TCP connections, - internally aborting all executing and queued tasks for the given - initiator at the target, terminating all outstanding SCSI commands - with an appropriate SCSI service response at the initiator, and - restarting a session on a new set of connection(s) (TCP connection - establishment and login on all new connections). - - For possible clearing effects of session recovery on SCSI and iSCSI - objects, refer to Appendix F. - Clearing Effects of Various Events on - Targets -. - -6.1.5. Error Recovery Hierarchy - - The error recovery classes described so far are organized into a - hierarchy for ease in understanding and to limit the implementation - complexity. With few and well defined recovery levels - interoperability is easier to achieve. The attributes of this - hierarchy are as follows: - - a) Each level is a superset of the capabilities of the previous - level. For example, Level 1 support implies supporting all - capabilities of Level 0 and more. - b) As a corollary, supporting a higher error recovery level means - increased sophistication and possibly an increase in resource - requirements. - c) Supporting error recovery level "n" is advertised and - negotiated by each iSCSI entity by exchanging the text key - "ErrorRecoveryLevel=n". The lower of the two exchanged values - is the operational ErrorRecoveryLevel for the session. - - - - - - -Satran, et al. Standards Track [Page 72] - -RFC 3720 iSCSI April 2004 - - - The following diagram represents the error recovery hierarchy. - - + - / - / 2 \ <-- Connection recovery - +-----+ - / 1 \ <-- Digest failure recovery - +---------+ - / 0 \ <-- Session failure recovery - +-------------+ - - The following table lists the error recovery capabilities expected - from the implementations that support each error recovery level. - - +-------------------+--------------------------------------------+ - |ErrorRecoveryLevel | Associated Error recovery capabilities | - +-------------------+--------------------------------------------+ - | 0 | Session recovery class | - | | (Section 6.1.4.4 Session Recovery) | - +-------------------+--------------------------------------------+ - | 1 | Digest failure recovery (See Note below.) | - | | plus the capabilities of ER Level 0 | - +-------------------+--------------------------------------------+ - | 2 | Connection recovery class | - | | (Section 6.1.4.3 Connection Recovery) | - | | plus the capabilities of ER Level 1 | - +-------------------+--------------------------------------------+ - - Note: Digest failure recovery is comprised of two recovery classes: - Within-Connection recovery class (Section 6.1.4.2 Recovery Within- - connection) and Within-Command recovery class (Section 6.1.4.1 - Recovery Within-command). - - When a defined value of ErrorRecoveryLevel is proposed by an - originator in a text negotiation, the originator MUST support the - functionality defined for the proposed value and additionally, the - functionality corresponding to any defined value numerically less - than the proposed. When a defined value of ErrorRecoveryLevel is - returned by a responder in a text negotiation, the responder MUST - support the functionality corresponding to the ErrorRecoveryLevel it - is accepting. - - When either party attempts to use error recovery functionality beyond - what is negotiated, the recovery attempts MAY fail unless an a priori - agreement outside the scope of this document exists between the two - parties to provide such support. - - - - - -Satran, et al. Standards Track [Page 73] - -RFC 3720 iSCSI April 2004 - - - Implementations MUST support error recovery level "0", while the rest - are OPTIONAL to implement. In implementation terms, the above - striation means that the following incremental sophistication with - each level is required. - - +-------------------+---------------------------------------------+ - |Level transition | Incremental requirement | - +-------------------+---------------------------------------------+ - | 0->1 | PDU retransmissions on the same connection | - +-------------------+---------------------------------------------+ - | 1->2 | Retransmission across connections and | - | | allegiance reassignment | - +-------------------+---------------------------------------------+ - -6.2. Retry and Reassign in Recovery - - This section summarizes two important and somewhat related iSCSI - protocol features used in error recovery. - -6.2.1. Usage of Retry - - By resending the same iSCSI command PDU ("retry") in the absence of a - command acknowledgement (by way of an ExpCmdSN update) or a response, - an initiator attempts to "plug" (what it thinks are) the - discontinuities in CmdSN ordering on the target end. Discarded - command PDUs, due to digest errors, may have created these - discontinuities. - - Retry MUST NOT be used for reasons other than plugging command - sequence gaps, and in particular, cannot be used for requesting PDU - retransmissions from a target. Any such PDU retransmission requests - for a currently allegiant command in progress may be made using the - SNACK mechanism described in section 10.16, although the usage of - SNACK is OPTIONAL. - - If initiators, as part of plugging command sequence gaps as described - above, inadvertently issue retries for allegiant commands already in - progress (i.e., targets did not see the discontinuities in CmdSN - ordering), the duplicate commands are silently ignored by targets as - specified in section 3.2.2.1. - - When an iSCSI command is retried, the command PDU MUST carry the - original Initiator Task Tag and the original operational attributes - (e.g., flags, function names, LUN, CDB etc.) as well as the original - CmdSN. The command being retried MUST be sent on the same connection - as the original command unless the original connection was already - successfully logged out. - - - - -Satran, et al. Standards Track [Page 74] - -RFC 3720 iSCSI April 2004 - - -6.2.2. Allegiance Reassignment - - By issuing a "task reassign" task management request (Section 10.5.1 - Function), the initiator signals its intent to continue an already - active command (but with no current connection allegiance) as part of - connection recovery. This means that a new connection allegiance is - requested for the command, which seeks to associate it to the - connection on which the task management request is being issued. - Before the allegiance reassignment is attempted for a task, an - implicit or explicit Logout with the reason code "remove the - connection for recovery" ( see section 10.14) MUST be successfully - completed for the previous connection to which the task was - allegiant. - - In reassigning connection allegiance for a command, the targets - SHOULD continue the command from its current state. For example, - when reassigning read commands, the target SHOULD take advantage of - the ExpDataSN field provided by the Task Management function request - (which must be set to zero if there was no data transfer) and bring - the read command to completion by sending the remaining data and - sending (or resending) the status. ExpDataSN acknowledges all data - sent up to, but not including, the Data-In PDU and or R2T with DataSN - (or R2TSN) equal to ExpDataSN. However, targets may choose to - send/receive all unacknowledged data or all of the data on a - reassignment of connection allegiance if unable to recover or - maintain an accurate state. Initiators MUST not subsequently request - data retransmission through Data SNACK for PDUs numbered less than - ExpDataSN (i.e., prior to the acknowledged sequence number). For all - types of commands, a reassignment request implies that the task is - still considered in progress by the initiator and the target must - conclude the task appropriately if the target returns the "Function - Complete" response to the reassignment request. This might possibly - involve retransmission of data/R2T/status PDUs as necessary, but MUST - involve the (re)transmission of the status PDU. - - It is OPTIONAL for targets to support the allegiance reassignment. - This capability is negotiated via the ErrorRecoveryLevel text key - during the login time. When a target does not support allegiance - reassignment, it MUST respond with a Task Management response code of - "Allegiance reassignment not supported". If allegiance reassignment - is supported by the target, but the task is still allegiant to a - different connection, or a successful recovery Logout of the - previously allegiant connection was not performed, the target MUST - respond with a Task Management response code of "Task still - allegiant". - - - - - - -Satran, et al. Standards Track [Page 75] - -RFC 3720 iSCSI April 2004 - - - If allegiance reassignment is supported by the target, the Task - Management response to the reassignment request MUST be issued before - the reassignment becomes effective. - - If a SCSI Command that involves data input is reassigned, any SNACK - Tag it holds for a final response from the original connection is - deleted and the default value of 0 MUST be used instead. - -6.3. Usage Of Reject PDU in Recovery - - Targets MUST NOT implicitly terminate an active task by sending a - Reject PDU for any PDU exchanged during the life of the task. If the - target decides to terminate the task, a Response PDU (SCSI, Text, - Task, etc.) must be returned by the target to conclude the task. If - the task had never been active before the Reject (i.e., the Reject is - on the command PDU), targets should not send any further responses - because the command itself is being discarded. - - The above rule means that the initiator can eventually expect a - response on receiving Rejects, if the received Reject is for a PDU - other than the command PDU itself. The non-command Rejects only have - diagnostic value in logging the errors, and they can be used for - retransmission decisions by the initiators. - - The CmdSN of the rejected command PDU (if it is a non-immediate - command) MUST NOT be considered received by the target (i.e., a - command sequence gap must be assumed for the CmdSN), even though the - CmdSN of the rejected command PDU may be reliably ascertained. Upon - receiving the Reject, the initiator MUST plug the CmdSN gap in order - to continue to use the session. The gap may be plugged either by - transmitting a command PDU with the same CmdSN, or by aborting the - task (see section 6.9 on how an abort may plug a CmdSN gap). - - When a data PDU is rejected and its DataSN can be ascertained, a - target MUST advance ExpDataSN for the current data burst if a - recovery R2T is being generated. The target MAY advance its - ExpDataSN if it does not attempt to recover the lost data PDU. - -6.4. Connection Timeout Management - - iSCSI defines two session-global timeout values (in seconds) - - Time2Wait and Time2Retain - that are applicable when an iSCSI Full - Feature Phase connection is taken out of service either intentionally - or by an exception. Time2Wait is the initial "respite time" before - attempting an explicit/implicit Logout for the CID in question or - task reassignment for the affected tasks (if any). Time2Retain is - the maximum time after the initial respite interval that the task - and/or connection state(s) is/are guaranteed to be maintained on the - - - -Satran, et al. Standards Track [Page 76] - -RFC 3720 iSCSI April 2004 - - - target to cater to a possible recovery attempt. Recovery attempts - for the connection and/or task(s) SHOULD NOT be made before Time2Wait - seconds, but MUST be completed within Time2Retain seconds after that - initial Time2Wait waiting period. - -6.4.1. Timeouts on Transport Exception Events - - A transport connection shutdown or a transport reset without any - preceding iSCSI protocol interactions informing the end-points of the - fact causes a Full Feature Phase iSCSI connection to be abruptly - terminated. The timeout values to be used in this case are the - negotiated values of defaultTime2Wait (Section 12.15 - DefaultTime2Wait) and DefaultTime2Retain (Section 12.16 - DefaultTime2Retain) text keys for the session. - -6.4.2. Timeouts on Planned Decommissioning - - Any planned decommissioning of a Full Feature Phase iSCSI connection - is preceded by either a Logout Response PDU, or an Async Message PDU. - The Time2Wait and Time2Retain field values (section 10.15) in a - Logout Response PDU, and the Parameter2 and Parameter3 fields of an - Async Message (AsyncEvent types "drop the connection" or "drop all - the connections"; section 10.9.1) specify the timeout values to be - used in each of these cases. - - These timeout values are only applicable for the affected connection, - and the tasks active on that connection. These timeout values have - no bearing on initiator timers (if any) that are already running on - connections or tasks associated with that session. - -6.5. Implicit Termination of Tasks - - A target implicitly terminates the active tasks due to iSCSI protocol - dynamics in the following cases: - - a) When a connection is implicitly or explicitly logged out with - the reason code of "Close the connection" and there are active - tasks allegiant to that connection. - - b) When a connection fails and the connection state eventually - times out (state transition M1 in Section 7.2.2 State - Transition Descriptions for Initiators and Targets) and there - are active tasks allegiant to that connection. - - c) When a successful Logout with the reason code of "remove the - connection for recovery" is performed while there are active - tasks allegiant to that connection, and those tasks eventually - - - - -Satran, et al. Standards Track [Page 77] - -RFC 3720 iSCSI April 2004 - - - time out after the Time2Wait and Time2Retain periods without - allegiance reassignment. - - d) When a connection is implicitly or explicitly logged out with - the reason code of "Close the session" and there are active - tasks in that session. - - If the tasks terminated in the above cases a), b, c) and d)are SCSI - tasks, they must be internally terminated as if with CHECK CONDITION - status. This status is only meaningful for appropriately handling - the internal SCSI state and SCSI side effects with respect to - ordering because this status is never communicated back as a - terminating status to the initiator. However additional actions may - have to be taken at SCSI level depending on the SCSI context as - defined by the SCSI standards (e.g., queued commands and ACA, in - cases a), b), and c), after the tasks are terminated, the target MUST - report a Unit Attention condition on the next command processed on - any connection for each affected I_T_L nexus with the status of CHECK - CONDITION, and the ASC/ASCQ value of 47h/7Fh - "SOME COMMANDS CLEARED - BY ISCSI PROTOCOL EVENT" , etc. - see [SAM2] and [SPC3]). - -6.6. Format Errors - - The following two explicit violations of PDU layout rules are format - errors: - - a) Illegal contents of any PDU header field except the Opcode - (legal values are specified in Section 10 iSCSI PDU Formats). - b) Inconsistent field contents (consistent field contents are - specified in Section 10 iSCSI PDU Formats). - - Format errors indicate a major implementation flaw in one of the - parties. - - When a target or an initiator receives an iSCSI PDU with a format - error, it MUST immediately terminate all transport connections in the - session either with a connection close or with a connection reset and - escalate the format error to session recovery (see Section 6.1.4.4 - Session Recovery). - -6.7. Digest Errors - - The discussion of the legal choices in handling digest errors below - excludes session recovery as an explicit option, but either party - detecting a digest error may choose to escalate the error to session - recovery. - - - - - -Satran, et al. Standards Track [Page 78] - -RFC 3720 iSCSI April 2004 - - - When a target or an initiator receives any iSCSI PDU, with a header - digest error, it MUST either discard the header and all data up to - the beginning of a later PDU or close the connection. Because the - digest error indicates that the length field of the header may have - been corrupted, the location of the beginning of a later PDU needs to - be reliably ascertained by other means such as the operation of a - sync and steering layer. - - When a target receives any iSCSI PDU with a payload digest error, it - MUST answer with a Reject PDU with a reason code of - Data-Digest-Error and discard the PDU. - - - If the discarded PDU is a solicited or unsolicited iSCSI data - PDU (for immediate data in a command PDU, non-data PDU rule - below applies), the target MUST do one of the following: - a) Request retransmission with a recovery R2T. - b) Terminate the task with a response PDU with a CHECK - CONDITION Status and an iSCSI Condition of "protocol service - CRC error" (Section 10.4.7.2 Sense Data). If the target - chooses to implement this option, it MUST wait to receive - all the data (signaled by a Data PDU with the final bit set - for all outstanding R2Ts) before sending the response PDU. - A task management command (such as an abort task) from the - initiator during this wait may also conclude the task. - - No further action is necessary for targets if the discarded PDU - is a non-data PDU. In case of immediate data being present on - a discarded command, the immediate data is implicitly recovered - when the task is retried (see section 6.2.1), followed by the - entire data transfer for the task. - - When an initiator receives any iSCSI PDU with a payload digest error, - it MUST discard the PDU. - - - If the discarded PDU is an iSCSI data PDU, the initiator MUST do - one of the following: - - a) Request the desired data PDU through SNACK. In response to the - SNACK, the target MUST either resend the data PDU or reject the - SNACK with a Reject PDU with a reason code of "SNACK reject" in - which case: - i) If the status has not already been sent for the command, - the target MUST terminate the command with a CHECK - CONDITION Status and an iSCSI Condition of "SNACK rejected" - (Section 10.4.7.2 Sense Data). - ii) If the status was already sent, no further action is - necessary for the target. The initiator in this case MUST - wait for the status to be received and then discard it, so - as to internally signal the completion with CHECK CONDITION - - - -Satran, et al. Standards Track [Page 79] - -RFC 3720 iSCSI April 2004 - - - Status and an iSCSI Condition of "protocol service CRC - error" (Section 10.4.7.2 Sense Data). - b) Abort the task and terminate the command with an error. - - - If the discarded PDU is a response PDU, the initiator MUST do one - of the following: - - a) Request PDU retransmission with a status SNACK. - b) Logout the connection for recovery and continue the tasks on a - different connection instance as described in Section 6.2 Retry - and Reassign in Recovery. - c) Logout to close the connection (abort all the commands - associated with the connection). - - - No further action is necessary for initiators if the discarded PDU - is an unsolicited PDU (e.g., Async, Reject). Task timeouts as in - the initiator waiting for a command completion, or process - timeouts, as in the target waiting for a Logout, will ensure that - the correct operational behavior will result in these cases - despite the discarded PDU. - -6.8. Sequence Errors - - When an initiator receives an iSCSI R2T/data PDU with an out of order - R2TSN/DataSN or a SCSI response PDU with an ExpDataSN that implies - missing data PDU(s), it means that the initiator must have detected a - header or payload digest error on one or more earlier R2T/data PDUs. - The initiator MUST address these implied digest errors as described - in Section 6.7 Digest Errors. When a target receives a data PDU with - an out of order DataSN, it means that the target must have hit a - header or payload digest error on at least one of the earlier data - PDUs. The target MUST address these implied digest errors as - described in Section 6.7 Digest Errors. - - When an initiator receives an iSCSI status PDU with an out of order - StatSN that implies missing responses, it MUST address the one or - more missing status PDUs as described in Section 6.7 Digest Errors. - As a side effect of receiving the missing responses, the initiator - may discover missing data PDUs. If the initiator wants to recover - the missing data for a command, it MUST NOT acknowledge the received - responses that start from the StatSN of the relevant command, until - it has completed receiving all the data PDUs of the command. - - When an initiator receives duplicate R2TSNs (due to proactive - retransmission of R2Ts by the target) or duplicate DataSNs (due to - proactive SNACKs by the initiator), it MUST discard the duplicates. - - - - - -Satran, et al. Standards Track [Page 80] - -RFC 3720 iSCSI April 2004 - - -6.9. SCSI Timeouts - - An iSCSI initiator MAY attempt to plug a command sequence gap on the - target end (in the absence of an acknowledgement of the command by - way of ExpCmdSN) before the ULP timeout by retrying the - unacknowledged command, as described in Section 6.2 Retry and - Reassign in Recovery. - - On a ULP timeout for a command (that carried a CmdSN of n), if the - iSCSI initiator intends to continue the session, it MUST abort the - command by either using an appropriate Task Management function - request for the specific command, or a "close the connection" Logout. - When using an ABORT TASK, if the ExpCmdSN is still less than (n+1), - the target may see the abort request while missing the original - command itself due to one of the following reasons: - - - Original command was dropped due to digest error. - - Connection on which the original command was sent was - successfully logged out. Upon logout, the unacknowledged - commands issued on the connection being logged out are - discarded. - - If the abort request is received and the original command is missing, - targets MUST consider the original command with that RefCmdSN to be - received and issue a Task Management response with the response code: - "Function Complete". This response concludes the task on both ends. - If the abort request is received and the target can determine (based - on the Referenced Task Tag) that the command was received and - executed and also that the response was sent prior to the abort, then - the target MUST respond with the response code of "Task Does Not - Exist". - -6.10. Negotiation Failures - - Text request and response sequences, when used to set/negotiate - operational parameters, constitute the negotiation/parameter setting. - A negotiation failure is considered to be one or more of the - following: - - - None of the choices, or the stated value, is acceptable to one - of the sides in the negotiation. - - The text request timed out and possibly terminated. - - The text request was answered with a Reject PDU. - - - - - - - - -Satran, et al. Standards Track [Page 81] - -RFC 3720 iSCSI April 2004 - - - The following two rules should be used to address negotiation - failures: - - - During Login, any failure in negotiation MUST be considered a - login process failure and the Login Phase must be terminated, - and with it, the connection. If the target detects the - failure, it must terminate the login with the appropriate Login - Response code. - - - A failure in negotiation, while in the Full Feature Phase, will - terminate the entire negotiation sequence that may consist of a - series of text requests that use the same Initiator Task Tag. - The operational parameters of the session or the connection - MUST continue to be the values agreed upon during an earlier - successful negotiation (i.e., any partial results of this - unsuccessful negotiation MUST NOT take effect and MUST be - discarded). - -6.11. Protocol Errors - - Mapping framed messages over a "stream" connection, such as TCP, - makes the proposed mechanisms vulnerable to simple software framing - errors. On the other hand, the introduction of framing mechanisms to - limit the effects of these errors may be onerous on performance for - simple implementations. Command Sequence Numbers and the above - mechanisms for connection drop and reestablishment help handle this - type of mapping errors. - - All violations of iSCSI PDU exchange sequences specified in this - document are also protocol errors. This category of errors can only - be addressed by fixing the implementations; iSCSI defines Reject and - response codes to enable this. - -6.12. Connection Failures - - iSCSI can keep a session in operation if it is able to - keep/establish at least one TCP connection between the initiator and - the target in a timely fashion. Targets and/or initiators may - recognize a failing connection by either transport level means (TCP), - a gap in the command sequence number, a response stream that is not - filled for a long time, or by a failing iSCSI NOP (acting as a ping). - The latter MAY be used periodically to increase the speed and - likelihood of detecting connection failures. Initiators and targets - MAY also use the keep-alive option on the TCP connection to enable - early link failure detection on otherwise idle links. - - - - - - -Satran, et al. Standards Track [Page 82] - -RFC 3720 iSCSI April 2004 - - - On connection failure, the initiator and target MUST do one of the - following: - - - Attempt connection recovery within the session (Section 6.1.4.3 - Connection Recovery). - - - Logout the connection with the reason code "closes the - connection" (Section 10.14.5 Implicit termination of tasks), - re-issue missing commands, and implicitly terminate all active - commands. This option requires support for the - within-connection recovery class (Section 6.1.4.2 Recovery - Within-connection). - - - Perform session recovery (Section 6.1.4.4 Session Recovery). - - Either side may choose to escalate to session recovery (via the - initiator dropping all the connections, or via an Async Message that - announces the similar intent from a target), and the other side MUST - give it precedence. On a connection failure, a target MUST terminate - and/or discard all of the active immediate commands regardless of - which of the above options is used (i.e., immediate commands are not - recoverable across connection failures). - -6.13. Session Errors - - If all of the connections of a session fail and cannot be - reestablished in a short time, or if initiators detect protocol - errors repeatedly, an initiator may choose to terminate a session and - establish a new session. - - In this case, the initiator takes the following actions: - - - Resets or closes all the transport connections. - - Terminates all outstanding requests with an appropriate - response before initiating a new session. If the same I_T - nexus is intended to be reestablished, the initiator MUST - employ session reinstatement (see section 5.3.5). - - When the session timeout (the connection state timeout for the last - failed connection) happens on the target, it takes the following - actions: - - - Resets or closes the TCP connections (closes the session). - - Terminates all active tasks that were allegiant to the - connection(s) that constituted the session. - - A target MUST also be prepared to handle a session reinstatement - request from the initiator, that may be addressing session errors. - - - -Satran, et al. Standards Track [Page 83] - -RFC 3720 iSCSI April 2004 - - -7. State Transitions - - iSCSI connections and iSCSI sessions go through several well-defined - states from the time they are created to the time they are cleared. - - The connection state transitions are described in two separate but - dependent state diagrams for ease in understanding. The first - diagram, "standard connection state diagram", describes the - connection state transitions when the iSCSI connection is not waiting - for, or undergoing, a cleanup by way of an explicit or implicit - Logout. The second diagram, "connection cleanup state diagram", - describes the connection state transitions while performing the iSCSI - connection cleanup. - - The "session state diagram" describes the state transitions an iSCSI - session would go through during its lifetime, and it depends on the - states of possibly multiple iSCSI connections that participate in the - session. - - States and state transitions are described in the text, tables and - diagrams. The diagrams are used for illustration. The text and the - tables are the governing specification. - -7.1. Standard Connection State Diagrams - -7.1.1. State Descriptions for Initiators and Targets - - State descriptions for the standard connection state diagram are as - follows: - - -S1: FREE - -initiator: State on instantiation, or after successful - connection closure. - -target: State on instantiation, or after successful connection - closure. - -S2: XPT_WAIT - -initiator: Waiting for a response to its transport connection - establishment request. - -target: Illegal - -S3: XPT_UP - -initiator: Illegal - -target: Waiting for the Login process to commence. - -S4: IN_LOGIN - -initiator: Waiting for the Login process to conclude, possibly - involving several PDU exchanges. - -target: Waiting for the Login process to conclude, possibly - involving several PDU exchanges. - - - - -Satran, et al. Standards Track [Page 84] - -RFC 3720 iSCSI April 2004 - - - -S5: LOGGED_IN - -initiator: In Full Feature Phase, waiting for all internal, - iSCSI, and transport events. - -target: In Full Feature Phase, waiting for all internal, iSCSI, - and transport events. - -S6: IN_LOGOUT - -initiator: Waiting for a Logout response. - -target: Waiting for an internal event signaling completion of - logout processing. - -S7: LOGOUT_REQUESTED - -initiator: Waiting for an internal event signaling readiness to - proceed with Logout. - -target: Waiting for the Logout process to start after having - requested a Logout via an Async Message. - -S8: CLEANUP_WAIT - -initiator: Waiting for the context and/or resources to initiate - the cleanup processing for this CSM. - -target: Waiting for the cleanup process to start for this CSM. - -7.1.2. State Transition Descriptions for Initiators and Targets - - -T1: - -initiator: Transport connect request was made (e.g., TCP SYN - sent). - -target: Illegal - -T2: - -initiator: Transport connection request timed out, a transport - reset was received, or an internal event of receiving a - Logout response (success) on another connection for a - "close the session" Logout request was received. - -target:Illegal - -T3: - -initiator: Illegal - -target: Received a valid transport connection request that - establishes the transport connection. - -T4: - -initiator: Transport connection established, thus prompting the - initiator to start the iSCSI Login. - -target: Initial iSCSI Login Request was received. - -T5: - -initiator: The final iSCSI Login Response with a Status-Class - of zero was received. - -target: The final iSCSI Login Request to conclude the Login - Phase was received, thus prompting the target to send the - final iSCSI Login Response with a Status-Class of zero. - - - - - - -Satran, et al. Standards Track [Page 85] - -RFC 3720 iSCSI April 2004 - - - -T6: - -initiator: Illegal - -target: Timed out waiting for an iSCSI Login, transport - disconnect indication was received, transport reset was - received, or an internal event indicating a transport - timeout was received. In all these cases, the connection is - to be closed. - -T7: - -initiator - one of the following events caused the transition: - - The final iSCSI Login Response was received with a - non-zero Status-Class. - - Login timed out. - - A transport disconnect indication was received. - - A transport reset was received. - - An internal event was received indicating a transport - timeout. - - An internal event of receiving a Logout response (success) - on another connection for a "close the session" Logout - request was received. - - In all these cases, the transport connection is closed. - - -target - one of the following events caused the transition: - - The final iSCSI Login Request to conclude the Login Phase - was received, prompting the target to send the final iSCSI - Login Response with a non-zero Status-Class. - - Login timed out. - - Transport disconnect indication was received. - - Transport reset was received. - - An internal event indicating a transport timeout was - received. - - On another connection a "close the session" Logout request - was received. - In all these cases, the connection is to be closed. - -T8: - -initiator: An internal event of receiving a Logout response - (success) on another connection for a "close the session" - Logout request was received, thus closing this connection - requiring no further cleanup. - -target: An internal event of sending a Logout response - (success) on another connection for a "close the session" - Logout request was received, or an internal event of a - successful connection/session reinstatement is received, - thus prompting the target to close this connection cleanly. - - - - - - - -Satran, et al. Standards Track [Page 86] - -RFC 3720 iSCSI April 2004 - - - -T9, T10: - -initiator: An internal event that indicates the readiness to - start the Logout process was received, thus prompting an - iSCSI Logout to be sent by the initiator. - -target: An iSCSI Logout request was received. - -T11, T12: - -initiator: Async PDU with AsyncEvent "Request Logout" was - received. - -target: An internal event that requires the decommissioning of - the connection is received, thus causing an Async PDU with - an AsyncEvent "Request Logout" to be sent. - -T13: - -initiator: An iSCSI Logout response (success) was received, or - an internal event of receiving a Logout response (success) - on another connection for a "close the session" Logout - request was received. - -target: An internal event was received that indicates - successful processing of the Logout, which prompts an iSCSI - Logout response (success) to be sent; an internal event of - sending a Logout response (success) on another connection - for a "close the session" Logout request was received; or an - internal event of a successful connection/session - reinstatement is received. In all these cases, the - transport connection is closed. - - -T14: - -initiator: Async PDU with AsyncEvent "Request Logout" was - received again. - -target: Illegal - -T15, T16: - -initiator: One or more of the following events caused this - transition: - -Internal event that indicates a transport connection - timeout was received thus prompting transport RESET or - transport connection closure. - -A transport RESET. - -A transport disconnect indication. - -Async PDU with AsyncEvent "Drop connection" (for this CID). - -Async PDU with AsyncEvent "Drop all connections". - -target: One or more of the following events caused this - transition: - -Internal event that indicates a transport connection - timeout was received, thus prompting transport RESET or - transport connection closure. - -An internal event of a failed connection/session - reinstatement is received. - -A transport RESET. - -A transport disconnect indication. - - - -Satran, et al. Standards Track [Page 87] - -RFC 3720 iSCSI April 2004 - - - -Internal emergency cleanup event was received which prompts - an Async PDU with AsyncEvent "Drop connection" (for this - CID), or event "Drop all connections". - -T17: - -initiator: One or more of the following events caused this - transition: - -Logout response, (failure i.e., a non-zero status) was - received, or Logout timed out. - -Any of the events specified for T15 and T16. - -target: One or more of the following events caused this - transition: - -Internal event that indicates a failure of the Logout - processing was received, which prompts a Logout response - (failure, i.e., a non-zero status) to be sent. - -Any of the events specified for T15 and T16. - -T18: - -initiator: An internal event of receiving a Logout response - (success) on another connection for a "close the session" - Logout request was received. - -target: An internal event of sending a Logout response - (success) on another connection for a "close the session" - Logout request was received, or an internal event of a - successful connection/session reinstatement is received. In - both these cases, the connection is closed. - - The CLEANUP_WAIT state (S8) implies that there are possible iSCSI - tasks that have not reached conclusion and are still considered busy. - -7.1.3. Standard Connection State Diagram for an Initiator - - Symbolic names for States: - - S1: FREE - S2: XPT_WAIT - S4: IN_LOGIN - S5: LOGGED_IN - S6: IN_LOGOUT - S7: LOGOUT_REQUESTED - S8: CLEANUP_WAIT - - - - - - - - - - - - -Satran, et al. Standards Track [Page 88] - -RFC 3720 iSCSI April 2004 - - - States S5, S6, and S7 constitute the Full Feature Phase operation of - the connection. - - The state diagram is as follows: - - -------<-------------+ - +--------->/ S1 \<----+ | - T13| +->\ /<-+ \ | - | / ---+--- \ \ | - | / | T2 \ | | - | T8 | |T1 | | | - | | | / |T7 | - | | | / | | - | | | / | | - | | V / / | - | | ------- / / | - | | / S2 \ / | - | | \ / / | - | | ---+--- / | - | | |T4 / | - | | V / | T18 - | | ------- / | - | | / S4 \ | - | | \ / | - | | ---+--- | T15 - | | |T5 +--------+---------+ - | | | /T16+-----+------+ | - | | | / -+-----+--+ | | - | | | / / S7 \ |T12| | - | | | / +->\ /<-+ V V - | | | / / -+----- ------- - | | | / /T11 |T10 / S8 \ - | | V / / V +----+ \ / - | | ---+-+- ----+-- | ------- - | | / S5 \T9 / S6 \<+ ^ - | +-----\ /--->\ / T14 | - | ------- --+----+------+T17 - +---------------------------+ - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 89] - -RFC 3720 iSCSI April 2004 - - - The following state transition table represents the above diagram. - Each row represents the starting state for a given transition, which - after taking a transition marked in a table cell would end in the - state represented by the column of the cell. For example, from state - S1, the connection takes the T1 transition to arrive at state S2. - The fields marked "-" correspond to undefined transitions. - - +----+---+---+---+---+----+---+ - |S1 |S2 |S4 |S5 |S6 |S7 |S8 | - ---+----+---+---+---+---+----+---+ - S1| - |T1 | - | - | - | - | - | - ---+----+---+---+---+---+----+---+ - S2|T2 |- |T4 | - | - | - | - | - ---+----+---+---+---+---+----+---+ - S4|T7 |- |- |T5 | - | - | - | - ---+----+---+---+---+---+----+---+ - S5|T8 |- |- | - |T9 |T11 |T15| - ---+----+---+---+---+---+----+---+ - S6|T13 |- |- | - |T14|- |T17| - ---+----+---+---+---+---+----+---+ - S7|T18 |- |- | - |T10|T12 |T16| - ---+----+---+---+---+---+----+---+ - S8| - |- |- | - | - | - | - | - ---+----+---+---+---+---+----+---+ - -7.1.4. Standard Connection State Diagram for a Target - - Symbolic names for States: - - S1: FREE - S3: XPT_UP - S4: IN_LOGIN - S5: LOGGED_IN - S6: IN_LOGOUT - S7: LOGOUT_REQUESTED - S8: CLEANUP_WAIT - - States S5, S6, and S7 constitute the Full Feature Phase operation of - the connection. - - - - - - - - - - - - -Satran, et al. Standards Track [Page 90] - -RFC 3720 iSCSI April 2004 - - - The state diagram is as follows: - - -------<-------------+ - +--------->/ S1 \<----+ | - T13| +->\ /<-+ \ | - | / ---+--- \ \ | - | / | T6 \ | | - | T8 | |T3 | | | - | | | / |T7 | - | | | / | | - | | | / | | - | | V / / | - | | ------- / / | - | | / S3 \ / | - | | \ / / | T18 - | | ---+--- / | - | | |T4 / | - | | V / | - | | ------- / | - | | / S4 \ | - | | \ / | - | | ---+--- T15 | - | | |T5 +--------+---------+ - | | | /T16+-----+------+ | - | | | / -+-----+---+ | | - | | | / / S7 \ |T12| | - | | | / +->\ /<-+ V V - | | | / / -+----- ------- - | | | / /T11 |T10 / S8 \ - | | V / / V \ / - | | ---+-+- ------- ------- - | | / S5 \T9 / S6 \ ^ - | +-----\ /--->\ / | - | ------- --+----+--------+T17 - +---------------------------+ - - The following state transition table represents the above diagram, - and follows the conventions described for the initiator diagram. - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 91] - -RFC 3720 iSCSI April 2004 - - - +----+---+---+---+---+----+---+ - |S1 |S3 |S4 |S5 |S6 |S7 |S8 | - ---+----+---+---+---+---+----+---+ - S1| - |T3 | - | - | - | - | - | - ---+----+---+---+---+---+----+---+ - S3|T6 |- |T4 | - | - | - | - | - ---+----+---+---+---+---+----+---+ - S4|T7 |- |- |T5 | - | - | - | - ---+----+---+---+---+---+----+---+ - S5|T8 |- |- | - |T9 |T11 |T15| - ---+----+---+---+---+---+----+---+ - S6|T13 |- |- | - |- |- |T17| - ---+----+---+---+---+---+----+---+ - S7|T18 |- |- | - |T10|T12 |T16| - ---+----+---+---+---+---+----+---+ - S8| - |- |- | - | - | - | - | - ---+----+---+---+---+---+----+---+ - -7.2. Connection Cleanup State Diagram for Initiators and Targets - - Symbolic names for states: - - R1: CLEANUP_WAIT (same as S8) - R2: IN_CLEANUP - R3: FREE (same as S1) - - Whenever a connection state machine (e.g., CSM-C) enters the - CLEANUP_WAIT state (S8), it must go through the state transitions - described in the connection cleanup state diagram either a) using a - separate full-feature phase connection (let's call it CSM-E) in the - LOGGED_IN state in the same session, or b) using a new transport - connection (let's call it CSM-I) in the FREE state that is to be - added to the same session. In the CSM-E case, an explicit logout for - the CID that corresponds to CSM-C (either as a connection or session - logout) needs to be performed to complete the cleanup. In the CSM-I - case, an implicit logout for the CID that corresponds to CSM-C needs - to be performed by way of connection reinstatement (section 5.3.4) - for that CID. In either case, the protocol exchanges on CSM-E or - CSM-I determine the state transitions for CSM-C. Therefore, this - cleanup state diagram is only applicable to the instance of the - connection in cleanup (i.e., CSM-C). In the case of an implicit - logout for example, CSM-C reaches FREE (R3) at the time CSM-I reaches - LOGGED_IN. In the case of an explicit logout, CSM-C reaches FREE - (R3) when CSM-E receives a successful logout response while - continuing to be in the LOGGED_IN state. - - - - - - -Satran, et al. Standards Track [Page 92] - -RFC 3720 iSCSI April 2004 - - - An initiator must initiate an explicit or implicit connection logout - for a connection in the CLEANUP_WAIT state, if the initiator intends - to continue using the associated iSCSI session. - - The following state diagram applies to both initiators and targets. - - ------- - / R1 \ - +--\ /<-+ - / ---+--- - / | \ M3 - M1 | |M2 | - | | / - | | / - | | / - | V / - | ------- / - | / R2 \ - | \ / - | ------- - | | - | |M4 - | | - | | - | | - | V - | ------- - | / R3 \ - +---->\ / - ------- - - The following state transition table represents the above diagram, - and follows the same conventions as in earlier sections. - - +----+----+----+ - |R1 |R2 |R3 | - -----+----+----+----+ - R1 | - |M2 |M1 | - -----+----+----+----+ - R2 |M3 | - |M4 | - -----+----+----+----+ - R3 | - | - | - | - -----+----+----+----+ - - - - - - - - -Satran, et al. Standards Track [Page 93] - -RFC 3720 iSCSI April 2004 - - -7.2.1. State Descriptions for Initiators and Targets - - -R1: CLEANUP_WAIT (Same as S8) - -initiator: Waiting for the internal event to initiate the - cleanup processing for CSM-C. - -target: Waiting for the cleanup process to start for CSM-C. - -R2: IN_CLEANUP - -initiator: Waiting for the connection cleanup process to - conclude for CSM-C. - -target: Waiting for the connection cleanup process to conclude - for CSM-C. - -R3: FREE (Same as S1) - -initiator: End state for CSM-C. - -target: End state for CSM-C. - -7.2.2. State Transition Descriptions for Initiators and Targets - - -M1: One or more of the following events was received: - -initiator: - -An internal event that indicates connection state timeout. - -An internal event of receiving a successful Logout response - on a different connection for a "close the session" - Logout. - -target: - -An internal event that indicates connection state timeout. - -An internal event of sending a Logout response (success) on - a different connection for a "close the session" Logout - request. - - -M2: An implicit/explicit logout process was initiated by the - initiator. - -In CSM-I usage: - -initiator: An internal event requesting the connection (or - session) reinstatement was received, thus prompting a - connection (or session) reinstatement Login to be sent - transitioning CSM-I to state IN_LOGIN. - -target: A connection/session reinstatement Login was - received while in state XPT_UP. - -In CSM-E usage: - -initiator: An internal event that indicates that an - explicit logout was sent for this CID in state LOGGED_IN. - -target: An explicit logout was received for this CID in - state LOGGED_IN. - - - - - - - - -Satran, et al. Standards Track [Page 94] - -RFC 3720 iSCSI April 2004 - - - -M3: Logout failure detected - -In CSM-I usage: - -initiator: CSM-I failed to reach LOGGED_IN and arrived into - FREE instead. - -target: CSM-I failed to reach LOGGED_IN and arrived into - FREE instead. - -In CSM-E usage: - -initiator: CSM-E either moved out of LOGGED_IN, or Logout - timed out and/or aborted, or Logout response (failure) - was received. - -target: CSM-E either moved out of LOGGED_IN, Logout timed - out and/or aborted, or an internal event that indicates a - failed Logout processing was received. A Logout response - (failure) was sent in the last case. - - -M4: Successful implicit/explicit logout was performed. - - - In CSM-I usage: - -initiator: CSM-I reached state LOGGED_IN, or an internal - event of receiving a Logout response (success) on another - connection for a "close the session" Logout request was - received. - -target: CSM-I reached state LOGGED_IN, or an internal event - of sending a Logout response (success) on a different - connection for a "close the session" Logout request was - received. - - In CSM-E usage: - -initiator: CSM-E stayed in LOGGED_IN and received a Logout - response (success), or an internal event of receiving a - Logout response (success) on another connection for a - "close the session" Logout request was received. - -target: CSM-E stayed in LOGGED_IN and an internal event - indicating a successful Logout processing was received, - or an internal event of sending a Logout response - (success) on a different connection for a "close the - session" Logout request was received. - -7.3. Session State Diagrams - -7.3.1. Session State Diagram for an Initiator - - Symbolic Names for States: - - Q1: FREE - Q3: LOGGED_IN - Q4: FAILED - - State Q3 represents the Full Feature Phase operation of the session. - - - -Satran, et al. Standards Track [Page 95] - -RFC 3720 iSCSI April 2004 - - - The state diagram is as follows: - - ------- - / Q1 \ - +------>\ /<-+ - / ---+--- | - / | |N3 - N6 | |N1 | - | | | - | N4 | | - | +--------+ | / - | | | | / - | | | | / - | | V V / - -+--+-- -----+- - / Q4 \ N5 / Q3 \ - \ /<---\ / - ------- ------- - - The state transition table is as follows: - - +----+----+----+ - |Q1 |Q3 |Q4 | - -----+----+----+----+ - Q1 | - |N1 | - | - -----+----+----+----+ - Q3 |N3 | - |N5 | - -----+----+----+----+ - Q4 |N6 |N4 | - | - -----+----+----+----+ - -7.3.2. Session State Diagram for a Target - - Symbolic Names for States: - - Q1: FREE - Q2: ACTIVE - Q3: LOGGED_IN - Q4: FAILED - Q5: IN_CONTINUE - - State Q3 represents the Full Feature Phase operation of the session. - - - - - - - - - -Satran, et al. Standards Track [Page 96] - -RFC 3720 iSCSI April 2004 - - - The state diagram is as follows: - - ------- - +------------------>/ Q1 \ - / +-------------->\ /<-+ - | | ---+--- | - | | ^ | |N3 - N6 | |N11 N9| V N1 | - | | +------ | - | | / Q2 \ | - | | \ / | - | --+---- +--+--- | - | / Q5 \ | | - | \ / N10 | | - | +-+---+------------+ |N2 / - | ^ | | | / - |N7| |N8 | | / - | | | | V / - -+--+-V V----+- - / Q4 \ N5 / Q3 \ - \ /<-------------\ / - ------- ------- - - The state transition table is as follows: - - +----+----+----+----+----+ - |Q1 |Q2 |Q3 |Q4 |Q5 | - -----+----+----+----+----+----+ - Q1 | - |N1 | - | - | - | - -----+----+----+----+----+----+ - Q2 |N9 | - |N2 | - | - | - -----+----+----+----+----+----+ - Q3 |N3 | - | - |N5 | - | - -----+----+----+----+----+----+ - Q4 |N6 | - | - | - |N7 | - -----+----+----+----+----+----+ - Q5 |N11 | - |N10 |N8 | - | - -----+----+----+----+----+----+ - -7.3.3. State Descriptions for Initiators and Targets - - -Q1: FREE - -initiator: State on instantiation or after cleanup. - -target: State on instantiation or after cleanup. - - - - - - - -Satran, et al. Standards Track [Page 97] - -RFC 3720 iSCSI April 2004 - - - -Q2: ACTIVE - -initiator: Illegal. - -target: The first iSCSI connection in the session transitioned - to IN_LOGIN, waiting for it to complete the login process. - - -Q3: LOGGED_IN - -initiator: Waiting for all session events. - -target: Waiting for all session events. - - -Q4: FAILED - -initiator: Waiting for session recovery or session - continuation. - -target: Waiting for session recovery or session continuation. - - -Q5: IN_CONTINUE - -initiator: Illegal. - -target: Waiting for session continuation attempt to reach a - conclusion. - -7.3.4. State Transition Descriptions for Initiators and Targets - - -N1: - -initiator: At least one transport connection reached the - LOGGED_IN state. - -target: The first iSCSI connection in the session had reached - the IN_LOGIN state. - - -N2: - -initiator: Illegal. - -target: At least one iSCSI connection reached the LOGGED_IN - state. - - -N3: - -initiator: Graceful closing of the session via session closure - (Section 5.3.6 Session Continuation and Failure). - -target: Graceful closing of the session via session closure - (Section 5.3.6 Session Continuation and Failure) or a - successful session reinstatement cleanly closed the session. - - -N4: - -initiator: A session continuation attempt succeeded. - -target: Illegal. - - -N5: - -initiator: Session failure (Section 5.3.6 Session Continuation - and Failure) occurred. - -target: Session failure (Section 5.3.6 Session Continuation and - Failure) occurred. - - - -Satran, et al. Standards Track [Page 98] - -RFC 3720 iSCSI April 2004 - - - -N6: - -initiator: Session state timeout occurred, or a session - reinstatement cleared this session instance. This results - in the freeing of all associated resources and the session - state is discarded. - -target: Session state timeout occurred, or a session - reinstatement cleared this session instance. This results - in the freeing of all associated resources and the session - state is discarded. - - -N7: - -initiator: Illegal. - -target: A session continuation attempt is initiated. - - -N8: - -initiator: Illegal. - -target: The last session continuation attempt failed. - - -N9: - -initiator: Illegal. - -target: Login attempt on the leading connection failed. - - -N10: - -initiator: Illegal. - -target: A session continuation attempt succeeded. - - -N11: - -initiator: Illegal. - -target: A successful session reinstatement cleanly closed the - session. - -8. Security Considerations - - Historically, native storage systems have not had to consider - security because their environments offered minimal security risks. - That is, these environments consisted of storage devices either - directly attached to hosts or connected via a Storage Area Network - (SAN) distinctly separate from the communications network. The use - of storage protocols, such as SCSI, over IP-networks requires that - security concerns be addressed. iSCSI implementations MUST provide - means of protection against active attacks (e.g., pretending to be - another identity, message insertion, deletion, modification, and - replaying) and passive attacks (e.g., eavesdropping, gaining - advantage by analyzing the data sent over the line). - - - - - - - -Satran, et al. Standards Track [Page 99] - -RFC 3720 iSCSI April 2004 - - - Although technically possible, iSCSI SHOULD NOT be configured without - security. iSCSI configured without security should be confined, in - extreme cases, to closed environments without any security risk. - [RFC3723] specifies the mechanisms that must be used in order to - mitigate risks fully described in that document. - - The following section describes the security mechanisms provided by - an iSCSI implementation. - -8.1. iSCSI Security Mechanisms - - The entities involved in iSCSI security are the initiator, target, - and the IP communication end points. iSCSI scenarios in which - multiple initiators or targets share a single communication end point - are expected. To accommodate such scenarios, iSCSI uses two separate - security mechanisms: In-band authentication between the initiator and - the target at the iSCSI connection level (carried out by exchange of - iSCSI Login PDUs), and packet protection (integrity, authentication, - and confidentiality) by IPsec at the IP level. The two security - mechanisms complement each other. The in-band authentication - provides end-to-end trust (at login time) between the iSCSI initiator - and the target while IPsec provides a secure channel between the IP - communication end points. - - Further details on typical iSCSI scenarios and the relation between - the initiators, targets, and the communication end points can be - found in [RFC3723]. - -8.2. In-band Initiator-Target Authentication - - During login, the target MAY authenticate the initiator and the - initiator MAY authenticate the target. The authentication is - performed on every new iSCSI connection by an exchange of iSCSI Login - PDUs using a negotiated authentication method. - - The authentication method cannot assume an underlying IPsec - protection, because IPsec is optional to use. An attacker should - gain as little advantage as possible by inspecting the authentication - phase PDUs. Therefore, a method using clear text (or equivalent) - passwords is not acceptable; on the other hand, identity protection - is not strictly required. - - The authentication mechanism protects against an unauthorized login - to storage resources by using a false identity (spoofing). Once the - authentication phase is completed, if the underlying IPsec is not - used, all PDUs are sent and received in clear. The authentication - - - - - -Satran, et al. Standards Track [Page 100] - -RFC 3720 iSCSI April 2004 - - - mechanism alone (without underlying IPsec) should only be used when - there is no risk of eavesdropping, message insertion, deletion, - modification, and replaying. - - Section 11 iSCSI Security Text Keys and Authentication Methods - defines several authentication methods and the exact steps that must - be followed in each of them, including the iSCSI-text-keys and their - allowed values in each step. Whenever an iSCSI initiator gets a - response whose keys, or their values, are not according to the step - definition, it MUST abort the connection. Whenever an iSCSI target - gets a response whose keys, or their values, are not according to the - step definition, it MUST answer with a Login reject with the - "Initiator Error" or "Missing Parameter" status. These statuses are - not intended for cryptographically incorrect values such as the CHAP - response, for which "Authentication Failure" status MUST be - specified. The importance of this rule can be illustrated in CHAP - with target authentication (see Section 11.1.4 Challenge Handshake - Authentication Protocol (CHAP)) where the initiator would have been - able to conduct a reflection attack by omitting his response key - (CHAP_R) using the same CHAP challenge as the target and reflecting - the target's response back to the target. In CHAP, this is prevented - because the target must answer the missing CHAP_R key with a Login - reject with the "Missing Parameter" status. - - For some of the authentication methods, a key specifies the identity - of the iSCSI initiator or target for authentication purposes. The - value associated with that key MAY be different from the iSCSI name - and SHOULD be configurable. (CHAP_N, see Section 11.1.4 Challenge - Handshake Authentication Protocol (CHAP) and SRP_U, see Section - 11.1.3 Secure Remote Password (SRP)). - -8.2.1. CHAP Considerations - - Compliant iSCSI initiators and targets MUST implement the CHAP - authentication method [RFC1994] (according to Section 11.1.4 - Challenge Handshake Authentication Protocol (CHAP) including the - target authentication option). - - When CHAP is performed over a non-encrypted channel, it is vulnerable - to an off-line dictionary attack. Implementations MUST support use - of up to 128 bit random CHAP secrets, including the means to generate - such secrets and to accept them from an external generation source. - Implementations MUST NOT provide secret generation (or expansion) - means other than random generation. - - An administrative entity of an environment in which CHAP is used with - a secret that has less than 96 random bits MUST enforce IPsec - encryption (according to the implementation requirements in Section - - - -Satran, et al. Standards Track [Page 101] - -RFC 3720 iSCSI April 2004 - - - 8.3.2 Confidentiality) to protect the connection. Moreover, in this - case IKE authentication with group pre-shared cryptographic keys - SHOULD NOT be used unless it is not essential to protect group - members against off-line dictionary attacks by other members. - - CHAP secrets MUST be an integral number of bytes (octets). A - compliant implementation SHOULD NOT continue with the login step in - which it should send a CHAP response (CHAP_R, Section 11.1.4 - Challenge Handshake Authentication Protocol (CHAP)) unless it can - verify that the CHAP secret is at least 96 bits, or that IPsec - encryption is being used to protect the connection. - - Any CHAP secret used for initiator authentication MUST NOT be - configured for authentication of any target, and any CHAP secret used - for target authentication MUST NOT be configured for authentication - of any initiator. If the CHAP response received by one end of an - iSCSI connection is the same as the CHAP response that the receiving - endpoint would have generated for the same CHAP challenge, the - response MUST be treated as an authentication failure and cause the - connection to close (this ensures that the same CHAP secret is not - used for authentication in both directions). Also, if an iSCSI - implementation can function as both initiator and target, different - CHAP secrets and identities MUST be configured for these two roles. - The following is an example of the attacks prevented by the above - requirements: - - Rogue wants to impersonate Storage to Alice, and knows that a - single secret is used for both directions of Storage-Alice - authentication. - - Rogue convinces Alice to open two connections to Rogue, and Rogue - identifies itself as Storage on both connections. - - Rogue issues a CHAP challenge on connection 1, waits for Alice to - respond, and then reflects Alice's challenge as the initial - challenge to Alice on connection 2. - - If Alice doesn't check for the reflection across connections, - Alice's response on connection 2 enables Rogue to impersonate - Storage on connection 1, even though Rogue does not know the - Alice-Storage CHAP secret. - - Originators MUST NOT reuse the CHAP challenge sent by the Responder - for the other direction of a bidirectional authentication. - Responders MUST check for this condition and close the iSCSI TCP - connection if it occurs. - - - - - -Satran, et al. Standards Track [Page 102] - -RFC 3720 iSCSI April 2004 - - - The same CHAP secret SHOULD NOT be configured for authentication of - multiple initiators or multiple targets, as this enables any of them - to impersonate any other one of them, and compromising one of them - enables the attacker to impersonate any of them. It is recommended - that iSCSI implementations check for use of identical CHAP secrets by - different peers when this check is feasible, and take appropriate - measures to warn users and/or administrators when this is detected. - - When an iSCSI initiator or target authenticates itself to - counterparts in multiple administrative domains, it SHOULD use a - different CHAP secret for each administrative domain to avoid - propagating security compromises across domains. - - Within a single administrative domain: - - A single CHAP secret MAY be used for authentication of an initiator - to multiple targets. - - A single CHAP secret MAY be used for an authentication of a target - to multiple initiators when the initiators use an external server - (e.g., RADIUS) to verify the target's CHAP responses and do not know - the target's CHAP secret. - - If an external response verification server (e.g., RADIUS) is not - used, employing a single CHAP secret for authentication of a target - to multiple initiators requires that all such initiators know that - target secret. Any of these initiators can impersonate the target to - any other such initiator, and compromise of such an initiator enables - an attacker to impersonate the target to all such initiators. - Targets SHOULD use separate CHAP secrets for authentication to each - initiator when such risks are of concern; in this situation it may be - useful to configure a separate logical iSCSI target with its own - iSCSI Node Name for each initiator or group of initiators among which - such separation is desired. - -8.2.2. SRP Considerations - - The strength of the SRP authentication method (specified in - [RFC2945]) is dependent on the characteristics of the group being - used (i.e., the prime modulus N and generator g). As described in - [RFC2945], N is required to be a Sophie-German prime (of the form - N = 2q + 1, where q is also prime) and the generator g is a primitive - root of GF(n). In iSCSI authentication, the prime modulus N MUST be - at least 768 bits. - - The list of allowed SRP groups is provided in [RFC3723]. - - - - - - - -Satran, et al. Standards Track [Page 103] - -RFC 3720 iSCSI April 2004 - - -8.3. IPsec - - iSCSI uses the IPsec mechanism for packet protection (cryptographic - integrity, authentication, and confidentiality) at the IP level - between the iSCSI communicating end points. The following sections - describe the IPsec protocols that must be implemented for data - integrity and authentication, confidentiality, and cryptographic key - management. - - An iSCSI initiator or target may provide the required IPsec support - fully integrated or in conjunction with an IPsec front-end device. - In the latter case, the compliance requirements with regard to IPsec - support apply to the "combined device". Only the "combined device" - is to be considered an iSCSI device. - - Detailed considerations and recommendations for using IPsec for iSCSI - are provided in [RFC3723]. - -8.3.1. Data Integrity and Authentication - - Data authentication and integrity is provided by a cryptographic - keyed Message Authentication Code in every sent packet. This code - protects against message insertion, deletion, and modification. - Protection against message replay is realized by using a sequence - counter. - - An iSCSI compliant initiator or target MUST provide data integrity - and authentication by implementing IPsec [RFC2401] with ESP [RFC2406] - in tunnel mode and MAY provide data integrity and authentication by - implementing IPsec with ESP in transport mode. The IPsec - implementation MUST fulfill the following iSCSI specific - requirements: - - - HMAC-SHA1 MUST be implemented [RFC2404]. - - AES CBC MAC with XCBC extensions SHOULD be implemented - [RFC3566]. - - The ESP anti-replay service MUST also be implemented. - - At the high speeds iSCSI is expected to operate, a single IPsec SA - could rapidly cycle through the 32-bit IPsec sequence number space. - In view of this, it may be desirable in the future for an iSCSI - implementation that operates at speeds of 1 Gbps or greater to - implement the IPsec sequence number extension [SEQ-EXT]. - - - - - - - -Satran, et al. Standards Track [Page 104] - -RFC 3720 iSCSI April 2004 - - -8.3.2. Confidentiality - - Confidentiality is provided by encrypting the data in every packet. - When confidentiality is used it MUST be accompanied by data integrity - and authentication to provide comprehensive protection against - eavesdropping, message insertion, deletion, modification, and - replaying. - - An iSCSI compliant initiator or target MUST provide confidentiality - by implementing IPsec [RFC2401] with ESP [RFC2406] in tunnel mode and - MAY provide confidentiality by implementing IPsec with ESP in - transport mode, with the following iSCSI specific requirements: - - - 3DES in CBC mode MUST be implemented [RFC2451]. - - AES in Counter mode SHOULD be implemented [RFC3686]. - - DES in CBC mode SHOULD NOT be used due to its inherent weakness. The - NULL encryption algorithm MUST also be implemented. - -8.3.3. Policy, Security Associations, and Cryptographic Key Management - - A compliant iSCSI implementation MUST meet the cryptographic key - management requirements of the IPsec protocol suite. Authentication, - security association negotiation, and cryptographic key management - MUST be provided by implementing IKE [RFC2409] using the IPsec DOI - [RFC2407] with the following iSCSI specific requirements: - - - Peer authentication using a pre-shared cryptographic key MUST be - supported. Certificate-based peer authentication using digital - signatures MAY be supported. Peer authentication using the - public key encryption methods outlined in IKE sections 5.2 and - 5.3[7] SHOULD NOT be used. - - - When digital signatures are used to achieve authentication, an - IKE negotiator SHOULD use IKE Certificate Request Payload(s) to - specify the certificate authority. IKE negotiators SHOULD check - the pertinent Certificate Revocation List (CRL) before accepting - a PKI certificate for use in IKE authentication procedures. - - - Conformant iSCSI implementations MUST support IKE Main Mode and - SHOULD support Aggressive Mode. IKE main mode with pre-shared - key authentication method SHOULD NOT be used when either the - initiator or the target uses dynamically assigned IP addresses. - While in many cases pre-shared keys offer good security, - situations in which dynamically assigned addresses are used force - the use of a group pre-shared key, which creates vulnerability to - a man-in-the-middle attack. - - - - -Satran, et al. Standards Track [Page 105] - -RFC 3720 iSCSI April 2004 - - - - In the IKE Phase 2 Quick Mode, exchanges for creating the Phase 2 - SA, the Identity Payload, fields MUST be present. ID_IPV4_ADDR, - ID_IPV6_ADDR (if the protocol stack supports IPv6) and ID_FQDN - Identity payloads MUST be supported; ID_USER_FQDN SHOULD be - supported. The IP Subnet, IP Address Range, ID_DER_ASN1_DN, and - ID_DER_ASN1_GN formats SHOULD NOT be used. The ID_KEY_ID - Identity Payload MUST NOT be used. - - Manual cryptographic keying MUST NOT be used because it does not - provide the necessary re-keying support. - - When IPsec is used, the receipt of an IKE Phase 2 delete message - SHOULD NOT be interpreted as a reason for tearing down the iSCSI TCP - connection. If additional traffic is sent on it, a new IKE Phase 2 - SA will be created to protect it. - - The method used by the initiator to determine whether the target - should be connected using IPsec is regarded as an issue of IPsec - policy administration, and thus not defined in the iSCSI standard. - - If an iSCSI target is discovered via a SendTargets request in a - discovery session not using IPsec, the initiator should assume that - it does not need IPsec to establish a session to that target. If an - iSCSI target is discovered using a discovery session that does use - IPsec, the initiator SHOULD use IPsec when establishing a session to - that target. - -9. Notes to Implementers - - This section notes some of the performance and reliability - considerations of the iSCSI protocol. This protocol was designed to - allow efficient silicon and software implementations. The iSCSI task - tag mechanism was designed to enable Direct Data Placement (DDP - a - DMA form) at the iSCSI level or lower. - - The guiding assumption made throughout the design of this protocol is - that targets are resource constrained relative to initiators. - - Implementers are also advised to consider the implementation - consequences of the iSCSI to SCSI mapping model as outlined in - Section 3.4.3 Consequences of the Model. - -9.1. Multiple Network Adapters - - The iSCSI protocol allows multiple connections, not all of which need - to go over the same network adapter. If multiple network connections - are to be utilized with hardware support, the iSCSI protocol - - - - -Satran, et al. Standards Track [Page 106] - -RFC 3720 iSCSI April 2004 - - - command-data-status allegiance to one TCP connection ensures that - there is no need to replicate information across network adapters or - otherwise require them to cooperate. - - However, some task management commands may require some loose form of - cooperation or replication at least on the target. - -9.1.1. Conservative Reuse of ISIDs - - Historically, the SCSI model (and implementations and applications - based on that model) has assumed that SCSI ports are static, physical - entities. Recent extensions to the SCSI model have taken advantage - of persistent worldwide unique names for these ports. In iSCSI - however, the SCSI initiator ports are the endpoints of dynamically - created sessions, so the presumptions of "static and physical" do not - apply. In any case, the model clauses (particularly, Section 3.4.2 - SCSI Architecture Model) provide for persistent, reusable names for - the iSCSI-type SCSI initiator ports even though there does not need - to be any physical entity bound to these names. - - To both minimize the disruption of legacy applications and to better - facilitate the SCSI features that rely on persistent names for SCSI - ports, iSCSI implementations SHOULD attempt to provide a stable - presentation of SCSI Initiator Ports (both to the upper OS-layers and - to the targets to which they connect). This can be achieved in an - initiator implementation by conservatively reusing ISIDs. In other - words, the same ISID should be used in the Login process to multiple - target portal groups (of the same iSCSI Target or different iSCSI - Targets). The ISID RULE (Section 3.4.3 Consequences of the Model) - only prohibits reuse to the same target portal group. It does not - "preclude" reuse to other target portal groups. The principle of - conservative reuse "encourages" reuse to other target portal groups. - When a SCSI target device sees the same (InitiatorName, ISID) pair in - different sessions to different target portal groups, it can identify - the underlying SCSI Initiator Port on each session as the same SCSI - port. In effect, it can recognize multiple paths from the same - source. - -9.1.2. iSCSI Name, ISID, and TPGT Use - - The designers of the iSCSI protocol envisioned there being one iSCSI - Initiator Node Name per operating system image on a machine. This - enables SAN resource configuration and authentication schemes based - on a system's identity. It supports the notion that it should be - possible to assign access to storage resources based on "initiator - device" identity. - - - - - -Satran, et al. Standards Track [Page 107] - -RFC 3720 iSCSI April 2004 - - - When there are multiple hardware or software components coordinated - as a single iSCSI Node, there must be some (logical) entity that - represents the iSCSI Node that makes the iSCSI Node Name available to - all components involved in session creation and login. Similarly, - this entity that represents the iSCSI Node must be able to coordinate - session identifier resources (ISID for initiators) to enforce both - the ISID and TSIH RULES (see Section 3.4.3 Consequences of the - Model). - - For targets, because of the closed environment, implementation of - this entity should be straightforward. However, vendors of iSCSI - hardware (e.g., NICs or HBAs) intended for targets, SHOULD provide - mechanisms for configuration of the iSCSI Node Name across the portal - groups instantiated by multiple instances of these components within - a target. - - However, complex targets making use of multiple Target Portal Group - Tags may reconfigure them to achieve various quality goals. The - initiators have two mechanisms at their disposal to discover and/or - check reconfiguring targets - the discovery session type and a key - returned by the target during login to confirm the TPGT. An - initiator should attempt to "rediscover" the target configuration - anytime a session is terminated unexpectedly. - - For initiators, in the long term, it is expected that operating - system vendors will take on the role of this entity and provide - standard APIs that can inform components of their iSCSI Node Name and - can configure and/or coordinate ISID allocation, use, and reuse. - - Recognizing that such initiator APIs are not available today, other - implementations of the role of this entity are possible. For - example, a human may instantiate the (common) Node name as part of - the installation process of each iSCSI component involved in session - creation and login. This may be done either by pointing the - component to a vendor-specific location for this datum or to a - system-wide location. The structure of the ISID namespace (see - Section 10.12.5 ISID and [RFC3721]) facilitates implementation of the - ISID coordination by allowing each component vendor to independently - (of other vendor's components) coordinate allocation, use, and reuse - of its own partition of the ISID namespace in a vendor-specific - manner. Partitioning of the ISID namespace within initiator portal - groups managed by that vendor allows each such initiator portal group - to act independently of all other portal groups when selecting an - ISID for a login; this facilitates enforcement of the ISID RULE (see - Section 3.4.3 Consequences of the Model) at the initiator. - - - - - - -Satran, et al. Standards Track [Page 108] - -RFC 3720 iSCSI April 2004 - - - A vendor of iSCSI hardware (e.g., NICs or HBAs) intended for use in - initiators MUST implement a mechanism for configuring the iSCSI Node - Name. Vendors, and administrators must ensure that iSCSI Node Names - are unique worldwide. It is therefore important that when one - chooses to reuse the iSCSI Node Name of a disabled unit, not to - re-assign that name to the original unit unless its worldwide - uniqueness can be ascertained again. - - In addition, a vendor of iSCSI hardware must implement a mechanism to - configure and/or coordinate ISIDs for all sessions managed by - multiple instances of that hardware within a given iSCSI Node. Such - configuration might be either permanently pre-assigned at the factory - (in a necessarily globally unique way), statically assigned (e.g., - partitioned across all the NICs at initialization in a locally unique - way), or dynamically assigned (e.g., on-line allocator, also in a - locally unique way). In the latter two cases, the configuration may - be via public APIs (perhaps driven by an independent vendor's - software, such as the OS vendor) or via private APIs driven by the - vendor's own software. - -9.2. Autosense and Auto Contingent Allegiance (ACA) - - Autosense refers to the automatic return of sense data to the - initiator in case a command did not complete successfully. iSCSI - initiators and targets MUST support and use autosense. - - ACA helps preserve ordered command execution in the presence of - errors. As iSCSI can have many commands in-flight between initiator - and target, iSCSI initiators and targets SHOULD support ACA. - -9.3. iSCSI Timeouts - - iSCSI recovery actions are often dependent on iSCSI time-outs being - recognized and acted upon before SCSI time-outs. Determining the - right time-outs to use for various iSCSI actions (command - acknowledgements expected, status acknowledgements, etc.) is very - much dependent on infrastructure (hardware, links, TCP/IP stack, - iSCSI driver). As a guide, the implementer may use an average - Nop-Out/Nop-In turnaround delay multiplied by a "safety factor" - (e.g., 4) as a good estimate for the basic delay of the iSCSI stack - for a given connection. The safety factor should account for the - network load variability. For connection teardown the implementer - may want to consider also the TCP common practice for the given - infrastructure. - - - - - - - -Satran, et al. Standards Track [Page 109] - -RFC 3720 iSCSI April 2004 - - - Text negotiations MAY also be subject to either time-limits or limits - in the number of exchanges. Those SHOULD be generous enough to avoid - affecting interoperability (e.g., allowing each key to be negotiated - on a separate exchange). - - The relation between iSCSI timeouts and SCSI timeouts should also be - considered. SCSI timeouts should be longer than iSCSI timeouts plus - the time required for iSCSI recovery whenever iSCSI recovery is - planned. Alternatively, an implementer may choose to interlock iSCSI - timeouts and recovery with SCSI timeouts so that SCSI recovery will - become active only where iSCSI is not planned to, or failed to, - recover. - - The implementer may also want to consider the interaction between - various iSCSI exception events - such as a digest failure - and - subsequent timeouts. When iSCSI error recovery is active, a digest - failure is likely to result in discovering a missing command or data - PDU. In these cases, an implementer may want to lower the timeout - values to enable faster initiation for recovery procedures. - -9.4. Command Retry and Cleaning Old Command Instances - - To avoid having old, retried command instances appear in a valid - command window after a command sequence number wrap around, the - protocol requires (see Section 3.2.2.1 Command Numbering and - Acknowledging) that on every connection on which a retry has been - issued, a non-immediate command be issued and acknowledged within a - 2**31-1 commands interval from the CmdSN of the retried command. - This requirement can be fulfilled by an implementation in several - ways. - - The simplest technique to use is to send a (non-retry) non-immediate - SCSI command (or a NOP if no SCSI command is available for a while) - after every command retry on the connection on which the retry was - attempted. As errors are deemed rare events, this technique is - probably the most effective, as it does not involve additional checks - at the initiator when issuing commands. - -9.5. Synch and Steering Layer and Performance - - While a synch and steering layer is optional, an initiator/target - that does not have it working against a target/initiator that demands - synch and steering may experience performance degradation caused by - packet reordering and loss. Providing a synch and steering mechanism - is recommended for all high-speed implementations. - - - - - - -Satran, et al. Standards Track [Page 110] - -RFC 3720 iSCSI April 2004 - - -9.6. Considerations for State-dependent Devices and Long-lasting SCSI - Operations - - Sequential access devices operate on the principle that the position - of the device is based on the last command processed. As such, - command processing order and knowledge of whether or not the previous - command was processed is of the utmost importance to maintain data - integrity. For example, inadvertent retries of SCSI commands when it - is not known if the previous SCSI command was processed is a - potential data integrity risk. - - For a sequential access device, consider the scenario in which a SCSI - SPACE command to backspace one filemark is issued and then re-issued - due to no status received for the command. If the first SPACE - command was actually processed, the re-issued SPACE command, if - processed, will cause the position to change. Thus, a subsequent - write operation will write data to the wrong position and any - previous data at that position will be overwritten. - - For a medium changer device, consider the scenario in which an - EXCHANGE MEDIUM command (the SOURCE ADDRESS and DESTINATION ADDRESS - are the same thus performing a swap) is issued and then re-issued due - to no status received for the command. If the first EXCHANGE MEDIUM - command was actually processed, the re-issued EXCHANGE MEDIUM - command, if processed, will perform the swap again. The net effect - is that a swap was not performed thus leaving a data integrity - exposure. - - All commands that change the state of the device (as in SPACE - commands for sequential access devices, and EXCHANGE MEDIUM for - medium changer device), MUST be issued as non-immediate commands for - deterministic and in order delivery to iSCSI targets. - - For many of those state changing commands, the execution model also - assumes that the command is executed exactly once. Devices - implementing READ POSITION and LOCATE provide a means for SCSI level - command recovery and new tape-class devices should support those - commands. In their absence a retry at SCSI level is difficult and - error recovery at iSCSI level is advisable. - - Devices operating on long latency delivery subsystems and performing - long lasting SCSI operations may need mechanisms that enable - connection replacement while commands are running (e.g., during an - extended copy operation). - - - - - - - -Satran, et al. Standards Track [Page 111] - -RFC 3720 iSCSI April 2004 - - -9.6.1. Determining the Proper ErrorRecoveryLevel - - The implementation and use of a specific ErrorRecoveryLevel should be - determined based on the deployment scenarios of a given iSCSI - implementation. Generally, the following factors must be considered - before deciding on the proper level of recovery: - - a) Application resilience to I/O failures. - b) Required level of availability in the face of transport - connection failures. - c) Probability of transport layer "checksum escape". This in - turn decides the iSCSI digest failure frequency, and thus the - criticality of iSCSI-level error recovery. The details of - estimating this probability are outside the scope of this - document. - - - A consideration of the above factors for SCSI tape devices as an - example suggests that implementations SHOULD use ErrorRecoveryLevel=1 - when transport connection failure is not a concern and SCSI level - recovery is unavailable, and ErrorRecoveryLevel=2 when the connection - failure is also of high likelihood during a backup/retrieval. - - For extended copy operations, implementations SHOULD use - ErrorRecoveryLevel=2 whenever there is a relatively high likelihood - of connection failure. - -10. iSCSI PDU Formats - - All multi-byte integers that are specified in formats defined in this - document are to be represented in network byte order (i.e., big - endian). Any field that appears in this document assumes that the - most significant byte is the lowest numbered byte and the most - significant bit (within byte or field) is the lowest numbered bit - unless specified otherwise. - - Any compliant sender MUST set all bits not defined and all reserved - fields to zero unless specified otherwise. Any compliant receiver - MUST ignore any bit not defined and all reserved fields unless - specified otherwise. Receipt of reserved code values in defined - fields MUST be reported as a protocol error. - - Reserved fields are marked by the word "reserved", some abbreviation - of "reserved", or by "." for individual bits when no other form of - marking is technically feasible. - - - - - - -Satran, et al. Standards Track [Page 112] - -RFC 3720 iSCSI April 2004 - - -10.1. iSCSI PDU Length and Padding - - iSCSI PDUs are padded to the closest integer number of four byte - words. The padding bytes SHOULD be sent as 0. - -10.2. PDU Template, Header, and Opcodes - - All iSCSI PDUs have one or more header segments and, optionally, a - data segment. After the entire header segment group a header-digest - MAY follow. The data segment MAY also be followed by a data-digest. - - The Basic Header Segment (BHS) is the first segment in all of the - iSCSI PDUs. The BHS is a fixed-length 48-byte header segment. It - MAY be followed by Additional Header Segments (AHS), a Header-Digest, - a Data Segment, and/or a Data-Digest. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 113] - -RFC 3720 iSCSI April 2004 - - - The overall structure of an iSCSI PDU is as follows: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0/ Basic Header Segment (BHS) / - +/ / - +---------------+---------------+---------------+---------------+ - 48/ Additional Header Segment 1 (AHS) (optional) / - +/ / - +---------------+---------------+---------------+---------------+ - / Additional Header Segment 2 (AHS) (optional) / - +/ / - +---------------+---------------+---------------+---------------+ - ---- - +---------------+---------------+---------------+---------------+ - / Additional Header Segment n (AHS) (optional) / - +/ / - +---------------+---------------+---------------+---------------+ - ---- - +---------------+---------------+---------------+---------------+ - k/ Header-Digest (optional) / - +/ / - +---------------+---------------+---------------+---------------+ - l/ Data Segment(optional) / - +/ / - +---------------+---------------+---------------+---------------+ - m/ Data-Digest (optional) / - +/ / - +---------------+---------------+---------------+---------------+ - - All PDU segments and digests are padded to the closest integer number - of four byte words. For example, all PDU segments and digests start - at a four byte word boundary and the padding ranges from 0 to 3 - bytes. The padding bytes SHOULD be sent as 0. - - iSCSI response PDUs do not have AH Segments. - -10.2.1. Basic Header Segment (BHS) - - The BHS is 48 bytes long. The Opcode and DataSegmentLength fields - appear in all iSCSI PDUs. In addition, when used, the Initiator Task - Tag and Logical Unit Number always appear in the same location in the - header. - - - - - - -Satran, et al. Standards Track [Page 114] - -RFC 3720 iSCSI April 2004 - - - The format of the BHS is: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|I| Opcode |F| Opcode-specific fields | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| LUN or Opcode-specific fields | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20/ Opcode-specific fields / - +/ / - +---------------+---------------+---------------+---------------+ - 48 - -10.2.1.1 I - - For request PDUs, the I bit set to 1 is an immediate delivery marker. - -10.2.1.2. Opcode - - The Opcode indicates the type of iSCSI PDU the header encapsulates. - - The Opcodes are divided into two categories: initiator opcodes and - target opcodes. Initiator opcodes are in PDUs sent by the initiator - (request PDUs). Target opcodes are in PDUs sent by the target - (response PDUs). - - Initiators MUST NOT use target opcodes and targets MUST NOT use - initiator opcodes. - - Initiator opcodes defined in this specification are: - - 0x00 NOP-Out - 0x01 SCSI Command (encapsulates a SCSI Command Descriptor Block) - 0x02 SCSI Task Management function request - 0x03 Login Request - 0x04 Text Request - 0x05 SCSI Data-Out (for WRITE operations) - 0x06 Logout Request - 0x10 SNACK Request - 0x1c-0x1e Vendor specific codes - - - -Satran, et al. Standards Track [Page 115] - -RFC 3720 iSCSI April 2004 - - - - Target opcodes are: - - 0x20 NOP-In - 0x21 SCSI Response - contains SCSI status and possibly sense - information or other response information. - 0x22 SCSI Task Management function response - 0x23 Login Response - 0x24 Text Response - 0x25 SCSI Data-In - for READ operations. - 0x26 Logout Response - 0x31 Ready To Transfer (R2T) - sent by target when it is ready - to receive data. - 0x32 Asynchronous Message - sent by target to indicate certain - special conditions. - 0x3c-0x3e Vendor specific codes - 0x3f Reject - - All other opcodes are reserved. - -10.2.1.3. Final (F) bit - - When set to 1 it indicates the final (or only) PDU of a sequence. - -10.2.1.4. Opcode-specific Fields - - These fields have different meanings for different opcode types. - -10.2.1.5. TotalAHSLength - - Total length of all AHS header segments in units of four byte words - including padding, if any. - - The TotalAHSLength is only used in PDUs that have an AHS and MUST be - 0 in all other PDUs. - -10.2.1.6. DataSegmentLength - - This is the data segment payload length in bytes (excluding padding). - The DataSegmentLength MUST be 0 whenever the PDU has no data segment. - -10.2.1.7. LUN - - Some opcodes operate on a specific Logical Unit. The Logical Unit - Number (LUN) field identifies which Logical Unit. If the opcode does - not relate to a Logical Unit, this field is either ignored or may be - used in an opcode specific way. The LUN field is 64-bits and should - - - - -Satran, et al. Standards Track [Page 116] - -RFC 3720 iSCSI April 2004 - - - be formatted in accordance with [SAM2]. For example, LUN[0] from - [SAM2] is BHS byte 8 and so on up to LUN[7] from [SAM2], which is BHS - byte 15. - -10.2.1.8. Initiator Task Tag - - The initiator assigns a Task Tag to each iSCSI task it issues. While - a task exists, this tag MUST uniquely identify the task session-wide. - SCSI may also use the initiator task tag as part of the SCSI task - identifier when the timespan during which an iSCSI initiator task tag - must be unique extends over the timespan during which a SCSI task tag - must be unique. However, the iSCSI Initiator Task Tag must exist and - be unique even for untagged SCSI commands. - -10.2.2. Additional Header Segment (AHS) - - The general format of an AHS is: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0| AHSLength | AHSType | AHS-Specific | - +---------------+---------------+---------------+---------------+ - 4/ AHS-Specific / - +/ / - +---------------+---------------+---------------+---------------+ - x - -10.2.2.1. AHSType - - The AHSType field is coded as follows: - - bit 0-1 - Reserved - - bit 2-7 - AHS code - - 0 - Reserved - 1 - Extended CDB - 2 - Expected Bidirectional Read Data Length - 3 - 63 Reserved - -10.2.2.2. AHSLength - - This field contains the effective length in bytes of the AHS - excluding AHSType and AHSLength and padding, if any. The AHS is - padded to the smallest integer number of 4 byte words (i.e., from 0 - up to 3 padding bytes). - - - -Satran, et al. Standards Track [Page 117] - -RFC 3720 iSCSI April 2004 - - -10.2.2.3. Extended CDB AHS - - The format of the Extended CDB AHS is: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0| AHSLength (CDBLength-15) | 0x01 | Reserved | - +---------------+---------------+---------------+---------------+ - 4/ ExtendedCDB...+padding / - +/ / - +---------------+---------------+---------------+---------------+ - x - - This type of AHS MUST NOT be used if the CDBLength is less than 17. - The length includes the reserved byte 3. - -10.2.2.4. Bidirectional Expected Read-Data Length AHS - - The format of the Bidirectional Read Expected Data Transfer Length - AHS is: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0| AHSLength (0x0005) | 0x02 | Reserved | - +---------------+---------------+---------------+---------------+ - 4| Expected Read-Data Length | - +---------------+---------------+---------------+---------------+ - 8 - -10.2.3. Header Digest and Data Digest - - Optional header and data digests protect the integrity of the header - and data, respectively. The digests, if present, are located, - respectively, after the header and PDU-specific data, and cover - respectively the header and the PDU data, each including the padding - bytes, if any. - - The existence and type of digests are negotiated during the Login - Phase. - - The separation of the header and data digests is useful in iSCSI - routing applications, in which only the header changes when a message - is forwarded. In this case, only the header digest should be - recalculated. - - - -Satran, et al. Standards Track [Page 118] - -RFC 3720 iSCSI April 2004 - - - Digests are not included in data or header length fields. - - A zero-length Data Segment also implies a zero-length data-digest. - -10.2.4. Data Segment - - The (optional) Data Segment contains PDU associated data. Its - payload effective length is provided in the BHS field - - DataSegmentLength. The Data Segment is also padded to an integer - number of 4 byte words. - -10.3. SCSI Command - - The format of the SCSI Command PDU is: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|I| 0x01 |F|R|W|. .|ATTR | Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| Logical Unit Number (LUN) | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| Expected Data Transfer Length | - +---------------+---------------+---------------+---------------+ - 24| CmdSN | - +---------------+---------------+---------------+---------------+ - 28| ExpStatSN | - +---------------+---------------+---------------+---------------+ - 32/ SCSI Command Descriptor Block (CDB) / - +/ / - +---------------+---------------+---------------+---------------+ - 48/ AHS (Optional) / - +---------------+---------------+---------------+---------------+ - x/ Header Digest (Optional) / - +---------------+---------------+---------------+---------------+ - y/ (DataSegment, Command Data) (Optional) / - +/ / - +---------------+---------------+---------------+---------------+ - z/ Data Digest (Optional) / - +---------------+---------------+---------------+---------------+ - - - - -Satran, et al. Standards Track [Page 119] - -RFC 3720 iSCSI April 2004 - - -10.3.1. Flags and Task Attributes (byte 1) - - The flags for a SCSI Command are: - - bit 0 (F) is set to 1 when no unsolicited SCSI Data-Out PDUs follow - this PDU. When F=1 for a write and if Expected Data - Transfer Length is larger than the DataSegmentLength, the - target may solicit additional data through R2T. - - bit 1 (R) is set to 1 when the command is expected to input data. - - bit 2 (W) is set to 1 when the command is expected to output data. - - bit 3-4 Reserved. - - bit 5-7 contains Task Attributes. - - Task Attributes (ATTR) have one of the following integer values (see - [SAM2] for details): - - 0 - Untagged - 1 - Simple - 2 - Ordered - 3 - Head of Queue - 4 - ACA - 5-7 - Reserved - - Setting both the W and the F bit to 0 is an error. Either or both of - R and W MAY be 1 when either the Expected Data Transfer Length and/or - Bidirectional Read Expected Data Transfer Length are 0, but they MUST - NOT both be 0 when the Expected Data Transfer Length and/or - Bidirectional Read Expected Data Transfer Length are not 0 (i.e., - when some data transfer is expected the transfer direction is - indicated by the R and/or W bit). - -10.3.2. CmdSN - Command Sequence Number - - Enables ordered delivery across multiple connections in a single - session. - -10.3.3. ExpStatSN - - Command responses up to ExpStatSN-1 (mod 2**32) have been received - (acknowledges status) on the connection. - - - - - - - -Satran, et al. Standards Track [Page 120] - -RFC 3720 iSCSI April 2004 - - -10.3.4. Expected Data Transfer Length - - For unidirectional operations, the Expected Data Transfer Length - field contains the number of bytes of data involved in this SCSI - operation. For a unidirectional write operation (W flag set to 1 and - R flag set to 0), the initiator uses this field to specify the number - of bytes of data it expects to transfer for this operation. For a - 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 SAM2 byte count. - - 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 - MUST be present in the header sequence that indicates the - Bidirectional Read Expected Data Transfer Length. The Expected Data - Transfer Length field and the Bidirectional Read Expected Data - Transfer Length field correspond to the SAM2 byte count - - 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. - - 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 - of unsolicited data OR ONLY the immediate data, if any. - - Upon completion of a data transfer, the target informs the initiator - (through residual counts) of how many bytes were actually processed - (sent and/or received) by the target. - -10.3.5. CDB - SCSI Command Descriptor Block - - There are 16 bytes in the CDB field to accommodate the commonly used - CDBs. Whenever the CDB is larger than 16 bytes, an Extended CDB AHS - MUST be used to contain the CDB spillover. - -10.3.6. Data Segment - Command Data - - Some SCSI commands require additional parameter data to accompany the - SCSI command. This data may be placed beyond the boundary of the - iSCSI header in a data segment. Alternatively, user data (e.g., from - a WRITE operation) can be placed in the data segment (both cases are - - - - - -Satran, et al. Standards Track [Page 121] - -RFC 3720 iSCSI April 2004 - - - referred to as immediate data). These data are governed by the rules - for solicited vs. unsolicited data outlined in Section 3.2.4.2 Data - Transfer Overview. - -10.4. SCSI Response - - The format of the SCSI Response PDU is: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x21 |1|. .|o|u|O|U|.| Response | Status | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| Reserved | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| SNACK Tag or Reserved | - +---------------+---------------+---------------+---------------+ - 24| StatSN | - +---------------+---------------+---------------+---------------+ - 28| ExpCmdSN | - +---------------+---------------+---------------+---------------+ - 32| MaxCmdSN | - +---------------+---------------+---------------+---------------+ - 36| ExpDataSN or Reserved | - +---------------+---------------+---------------+---------------+ - 40| Bidirectional Read Residual Count or Reserved | - +---------------+---------------+---------------+---------------+ - 44| Residual Count or Reserved | - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - / Data Segment (Optional) / - +/ / - +---------------+---------------+---------------+---------------+ - | Data-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - - - - - - - -Satran, et al. Standards Track [Page 122] - -RFC 3720 iSCSI April 2004 - - -10.4.1. Flags (byte 1) - - bit 1-2 Reserved. - - bit 3 - (o) set for Bidirectional Read Residual Overflow. In this - case, the Bidirectional Read Residual Count indicates the number - of bytes that were not transferred to the initiator because the - initiator's Expected Bidirectional Read Data Transfer Length was - not sufficient. - - bit 4 - (u) set for Bidirectional Read Residual Underflow. In this - case, the Bidirectional Read Residual Count indicates the number - of bytes that were not transferred to the initiator out of the - number of bytes expected to be transferred. - - bit 5 - (O) set for Residual Overflow. In this case, the Residual - Count indicates the number of bytes that were not transferred - because the initiator's Expected Data Transfer Length was not - sufficient. For a bidirectional operation, the Residual Count - contains the residual for the write operation. - - bit 6 - (U) set for Residual Underflow. In this case, the Residual - Count indicates the number of bytes that were not transferred out - of the number of bytes that were expected to be transferred. For - a bidirectional operation, the Residual Count contains the - residual for the write operation. - - bit 7 - (0) Reserved. - - Bits O and U and bits o and u are mutually exclusive (i.e., having - both o and u or O and U set to 1 is a protocol error). For a - response other than "Command Completed at Target", bits 3-6 MUST be - 0. - -10.4.2. Status - - The Status field is used to report the SCSI status of the command (as - specified in [SAM2]) and is only valid if the Response Code is - Command Completed at target. - - - - - - - - - - - - -Satran, et al. Standards Track [Page 123] - -RFC 3720 iSCSI April 2004 - - - Some of the status codes defined in [SAM2] are: - - 0x00 GOOD - 0x02 CHECK CONDITION - 0x08 BUSY - 0x18 RESERVATION CONFLICT - 0x28 TASK SET FULL - 0x30 ACA ACTIVE - 0x40 TASK ABORTED - - See [SAM2] for the complete list and definitions. - - If a SCSI device error is detected while data from the initiator is - still expected (the command PDU did not contain all the data and the - target has not received a Data PDU with the final bit Set), the - target MUST wait until it receives a Data PDU with the F bit set in - the last expected sequence before sending the Response PDU. - -10.4.3. Response - - This field contains the iSCSI service response. - - iSCSI service response codes defined in this specification are: - - 0x00 - Command Completed at Target - 0x01 - Target Failure - 0x80-0xff - Vendor specific - - All other response codes are reserved. - - The Response is used to report a Service Response. 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 value 0x00 maps to the SCSI service response (see [SAM2] and - [SPC3]) of TASK COMPLETE or LINKED COMMAND COMPLETE. All other - Response values map to the SCSI service response of SERVICE DELIVERY - OR TARGET FAILURE. - - If a PDU that includes SCSI status (Response PDU or Data-In PDU - including status) does not arrive before the session is terminated, - the SCSI service response is SERVICE DELIVERY OR TARGET FAILURE. - - A non-zero Response field indicates a failure to execute the command - in which case the Status and Flag fields are undefined. - - - - - - - -Satran, et al. Standards Track [Page 124] - -RFC 3720 iSCSI April 2004 - - -10.4.4. SNACK Tag - - 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. - - After issuing a R-Data SNACK the initiator must discard any SCSI - status unless contained in an SCSI Response PDU carrying the same - SNACK Tag as the last issued R-Data SNACK for the SCSI command on the - current connection. - - For a detailed discussion on R-Data SNACK see Section 10.16 SNACK - Request. - -10.4.5. Residual Count - - The Residual Count field MUST be valid in the case where either the U - bit or the O bit is set. If neither bit is set, the Residual Count - field is reserved. Targets may set the residual count and initiators - may use it when the response code is "completed at target" (even if - the status returned is not GOOD). If the O bit is set, the Residual - Count indicates the number of bytes that were not transferred because - the initiator's Expected Data Transfer Length was not sufficient. If - the U bit is set, the Residual Count indicates the number of bytes - that were not transferred out of the number of bytes expected to be - transferred. - -10.4.6. Bidirectional Read Residual Count - - The Bidirectional Read Residual Count field MUST be valid in the case - where either the u bit or the o bit is set. If neither bit is set, - the Bidirectional Read Residual Count field is reserved. Targets may - set the Bidirectional Read Residual Count and initiators may use it - when the response code is "completed at target". If the o bit is - set, the Bidirectional Read Residual Count indicates the number of - bytes that were not transferred to the initiator because the - initiator's Expected Bidirectional Read Transfer Length was not - sufficient. If the u bit is set, the Bidirectional Read Residual - Count indicates the number of bytes that were not transferred to the - initiator out of the number of bytes expected to be transferred. - -10.4.7. Data Segment - Sense and Response Data Segment - - iSCSI targets MUST support and enable autosense. If Status is CHECK - CONDITION (0x02), then the Data Segment MUST contain sense data for - the failed command. - - - - -Satran, et al. Standards Track [Page 125] - -RFC 3720 iSCSI April 2004 - - - For some iSCSI responses, the response data segment MAY contain some - response related information, (e.g., for a target failure, it may - contain a vendor specific detailed description of the failure). - - If the DataSegmentLength is not 0, the format of the Data Segment is - as follows: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|SenseLength | Sense Data | - +---------------+---------------+---------------+---------------+ - x/ Sense Data / - +---------------+---------------+---------------+---------------+ - y/ Response Data / - / / - +---------------+---------------+---------------+---------------+ - z| - -10.4.7.1. SenseLength - - Length of Sense Data. - -10.4.7.2. Sense Data - - The Sense Data contains detailed information about a check condition - and [SPC3] specifies the format and content of the Sense Data. - - Certain iSCSI conditions result in the command being terminated at - the target (response Command Completed at Target) with a SCSI Check - Condition Status as outlined in the next table: - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 126] - -RFC 3720 iSCSI April 2004 - - - +--------------------------+----------+---------------------------+ - | iSCSI Condition |Sense | Additional Sense Code & | - | |Key | Qualifier | - +--------------------------+----------+---------------------------+ - | Unexpected unsolicited |Aborted | ASC = 0x0c ASCQ = 0x0c | - | data |Command-0B| Write Error | - +--------------------------+----------+---------------------------+ - | Incorrect amount of data |Aborted | ASC = 0x0c ASCQ = 0x0d | - | |Command-0B| Write Error | - +--------------------------+----------+---------------------------+ - | Protocol Service CRC |Aborted | ASC = 0x47 ASCQ = 0x05 | - | error |Command-0B| CRC Error Detected | - +--------------------------+----------+---------------------------+ - | SNACK rejected |Aborted | ASC = 0x11 ASCQ = 0x13 | - | |Command-0B| Read Error | - +--------------------------+----------+---------------------------+ - - The target reports the "Incorrect amount of data" condition if during - data output the total data length to output is greater than - FirstBurstLength and the initiator sent unsolicited non-immediate - data but the total amount of unsolicited data is different than - FirstBurstLength. The target reports the same error when the amount - of data sent as a reply to an R2T does not match the amount - requested. - -10.4.8. ExpDataSN - - The number of R2T and Data-In (read) PDUs the target has sent for the - command. - - 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. - -10.4.9. StatSN - Status Sequence Number - - StatSN is a Sequence Number that the target iSCSI layer generates per - connection and that in turn, enables the initiator to acknowledge - status reception. StatSN is incremented by 1 for every - response/status sent on a connection except for responses sent as a - result of a retry or SNACK. In the case of responses sent due to a - retransmission request, the StatSN MUST be the same as the first time - the PDU was sent unless the connection has since been restarted. - - - - - - - - - -Satran, et al. Standards Track [Page 127] - -RFC 3720 iSCSI April 2004 - - -10.4.10. ExpCmdSN - Next Expected CmdSN from this Initiator - - ExpCmdSN is a Sequence Number that the target iSCSI returns to the - initiator to acknowledge command reception. It is used to update a - local variable with the same name. An ExpCmdSN equal to MaxCmdSN+1 - indicates that the target cannot accept new commands. - -10.4.11. MaxCmdSN - Maximum CmdSN from this Initiator - - MaxCmdSN is a Sequence Number that the target iSCSI returns to the - initiator to indicate the maximum CmdSN the initiator can send. It - is used to update a local variable with the same name. If MaxCmdSN - is equal to ExpCmdSN-1, this indicates to the initiator that the - target cannot receive any additional commands. When MaxCmdSN changes - at the target while the target has no pending PDUs to convey this - information to the initiator, it MUST generate a NOP-IN to carry the - new MaxCmdSN. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 128] - -RFC 3720 iSCSI April 2004 - - -10.5. Task Management Function Request - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|I| 0x02 |1| Function | Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| Logical Unit Number (LUN) or Reserved | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| Referenced Task Tag or 0xffffffff | - +---------------+---------------+---------------+---------------+ - 24| CmdSN | - +---------------+---------------+---------------+---------------+ - 28| ExpStatSN | - +---------------+---------------+---------------+---------------+ - 32| RefCmdSN or Reserved | - +---------------+---------------+---------------+---------------+ - 36| ExpDataSN or Reserved | - +---------------+---------------+---------------+---------------+ - 40/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - -10.5.1. Function - - The Task Management functions provide an initiator with a way to - explicitly control the execution of one or more Tasks (SCSI and iSCSI - tasks). The Task Management function codes are listed below. For a - more detailed description of SCSI task management, see [SAM2]. - - 1 - ABORT TASK - aborts the task identified by the Referenced Task - Tag field. - - 2 - ABORT TASK SET - aborts all Tasks issued via this session on the - logical unit. - - 3 - CLEAR ACA - clears the Auto Contingent Allegiance condition. - - - - - -Satran, et al. Standards Track [Page 129] - -RFC 3720 iSCSI April 2004 - - - 4 - CLEAR TASK SET - aborts all Tasks in the appropriate task set as - defined by the TST field in the Control mode page (see [SPC3]). - - 5 - LOGICAL UNIT RESET - - 6 - TARGET WARM RESET - - 7 - TARGET COLD RESET - - 8 - TASK REASSIGN - reassigns connection allegiance for the task - identified by the Referenced Task Tag field to this connection, - thus resuming the iSCSI exchanges for the task. - - For all these functions, the Task Management function response MUST - be returned as detailed in Section 10.6 Task Management Function - Response. All these functions apply to the referenced tasks - regardless of whether they are proper SCSI tasks or tagged iSCSI - operations. Task management requests must act on all the commands - from the same session having a CmdSN lower than the task management - CmdSN. LOGICAL UNIT RESET, TARGET WARM RESET and TARGET COLD RESET - may affect commands from other sessions or commands from the same - session with CmdSN equal or exceeding CmdSN. - - If the task management request is marked for immediate delivery, it - must be considered immediately for execution, but the operations - involved (all or part of them) may be postponed to allow the target - to receive all relevant tasks. According to [SAM2], for all the - tasks covered by the Task Management response (i.e., with CmdSN lower - than the task management command CmdSN) but except the Task - Management response to a TASK REASSIGN, additional responses MUST NOT - be delivered to the SCSI layer after the Task Management response. - The iSCSI initiator MAY deliver to the SCSI layer all responses - received before the Task Management response (i.e., it is a matter of - implementation if the SCSI responses, received before the Task - Management response but after the task management request was issued, - are delivered to the SCSI layer by the iSCSI layer in the initiator). - The iSCSI target MUST ensure that no responses for the tasks covered - by a task management function are delivered to the iSCSI initiator - after the Task Management response except for a task covered by a - TASK REASSIGN. - - For ABORT TASK SET and CLEAR TASK SET, the issuing initiator MUST - continue to respond to all valid target transfer tags (received via - R2T, Text Response, NOP-In, or SCSI Data-In PDUs) related to the - affected task set, even after issuing the task management request. - The issuing initiator SHOULD however terminate (i.e., by setting the - F-bit to 1) these response sequences as quickly as possible. The - target on its part MUST wait for responses on all affected target - - - -Satran, et al. Standards Track [Page 130] - -RFC 3720 iSCSI April 2004 - - - transfer tags before acting on either of these two task management - requests. In case all or part of the response sequence is not - received (due to digest errors) for a valid TTT, the target MAY treat - it as a case of within-command error recovery class (see Section - 6.1.4.1 Recovery Within-command) if it is supporting - ErrorRecoveryLevel >= 1, or alternatively may drop the connection to - complete the requested task set function. - - If an ABORT TASK is issued for a task created by an immediate command - then RefCmdSN MUST be that of the Task Management request itself - (i.e., CmdSN and RefCmdSN are equal); otherwise RefCmdSN MUST be set - to the CmdSN of the task to be aborted (lower than CmdSN). - - If the connection is still active (it is not undergoing an implicit - or explicit logout), ABORT TASK MUST be issued on the same connection - to which the task to be aborted is allegiant at the time the Task - Management Request is issued. If the connection is implicitly or - explicitly logged out (i.e., no other request will be issued on the - failing connection and no other response will be received on the - failing connection), then an ABORT TASK function request may be - issued on another connection. This Task Management request will then - establish a new allegiance for the command to be aborted as well as - abort it (i.e., the task to be aborted will not have to be retried or - reassigned, and its status, if issued but not acknowledged, will be - reissued followed by the Task Management response). - - At the target an ABORT TASK function MUST NOT be executed on a Task - Management request; such a request MUST result in Task Management - response of "Function rejected". - - For the LOGICAL UNIT RESET function, the target MUST behave as - dictated by the Logical Unit Reset function in [SAM2]. - - The implementation of the TARGET WARM RESET function and the TARGET - COLD RESET function is OPTIONAL and when implemented, should act as - described below. The TARGET WARM RESET is also subject to SCSI - access controls on the requesting initiator as defined in [SPC3]. - When authorization fails at the target, the appropriate response as - described in Section 10.6 Task Management Function Response MUST be - returned by the target. The TARGET COLD RESET function is not - subject to SCSI access controls, but its execution privileges may be - managed by iSCSI mechanisms such as login authentication. - - When executing the TARGET WARM RESET and TARGET COLD RESET functions, - the target cancels all pending operations on all Logical Units known - by the issuing initiator. Both functions are equivalent to the - Target Reset function specified by [SAM2]. They can affect many - other initiators logged in with the servicing SCSI target port. - - - -Satran, et al. Standards Track [Page 131] - -RFC 3720 iSCSI April 2004 - - - The target MUST treat the TARGET COLD RESET function additionally as - a power on event, thus terminating all of its TCP connections to all - initiators (all sessions are terminated). For this reason, the - Service Response (defined by [SAM2]) for this SCSI task management - function may not be reliably delivered to the issuing initiator port. - - For the TASK REASSIGN function, the target should reassign the - connection allegiance to this new connection (and thus resume iSCSI - exchanges for the task). TASK REASSIGN MUST ONLY be received by the - target after the connection on which the command was previously - executing has been successfully logged-out. The Task Management - response MUST be issued before the reassignment becomes effective. - For additional usage semantics see Section 6.2 Retry and Reassign in - Recovery. - - At the target a TASK REASSIGN function request MUST NOT be executed - to reassign the connection allegiance of a Task Management function - request, an active text negotiation task, or a Logout task; such a - request MUST result in Task Management response of "Function - rejected". - - TASK REASSIGN MUST be issued as an immediate command. - -10.5.2. TotalAHSLength and DataSegmentLength - - For this PDU TotalAHSLength and DataSegmentLength MUST be 0. - -10.5.3. LUN - - This field is required for functions that address a specific LU - (ABORT TASK, CLEAR TASK SET, ABORT TASK SET, CLEAR ACA, LOGICAL UNIT - RESET) and is reserved in all others. - -10.5.4. Referenced Task Tag - - The Initiator Task Tag of the task to be aborted for the ABORT TASK - function or reassigned for the TASK REASSIGN function. For all the - other functions this field MUST be set to the reserved value - 0xffffffff. - -10.5.5. RefCmdSN - - If an ABORT TASK is issued for a task created by an immediate command - then RefCmdSN MUST be that of the Task Management request itself - (i.e., CmdSN and RefCmdSN are equal). - - - - - - -Satran, et al. Standards Track [Page 132] - -RFC 3720 iSCSI April 2004 - - - For an ABORT TASK of a task created by non-immediate command RefCmdSN - MUST be set to the CmdSN of the task identified by the Referenced - Task Tag field. Targets must use this field as described in section - 10.6.1 when the task identified by the Referenced Task Tag field is - not with the target. - - Otherwise, this field is reserved. - -10.5.6. ExpDataSN - - For recovery purposes, the iSCSI target and initiator maintain a data - acknowledgement reference number - the first input DataSN number - unacknowledged by the initiator. When issuing a new command, this - number is set to 0. If the function is TASK REASSIGN, which - establishes a new connection allegiance for a previously issued Read - or Bidirectional command, ExpDataSN will contain an updated data - acknowledgement reference number or the value 0; the latter - indicating that the data acknowledgement reference number is - unchanged. The initiator MUST discard any data PDUs from the - previous execution that it did not acknowledge and the target MUST - transmit all Data-In PDUs (if any) starting with the data - acknowledgement reference number. The number of retransmitted PDUs - may or may not be the same as the original transmission depending on - if there was a change in MaxRecvDataSegmentLength in the - reassignment. The target MAY also send no more Data-In PDUs if all - data has been acknowledged. - - The value of ExpDataSN MUST be 0 or higher than the DataSN of the - last acknowledged Data-In PDU, but not larger than DataSN+1 of the - last Data-In PDU sent by the target. Any other value MUST be ignored - by the target. - - For other functions this field is reserved. - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 133] - -RFC 3720 iSCSI April 2004 - - -10.6. Task Management Function Response - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x22 |1| Reserved | Response | Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------------------------------------------------------+ - 8/ Reserved / - / / - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| Reserved | - +---------------+---------------+---------------+---------------+ - 24| StatSN | - +---------------+---------------+---------------+---------------+ - 28| ExpCmdSN | - +---------------+---------------+---------------+---------------+ - 32| MaxCmdSN | - +---------------+---------------+---------------+---------------+ - 36/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - For the functions ABORT TASK, ABORT TASK SET, CLEAR ACA, CLEAR TASK - SET, LOGICAL UNIT RESET, TARGET COLD RESET, TARGET WARM RESET and - TASK REASSIGN, the target performs the requested Task Management - function and sends a Task Management response back to the initiator. - For TASK REASSIGN, the new connection allegiance MUST ONLY become - effective at the target after the target issues the Task Management - Response. - -10.6.1. Response - - The target provides a Response, which may take on the following - values: - - a) 0 - Function complete. - b) 1 - Task does not exist. - c) 2 - LUN does not exist. - d) 3 - Task still allegiant. - e) 4 - Task allegiance reassignment not supported. - - - - -Satran, et al. Standards Track [Page 134] - -RFC 3720 iSCSI April 2004 - - - f) 5 - Task management function not supported. - g) 6 - Function authorization failed. - h) 255 - Function rejected. - - All other values are reserved. - - For a discussion on usage of response codes 3 and 4, see Section - 6.2.2 Allegiance Reassignment. - - For the TARGET COLD RESET and TARGET WARM RESET functions, the target - cancels all pending operations across all Logical Units 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). - - 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 - response of FUNCTION COMPLETE. All other 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. - - 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 have been - confirmed (acknowledged through ExpStatSN) by the initiator on all - connections of this session. For the exact timeline of events, refer - to Section 10.6.2 Task Management Actions on Task Sets. - - For the ABORT TASK function, - - a) 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, - but if 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 received - and return the "Function complete" response. - - - - - - - -Satran, et al. Standards Track [Page 135] - -RFC 3720 iSCSI April 2004 - - - c) If the Referenced Task Tag does not identify an existing task - and if 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. - -10.6.2. Task Management Actions on Task Sets - - The execution of ABORT TASK SET and CLEAR TASK SET Task Management - function requests consists of the following sequence of events in the - specified order on each of the entities. - - The initiator: - - a) Issues ABORT TASK SET/CLEAR TASK SET request. - b) Continues to respond to each target transfer tag received - for the affected task set. - c) Receives any responses for the tasks in the affected task - set (may process them as usual because they are guaranteed - to be valid). - d) Receives the task set management response, thus concluding - all the tasks in the affected task set. - - The target: - - a) Receives the ABORT TASK SET/CLEAR TASK SET request. - b) Waits for all target transfer tags to be responded to and - for all affected tasks in the task set to be received. - c) Propagates the command to and receives the response from the - target SCSI layer. - d) Takes note of last-sent StatSN on each of the connections in - the iSCSI sessions (one or more) sharing the affected task - set, and waits for acknowledgement of each StatSN (may - solicit for acknowledgement by way of a NOP-In). If some - tasks originate from non-iSCSI I_T_L nexi then the means by - which the target insures that all affected tasks have - returned their status to the initiator are defined by the - specific protocol. - - e) Sends the task set management response to the issuing - initiator. - - - - - - - - - - - -Satran, et al. Standards Track [Page 136] - -RFC 3720 iSCSI April 2004 - - -10.6.3. TotalAHSLength and DataSegmentLength - - For this PDU TotalAHSLength and DataSegmentLength MUST be 0. - -10.7. SCSI Data-Out & SCSI Data-In - - The SCSI Data-Out PDU for WRITE operations has the following format: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x05 |F| Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| LUN or Reserved | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| Target Transfer Tag or 0xffffffff | - +---------------+---------------+---------------+---------------+ - 24| Reserved | - +---------------+---------------+---------------+---------------+ - 28| ExpStatSN | - +---------------+---------------+---------------+---------------+ - 32| Reserved | - +---------------+---------------+---------------+---------------+ - 36| DataSN | - +---------------+---------------+---------------+---------------+ - 40| Buffer Offset | - +---------------+---------------+---------------+---------------+ - 44| Reserved | - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - / DataSegment / - +/ / - +---------------+---------------+---------------+---------------+ - | Data-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - - - - - - - -Satran, et al. Standards Track [Page 137] - -RFC 3720 iSCSI April 2004 - - - The SCSI Data-In PDU for READ operations has the following format: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x25 |F|A|0 0 0|O|U|S| Reserved |Status or Rsvd | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| LUN or Reserved | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| Target Transfer Tag or 0xffffffff | - +---------------+---------------+---------------+---------------+ - 24| StatSN or Reserved | - +---------------+---------------+---------------+---------------+ - 28| ExpCmdSN | - +---------------+---------------+---------------+---------------+ - 32| MaxCmdSN | - +---------------+---------------+---------------+---------------+ - 36| DataSN | - +---------------+---------------+---------------+---------------+ - 40| Buffer Offset | - +---------------+---------------+---------------+---------------+ - 44| Residual Count | - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - / DataSegment / - +/ / - +---------------+---------------+---------------+---------------+ - | Data-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - Status can accompany the last Data-In PDU if the command did not end - with an exception (i.e., the status is "good status" - GOOD, - CONDITION MET or INTERMEDIATE CONDITION MET). The presence of status - (and of a residual count) is signaled though the S flag bit. - Although targets MAY choose to send even non-exception status in - separate responses, initiators MUST support non-exception status in - Data-In PDUs. - - - - - - -Satran, et al. Standards Track [Page 138] - -RFC 3720 iSCSI April 2004 - - -10.7.1. F (Final) Bit - - For outgoing data, this bit is 1 for the last PDU of unsolicited data - or the last PDU of a sequence that answers an R2T. - - For incoming data, this bit is 1 for the last input (read) data PDU - of a sequence. Input can be split into several sequences, each - 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. - - 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 - FirstBurstLength for unsolicited data). However the number of - individual PDUs in a sequence (or in total) may be higher than the - MaxBurstLength (or FirstBurstLength) to MaxRecvDataSegmentLength - ratio (as PDUs may be limited in length by the sender capabilities). - Using DataSegmentLength of 0 may increase beyond what is reasonable - for the number of PDUs and should therefore be avoided. - - For Bidirectional operations, the F bit is 1 for both the end of the - input sequences and the end of the output sequences. - -10.7.2. A (Acknowledge) Bit - - For sessions with ErrorRecoveryLevel 1 or higher, the target sets - this bit to 1 to indicate that it requests a positive acknowledgement - from the initiator for the data received. The target should use the - A bit moderately; it MAY only set the A bit to 1 once every - MaxBurstLength bytes, or on the last Data-In PDU that concludes the - entire requested read data transfer for the task from the target's - 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. - - 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 - DataACK except when it is able to acknowledge the status for the task - immediately via ExpStatSN on other outbound PDUs if the status for - the task is also received. In the latter case (acknowledgement - through ExpStatSN), sending a SNACK of type DataACK in response to - the A bit is OPTIONAL, but if it is done, it must not be sent after - the status acknowledgement through ExpStatSN. If the initiator has - detected holes in the read data prior to that Data-In PDU, it MUST - - - -Satran, et al. Standards Track [Page 139] - -RFC 3720 iSCSI April 2004 - - - postpone issuing the SNACK of type DataACK until the holes are - filled. An initiator also MUST NOT acknowledge the status for the - task before those holes are filled. A status acknowledgement for a - task that generated the Data-In PDUs is considered by the target as - an implicit acknowledgement of the Data-In PDUs if such an - acknowledgement was requested by the target. - -10.7.3. Flags (byte 1) - - The last SCSI Data packet sent from a target to an initiator for a - SCSI command that completed successfully (with a status of GOOD, - CONDITION MET, INTERMEDIATE or INTERMEDIATE CONDITION MET) may also - optionally contain the Status for the data transfer. As Sense Data - cannot be sent together with the Command Status, if the command is - completed with an error, then the response and sense data MUST be - sent in a SCSI Response PDU (i.e., MUST NOT be sent in a SCSI Data - packet). If Status is sent with the data, then a SCSI Response PDU - MUST NOT be sent as this would violate SCSI rules (a single status). - For Bidirectional commands, the status MUST be sent in a SCSI - Response PDU. - - bit 2-4 - Reserved. - - bit 5-6 - used the same as in a SCSI Response. These bits are - only valid when S is set to 1. For details see Section - 10.4.1 Flags (byte 1). - - bit 7 S (status)- set to indicate that the Command Status field - contains status. If this bit is set to 1, the F bit - MUST also be set to 1. - - The fields StatSN, Status, and Residual Count only have meaningful - content if the S bit is set to 1 and their values are defined in - Section 10.4 SCSI Response. - -10.7.4. Target Transfer Tag and LUN - - 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. - - On incoming data, the Target Transfer Tag and LUN MUST be provided by - 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. - - - - -Satran, et al. Standards Track [Page 140] - -RFC 3720 iSCSI April 2004 - - - 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. If the Target Transfer Tag is - provided, then the LUN field MUST hold a valid value and be - consistent with whatever was specified with the command; otherwise, - the LUN field is reserved. - -10.7.5. DataSN - - 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. - - R2T and Data-In PDUs, in the context of bidirectional commands, share - the numbering sequence (see Section 3.2.2.3 Data Sequencing). - - For output (write) data PDUs, the DataSN is the Data-Out PDU number - within the current output sequence. The current output sequence is - either identified by the Initiator Task Tag (for unsolicited data) or - is a data sequence generated for one R2T (for data solicited through - R2T). - -10.7.6. Buffer Offset - - 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. - - 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. - - 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. - -10.7.7. DataSegmentLength - - 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. - - 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. - - - - -Satran, et al. Standards Track [Page 141] - -RFC 3720 iSCSI April 2004 - - -10.8. Ready To Transfer (R2T) - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x31 |1| Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| LUN | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| Target Transfer Tag | - +---------------+---------------+---------------+---------------+ - 24| StatSN | - +---------------+---------------+---------------+---------------+ - 28| ExpCmdSN | - +---------------+---------------+---------------+---------------+ - 32| MaxCmdSN | - +---------------+---------------+---------------+---------------+ - 36| R2TSN | - +---------------+---------------+---------------+---------------+ - 40| Buffer Offset | - +---------------+---------------+---------------+---------------+ - 44| Desired Data Transfer Length | - +---------------------------------------------------------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - When an initiator has submitted a SCSI Command with data that passes - from the initiator to the target (WRITE), the target may specify - which blocks of data it is ready to receive. The target may request - that the data blocks be delivered in whichever order is convenient - for the target at that particular instant. This information is - passed from the target to the initiator in the Ready To Transfer - (R2T) PDU. - - In order to allow write operations without an explicit initial R2T, - the initiator and target MUST have negotiated the key InitialR2T to - No during Login. - - An R2T MAY be answered with one or more SCSI Data-Out PDUs with a - matching Target Transfer Tag. If an R2T is answered with a single - Data-Out PDU, the Buffer Offset in the Data PDU MUST be the same as - - - -Satran, et al. Standards Track [Page 142] - -RFC 3720 iSCSI April 2004 - - - the one specified by the R2T, and the data length of the Data PDU - MUST be the same as the Desired Data Transfer Length specified in the - R2T. If the R2T is answered with a sequence of Data PDUs, the Buffer - Offset and Length MUST be within the range of those specified by R2T, - and the last PDU MUST have the F bit set to 1. If the last PDU - (marked with the F bit) is received before the Desired Data Transfer - Length is transferred, a target MAY choose to Reject that - - PDU with "Protocol error" reason code. DataPDUInOrder governs the - Data-Out PDU ordering. If DataPDUInOrder is set to Yes, the Buffer - Offsets and Lengths for consecutive PDUs MUST form a continuous - non-overlapping range and the PDUs MUST be sent in increasing offset - order. - - The target may send several R2T PDUs. It, therefore, can have a - number of pending data transfers. The number of outstanding R2T PDUs - are limited by the value of the negotiated key MaxOutstandingR2T. - Within a connection, outstanding R2Ts MUST be fulfilled by the - initiator in the order in which they were received. - - R2T PDUs MAY also be used to recover Data Out PDUs. Such an R2T - (Recovery-R2T) is generated by a target upon detecting the loss of - one or more Data-Out PDUs due to: - - - Digest error - - Sequence error - - Sequence reception timeout - - A Recovery-R2T carries the next unused R2TSN, but requests part of or - the entire data burst that an earlier R2T (with a lower R2TSN) had - already requested. - - DataSequenceInOrder governs the buffer offset ordering in consecutive - R2Ts. If DataSequenceInOrder is Yes, then consecutive R2Ts MUST - refer to continuous non-overlapping ranges except for Recovery-R2Ts. - -10.8.1. TotalAHSLength and DataSegmentLength - - For this PDU TotalAHSLength and DataSegmentLength MUST be 0. - -10.8.2. R2TSN - - R2TSN is the R2T PDU input PDU number within the command identified - by the Initiator Task Tag. - - For bidirectional commands R2T and Data-In PDUs share the input PDU - numbering sequence (see Section 3.2.2.3 Data Sequencing). - - - - -Satran, et al. Standards Track [Page 143] - -RFC 3720 iSCSI April 2004 - - -10.8.3. StatSN - - The StatSN field will contain the next StatSN. The StatSN for this - connection is not advanced after this PDU is sent. - -10.8.4. Desired Data Transfer Length and Buffer Offset - - The target specifies how many bytes it wants the initiator to send - because of this R2T PDU. The target may request the data from the - initiator in several chunks, not necessarily in the original order of - the data. 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 Desired Data - Transfer Length MUST NOT be 0 and MUST not exceed MaxBurstLength. - -10.8.5. Target Transfer Tag - - The target assigns its own tag to each R2T request that it sends to - the initiator. This tag can be used by the target to easily identify - the data it receives. The Target Transfer Tag and LUN are copied in - the outgoing data PDUs and are only used by the target. There is no - protocol rule about the Target Transfer Tag except that the value - 0xffffffff is reserved and MUST NOT be sent by a target in an R2T. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 144] - -RFC 3720 iSCSI April 2004 - - -10.9. Asynchronous Message - - An Asynchronous Message may be sent from the target to the initiator - without correspondence to a particular command. The target specifies - the reason for the event and sense data. - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x32 |1| Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| LUN or Reserved | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| 0xffffffff | - +---------------+---------------+---------------+---------------+ - 20| Reserved | - +---------------+---------------+---------------+---------------+ - 24| StatSN | - +---------------+---------------+---------------+---------------+ - 28| ExpCmdSN | - +---------------+---------------+---------------+---------------+ - 32| MaxCmdSN | - +---------------+---------------+---------------+---------------+ - 36| AsyncEvent | AsyncVCode | Parameter1 or Reserved | - +---------------+---------------+---------------+---------------+ - 40| Parameter2 or Reserved | Parameter3 or Reserved | - +---------------+---------------+---------------+---------------+ - 44| Reserved | - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - / DataSegment - Sense Data and iSCSI Event Data / - +/ / - +---------------+---------------+---------------+---------------+ - | Data-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - Some Asynchronous Messages are strictly related to iSCSI while others - are related to SCSI [SAM2]. - - StatSN counts this PDU as an acknowledgeable event (StatSN is - advanced), which allows for initiator and target state - synchronization. - - - -Satran, et al. Standards Track [Page 145] - -RFC 3720 iSCSI April 2004 - - -10.9.1. AsyncEvent - - The codes used for iSCSI Asynchronous Messages (events) are: - - 0 - a SCSI Asynchronous Event is reported in the sense data. - Sense Data that accompanies the report, in the data segment, - identifies the condition. The sending of a SCSI Event - (Asynchronous Event Reporting in SCSI terminology) is - dependent on the target support for SCSI asynchronous event - reporting (see [SAM2]) as indicated in the standard INQUIRY - data (see [SPC3]). Its use may be enabled by parameters in - the SCSI Control mode page (see [SPC3]). - - 1 - target requests Logout. This Async Message MUST be sent on - the same connection as the one requesting to be logged out. - The initiator MUST honor this request by issuing a Logout as - early as possible, but no later than Parameter3 seconds. - Initiator MUST send a Logout with a reason code of "Close the - connection" OR "Close the session" to close all the - connections. Once this message is received, the initiator - SHOULD NOT issue new iSCSI commands on the connection to be - logged out. The target MAY reject any new I/O requests that - it receives after this Message with the reason code "Waiting - for Logout". If the initiator does not Logout in Parameter3 - seconds, the target should send an Async PDU with iSCSI event - code "Dropped the connection" if possible, or simply terminate - the transport connection. Parameter1 and Parameter2 are - reserved. - - 2 - target indicates it will drop the connection. The Parameter1 - field indicates the CID of the connection that is going to be - dropped. - - The Parameter2 field (Time2Wait) indicates, in seconds, the - minimum time to wait before attempting to reconnect or - reassign. - - The Parameter3 field (Time2Retain) indicates the maximum time - allowed to reassign commands after the initial wait (in - Parameter2). - - 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. - - - - -Satran, et al. Standards Track [Page 146] - -RFC 3720 iSCSI April 2004 - - - A value of 0 for Parameter2 indicates that reconnect can be - attempted immediately. - - 3 - target indicates it will drop all the connections of this - session. - - Parameter1 field is reserved. - - The Parameter2 field (Time2Wait) indicates, in seconds, the - minimum time to wait before attempting to reconnect. The - Parameter3 field (Time2Retain) indicates the maximum time - allowed to reassign commands after the initial wait (in - Parameter2). - - 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. - - 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 - session. A value of 0 for Parameter2 indicates that reconnect - can be attempted immediately. - - 4 - target requests parameter negotiation on this connection. The - initiator MUST honor this request by issuing a Text Request - (that can be empty) on the same connection as early as - possible, but no later than Parameter3 seconds, unless a Text - Request is already pending on the connection, or by issuing a - Logout Request. If the initiator does not issue a Text - Request the target may reissue the Asynchronous Message - requesting parameter negotiation. - - 255 - vendor specific iSCSI Event. The AsyncVCode details the - vendor code, and data MAY accompany the report. - - All other event codes are reserved. - -10.9.2. AsyncVCode - - AsyncVCode is a vendor specific detail code that is only valid if the - AsyncEvent field indicates a vendor specific event. Otherwise, it is - reserved. - -10.9.3. LUN - - The LUN field MUST be valid if AsyncEvent is 0. Otherwise, this - field is reserved. - - - -Satran, et al. Standards Track [Page 147] - -RFC 3720 iSCSI April 2004 - - -10.9.4. Sense Data and iSCSI Event Data - - For a SCSI event, this data accompanies the report in the data - segment and identifies the condition. - - For an iSCSI event, additional vendor-unique data MAY accompany the - Async event. Initiators MAY ignore the data when not understood - while processing the rest of the PDU. - - If the DataSegmentLength is not 0, the format of the DataSegment is - as follows: - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|SenseLength | Sense Data | - +---------------+---------------+---------------+---------------+ - x/ Sense Data / - +---------------+---------------+---------------+---------------+ - y/ iSCSI Event Data / - / / - +---------------+---------------+---------------+---------------+ - z| - -10.9.4.1. SenseLength - - This is the length of Sense Data. When the Sense Data field is empty - (e.g., the event is not a SCSI event) SenseLength is 0. - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 148] - -RFC 3720 iSCSI April 2004 - - -10.10. Text Request - - The Text Request is provided to allow for the exchange of information - and for future extensions. It permits the initiator to inform a - target of its capabilities or to request some special operations. - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|I| 0x04 |F|C| Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| LUN or Reserved | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| Target Transfer Tag or 0xffffffff | - +---------------+---------------+---------------+---------------+ - 24| CmdSN | - +---------------+---------------+---------------+---------------+ - 28| ExpStatSN | - +---------------+---------------+---------------+---------------+ - 32/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - / DataSegment (Text) / - +/ / - +---------------+---------------+---------------+---------------+ - | Data-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - An initiator MUST have at most one outstanding Text Request on a - connection at any given time. - - On a connection failure, an initiator must either explicitly abort - any active allegiant text negotiation task or must cause such a task - to be implicitly terminated by the target. - - - - - - - - -Satran, et al. Standards Track [Page 149] - -RFC 3720 iSCSI April 2004 - - -10.10.1. F (Final) Bit - - When set to 1, indicates that this is the last or only text request - in a sequence of Text Requests; otherwise, it indicates that more - Text Requests will follow. - -10.10.2. C (Continue) Bit - - When set to 1, indicates that the text (set of key=value pairs) in - this Text Request is not complete (it will be continued on subsequent - Text Requests); otherwise, it indicates that this Text Request ends a - set of key=value pairs. A Text Request with the C bit set to 1 MUST - have the F bit set to 0. - -10.10.3. Initiator Task Tag - - The initiator assigned identifier for this Text Request. If the - command is sent as part of a sequence of text requests and responses, - the Initiator Task Tag MUST be the same for all the requests within - the sequence (similar to linked SCSI commands). The I bit for all - requests in a sequence also MUST be the same. - -10.10.4. Target Transfer Tag - - 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). - - 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 - associated with the specified Initiator Task Tag. It MUST do so - whenever it sets the F bit to 0 in the response. By copying the - 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. - - 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. - - If the Target Transfer Tag is not 0xffffffff, the LUN field MUST be - sent by the target in the Text Response. - - - - - - -Satran, et al. Standards Track [Page 150] - -RFC 3720 iSCSI April 2004 - - - 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 in the following example: - - 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) - T->I Text <part 2> (F=0, TTT=0x12345678) - I->T Text <empty> (F=1, TTT=0x12345678) - ... - T->I Text <part n> (F=1, TTT=0xffffffff) - -10.10.5. Text - - The data lengths of a text request MUST NOT exceed the iSCSI target - MaxRecvDataSegmentLength (a per connection and per direction - negotiated parameter). The text format is specified in Section 5.2 - Text Mode Negotiation. - - Chapter 11 and Chapter 12 list some basic Text key=value pairs, some - of which can be used in Login Request/Response and some in Text - Request/Response. - - A key=value pair can span Text request or 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. - - 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. - - Chapter 5 details the rules for the Text Requests and Responses. - - Text operations are usually meant for parameter setting/ - negotiations, but can also be used to perform some long lasting - operations. - - Text operations that take a long time should be placed in their own - Text request. - - - - - - - -Satran, et al. Standards Track [Page 151] - -RFC 3720 iSCSI April 2004 - - -10.11. Text Response - - The Text Response PDU contains the target's responses to the - initiator's Text request. The format of the Text field matches that - of the Text request. - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x24 |F|C| Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| LUN or Reserved | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| Target Transfer Tag or 0xffffffff | - +---------------+---------------+---------------+---------------+ - 24| StatSN | - +---------------+---------------+---------------+---------------+ - 28| ExpCmdSN | - +---------------+---------------+---------------+---------------+ - 32| MaxCmdSN | - +---------------+---------------+---------------+---------------+ - 36/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - / DataSegment (Text) / - +/ / - +---------------+---------------+---------------+---------------+ - | Data-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - -10.11.1. F (Final) Bit - - When set to 1, in response to a Text Request with the Final bit set - to 1, the F bit indicates that the target has finished the whole - operation. Otherwise, if set to 0 in response to a Text Request with - 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. - - - -Satran, et al. Standards Track [Page 152] - -RFC 3720 iSCSI April 2004 - - - 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 of 0xffffffff. - - 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 0xffffffff. - -10.11.2. C (Continue) Bit - - When set to 1, indicates that the text (set of key=value pairs) in - this Text Response is not complete (it will be continued on - subsequent Text Responses); otherwise, it indicates that this Text - Response ends a set of key=value pairs. A Text Response with the C - bit set to 1 MUST have the F bit set to 0. - -10.11.3. Initiator Task Tag - - The Initiator Task Tag matches the tag used in the initial Text - Request. - -10.11.4. Target Transfer Tag - - When a target has more work to do (e.g., cannot transfer all the - remaining text data in a single Text Response or has to continue the - negotiation) and has enough resources to proceed, it MUST set the - Target Transfer Tag to a value other than the reserved value of - 0xffffffff. Otherwise, the Target Transfer Tag MUST be set to - 0xffffffff. - - When the Target Transfer Tag is not 0xffffffff, the LUN field may be - significant. - - The initiator MUST copy the Target Transfer Tag and LUN in its next - request to indicate that it wants the rest of the data. - - When the target receives a Text Request with the Target Transfer Tag - set to the reserved value of 0xffffffff, it resets its internal - information (resets state) associated with the given Initiator Task - Tag (restarts the negotiation). - - 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. - - - - - - -Satran, et al. Standards Track [Page 153] - -RFC 3720 iSCSI April 2004 - - - A target may reset its internal state associated with an Initiator - Task Tag (the current negotiation state), state expressed through the - Target Transfer Tag if the initiator fails to continue the exchange - for some time. The target may reject subsequent Text Requests with - the Target Transfer Tag set to the "stale" value. - -10.11.5. StatSN - - The target StatSN variable is advanced by each Text Response sent. - -10.11.6. Text Response Data - - The data lengths of a text response MUST NOT exceed the iSCSI - initiator MaxRecvDataSegmentLength (a per connection and per - direction negotiated parameter). - - The text in the Text Response Data is governed by the same rules as - the text in the Text Request Data (see Section 10.10.5 Text). - - 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 - response to the initiator. - -10.12. Login Request - - After establishing a TCP connection between an initiator and a - target, the initiator MUST start a Login Phase to gain further access - to the target's resources. - - The Login Phase (see Chapter 5) consists of a sequence of Login - Requests and Responses that carry the same Initiator Task Tag. - - Login Requests are always considered as immediate. - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 154] - -RFC 3720 iSCSI April 2004 - - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|1| 0x03 |T|C|.|.|CSG|NSG| Version-max | Version-min | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| ISID | - + +---------------+---------------+ - 12| | TSIH | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| CID | Reserved | - +---------------+---------------+---------------+---------------+ - 24| CmdSN | - +---------------+---------------+---------------+---------------+ - 28| ExpStatSN or Reserved | - +---------------+---------------+---------------+---------------+ - 32| Reserved | - +---------------+---------------+---------------+---------------+ - 36| Reserved | - +---------------+---------------+---------------+---------------+ - 40/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 48/ DataSegment - Login Parameters in Text request Format / - +/ / - +---------------+---------------+---------------+---------------+ - -10.12.1. T (Transit) Bit - - If set to 1, indicates that the initiator is ready to transit to the - next stage. - - If the T bit is set to 1 and NSG is FullFeaturePhase, then this also - indicates that the initiator is ready for the Final Login Response - (see Chapter 5). - -10.12.2. C (Continue) Bit - - When set to 1, indicates that the text (set of key=value pairs) in - this Login Request is not complete (it will be continued on - subsequent Login Requests); otherwise, it indicates that this Login - Request ends a set of key=value pairs. A Login Request with the C - bit set to 1 MUST have the T bit set to 0. - - - - -Satran, et al. Standards Track [Page 155] - -RFC 3720 iSCSI April 2004 - - -10.12.3. CSG and NSG - - Through these fields, Current Stage (CSG) and Next Stage (NSG), the - Login negotiation requests and responses are associated with a - specific stage in the session (SecurityNegotiation, - LoginOperationalNegotiation, FullFeaturePhase) and may indicate the - next stage to which they want to move (see Chapter 5). The next - stage value is only valid when the T bit is 1; otherwise, it is - reserved. - - The stage codes are: - - - 0 - SecurityNegotiation - - 1 - LoginOperationalNegotiation - - 3 - FullFeaturePhase - - All other codes are reserved. - -10.12.4. Version - - The version number of the current draft is 0x00. As such, all - devices MUST carry version 0x00 for both Version-min and Version-max. - -10.12.4.1. Version-max - - Maximum Version number supported. - - All Login Requests within the Login Phase MUST carry the same - Version-max. - - The target MUST use the value presented with the first Login Request. - -10.12.4.2. Version-min - - All Login Requests within the Login Phase MUST carry the same - Version-min. The target MUST use the value presented with the first - Login Request. - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 156] - -RFC 3720 iSCSI April 2004 - - -10.12.5. ISID - - This is an initiator-defined component of the session identifier and - is structured as follows (see [RFC3721] and Section 9.1.1 - Conservative Reuse of ISIDs for details): - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 8| T | A | B | C | - +---------------+---------------+---------------+---------------+ - 12| D | - +---------------+---------------+ - - The T field identifies the format and usage of A, B, C, and D as - indicated below: - - T - - 00b OUI-Format - A&B are a 22 bit OUI - (the I/G & U/L bits are omitted) - C&D 24 bit qualifier - 01b EN - Format (IANA Enterprise Number) - A - Reserved - B&C EN (IANA Enterprise Number) - D - Qualifier - 10b "Random" - A - Reserved - B&C Random - D - Qualifier - 11b A,B,C&D Reserved - - For the T field values 00b and 01b, a combination of A and B (for - 00b) or B and C (for 01b) identifies the vendor or organization whose - component (software or hardware) generates this ISID. A vendor or - organization with one or more OUIs, or one or more Enterprise - Numbers, MUST use at least one of these numbers and select the - appropriate value for the T field when its components generate ISIDs. - An OUI or EN MUST be set in the corresponding fields in network byte - order (byte big-endian). - - If the T field is 10b, B and C are set to a random 24-bit unsigned - integer value in network byte order (byte big-endian). See [RFC3721] - for how this affects the principle of "conservative reuse". - - - - - -Satran, et al. Standards Track [Page 157] - -RFC 3720 iSCSI April 2004 - - - The Qualifier field is a 16 or 24-bit unsigned integer value that - provides a range of possible values for the ISID within the selected - namespace. It may be set to any value within the constraints - specified in the iSCSI protocol (see Section 3.4.3 Consequences of - the Model and Section 9.1.1 Conservative Reuse of ISIDs). - - The T field value of 11b is reserved. - - If the ISID is derived from something assigned to a hardware adapter - or interface by a vendor, as a preset default value, it MUST be - configurable to a value assigned according to the SCSI port behavior - desired by the system in which it is installed (see Section 9.1.1 - Conservative Reuse of ISIDs and Section 9.1.2 iSCSI Name, ISID, and - TPGT Use). The resultant ISID MUST also be persistent over power - cycles, reboot, card swap, etc. - -10.12.6. TSIH - - TSIH must be set in the first Login Request. The reserved value 0 - MUST be used on the first connection for a new session. Otherwise, - 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. - - All Login Requests within a Login Phase MUST carry the same TSIH. - - The target MUST check the value presented with the first Login - Request and act as specified in Section 5.3.1 Login Phase Start. - -10.12.7. Connection ID - CID - - A unique ID for this connection within the session. - - All Login Requests within the Login Phase MUST carry the same CID. - - The target MUST use the value presented with the first Login Request. - - 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 (see Section 5.3.4 Connection Reinstatement). For the details - of the implicit Logout Request, see Section 10.14 Logout Request. - - - - - - - - - -Satran, et al. Standards Track [Page 158] - -RFC 3720 iSCSI April 2004 - - -10.12.8. CmdSN - - 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. - - Examples: - - - Login on a leading connection - if the leading login carries - the CmdSN 123, all other Login Requests in the same Login Phase - carry the CmdSN 123 and the first non-immediate command in - FullFeaturePhase also carries the CmdSN 123. - - - Login on other than a leading connection - if the current CmdSN - at the time the first login on the connection is issued is 500, - then that PDU carries CmdSN=500. Subsequent Login Requests - that are 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 CmdSN. - - If the Login Request is a leading Login Request, the target MUST use - the value presented in CmdSN as the target value for ExpCmdSN. - -10.12.9. ExpStatSN - - For the first Login Request on a connection this is ExpStatSN for the - old connection and this field is only valid if the Login Request - restarts a connection (see Section 5.3.4 Connection Reinstatement). - - For subsequent Login Requests it is used to acknowledge the Login - Responses with their increasing StatSN values. - -10.12.10. Login Parameters - - The initiator MUST provide some basic parameters in order to enable - the target to determine if the initiator may use the target's - resources and the initial text parameters for the security exchange. - - All the rules specified in Section 10.10.5 Text for text requests - also hold for Login Requests. Keys and their explanations are listed - in Chapter 11 (security negotiation keys) and Chapter 12 (operational - parameter negotiation keys). All keys in Chapter 12, except for the - X extension formats, MUST be supported by iSCSI initiators and - targets. Keys in Chapter 11 only need to be supported when the - function to which they refer is mandatory to implement. - - - - - -Satran, et al. Standards Track [Page 159] - -RFC 3720 iSCSI April 2004 - - -10.13. Login Response - - The Login Response indicates the progress and/or end of the Login - Phase. - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x23 |T|C|.|.|CSG|NSG| Version-max | Version-active| - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| ISID | - + +---------------+---------------+ - 12| | TSIH | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| Reserved | - +---------------+---------------+---------------+---------------+ - 24| StatSN | - +---------------+---------------+---------------+---------------+ - 28| ExpCmdSN | - +---------------+---------------+---------------+---------------+ - 32| MaxCmdSN | - +---------------+---------------+---------------+---------------+ - 36| Status-Class | Status-Detail | Reserved | - +---------------+---------------+---------------+---------------+ - 40/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 48/ DataSegment - Login Parameters in Text request Format / - +/ / - +---------------+---------------+---------------+---------------+ - -10.13.1. Version-max - - This is the highest version number supported by the target. - - All Login Responses within the Login Phase MUST carry the same - Version-max. - - The initiator MUST use the value presented as a response to the first - Login Request. - - - - - - -Satran, et al. Standards Track [Page 160] - -RFC 3720 iSCSI April 2004 - - -10.13.2. Version-active - - Indicates the highest version supported by the target and initiator. - If the target does not support a version within the 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. - - The initiator MUST use the value presented as a response to the first - Login Request. - -10.13.3. TSIH - - The TSIH is the target assigned session identifying handle. Its - internal format and content are not defined by this protocol except - for the value 0 that is reserved. With the exception of the Login - Final-Response in a new session, this field should be set to the TSIH - provided by the initiator in the Login Request. For a new session, - the target MUST generate a non-zero TSIH and ONLY return it in the - Login Final-Response (see Section 5.3 Login Phase). - -10.13.4. StatSN - - For the first Login Response (the response to the first Login - Request), this is the starting status Sequence Number for the - connection. The next response of any kind, including the next Login - Response, if any, in the same Login Phase, will carry this number + - 1. This field is only valid if the Status-Class is 0. - -10.13.5. Status-Class and Status-Detail - - The Status returned in a Login Response indicates the execution - status of the Login Phase. The status includes: - - Status-Class - Status-Detail - - 0 Status-Class indicates success. - - A non-zero Status-Class indicates an exception. In this case, - Status-Class is sufficient for a simple initiator to use when - handling exceptions, without having to look at the Status-Detail. - The Status-Detail allows finer-grained exception handling for more - sophisticated initiators and for better information for logging. - - - - - -Satran, et al. Standards Track [Page 161] - -RFC 3720 iSCSI April 2004 - - - The status classes are as follows: - - 0 - 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. - - 1 - Redirection - indicates that the initiator must take further - action to complete the request. This is usually due to the - target moving to a different address. All of the redirection - status class responses MUST return one or more text key - parameters of the type "TargetAddress", which indicates the - target's new address. A redirection response MAY be issued by - a target prior or after completing a security negotiation if a - security negotiation is required. A redirection SHOULD be - accepted by an initiator even without having the target - complete a security negotiation if any security negotiation is - required, and MUST be accepted by the initiator after the - completion of the security negotiation if any security - negotiation is required. - - 2 - Initiator Error (not a format error) - indicates that the - initiator most likely caused the error. 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. - - 3 - Target Error - indicates that the target sees no errors in the - initiator's Login Request, but is currently incapable of - fulfilling the request. The initiator may re-try the same - Login Request later. - - The table below shows all of the currently allocated status codes. - The codes are in hexadecimal; the first byte is the status class and - the second byte is the status detail. - - ----------------------------------------------------------------- - Status | Code | Description - |(hex) | - ----------------------------------------------------------------- - Success | 0000 | Login is proceeding OK (*1). - ----------------------------------------------------------------- - Target moved | 0101 | The requested iSCSI Target Name (ITN) - temporarily | | has temporarily moved - | | to the address provided. - ----------------------------------------------------------------- - Target moved | 0102 | The requested ITN has permanently moved - permanently | | to the address provided. - ----------------------------------------------------------------- - - - -Satran, et al. Standards Track [Page 162] - -RFC 3720 iSCSI April 2004 - - - Initiator | 0200 | Miscellaneous iSCSI initiator - error | | errors. - ---------------------------------------------------------------- - Authentication| 0201 | The initiator could not be - failure | | successfully authenticated or target - | | authentication is not supported. - ----------------------------------------------------------------- - Authorization | 0202 | The initiator is not allowed access - failure | | to the given target. - ----------------------------------------------------------------- - Not found | 0203 | The requested ITN does not - | | exist at this address. - ----------------------------------------------------------------- - Target removed| 0204 | The requested ITN has been removed and - | |no forwarding address is provided. - ----------------------------------------------------------------- - Unsupported | 0205 | The requested iSCSI version range is - version | | not supported by the target. - ----------------------------------------------------------------- - Too many | 0206 | Too many connections on this SSID. - connections | | - ----------------------------------------------------------------- - Missing | 0207 | Missing parameters (e.g., iSCSI - parameter | | Initiator and/or Target Name). - ----------------------------------------------------------------- - Can't include | 0208 | Target does not support session - in session | | spanning to this connection (address). - ----------------------------------------------------------------- - Session type | 0209 | Target does not support this type of - not supported | | of session or not from this Initiator. - ----------------------------------------------------------------- - Session does | 020a | Attempt to add a connection - not exist | | to a non-existent session. - ----------------------------------------------------------------- - Invalid during| 020b | Invalid Request type during Login. - login | | - ----------------------------------------------------------------- - Target error | 0300 | Target hardware or software error. - ----------------------------------------------------------------- - Service | 0301 | The iSCSI service or target is not - unavailable | | currently operational. - ----------------------------------------------------------------- - Out of | 0302 | The target has insufficient session, - resources | | connection, or other resources. - ----------------------------------------------------------------- - - - - - - -Satran, et al. Standards Track [Page 163] - -RFC 3720 iSCSI April 2004 - - - (*1) If the response T bit is 1 in both the request and the matching - response, and the NSG is FullFeaturePhase in both the request and the - matching response, the Login Phase is finished and the initiator may - proceed to issue SCSI commands. - - If the Status Class is not 0, the initiator and target MUST close the - TCP connection. - - If the target wishes to reject the Login Request for more than one - reason, it should return the primary reason for the rejection. - -10.13.6. T (Transit) bit - - 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 NSG is FullFeaturePhase, then this is also - the Final Login Response (see Chapter 5). A T bit of 0 indicates a - "partial" response, which means "more negotiation needed". - - A Login Response with a T bit set to 1 MUST NOT contain key=value - pairs that may require additional answers from the initiator within - the same stage. - - 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. - -10.13.7. C (Continue) Bit - - When set to 1, indicates that the text (set of key=value pairs) in - this Login Response is not complete (it will be continued on - subsequent Login Responses); otherwise, it indicates that this Login - Response ends a set of key=value pairs. A Login Response with the C - bit set to 1 MUST have the T bit set to 0. - -10.13.8. Login Parameters - - 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. - - All the rules specified in Section 10.11.6 Text Response Data for - text responses also hold for Login Responses. Keys and their - explanations are listed in Chapter 11 (security negotiation keys) and - Chapter 12 (operational parameter negotiation keys). All keys in - Chapter 12, except for the X extension formats, MUST be supported by - iSCSI initiators and targets. Keys in Chapter 11, only need to be - supported when the function to which they refer is mandatory to - implement. - - - - -Satran, et al. Standards Track [Page 164] - -RFC 3720 iSCSI April 2004 - - -10.14. Logout Request - - The Logout Request is used to perform a controlled closing of a - connection. - - An initiator MAY use a Logout Request to remove a connection from a - session or to close an entire session. - - After sending the Logout Request PDU, an initiator MUST NOT send any - new iSCSI requests on the closing connection. If the Logout Request - is intended to close the session, new iSCSI requests MUST NOT be sent - on any of the connections participating in the session. - - When receiving a Logout Request with the reason code of "close the - connection" or "close the session", the target MUST terminate all - pending commands, whether acknowledged via ExpCmdSN or not, on that - connection or session respectively. - - When receiving a Logout Request with the reason code "remove - connection for recovery", the target MUST discard all requests not - yet acknowledged via ExpCmdSN that were issued on the specified - connection, and suspend all data/status/R2T transfers on behalf of - pending commands on the specified connection. - - The target then issues the Logout Response and half-closes the TCP - connection (sends FIN). After receiving the Logout Response and - attempting to receive the FIN (if still possible), the initiator MUST - completely close the logging-out connection. For the terminated - commands, no additional responses should be expected. - - A Logout for a CID may be performed on a different transport - connection when the TCP connection for the CID has already been - terminated. In such a case, only a logical "closing" of the iSCSI - connection for the CID is implied with a Logout. - - All commands that were not terminated or not completed (with status) - and acknowledged when the connection is closed completely can be - reassigned to a new connection if the target supports connection - recovery. - - If an initiator intends to start recovery for a failing connection, - it MUST use the Logout Request to "clean-up" the target end of a - failing connection and enable recovery to start, or the Login Request - with a non-zero TSIH and the same CID on a new connection for the - same effect (see Section 10.14.3 CID). In sessions with a single - connection, the connection can be closed and then a new connection - reopened. A connection reinstatement login can be used for recovery - (see Section 5.3.4 Connection Reinstatement). - - - -Satran, et al. Standards Track [Page 165] - -RFC 3720 iSCSI April 2004 - - - A successful completion of a Logout Request with the reason code of - "close the connection" or "remove the connection for recovery" - results at the target in the discarding of unacknowledged commands - received on the connection being logged out. These are commands that - have arrived on the connection being logged out, but have not been - delivered to SCSI because one or more commands with a smaller CmdSN - has not been received by iSCSI. See Section 3.2.2.1 Command - Numbering and Acknowledging. The resulting holes the in command - sequence numbers will have to be handled by appropriate recovery (see - Chapter 6) unless the session is also closed. - - The entire logout discussion in this section is also applicable for - an implicit Logout realized via a connection reinstatement or session - reinstatement. When a Login Request performs an implicit Logout, the - implicit Logout is performed as if having the reason codes specified - below: - - Reason code Type of implicit Logout - ------------------------------------------- - 0 session reinstatement - 1 connection reinstatement when - the operational ErrorRecoveryLevel < 2 - 2 connection reinstatement when - the operational ErrorRecoveryLevel = 2 - - - - - - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 166] - -RFC 3720 iSCSI April 2004 - - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|I| 0x06 |1| Reason Code | Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------------------------------------------------------+ - 8/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| CID or Reserved | Reserved | - +---------------+---------------+---------------+---------------+ - 24| CmdSN | - +---------------+---------------+---------------+---------------+ - 28| ExpStatSN | - +---------------+---------------+---------------+---------------+ - 32/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - -10.14.1. Reason Code - - Reason Code indicates the reason for Logout as follows: - - 0 - close the session. All commands associated with the session - (if any) are terminated. - - 1 - close the connection. All commands associated with connection - (if any) are terminated. - - 2 - remove the connection for recovery. Connection is closed and - all commands associated with it, if any, are to be prepared - for a new allegiance. - - All other values are reserved. - - - - - - - - - - - -Satran, et al. Standards Track [Page 167] - -RFC 3720 iSCSI April 2004 - - -10.14.2. TotalAHSLength and DataSegmentLength - - For this PDU TotalAHSLength and DataSegmentLength MUST be 0. - -10.14.3. CID - - This is the connection ID of the connection to be closed (including - closing the TCP stream). This field is only valid if the reason code - is not "close the session". - -10.14.4. ExpStatSN - - This is the last ExpStatSN value for the connection to be closed. - -10.14.5. Implicit termination of tasks - - 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 - the reason code of "Close the connection" and there are active - tasks allegiant to that connection. - - b) When a connection fails and eventually the connection state - times out (state transition M1 in Section 7.2.2 State - Transition Descriptions for Initiators and Targets) and there - are active tasks allegiant to that connection. - - c) 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 - the reason code of "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 - internal SCSI state and SCSI side effects with respect to ordering - because this status is never communicated back as a terminating - status to the initiator. However additional actions may have to be - taken at SCSI level depending on the SCSI context as defined by the - SCSI standards (e.g., queued commands and ACA, in cases a), b), and - c), after the tasks are terminated, the target MUST report a Unit - Attention condition on the next command processed on any connection - for each affected I_T_L nexus with the status of CHECK CONDITION, and - - - -Satran, et al. Standards Track [Page 168] - -RFC 3720 iSCSI April 2004 - - - the ASC/ASCQ value of 47h/7Fh - "SOME COMMANDS CLEARED BY ISCSI - PROTOCOL EVENT" - etc. - see [SAM2] and [SPC3]). - -10.15. Logout Response - - The Logout Response is used by the target to indicate if the cleanup - operation for the connection(s) has completed. - - After Logout, the TCP connection referred by the CID MUST be closed - at both ends (or all connections must be closed if the logout reason - was session close). - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x26 |1| Reserved | Response | Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------------------------------------------------------+ - 8/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag | - +---------------+---------------+---------------+---------------+ - 20| Reserved | - +---------------+---------------+---------------+---------------+ - 24| StatSN | - +---------------+---------------+---------------+---------------+ - 28| ExpCmdSN | - +---------------+---------------+---------------+---------------+ - 32| MaxCmdSN | - +---------------+---------------+---------------+---------------+ - 36| Reserved | - +---------------------------------------------------------------+ - 40| Time2Wait | Time2Retain | - +---------------+---------------+---------------+---------------+ - 44| Reserved | - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - - - - - - - - - -Satran, et al. Standards Track [Page 169] - -RFC 3720 iSCSI April 2004 - - -10.15.1. Response - - Logout Response: - - 0 - connection or session closed successfully. - - 1 - CID not found. - - 2 - connection recovery is not supported. If Logout reason code - was recovery and target does not support it as indicated by the - ErrorRecoveryLevel. - - 3 - cleanup failed for various reasons. - -10.15.2. TotalAHSLength and DataSegmentLength - - For this PDU TotalAHSLength and DataSegmentLength MUST be 0. - -10.15.3. Time2Wait - - If the Logout Response code is 0 and if the operational - 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 if the operational ErrorRecoveryLevel is less - than 2, this field is to be ignored. - - This field is invalid if the Logout Response code is 1. - - 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. - - If Time2Wait is 0, the reassignment or a new Logout may be attempted - immediately. - -10.15.4. Time2Retain - - If the Logout response code is 0 and if the operational - ErrorRecoveryLevel is 2, this is the maximum amount of time, in - seconds, after the initial wait (Time2Wait), the target waits for the - allegiance reassignment for any active task after which the task - state is discarded. If the Logout response code is 0 and if the - operational ErrorRecoveryLevel is less than 2, this field is to be - ignored. - - This field is invalid if the Logout response code is 1. - - - - - -Satran, et al. Standards Track [Page 170] - -RFC 3720 iSCSI April 2004 - - - If the Logout response code is 2 or 3, this field specifies the - maximum amount of time, in seconds, after the initial wait - (Time2Wait), the target waits for a new implicit or explicit logout. - - If it is the last connection of a session, the whole session state is - discarded after Time2Retain. - - 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. - -10.16. SNACK Request - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x10 |1|.|.|.| Type | Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| LUN or Reserved | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag or 0xffffffff | - +---------------+---------------+---------------+---------------+ - 20| Target Transfer Tag or SNACK Tag or 0xffffffff | - +---------------+---------------+---------------+---------------+ - 24| Reserved | - +---------------+---------------+---------------+---------------+ - 28| ExpStatSN | - +---------------+---------------+---------------+---------------+ - 32/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 40| BegRun | - +---------------------------------------------------------------+ - 44| RunLength | - +---------------------------------------------------------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - If the implementation supports ErrorRecoveryLevel greater than zero, - it MUST support all SNACK types. - - - - - - -Satran, et al. Standards Track [Page 171] - -RFC 3720 iSCSI April 2004 - - - The SNACK is used by the initiator to request the retransmission of - numbered-responses, data, or R2T PDUs from the target. The SNACK - request indicates the numbered-responses or data "runs" whose - retransmission is requested by the target, where the run starts with - the first StatSN, DataSN, or R2TSN whose retransmission is requested - and indicates the number of Status, Data, or R2T PDUs requested - including the first. 0 has special meaning when used as a starting - number and length: - - - When used in RunLength, it means all PDUs starting with the - initial. - - When used in both BegRun and RunLength, it means all - unacknowledged PDUs. - - The numbered-response(s) or R2T(s), requested by a SNACK, MUST be - delivered as exact replicas of the ones that the target transmitted - originally except for the fields ExpCmdSN, MaxCmdSN, and ExpDataSN, - which MUST carry the current values. R2T(s)requested by SNACK MUST - also carry the current value of StatSN. - - The numbered Data-In PDUs, requested by a Data SNACK MUST be - delivered as exact replicas of the ones that the target transmitted - originally except for the fields ExpCmdSN and MaxCmdSN, which MUST - carry the current values and except for resegmentation (see Section - 10.16.3 Resegmentation). - - Any SNACK that requests a numbered-response, Data, or R2T that was - not sent by the target or was already acknowledged by the initiator, - MUST be rejected with a reason code of "Protocol error". - -10.16.1. Type - - This field encodes the SNACK function as follows: - - 0-Data/R2T SNACK - requesting retransmission of one or more Data- - In or R2T PDUs. - - 1-Status SNACK - requesting retransmission of one or more numbered - responses. - - 2-DataACK - positively acknowledges Data-In PDUs. - - 3-R-Data SNACK - requesting retransmission of Data-In PDUs with - possible resegmentation and status tagging. - - - - - - - -Satran, et al. Standards Track [Page 172] - -RFC 3720 iSCSI April 2004 - - - All other values are reserved. - - Data/R2T SNACK, Status SNACK, or R-Data SNACK for a command MUST - precede status acknowledgement for the given command. - -10.16.2. Data Acknowledgement - - If an initiator operates at ErrorRecoveryLevel 1 or higher, it MUST - issue a SNACK of type DataACK after receiving a Data-In PDU with the - A bit set to 1. However, if the initiator has detected holes in the - 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). - - The DataACK is used to free resources at the target and not to - request or imply data retransmission. - - An initiator MUST NOT request retransmission for any data it had - already acknowledged. - -10.16.3. Resegmentation - - If the initiator MaxRecvDataSegmentLength changed between the - original transmission and the time the initiator requests - retransmission, the initiator MUST issue a R-Data SNACK (see Section - 10.16.1 Type). 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 MAY be different from the ones originally sent in order - to reflect 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. - - 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 - example, if it has already sent a response containing another value - in the SNACK Tag field or had the status included in the last Data-In - PDU, it must send a new SCSI Response PDU. If a target sends more - than one SCSI Response PDU due to this rule, all SCSI responses must - carry the same StatSN (see Section 10.4.4 SNACK Tag). If an - initiator attempts to recover a lost SCSI Response (with a - Status SNACK, see Section 10.16.1 Type) 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. - - - -Satran, et al. Standards Track [Page 173] - -RFC 3720 iSCSI April 2004 - - - For considerations in allegiance reassignment of a task to a - connection with a different MaxRecvDataSegmentLength, refer to - Section 6.2.2 Allegiance Reassignment. - -10.16.4. Initiator Task Tag - - For Status SNACK and DataACK, the Initiator Task Tag MUST be set to - the reserved value 0xffffffff. In all other cases, the Initiator - Task Tag field MUST be set to the Initiator Task Tag of the - referenced command. - -10.16.5. Target Transfer Tag or SNACK Tag - - For an 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. - - 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. - - In all other cases, the Target Transfer Tag field MUST be set to the - reserved value of 0xffffffff. - -10.16.6. BegRun - - 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). - - BegRun 0 when used in conjunction with RunLength 0 means resend all - unacknowledged Data-In, R2T or Response PDUs. - - BegRun MUST be 0 for a R-Data SNACK. - -10.16.7. RunLength - - The number of PDUs whose retransmission is requested. - - RunLength 0 signals that all Data-In, R2T, or Response PDUs carrying - the numbers equal to or greater than BegRun have to be resent. - - The RunLength MUST also be 0 for a DataACK SNACK in addition to - R-Data SNACK. - - - - - -Satran, et al. Standards Track [Page 174] - -RFC 3720 iSCSI April 2004 - - -10.17. Reject - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x3f |1| Reserved | Reason | Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 16| 0xffffffff | - +---------------+---------------+---------------+---------------+ - 20| Reserved | - +---------------+---------------+---------------+---------------+ - 24| StatSN | - +---------------+---------------+---------------+---------------+ - 28| ExpCmdSN | - +---------------+---------------+---------------+---------------+ - 32| MaxCmdSN | - +---------------+---------------+---------------+---------------+ - 36| DataSN/R2TSN or Reserved | - +---------------+---------------+---------------+---------------+ - 40| Reserved | - +---------------+---------------+---------------+---------------+ - 44| Reserved | - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - xx/ Complete Header of Bad PDU / - +/ / - +---------------+---------------+---------------+---------------+ - yy/Vendor specific data (if any) / - / / - +---------------+---------------+---------------+---------------+ - zz| Data-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - Reject is used to indicate an iSCSI error condition (protocol, - unsupported option, etc.). - - - - - - - - - -Satran, et al. Standards Track [Page 175] - -RFC 3720 iSCSI April 2004 - - -10.17.1. Reason - - The reject Reason is coded as follows: - - +------+----------------------------------------+------------------+ - | Code | Explanation | Can the original | - | (hex)| | PDU be re-sent? | - +------+----------------------------------------+------------------+ - | 0x01 | Reserved | no | - | | | | - | 0x02 | Data (payload) Digest Error | yes (Note 1) | - | | | | - | 0x03 | SNACK Reject | yes | - | | | | - | 0x04 | Protocol Error (e.g., SNACK request for| no | - | | a status that was already acknowledged)| | - | | | | - | 0x05 | Command not supported | no | - | | | | - | 0x06 | Immediate Command Reject - too many | yes | - | | immediate commands | | - | | | | - | 0x07 | Task in progress | no | - | | | | - | 0x08 | Invalid Data ACK | no | - | | | | - | 0x09 | Invalid PDU field | no (Note 2) | - | | | | - | 0x0a | Long Operation Reject - Can't generate | yes | - | | Target Transfer Tag - out of resources | | - | | | | - | 0x0b | Negotiation Reset | no | - | | | | - | 0x0c | Waiting for Logout | no | - +------+----------------------------------------+------------------+ - - Note 1: For iSCSI, Data-Out PDU retransmission is only done if the - target requests retransmission with a recovery R2T. However, if this - is the data digest error on immediate data, the initiator may choose - to retransmit the whole PDU including the immediate data. - - Note 2: A target should use this reason code for all invalid values - of PDU fields that are meant to describe a task, a response, or a - data transfer. Some examples are invalid TTT/ITT, buffer offset, LUN - qualifying a TTT, and an invalid sequence number in a SNACK. - - All other values for Reason are reserved. - - - - -Satran, et al. Standards Track [Page 176] - -RFC 3720 iSCSI April 2004 - - - In all the cases in which a pre-instantiated SCSI task is terminated - because of the reject, the target MUST issue a proper SCSI command - response with CHECK CONDITION as described in Section 10.4.3 - Response. In these cases in which a status for the SCSI task was - already sent before the reject, no additional status is required. If - the error is detected while data from the initiator is still expected - (i.e., the command PDU did not contain all the data and the target - has not received a Data-Out PDU with the Final bit set to 1 for the - unsolicited data, if any, and all outstanding R2Ts, if any), the - target MUST wait until it receives the last expected Data-Out PDUs - with the F bit set to 1 before sending the Response PDU. - - For additional usage semantics of Reject PDU, see Section 6.3 Usage - Of Reject PDU in Recovery. - -10.17.2. DataSN/R2TSN - - This field is only valid if the rejected PDU is a Data/R2T SNACK and - the Reject reason code is "Protocol error" (see Section 10.16 SNACK - Request). The DataSN/R2TSN is the next Data/R2T sequence number that - the target would send for the task, if any. - -10.17.3. StatSN, ExpCmdSN and MaxCmdSN - - These fields carry their usual values and are not related to the - rejected command. StatSN is advanced after a Reject. - -10.17.4. Complete Header of Bad PDU - - The target returns the header (not including digest) of the PDU in - error as the data of the response. - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 177] - -RFC 3720 iSCSI April 2004 - - -10.18. NOP-Out - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|I| 0x00 |1| Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| LUN or Reserved | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag or 0xffffffff | - +---------------+---------------+---------------+---------------+ - 20| Target Transfer Tag or 0xffffffff | - +---------------+---------------+---------------+---------------+ - 24| CmdSN | - +---------------+---------------+---------------+---------------+ - 28| ExpStatSN | - +---------------+---------------+---------------+---------------+ - 32/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - / DataSegment - Ping Data (optional) / - +/ / - +---------------+---------------+---------------+---------------+ - | Data-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - A NOP-Out may be used by an initiator as a "ping request" to verify - that a connection/session is still active and all its components are - operational. The NOP-In response is the "ping echo". - - A NOP-Out is also sent by an initiator in response to a NOP-In. - - A NOP-Out may also be used to confirm a changed ExpStatSN if another - PDU will not be available for a long time. - - Upon receipt of a NOP-In with the Target Transfer Tag set to a valid - value (not the reserved 0xffffffff), the initiator MUST respond with - a NOP-Out. In this case, the NOP-Out Target Transfer Tag MUST - contain a copy of the NOP-In Target Transfer Tag. - - - - - -Satran, et al. Standards Track [Page 178] - -RFC 3720 iSCSI April 2004 - - -10.18.1. Initiator Task Tag - - The NOP-Out MUST have the Initiator Task Tag set to a valid value - only if a response in the form of 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. - - When a target receives the NOP-Out with a valid Initiator Task Tag, - it MUST respond with a Nop-In Response (see Section 10.19 NOP-In). - - 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. - -10.18.2. Target Transfer Tag - - A target assigned identifier for the operation. - - 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. - - When the Target Transfer Tag is set to a value other than 0xffffffff, - the LUN field MUST also be copied from the NOP-In. - -10.18.3. Ping Data - - Ping data are reflected in the NOP-In Response. The length of the - reflected data are limited to MaxRecvDataSegmentLength. The length - of ping data are indicated by the DataSegmentLength. 0 is a valid - value for the DataSegmentLength and indicates the absence of ping - data. - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 179] - -RFC 3720 iSCSI April 2004 - - -10.19. NOP-In - - Byte/ 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0|.|.| 0x20 |1| Reserved | - +---------------+---------------+---------------+---------------+ - 4|TotalAHSLength | DataSegmentLength | - +---------------+---------------+---------------+---------------+ - 8| LUN or Reserved | - + + - 12| | - +---------------+---------------+---------------+---------------+ - 16| Initiator Task Tag or 0xffffffff | - +---------------+---------------+---------------+---------------+ - 20| Target Transfer Tag or 0xffffffff | - +---------------+---------------+---------------+---------------+ - 24| StatSN | - +---------------+---------------+---------------+---------------+ - 28| ExpCmdSN | - +---------------+---------------+---------------+---------------+ - 32| MaxCmdSN | - +---------------+---------------+---------------+---------------+ - 36/ Reserved / - +/ / - +---------------+---------------+---------------+---------------+ - 48| Header-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - / DataSegment - Return Ping Data / - +/ / - +---------------+---------------+---------------+---------------+ - | Data-Digest (Optional) | - +---------------+---------------+---------------+---------------+ - - NOP-In is either sent by a target as a response to a NOP-Out, as a - "ping" to an initiator, or as a means to carry a changed ExpCmdSN - and/or MaxCmdSN if another PDU will not be available for a long time - (as determined by the target). - - When a target receives the NOP-Out with a valid Initiator Task Tag - (not the reserved value 0xffffffff), it MUST respond with a NOP-In - 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. - - - - - -Satran, et al. Standards Track [Page 180] - -RFC 3720 iSCSI April 2004 - - - Otherwise, when a target sends a NOP-In that is not a response to a - Nop-Out received from the initiator, the Initiator Task Tag MUST be - set to 0xffffffff and the Data Segment MUST NOT contain any data - (DataSegmentLength MUST be 0). - -10.19.1. Target Transfer Tag - - If the target is responding to a NOP-Out, this is set to the reserved - value 0xffffffff. - - 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 0xffffffff). - - If the target is initiating a NOP-In without wanting to receive a - corresponding NOP-Out, this field MUST hold the reserved value of - 0xffffffff. - -10.19.2. StatSN - - The StatSN field will always contain the next StatSN. However, when - the Initiator Task Tag is set to 0xffffffff, StatSN for the - connection is not advanced after this PDU is sent. - -10.19.3. LUN - - A LUN MUST be set to a correct value when the Target Transfer Tag is - valid (not the reserved value 0xffffffff). - -11. iSCSI Security Text Keys and Authentication Methods - - Only the following keys are used during the SecurityNegotiation stage - of the Login Phase: - - SessionType - InitiatorName - TargetName - TargetAddress - InitiatorAlias - TargetAlias - TargetPortalGroupTag - AuthMethod and the keys used by the authentication methods - specified under Section 11.1 AuthMethod along with all of - their associated keys as well as Vendor Specific - Authentication Methods. - - - - - - -Satran, et al. Standards Track [Page 181] - -RFC 3720 iSCSI April 2004 - - - Other keys MUST NOT be used. - - SessionType, InitiatorName, TargetName, InitiatorAlias, TargetAlias, - and TargetPortalGroupTag are described in Chapter 12 as they can be - used also in the OperationalNegotiation stage. - - All security keys have connection-wide applicability. - -11.1. AuthMethod - - Use: During Login - Security Negotiation Senders: Initiator and - Target Scope: connection - - AuthMethod = <list-of-values> - - The main item of security negotiation is the authentication method - (AuthMethod). - - The authentication methods that can be used (appear in the - list-of-values) are either those listed in the following table or are - vendor-unique methods: - - +------------------------------------------------------------+ - | Name | Description | - +------------------------------------------------------------+ - | KRB5 | Kerberos V5 - defined in [RFC1510] | - +------------------------------------------------------------+ - | SPKM1 | Simple Public-Key GSS-API Mechanism | - | | defined in [RFC2025] | - +------------------------------------------------------------+ - | SPKM2 | Simple Public-Key GSS-API Mechanism | - | | defined in [RFC2025] | - +------------------------------------------------------------+ - | 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. - - 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 - - - -Satran, et al. Standards Track [Page 182] - -RFC 3720 iSCSI April 2004 - - - selected. It follows that if the target makes the authentication - method proposal the initiator sends the first keys(s) of the exchange - together with its authentication method selection. - - 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. - - 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 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. - - Extension authentication methods MUST be named using one of the - following two formats: - - a) Z-reversed.vendor.dns_name.do_something= - b) Z<#><IANA-registered-string>= - - Authentication methods named using the Z- format are used as private - extensions. Authentication methods named using the Z# format are - used as public extensions that must be registered with IANA and MUST - be described by an informational RFC. - - For all of the public or private extension authentication methods, - the method specific keys MUST conform to the format specified in - Section 5.1 Text Format for standard-label. - - To identify the vendor for private extension authentication methods, - we suggest you use the reversed DNS-name as a prefix to the proper - digest names. - - The part of digest-name following Z- and Z# MUST conform to the - format for standard-label specified in Section 5.1 Text Format. - - Support for public or private extension authentication methods is - OPTIONAL. - - The following subsections define the specific exchanges for each of - the standardized authentication methods. As mentioned earlier the - first step is always done by the initiator. - - - - - -Satran, et al. Standards Track [Page 183] - -RFC 3720 iSCSI April 2004 - - -11.1.1. Kerberos - - For KRB5 (Kerberos V5) [RFC1510] and [RFC1964], the initiator MUST - use: - - KRB_AP_REQ=<KRB_AP_REQ> - - where KRB_AP_REQ is the client message as defined in [RFC1510]. - - 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/". - - 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: - - KRB_AP_REP=<KRB_AP_REP> - - where KRB_AP_REP is the server's response message as defined in - [RFC1510]. - - If mutual authentication was selected and target authentication - fails, the initiator MUST close the connection. - - 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. - -11.1.2. Simple Public-Key Mechanism (SPKM) - - For SPKM1 and SPKM2 [RFC2025], the initiator MUST use: - - SPKM_REQ=<SPKM-REQ> - - where SPKM-REQ is the first initiator token as defined in [RFC2025]. - - [RFC2025] defines situations where each side may send an error token - that may cause the peer to re-generate and resend its last token. - This scheme is followed in iSCSI, and the error token syntax is: - - SPKM_ERROR=<SPKM-ERROR> - - - - - - -Satran, et al. Standards Track [Page 184] - -RFC 3720 iSCSI April 2004 - - - However, SPKM-DEL tokens that are defined by [RFC2025] for fatal - errors will not be used by iSCSI. If the target needs to send a - SPKM-DEL token, it will, instead, send a Login "login reject" message - with the "Authentication Failure" status and terminate the - connection. If the initiator needs to send a SPKM-DEL token, it will - close the connection. - - In the following sections, we assume that no SPKM-ERROR tokens are - required. - - If the initiator authentication fails, the target MUST return an - error. Otherwise, if the AuthMethod is SPKM1 or if the initiator has - selected the mutual authentication option (by setting mutual-state - bit in the options field of the REQ-TOKEN in the SPKM-REQ), the - target MUST reply with: - - SPKM_REP_TI=<SPKM-REP-TI> - - where SPKM-REP-TI is the target token as defined in [RFC2025]. - - If mutual authentication was selected and target authentication - fails, the initiator MUST close the connection. Otherwise, if the - AuthMethod is SPKM1, the initiator MUST continue with: - - SPKM_REP_IT=<SPKM-REP-IT> - - where SPKM-REP-IT is the second initiator token as defined in - [RFC2025]. If the initiator authentication fails, the target MUST - answer with a Login reject with "Authentication Failure" status. - - SPKM requires support for very long authentication items. - - All the SPKM-* tokens 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. - -11.1.3. Secure Remote Password (SRP) - - For SRP [RFC2945], the initiator MUST use: - - SRP_U=<U> TargetAuth=Yes /* or TargetAuth=No */ - - The target MUST answer with a Login reject with the "Authorization - Failure" status or reply with: - - SRP_GROUP=<G1,G2...> SRP_s=<s> - - Where G1,G2... are proposed groups, in order of preference. - - - -Satran, et al. Standards Track [Page 185] - -RFC 3720 iSCSI April 2004 - - - The initiator MUST either close the connection or continue with: - - SRP_A=<A> SRP_GROUP=<G> - - 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: - - SRP_B=<B> - - The initiator MUST close the connection or continue with: - - SRP_M=<M> - - 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: - - SRP_HM=<H(A | M | K)> - - If the target authentication fails, the initiator MUST close the - connection. - - 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]. 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. - - 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, targets - MUST always offer "SRP-1536" as one of the proposed groups. - -11.1.4. Challenge Handshake Authentication Protocol (CHAP) - - For CHAP [RFC1994], in the first step, the initiator MUST send: - - CHAP_A=<A1,A2...> - - Where A1,A2... are proposed algorithms, in order of preference. - - - - - - -Satran, et al. Standards Track [Page 186] - -RFC 3720 iSCSI April 2004 - - - In the second step, the target MUST answer with a Login reject with - the "Authentication Failure" status or reply with: - - CHAP_A=<A> CHAP_I=<I> CHAP_C=<C> - - Where A is one of A1,A2... that were proposed by the initiator. - - In the third step, the initiator MUST continue with: - - CHAP_N=<N> CHAP_R=<R> - - or, if it requires target authentication, with: - - CHAP_N=<N> CHAP_R=<R> CHAP_I=<I> CHAP_C=<C> - - 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: - - CHAP_N=<N> CHAP_R=<R> - - If target authentication fails, the initiator MUST close the - connection. - - Where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, - Algorithm, Identifier, Challenge, and Response as defined in - [RFC1994], N is a text string, A,A1,A2, and I are numbers, and C and - R are large-binary-values and their binary length (not the length of - the character string that represents them in encoded form) MUST not - exceed 1024 bytes. - - For the Algorithm, as stated in [RFC1994], one value is required to - be implemented: - - 5 (CHAP with MD5) - - To guarantee interoperability, initiators MUST always offer it as one - of the proposed algorithms. - -12. Login/Text Operational Text Keys - - Some session specific parameters MUST only be carried on the leading - connection and cannot be changed after the leading connection login - (e.g., MaxConnections, the maximum number of connections). This - - - - - -Satran, et al. Standards Track [Page 187] - -RFC 3720 iSCSI April 2004 - - - holds for a single connection session with regard to connection - restart. The keys that fall into this category have the use: LO - (Leading Only). - - Keys that can only be used during login have the use: IO (initialize - only), while those that can be used in both the Login Phase and Full - Feature Phase have the use: ALL. - - Keys that can only be used during Full Feature Phase use FFPO (Full - Feature Phase only). - - Keys marked as Any-Stage may also appear in the SecurityNegotiation - stage while all other keys described in this chapter are operational - keys. - - Keys that do not require an answer are marked as Declarative. - - Key scope is indicated as session-wide (SW) or connection-only (CO). - - Result function, wherever mentioned, states the function that can be - applied to check the validity of the responder selection. Minimum - means that the selected value cannot exceed the offered value. - Maximum means that the selected value cannot be lower than the - offered value. AND means that the selected value must be a possible - result of a Boolean "and" function with an arbitrary Boolean value - (e.g., if the offered value is No the selected value must be No). OR - means that the selected value must be a possible result of a Boolean - "or" function with an arbitrary Boolean value (e.g., if the offered - value is Yes the selected value must be Yes). - -12.1. HeaderDigest and DataDigest - - Use: IO - Senders: Initiator and Target - Scope: CO - - HeaderDigest = <list-of-values> - DataDigest = <list-of-values> - - Default is None for both HeaderDigest and DataDigest. - - 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. - - - - - -Satran, et al. Standards Track [Page 188] - -RFC 3720 iSCSI April 2004 - - - The following table lists cyclic integrity checksums that can be - negotiated for the digests and that 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 | - +---------------------------------------------+ - - The generator polynomial for this digest is given in - hex-notation (e.g., 0x3b stands for 0011 1011 and the polynomial is - x**5+X**4+x**3+x+1). - - When the Initiator and Target agree on a digest, this digest MUST be - used for every PDU in Full Feature Phase. - - Padding bytes, when present in a segment covered by a CRC, SHOULD be - set to 0 and are included in the CRC. - - 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 M(x) of degree n-1; bit 7 of the lowest numbered - byte is considered the most significant bit (x^n-1), followed - by bit 6 of the lowest numbered byte through bit 0 of the - highest numbered byte (x^0). - - - The most significant 32 bits are complemented. - - - The polynomial is multiplied by x^32 then divided by G(x). The - generator polynomial produces a remainder R(x) of degree <= 31. - - - The coefficients of R(x) are considered a 32 bit sequence. - - - The bit sequence is complemented and the result is the CRC. - - - The CRC bits are mapped into the digest word. The x^31 - coefficient in bit 7 of the lowest numbered byte of the digest - continuing through to the byte up to the x^24 coefficient in - bit 0 of the lowest numbered byte, continuing with the x^23 - coefficient in bit 7 of next byte through x^0 in bit 0 of the - highest numbered byte. - - - - -Satran, et al. Standards Track [Page 189] - -RFC 3720 iSCSI April 2004 - - - - Computing the CRC over any segment (data or header) extended - to include the CRC built using the generator 0x11edc6f41 will - always 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]. - - 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 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. - - Extension digest algorithms MUST be named using one of the following - two formats: - - a) Y-reversed.vendor.dns_name.do_something= - b) Y<#><IANA-registered-string>= - - Digests named using the Y- format are used for private purposes - (unregistered). Digests named using the Y# format (public extension) - must be registered with IANA and MUST be described by an - informational RFC. - - For private extension digests, to identify the vendor, we suggest - you use the reversed DNS-name as a prefix to the proper digest - names. - - The part of digest-name following Y- and Y# MUST conform to the - format for standard-label specified in Section 5.1 Text Format. - - Support for public or private extension digests is OPTIONAL. - -12.2. MaxConnections - - 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. - - - -Satran, et al. Standards Track [Page 190] - -RFC 3720 iSCSI April 2004 - - - - Initiator and target negotiate the maximum number of connections - requested/acceptable. - -12.3. SendTargets - - Use: FFPO - Senders: Initiator - Scope: SW - - For a complete description, see Appendix D. - SendTargets - Operation -. - -12.4. TargetName - - Use: IO by initiator, FFPO by target - only as response to a - SendTargets, Declarative, Any-Stage - - Senders: Initiator and Target - Scope: SW - - TargetName=<iSCSI-name-value> - - Examples: - - TargetName=iqn.1993-11.com.disk-vendor:diskarrays.sn.45678 - TargetName=eui.020000023B040506 - - 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 TargetName key may also be returned by the "SendTargets" text - request (which is its only use when issued by a target). - - TargetName MUST not be redeclared within the login phase. - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 191] - -RFC 3720 iSCSI April 2004 - - -12.5. InitiatorName - - Use: IO, Declarative, Any-Stage - Senders: Initiator - Scope: SW - - InitiatorName=<iSCSI-name-value> - - Examples: - - InitiatorName=iqn.1992-04.com.os-vendor.plan9:cdrom.12345 - InitiatorName=iqn.2001-02.com.ssp.users:customer235.host90 - - 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. - - InitiatorName MUST not be redeclared within the login phase. - -12.6. TargetAlias - - Use: ALL, Declarative, Any-Stage - Senders: Target - Scope: SW - - TargetAlias=<iSCSI-local-name-value> - - Examples: - - TargetAlias=Bob-s Disk - TargetAlias=Database Server 1 Log Disk - TargetAlias=Web Server 3 Disk 20 - - 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 (see Section 12.21 - SessionType). This string is not used as an identifier, nor is it - meant to be used for authentication or authorization decisions. It - can be displayed by the initiator's user interface in a list of - targets to which it is connected. - - - - - - - - - - -Satran, et al. Standards Track [Page 192] - -RFC 3720 iSCSI April 2004 - - -12.7. InitiatorAlias - - Use: ALL, Declarative, Any-Stage - Senders: Initiator - Scope: SW - - InitiatorAlias=<iSCSI-local-name-value> - - Examples: - - InitiatorAlias=Web Server 4 - InitiatorAlias=spyalley.nsa.gov - InitiatorAlias=Exchange Server - - 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 - is not used as an identifier, nor is meant to be used for - authentication or authorization decisions. It can be displayed by - the target's user interface in a list of initiators to which it is - connected. - -12.8. TargetAddress - - Use: ALL, Declarative, Any-Stage - Senders: Target - Scope: SW - - TargetAddress=domainname[:port][,portal-group-tag] - - The domainname can be specified as either a DNS host name, a - dotted-decimal IPv4 address, or a bracketed IPv6 address as specified - in [RFC2732]. - - If the TCP port is not specified, it is assumed to be the - IANA-assigned default port for iSCSI (see Section 13 IANA - Considerations). - - 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. - - - - - - - - -Satran, et al. Standards Track [Page 193] - -RFC 3720 iSCSI April 2004 - - - 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=computingcenter.example.com,23 - - Use of the portal-group-tag is described in Appendix D. - - SendTargets Operation -. The formats for the port and - portal-group-tag are the same as the one specified in Section 12.9 - TargetPortalGroupTag. - -12.9. TargetPortalGroupTag - - Use: IO by target, Declarative, Any-Stage - Senders: Target - Scope: SW - - TargetPortalGroupTag=<16-bit-binary-value> - - Examples: - TargetPortalGroupTag=1 - - The target portal group tag 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. - - For the complete usage expectations of this key see Section 5.3 Login - Phase. - -12.10. InitialR2T - - Use: LO - Senders: Initiator and Target - Scope: SW - Irrelevant when: SessionType=Discovery - - InitialR2T=<boolean-value> - - Examples: - - I->InitialR2T=No - T->InitialR2T=No - - - - -Satran, et al. Standards Track [Page 194] - -RFC 3720 iSCSI April 2004 - - - Default is Yes. - Result function is OR. - - The InitialR2T key is used to turn off the default use of R2T for - unidirectional 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). - - 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 - PDUs) can be sent unsolicited (i.e., not requiring an explicit R2T). - -12.11. ImmediateData - - Use: LO - Senders: Initiator and Target - Scope: SW - Irrelevant when: SessionType=Discovery - - ImmediateData=<boolean-value> - - Default is Yes. - Result function is AND. - - The initiator and target negotiate support for immediate data. To - turn immediate data off, the initiator or target must state its - desire to do so. ImmediateData can be turned on if both the - initiator and target have ImmediateData=Yes. - - 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. - - 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. - - 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. - - - - - -Satran, et al. Standards Track [Page 195] - -RFC 3720 iSCSI April 2004 - - - The following table is a summary of unsolicited data options: - - +----------+-------------+------------------+--------------+ - |InitialR2T|ImmediateData| Unsolicited |Immediate Data| - | | | Data Out PDUs | | - +----------+-------------+------------------+--------------+ - | No | No | Yes | No | - +----------+-------------+------------------+--------------+ - | No | Yes | Yes | Yes | - +----------+-------------+------------------+--------------+ - | Yes | No | No | No | - +----------+-------------+------------------+--------------+ - | Yes | Yes | No | Yes | - +----------+-------------+------------------+--------------+ - -12.12. MaxRecvDataSegmentLength - - Use: ALL, Declarative - Senders: Initiator and Target - Scope: CO - - MaxRecvDataSegmentLength=<numerical-value-512-to-(2**24-1)> - - Default is 8192 bytes. - - The initiator or target declares the maximum data segment length in - bytes it can receive in an iSCSI PDU. - - The transmitter (initiator or target) is required to send PDUs with a - data segment that does not exceed MaxRecvDataSegmentLength of the - receiver. - - A target receiver is additionally limited by MaxBurstLength for - solicited data and FirstBurstLength for unsolicited data. An - initiator MUST NOT send solicited PDUs exceeding MaxBurstLength nor - unsolicited PDUs exceeding FirstBurstLength (or - FirstBurstLength-Immediate Data Length if immediate data were sent). - -12.13. MaxBurstLength - - Use: LO - Senders: Initiator and Target - Scope: SW - Irrelevant when: SessionType=Discovery - - MaxBurstLength=<numerical-value-512-to-(2**24-1)> - - - - - -Satran, et al. Standards Track [Page 196] - -RFC 3720 iSCSI April 2004 - - - Default is 262144 (256 Kbytes). - Result function is Minimum. - - The initiator and target negotiate 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 that end - with a Data-In or Data-Out PDU with the F bit set to one. - -12.14. FirstBurstLength - - Use: LO - Senders: Initiator and Target - Scope: SW - Irrelevant when: SessionType=Discovery - Irrelevant when: ( InitialR2T=Yes and ImmediateData=No ) - - FirstBurstLength=<numerical-value-512-to-(2**24-1)> - - Default is 65536 (64 Kbytes). - Result function is Minimum. - - 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. - - FirstBurstLength MUST NOT exceed MaxBurstLength. - -12.15. DefaultTime2Wait - - Use: LO - Senders: Initiator and Target - Scope: SW - - DefaultTime2Wait=<numerical-value-0-to-3600> - - Default is 2. - Result function is Maximum. - - 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. - - A value of 0 indicates that logout or active task reassignment can be - attempted immediately. - - - - -Satran, et al. Standards Track [Page 197] - -RFC 3720 iSCSI April 2004 - - -12.16. DefaultTime2Retain - - Use: LO Senders: Initiator and Target Scope: SW - - DefaultTime2Retain=<numerical-value-0-to-3600> - - Default is 20. Result function is Minimum. - - 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. - - This value is also the session state timeout if the connection in - question is the last LOGGED_IN connection in the session. - - A value of 0 indicates that connection/task state is immediately - discarded by the target. - -12.17. MaxOutstandingR2T - - 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. - - 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 PDU - (with the F bit set to 1) is transferred, or a sequence reception - timeout (Section 6.1.4.1 Recovery Within-command) is encountered for - that data sequence. - -12.18. DataPDUInOrder - - Use: LO - Senders: Initiator and Target - Scope: SW - Irrelevant when: SessionType=Discovery - - DataPDUInOrder=<boolean-value> - - - - - -Satran, et al. Standards Track [Page 198] - -RFC 3720 iSCSI April 2004 - - - Default is Yes. - Result function is OR. - - 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 - overlays are forbidden. - -12.19. DataSequenceInOrder - - Use: LO - Senders: Initiator and Target - Scope: SW - Irrelevant when: SessionType=Discovery - - DataSequenceInOrder=<boolean-value> - - Default is Yes. - Result function is OR. - - 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 one. A Data-Out - sequence is sent either unsolicited or in response to an R2T. - Sequences cover an offset-range. - - If DataSequenceInOrder is set to No, Data PDU sequences may be - transferred in any order. - - 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). - - 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 - not 0 and DataSequenceInOrder is set to Yes then MaxOustandingR2T - MUST be set to 1. - -12.20. ErrorRecoveryLevel - - Use: LO - Senders: Initiator and Target - Scope: SW - - ErrorRecoveryLevel=<numerical-value-0-to-2> - - - - - -Satran, et al. Standards Track [Page 199] - -RFC 3720 iSCSI April 2004 - - - Default is 0. - Result function is Minimum. - - 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. - - In the description of recovery mechanisms, certain recovery classes - are specified. Section 6.1.5 Error Recovery Hierarchy describes the - mapping between the classes and the levels. - -12.21. SessionType - - Use: LO, Declarative, Any-Stage - Senders: Initiator - Scope: SW - - SessionType= <Discovery|Normal> - - Default is Normal. - - The initiator indicates the type of session it wants to create. The - target can either accept it or reject it. - - 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". - - The discovery session implies MaxConnections = 1 and overrides both - the default and an explicit setting. - -12.22. The Private or Public Extension Key Format - - Use: ALL - Senders: Initiator and Target - Scope: specific key dependent - - X-reversed.vendor.dns_name.do_something= - - or - - X<#><IANA-registered-string>= - - - - - - -Satran, et al. Standards Track [Page 200] - -RFC 3720 iSCSI April 2004 - - - Keys with this format are used for public or private extension - purposes. These keys always start with X- if unregistered with IANA - (private) or X# if registered with IANA (public). - - For unregistered keys, to identify the vendor, we suggest you use the - reversed DNS-name as a prefix to the key-proper. - - The part of key-name following X- and X# MUST conform to the format - for key-name specified in Section 5.1 Text Format. - - For IANA registered keys the string following X# must be registered - with IANA and the use of the key MUST be described by an - informational RFC. - - Vendor specific keys MUST ONLY be used in normal sessions. - - Support for public or private extension keys is OPTIONAL. - -13. IANA Considerations - - This section conforms to [RFC2434]. - - The well-known user TCP port number for iSCSI connections assigned by - IANA is 3260 and this is the default iSCSI port. Implementations - needing a system TCP port number may use port 860, the port assigned - by IANA as the iSCSI system port; however in order to use port 860, - it MUST be explicitly specified - implementations MUST NOT default to - use of port 860, as 3260 is the only allowed default. - - Extension keys, authentication methods, or digest types for which a - vendor or group of vendors intend to provide publicly available - descriptions MUST be described by an RFC and MUST be registered with - IANA. - - The IANA has set up the following three registries: - - a) iSCSI extended key registry - b) iSCSI authentication methods registry - c) iSCSI digests registry - - [RFC3723] also instructs IANA to maintain a registry for the values - of the SRP_GROUP key. The format of these values must conform to the - one specified for iSCSI extension item-label in Section 13.5.4 - Standard iSCSI extension item-label format. - - - - - - - -Satran, et al. Standards Track [Page 201] - -RFC 3720 iSCSI April 2004 - - - For the iSCSI authentication methods registry and the iSCSI digests - registry, IANA MUST also assign a 16-bit unsigned integer number (the - method number for the authentication method and the digest number for - the digest). - - The following initial values for the registry for authentication - methods are specified by the standards action of this document: - - Authentication Method | Number | - +----------------------------------------+--------+ - | CHAP | 1 | - +----------------------------------------+--------+ - | SRP | 2 | - +----------------------------------------+--------+ - | KRB5 | 3 | - +----------------------------------------+--------+ - | SPKM1 | 4 | - +----------------------------------------+--------+ - | SPKM2 | 5 | - +----------------------------------------+--------+ - - All other record numbers from 0 to 255 are reserved. IANA will - register numbers above 255. - - Authentication methods with numbers above 255 MUST be unique within - the registry and MUST be used with the prefix Z#. - - - The following initial values for the registry for digests are - specified by the standards action of this document: - - Digest | Number | - +----------------------------------------+--------+ - | CRC32C | 1 | - +----------------------------------------+--------+ - - All other record numbers from 0 to 255 are reserved. IANA will - register numbers above 255. - - Digests with numbers above 255 MUST be unique within the registry and - MUST be used with the prefix Y#. - - The RFC that describes the item to be registered MUST indicate in the - IANA Considerations section the string and iSCSI registry to which it - should be recorded. - - Extension Keys, Authentication Methods, and digests (iSCSI extension - items) must conform to a number of requirements as described below. - - - -Satran, et al. Standards Track [Page 202] - -RFC 3720 iSCSI April 2004 - - -13.1. Naming Requirements - - Each iSCSI extension item must have a unique name in its category. - This name will be used as a standard-label for the key, access - method, or digest and must conform to the syntax specified in Section - 13.5.4 Standard iSCSI extension item-label format for iSCSI extension - item-labels. - -13.2. Mechanism Specification Requirements - - For iSCSI extension items all of the protocols and procedures used by - a given iSCSI extension item must be described, either in the - specification of the iSCSI extension item itself or in some other - publicly available specification, in sufficient detail for the iSCSI - extension item to be implemented by any competent implementor. Use - of secret and/or proprietary methods in iSCSI extension items are - expressly prohibited. In addition, the restrictions imposed by - [RFC1602] on the standardization of patented algorithms must be - respected. - -13.3. Publication Requirements - - All iSCSI extension items must be described by an RFC. The RFC may - be informational rather than Standards-Track, although Standards - Track review and approval are encouraged for all iSCSI extension - items. - -13.4. Security Requirements - - Any known security issues that arise from the use of the iSCSI - extension item must be completely and fully described. It is not - required that the iSCSI extension item be secure or that it be free - from risks, but that the known risks be identified. Publication of a - new iSCSI extension item does not require an exhaustive security - review, and the security considerations section is subject to - continuing evaluation. - - Additional security considerations should be addressed by publishing - revised versions of the iSCSI extension item specification. - - For each of these registries, IANA must record the registered string, - which MUST conform to the format rules described in Section 13.5.4 - Standard iSCSI extension item-label format for iSCSI extension - item-labels, and the RFC number that describes it. The key prefix - (X#, Y# or Z#) is not part of the recorded string. - - - - - - -Satran, et al. Standards Track [Page 203] - -RFC 3720 iSCSI April 2004 - - -13.5. Registration Procedure - - Registration of a new iSCSI extension item starts with the - construction of an Internet Draft to become an RFC. - -13.5.1. Present the iSCSI extension item to the Community - - Send a proposed access type specification to the IPS WG mailing list, - or if the IPS WG is disbanded at the registration time, to a mailing - list designated by the IETF Transport Area Director for a review - period of a month. The intent of the public posting is to solicit - comments and feedback on the iSCSI extension item specification and a - review of any security considerations. - -13.5.2. iSCSI extension item review and IESG approval - - When the one month period has passed, the IPS WG chair or a person - nominated by the IETF Transport Area Director (the iSCSI extension - item reviewer) forwards the Internet Draft to the IESG for - publication as an informational RFC or rejects it. If the - specification is a standards track document, the usual IETF - procedures for such documents are followed. - - Decisions made by the iSCSI extension item reviewer must be published - within two weeks after the month-long review period. Decisions made - by the iSCSI extension item reviewer can be appealed through the IESG - appeal process. - -13.5.3. IANA Registration - - Provided that the iSCSI extension item has either passed review or - has been successfully appealed to the IESG, and the specification is - published as an RFC, then IANA will register the iSCSI extension item - and make the registration available to the community. - -13.5.4. Standard iSCSI extension item-label format - - The following character symbols are used iSCSI extension item-labels - (the hexadecimal values represent Unicode code points): - - (a-z, A-Z) - letters - (0-9) - digits - "." (0x2e) - dot - "-" (0x2d) - minus - "+" (0x2b) - plus - "@" (0x40) - commercial at - "_" (0x5f) - underscore - - - - -Satran, et al. Standards Track [Page 204] - -RFC 3720 iSCSI April 2004 - - - An iSCSI extension item-label is a string of one or more characters - that consist of letters, digits, dot, minus, plus, commercial at, or - underscore. An iSCSI extension item-label MUST begin with a capital - letter and must not exceed 63 characters. - -13.6. IANA Procedures for Registering iSCSI extension items - - The identity of the iSCSI extension item reviewer is communicated to - the IANA by the IESG. Then, the IANA only acts in response to iSCSI - extension item definitions that are approved by the iSCSI extension - item reviewer and forwarded by the reviewer to the IANA for - registration, or in response to a communication from the IESG that an - iSCSI extension item definition appeal has overturned the iSCSI - extension item reviewer's ruling. - -References - -Normative References - - [CAM] ANSI X3.232-199X, Common Access Method-3. - - [EUI] "Guidelines for 64-bit Global Identifier (EUI-64)", - http: - //standards.ieee.org/regauth/oui/tutorials/EUI64.html - - [OUI] "IEEE OUI and Company_Id Assignments", - http://standards.ieee.org/regauth/oui - - [RFC791] Postel, J., "Internet Protocol", STD 5, RFC 791, - September 1981. - - [RFC793] Postel, J., "Transmission Control Protocol", STD 7, - RFC 793, September 1981. - - [RFC1035] Mockapetris, P., "Domain Names - Implementation and - Specification", STD 13, RFC 1035, November 1987. - - [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts- - Communication Layer", STD 3, RFC 1122, October 1989. - - [RFC1510] Kohl, J. and C. Neuman, "The Kerberos Network - Authentication Service (V5)", RFC 1510, September - 1993. - - [RFC1737] Sollins, K. and L. Masinter "Functional Requirements - for Uniform Resource Names"RFC 1737, December 1994. - - - - - -Satran, et al. Standards Track [Page 205] - -RFC 3720 iSCSI April 2004 - - - [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", - RFC 1964, June 1996. - - [RFC1982] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC - 1982, August 1996. - - [RFC1994] Simpson, W., "PPP Challenge Handshake Authentication - Protocol (CHAP)", RFC 1994, August 1996. - - [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism - (SPKM)", RFC 2025, October 1996. - - [RFC2045] Borenstein, N. and N. Freed, "MIME (Multipurpose - Internet Mail Extensions) Part One: Mechanisms for - Specifying and Describing the Format of Internet - Message Bodies", RFC 2045, November 1996. - - [RFC2119] Bradner, S. "Key Words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC2279] Yergeau, F., "UTF-8, a Transformation Format of ISO - 10646", RFC 2279 October 1996. - - [RFC2373] Hinden, R. and S. Deering, "IP Version 6 Addressing - Architecture", RFC 2373, July 1998. - - [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter "Uniform - Resource Identifiers", RFC 2396, August 1998. - - [RFC2401] Kent, S. and R. Atkinson, "Security Architecture for - the Internet Protocol", RFC 2401, November 1998. - - [RFC2404] Madson, C. and R. Glenn, "The Use of HMAC-SHA-1-96 - within ESP and AH", RFC 2404, November 1998. - - [RFC2406] Kent, S. and R. Atkinson, "IP Encapsulating Security - Payload (ESP)", RFC 2406, November 1998. - - [RFC2407] Piper, D., "The Internet IP Security Domain of - Interpretation of ISAKMP", RFC 2407, November 1998. - - [RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange - (IKE)", RFC2409, November 1998. - - [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing - an IANA Considerations Section in RFCs.", BCP 26, RFC - 2434, October 1998. - - - - -Satran, et al. Standards Track [Page 206] - -RFC 3720 iSCSI April 2004 - - - [RFC2451] Pereira, R. and R. Adams " The ESP CBC-Mode Cipher - Algorithms", RFC 2451, November 1998. - - [RFC2732] Hinden, R., Carpenter, B. and L. Masinter, "Format for - Literal IPv6 Addresses in URL's", RFC 2451, December - 1999. - - [RFC2945] Wu, T., "The SRP Authentication and Key Exchange - System", RFC 2945, September 2000. - - [RFC3066] Alvestrand, H., "Tags for the Identification of - Languages", STD 47, RFC 3066, January 2001. - - [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ("stringprep")", RFC 3454, - December 2002. - - [RFC3566] Frankel, S. and H. Herbert, "The AES-XCBC-MAC-96 - Algorithm and Its Use With IPsec", RFC 3566, September - 2003. - - [RFC3686] Housley, R., "Using Advanced Encryption Standard (AES) - Counter Mode with IPsec Encapsulating Security Payload - (ESP)", RFC 3686, January 2004. - - [RFC3722] Bakke, M., "String Profile for Internet Small Computer - Systems Interface (iSCSI) Names", RFC 3722, March - 2004. - - [RFC3723] Aboba, B., Tseng, J., Walker, J., Rangan, V. and F. - Travostino, "Securing Block Storage Protocols over - IP", RFC 3723, March 2004. - - [SAM2] T10/1157D, SCSI Architecture Model - 2 (SAM-2). - - [SBC] NCITS.306-1998, SCSI-3 Block Commands (SBC). - - [SPC3] T10/1416-D, SCSI Primary Commands-3. - - [UNICODE] Unicode Standard Annex #15, "Unicode Normalization - Forms", http://www.unicode.org/unicode/reports/tr15 - - - - - - - - - - -Satran, et al. Standards Track [Page 207] - -RFC 3720 iSCSI April 2004 - - -Informative References - - [BOOT] P. Sarkar, et al., "Bootstrapping Clients using the - iSCSI Protocol", Work in Progress, July 2003. - - [Castagnoli93] G. Castagnoli, S. Braeuer and M. Herrman "Optimization - of Cyclic Redundancy-Check Codes with 24 and 32 Parity - Bits", IEEE Transact. on Communications, Vol. 41, No. - 6, June 1993. - - [CORD] Chadalapaka, M. and R. Elliott, "SCSI Command - Ordering Considerations with iSCSI", Work in Progress. - - [RFC3347] Krueger, M., Haagens, R., Sapuntzakis, C. and M. - Bakke, "Small Computer Systems Interface protocol over - the Internet (iSCSI) Requirements and Design - Considerations", RFC 3347, July 2002. - - [RFC3385] Sheinwald, D., Staran, J., Thaler, P. and V. Cavanna, - "Internet Protocol Small Computer System Interface - (iSCSI) Cyclic Redundancy Check (CRC)/Checksum - Considerations", RFC 3385, September 2002. - - [RFC3721] Bakke M., Hafner, J., Hufferd, J., Voruganti, K. and - M. Krueger, "Internet Small Computer Systems Interface - (iSCSI) Naming and Discovery, RFC 3721, March 2004. - - [SEQ-EXT] Kent, S., "IP Encapsulating Security Payload (ESP)", - Work in Progress, July 2002. - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 208] - -RFC 3720 iSCSI April 2004 - - -Appendix A. Sync and Steering with Fixed Interval Markers - - This appendix presents a simple scheme for synchronization (PDU - boundary retrieval). It uses markers that include synchronization - information placed at fixed intervals in the TCP stream. - - A Marker consists of: - - Byte / 0 | 1 | 2 | 3 | - / | | | | - |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| - +---------------+---------------+---------------+---------------+ - 0| Next-iSCSI-PDU-start pointer - copy #1 | - +---------------+---------------+---------------+---------------+ - 4| Next-iSCSI-PDU-start pointer - copy #2 | - +---------------+---------------+---------------+---------------+ - - The Marker scheme uses payload byte stream counting that includes - every byte placed by iSCSI in the TCP stream except for the markers - themselves. It also excludes any bytes that TCP counts but are not - originated by iSCSI. - - Markers MUST NOT be included in digest calculation. - - The Marker indicates the offset to the next iSCSI PDU header. The - Marker is eight bytes in length and contains two 32-bit offset fields - that indicate how many bytes to skip in the TCP stream in order to - find the next iSCSI PDU header. The marker uses two copies of the - pointer so that a marker that spans a TCP packet boundary should - leave at least one valid copy in one of the packets. - - The structure and semantics of an inserted marker are independent of - the marker interval. - - The use of markers is negotiable. The initiator and target MAY - indicate their readiness to receive and/or send markers during login - separately for each connection. The default is No. - -A.1. Markers At Fixed Intervals - - A marker is inserted at fixed intervals in the TCP byte stream. - During login, each end of the iSCSI session specifies the interval at - which it is willing to receive the marker, or it disables the marker - altogether. If a receiver indicates that it desires a marker, the - sender MAY agree (during negotiation) and provide the marker at the - desired interval. However, in certain environments, a sender that - does not provide markers to a receiver that wants markers may suffer - an appreciable performance degradation. - - - -Satran, et al. Standards Track [Page 209] - -RFC 3720 iSCSI April 2004 - - - The marker interval and the initial marker-less interval are counted - in terms of the bytes placed in the TCP stream data by iSCSI. - - When reduced to iSCSI terms, markers MUST indicate the offset to a - 4-byte word boundary in the stream. The least significant two bits - of each marker word are reserved and are considered 0 for offset - computation. - - Padding iSCSI PDU payloads to 4-byte word boundaries simplifies - marker manipulation. - -A.2. Initial Marker-less Interval - - To enable the connection setup including the Login Phase negotiation, - marking (if any) is only started at the first marker interval after - the end of the Login Phase. However, in order to enable the marker - inclusion and exclusion mechanism to work without knowledge of the - length of the Login Phase, the first marker will be placed in the TCP - stream as if the Marker-less interval had included markers. - - Thus, all markers appear in the stream at locations conforming to the - formula: [(MI + 8) * n - 8] where MI = Marker Interval, n = integer - number. - - For example, if the marker interval is 512 bytes and the login ended - at byte 1003 (first iSCSI placed byte is 0), the first marker will be - inserted after byte 1031 in the stream. - -A.3. Negotiation - - The following operational key=value pairs are used to negotiate the - fixed interval markers. The direction (output or input) is relative - to the initiator. - -A.3.1. OFMarker, IFMarker - - Use: IO - Senders: Initiator and Target - Scope: CO - - OFMarker=<boolean-value> - IFMarker=<boolean-value> - - Default is No. - - Result function is AND. - - - - - -Satran, et al. Standards Track [Page 210] - -RFC 3720 iSCSI April 2004 - - - OFMarker is used to turn on or off the initiator to target markers - on the connection. IFMarker is used to turn on or off the target to - initiator markers on the connection. - - Examples: - - I->OFMarker=Yes,IFMarker=Yes - T->OFMarker=Yes,IFMarker=Yes - - Results in the Marker being used in both directions while: - - I->OFMarker=Yes,IFMarker=Yes - T->OFMarker=Yes,IFMarker=No - - Results in Marker being used from the initiator to the target, but - not from the target to initiator. - -A.3.2. OFMarkInt, IFMarkInt - - Use: IO - Senders: Initiator and Target - Scope: CO - OFMarkInt is Irrelevant when: OFMarker=No - IFMarkInt is Irrelevant when: IFMarker=No - - Offering: - - OFMarkInt=<numeric-range-from-1-to-65535> - IFMarkInt=<numeric-range-from-1-to-65535> - - Responding: - - OFMarkInt=<numeric-value-from-1-to-65535>|Reject - IFMarkInt=<numeric-value-from-1-to-65535>|Reject - - OFMarkInt is used to set the interval for the initiator to target - markers on the connection. IFMarkInt is used to set the interval for - the target to initiator markers on the connection. - - For the offering, the initiator or target indicates the minimum to - maximum interval (in 4-byte words) it wants the markers for one or - both directions. In case it only wants a specific value, only a - single value has to be specified. The responder selects a value - within the minimum and maximum offered or the only value offered or - indicates through the xFMarker key=value its inability to set and/or - receive markers. When the interval is unacceptable the responder - answers with "Reject". Reject is resetting the marker function in - the specified direction (Output or Input) to No. - - - -Satran, et al. Standards Track [Page 211] - -RFC 3720 iSCSI April 2004 - - - The interval is measured from the end of a marker to the beginning of - the next marker. For example, a value of 1024 means 1024 words (4096 - bytes of iSCSI payload between markers). - - The default is 2048. - -Appendix B. Examples - -B.1. Read Operation Example - - +------------------+-----------------------+----------------------+ - |Initiator Function| PDU Type | Target Function | - +------------------+-----------------------+----------------------+ - | Command request |SCSI Command (READ)>>> | | - | (read) | | | - +------------------+-----------------------+----------------------+ - | | |Prepare Data Transfer | - +------------------+-----------------------+----------------------+ - | Receive Data | <<< SCSI Data-In | Send Data | - +------------------+-----------------------+----------------------+ - | Receive Data | <<< SCSI Data-In | Send Data | - +------------------+-----------------------+----------------------+ - | Receive Data | <<< SCSI Data-In | Send Data | - +------------------+-----------------------+----------------------+ - | | <<< SCSI Response |Send Status and Sense | - +------------------+-----------------------+----------------------+ - | Command Complete | | | - +------------------+-----------------------+----------------------+ - - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 212] - -RFC 3720 iSCSI April 2004 - - -B.2. Write Operation Example - - +------------------+-----------------------+---------------------+ - |Initiator Function| PDU Type | Target Function | - +------------------+-----------------------+---------------------+ - | Command request |SCSI Command (WRITE)>>>| Receive command | - | (write) | | and queue it | - +------------------+-----------------------+---------------------+ - | | | Process old commands| - +------------------+-----------------------+---------------------+ - | | | Ready to process | - | | <<< R2T | WRITE command | - +------------------+-----------------------+---------------------+ - | Send Data | SCSI Data-Out >>> | Receive Data | - +------------------+-----------------------+---------------------+ - | | <<< R2T | Ready for data | - +------------------+-----------------------+---------------------+ - | | <<< R2T | Ready for data | - +------------------+-----------------------+---------------------+ - | Send Data | SCSI Data-Out >>> | Receive Data | - +------------------+-----------------------+---------------------+ - | Send Data | SCSI Data-Out >>> | Receive Data | - +------------------+-----------------------+---------------------+ - | | <<< SCSI Response |Send Status and Sense| - +------------------+-----------------------+---------------------+ - | Command Complete | | | - +------------------+-----------------------+---------------------+ - - - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 213] - -RFC 3720 iSCSI April 2004 - - -B.3. R2TSN/DataSN Use Examples - - Output (write) data DataSN/R2TSN Example - - +------------------+-----------------------+----------------------+ - |Initiator Function| PDU Type & Content | Target Function | - +------------------+-----------------------+----------------------+ - | Command request |SCSI Command (WRITE)>>>| Receive command | - | (write) | | and queue it | - +------------------+-----------------------+----------------------+ - | | | Process old commands | - +------------------+-----------------------+----------------------+ - | | <<< R2T | Ready for data | - | | R2TSN = 0 | | - +------------------+-----------------------+----------------------+ - | | <<< R2T | Ready for more data | - | | R2TSN = 1 | | - +------------------+-----------------------+----------------------+ - | Send Data | SCSI Data-Out >>> | Receive Data | - | for R2TSN 0 | DataSN = 0, F=0 | | - +------------------+-----------------------+----------------------+ - | Send Data | SCSI Data-Out >>> | Receive Data | - | for R2TSN 0 | DataSN = 1, F=1 | | - +------------------+-----------------------+----------------------+ - | Send Data | SCSI Data >>> | Receive Data | - | for R2TSN 1 | DataSN = 0, F=1 | | - +------------------+-----------------------+----------------------+ - | | <<< SCSI Response |Send Status and Sense | - | | ExpDataSN = 0 | | - +------------------+-----------------------+----------------------+ - | Command Complete | | | - +------------------+-----------------------+----------------------+ - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 214] - -RFC 3720 iSCSI April 2004 - - - Input (read) data DataSN Example - - +------------------+-----------------------+----------------------+ - |Initiator Function| PDU Type | Target Function | - +------------------+-----------------------+----------------------+ - | Command request |SCSI Command (READ)>>> | | - | (read) | | | - +------------------+-----------------------+----------------------+ - | | | Prepare Data Transfer| - +------------------+-----------------------+----------------------+ - | Receive Data | <<< SCSI Data-In | Send Data | - | | DataSN = 0, F=0 | | - +------------------+-----------------------+----------------------+ - | Receive Data | <<< SCSI Data-In | Send Data | - | | DataSN = 1, F=0 | | - +------------------+-----------------------+----------------------+ - | Receive Data | <<< SCSI Data-In | Send Data | - | | DataSN = 2, F=1 | | - +------------------+-----------------------+----------------------+ - | | <<< SCSI Response |Send Status and Sense | - | | ExpDataSN = 3 | | - +------------------+-----------------------+----------------------+ - | Command Complete | | | - +------------------+-----------------------+----------------------+ - - - - - - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 215] - -RFC 3720 iSCSI April 2004 - - - Bidirectional DataSN Example - - +------------------+-----------------------+----------------------+ - |Initiator Function| PDU Type | Target Function | - +------------------+-----------------------+----------------------+ - | Command request |SCSI Command >>> | | - | (Read-Write) | Read-Write | | - +------------------+-----------------------+----------------------+ - | | | Process old commands | - +------------------+-----------------------+----------------------+ - | | <<< R2T | Ready to process | - | | R2TSN = 0 | WRITE command | - +------------------+-----------------------+----------------------+ - | * Receive Data | <<< SCSI Data-In | Send Data | - | | DataSN = 1, F=0 | | - +------------------+-----------------------+----------------------+ - | * Receive Data | <<< SCSI Data-In | Send Data | - | | DataSN = 2, F=1 | | - +------------------+-----------------------+----------------------+ - | * Send Data | SCSI Data-Out >>> | Receive Data | - | for R2TSN 0 | DataSN = 0, F=1 | | - +------------------+-----------------------+----------------------+ - | | <<< SCSI Response |Send Status and Sense | - | | ExpDataSN = 3 | | - +------------------+-----------------------+----------------------+ - | Command Complete | | | - +------------------+-----------------------+----------------------+ - - *) Send data and Receive Data may be transferred simultaneously as in - an atomic Read-Old-Write-New or sequentially as in an atomic - Read-Update-Write (in the latter case the R2T may follow the received - data). - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 216] - -RFC 3720 iSCSI April 2004 - - - Unsolicited and immediate output (write) data with DataSN Example - - +------------------+-----------------------+----------------------+ - |Initiator Function| PDU Type & Content | Target Function | - +------------------+-----------------------+----------------------+ - | Command request |SCSI Command (WRITE)>>>| Receive command | - | (write) |F=0 | and data | - |+ Immediate data | | and queue it | - +------------------+-----------------------+----------------------+ - | Send Unsolicited | SCSI Write Data >>> | Receive more Data | - | Data | DataSN = 0, F=1 | | - +------------------+-----------------------+----------------------+ - | | | Process old commands | - +------------------+-----------------------+----------------------+ - | | <<< R2T | Ready for more data | - | | R2TSN = 0 | | - +------------------+-----------------------+----------------------+ - | Send Data | SCSI Write Data >>> | Receive Data | - | for R2TSN 0 | DataSN = 0, F=1 | | - +------------------+-----------------------+----------------------+ - | | <<< SCSI Response |Send Status and Sense | - | | | | - +------------------+-----------------------+----------------------+ - | Command Complete | | | - +------------------+-----------------------+----------------------+ - -B.4. CRC Examples - - N.B. all Values are Hexadecimal - - 32 bytes of zeroes: - - Byte: 0 1 2 3 - - 0: 00 00 00 00 - ... - 28: 00 00 00 00 - - CRC: aa 36 91 8a - - 32 bytes of ones: - - Byte: 0 1 2 3 - - 0: ff ff ff ff - ... - 28: ff ff ff ff - - - - -Satran, et al. Standards Track [Page 217] - -RFC 3720 iSCSI April 2004 - - - CRC: 43 ab a8 62 - - 32 bytes of incrementing 00..1f: - - Byte: 0 1 2 3 - - 0: 00 01 02 03 - ... - 28: 1c 1d 1e 1f - - CRC: 4e 79 dd 46 - - 32 bytes of decrementing 1f..00: - - Byte: 0 1 2 3 - - 0: 1f 1e 1d 1c - ... - 28: 03 02 01 00 - - CRC: 5c db 3f 11 - - An iSCSI - SCSI Read (10) Command PDU - - Byte: 0 1 2 3 - - 0: 01 c0 00 00 - 4: 00 00 00 00 - 8: 00 00 00 00 - 12: 00 00 00 00 - 16: 14 00 00 00 - 20: 00 00 04 00 - 24: 00 00 00 14 - 28: 00 00 00 18 - 32: 28 00 00 00 - 36: 00 00 00 00 - 40: 02 00 00 00 - 44: 00 00 00 00 - - CRC: 56 3a 96 d9 - - - - - - - - - - - -Satran, et al. Standards Track [Page 218] - -RFC 3720 iSCSI April 2004 - - -Appendix C. Login Phase Examples - - In the first example, the initiator and target authenticate each - other via Kerberos: - - I-> Login (CSG,NSG=0,1 T=1) - InitiatorName=iqn.1999-07.com.os:hostid.77 - TargetName=iqn.1999-07.com.example:diskarray.sn.88 - AuthMethod=KRB5,SRP,None - - T-> Login (CSG,NSG=0,0 T=0) - AuthMethod=KRB5 - - I-> Login (CSG,NSG=0,1 T=1) - KRB_AP_REQ=<krb_ap_req> - - (krb_ap_req contains the Kerberos V5 ticket and authenticator - with MUTUAL-REQUIRED set in the ap-options field) - - If the authentication is successful, the target proceeds with: - - T-> Login (CSG,NSG=0,1 T=1) - KRB_AP_REP=<krb_ap_rep> - - (krb_ap_rep is the Kerberos V5 mutual authentication reply) - - If the authentication is successful, the initiator may proceed - with: - - I-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=8192 - T-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=4096 - MaxBurstLength=8192 - I-> Login (CSG,NSG=1,0 T=0) MaxBurstLength=8192 - ... more iSCSI Operational Parameters - - T-> Login (CSG,NSG=1,0 T=0) - ... more iSCSI Operational Parameters - - And at the end: - - I-> Login (CSG,NSG=1,3 T=1) - optional iSCSI parameters - - T-> Login (CSG,NSG=1,3 T=1) "login accept" - - - - - - - -Satran, et al. Standards Track [Page 219] - -RFC 3720 iSCSI April 2004 - - - If the initiator's authentication by the target is not - successful, the target responds with: - - T-> Login "login reject" - - instead of the Login KRB_AP_REP message, and terminates the - connection. - - If the target's authentication by the initiator is not - successful, the initiator terminates the connection (without - responding to the Login KRB_AP_REP message). - - In the next example only the initiator is authenticated by the - target via Kerberos: - - I-> Login (CSG,NSG=0,1 T=1) - InitiatorName=iqn.1999-07.com.os:hostid.77 - TargetName=iqn.1999-07.com.example:diskarray.sn.88 - AuthMethod=SRP,KRB5,None - - T-> Login-PR (CSG,NSG=0,0 T=0) - AuthMethod=KRB5 - - I-> Login (CSG,NSG=0,1 T=1) - KRB_AP_REQ=krb_ap_req - - (MUTUAL-REQUIRED not set in the ap-options field of krb_ap_req) - - If the authentication is successful, the target proceeds with: - - T-> Login (CSG,NSG=0,1 T=1) - - I-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - T-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - . . . - - T-> Login (CSG,NSG=1,3 T=1)"login accept" - - - - - - - - - - -Satran, et al. Standards Track [Page 220] - -RFC 3720 iSCSI April 2004 - - - In the next example, the initiator and target authenticate each - other via SPKM1: - - I-> Login (CSG,NSG=0,1 T=1) - InitiatorName=iqn.1999-07.com.os:hostid.77 - TargetName=iqn.1999-07.com.example:diskarray.sn.88 - AuthMethod=SPKM1,KRB5,None - - T-> Login (CSG,NSG=0,0 T=0) - AuthMethod=SPKM1 - - I-> Login (CSG,NSG=0,0 T=0) - SPKM_REQ=<spkm-req> - - (spkm-req is the SPKM-REQ token with the mutual-state bit in the - options field of the REQ-TOKEN set) - - T-> Login (CSG,NSG=0,0 T=0) - SPKM_REP_TI=<spkm-rep-ti> - - If the authentication is successful, the initiator proceeds: - - I-> Login (CSG,NSG=0,1 T=1) - SPKM_REP_IT=<spkm-rep-it> - - If the authentication is successful, the target proceeds with: - - T-> Login (CSG,NSG=0,1 T=1) - - The initiator may proceed: - - I-> Login (CSG,NSG=1,0 T=0) ... iSCSI parameters - T-> Login (CSG,NSG=1,0 T=0) ... iSCSI parameters - - And at the end: - - I-> Login (CSG,NSG=1,3 T=1) - optional iSCSI parameters - - T-> Login (CSG,NSG=1,3 T=1) "login accept" - - - If the target's authentication by the initiator is not - successful, the initiator terminates the connection (without - responding to the Login SPKM_REP_TI message). - - - - - - -Satran, et al. Standards Track [Page 221] - -RFC 3720 iSCSI April 2004 - - - If the initiator's authentication by the target is not - successful, the target responds with: - - T-> Login "login reject" - - instead of the Login "proceed and change stage" message, and - terminates the connection. - - - In the next example, the initiator and target authenticate each - other via SPKM2: - - I-> Login (CSG,NSG=0,0 T=0) - InitiatorName=iqn.1999-07.com.os:hostid.77 - TargetName=iqn.1999-07.com.example:diskarray.sn.88 - AuthMethod=SPKM1,SPKM2 - - T-> Login-PR (CSG,NSG=0,0 T=0) - AuthMethod=SPKM2 - - I-> Login (CSG,NSG=0,1 T=1) - SPKM_REQ=<spkm-req> - - (spkm-req is the SPKM-REQ token with the mutual-state bit in the - options field of the REQ-TOKEN not set) - - If the authentication is successful, the target proceeds with: - - T-> Login (CSG,NSG=0,1 T=1) - - The initiator may proceed: - - I-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - T-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - And at the end: - - I-> Login (CSG,NSG=1,3 T=1) - optional iSCSI parameters - - T-> Login (CSG,NSG=1,3 T=1) "login accept" - - - - - - - -Satran, et al. Standards Track [Page 222] - -RFC 3720 iSCSI April 2004 - - - In the next example, the initiator and target authenticate each - other via SRP: - - I-> Login (CSG,NSG=0,1 T=1) - InitiatorName=iqn.1999-07.com.os:hostid.77 - TargetName=iqn.1999-07.com.example:diskarray.sn.88 - AuthMethod=KRB5,SRP,None - - T-> Login-PR (CSG,NSG=0,0 T=0) - AuthMethod=SRP - - I-> Login (CSG,NSG=0,0 T=0) - SRP_U=<user> - TargetAuth=Yes - - T-> Login (CSG,NSG=0,0 T=0) - SRP_GROUP=SRP-1536,SRP-1024 - SRP_s=<s> - - I-> Login (CSG,NSG=0,0 T=0) - SRP_GROUP=SRP-1536 - SRP_A=<A> - - T-> Login (CSG,NSG=0,0 T=0) - SRP_B=<B> - - I-> Login (CSG,NSG=0,1 T=1) - SRP_M=<M> - - If the initiator authentication is successful, the target - proceeds: - - T-> Login (CSG,NSG=0,1 T=1) - SRP_HM=<H(A | M | K)> - - Where N, g, s, A, B, M, and H(A | M | K) are defined in [RFC2945]. - - If the target authentication is not successful, the initiator - terminates the connection; otherwise, it proceeds. - - I-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - T-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - - - - - -Satran, et al. Standards Track [Page 223] - -RFC 3720 iSCSI April 2004 - - - And at the end: - - I-> Login (CSG,NSG=1,3 T=1) - optional iSCSI parameters - - T-> Login (CSG,NSG=1,3 T=1) "login accept" - - If the initiator authentication is not successful, the target - responds with: - - T-> Login "login reject" - - Instead of the T-> Login SRP_HM=<H(A | M | K)> message and - terminates the connection. - - In the next example, the initiator and target authenticate each - other via SRP: - - I-> Login (CSG,NSG=0,1 T=1) - InitiatorName=iqn.1999-07.com.os:hostid.77 - TargetName=iqn.1999-07.com.example:diskarray.sn.88 - AuthMethod=KRB5,SRP,None - - T-> Login-PR (CSG,NSG=0,0 T=0) - AuthMethod=SRP - - I-> Login (CSG,NSG=0,0 T=0) - SRP_U=<user> - TargetAuth=No - - T-> Login (CSG,NSG=0,0 T=0) - SRP_GROUP=SRP-1536 - SRP_s=<s> - - I-> Login (CSG,NSG=0,0 T=0) - SRP_GROUP=SRP-1536 - SRP_A=<A> - - T-> Login (CSG,NSG=0,0 T=0) - SRP_B=<B> - - I-> Login (CSG,NSG=0,1 T=1) - SRP_M=<M> - - If the initiator authentication is successful, the target - proceeds: - - T-> Login (CSG,NSG=0,1 T=1) - - - -Satran, et al. Standards Track [Page 224] - -RFC 3720 iSCSI April 2004 - - - - I-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - T-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - And at the end: - - I-> Login (CSG,NSG=1,3 T=1) - optional iSCSI parameters - - T-> Login (CSG,NSG=1,3 T=1) "login accept" - - In the next example the initiator and target authenticate each other - via CHAP: - - I-> Login (CSG,NSG=0,0 T=0) - InitiatorName=iqn.1999-07.com.os:hostid.77 - TargetName=iqn.1999-07.com.example:diskarray.sn.88 - AuthMethod=KRB5,CHAP,None - - T-> Login-PR (CSG,NSG=0,0 T=0) - AuthMethod=CHAP - - I-> Login (CSG,NSG=0,0 T=0) - CHAP_A=<A1,A2> - - T-> Login (CSG,NSG=0,0 T=0) - CHAP_A=<A1> - CHAP_I=<I> - CHAP_C=<C> - - I-> Login (CSG,NSG=0,1 T=1) - CHAP_N=<N> - CHAP_R=<R> - CHAP_I=<I> - CHAP_C=<C> - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 225] - -RFC 3720 iSCSI April 2004 - - - If the initiator authentication is successful, the target - proceeds: - - T-> Login (CSG,NSG=0,1 T=1) - CHAP_N=<N> - CHAP_R=<R> - - If the target authentication is not successful, the initiator - aborts the connection; otherwise, it proceeds. - - I-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - T-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - And at the end: - - I-> Login (CSG,NSG=1,3 T=1) - optional iSCSI parameters - - T-> Login (CSG,NSG=1,3 T=1) "login accept" - - If the initiator authentication is not successful, the target - responds with: - - T-> Login "login reject" - - Instead of the Login CHAP_R=<response> "proceed and change - stage" message and terminates the connection. - - In the next example, only the initiator is authenticated by the - target via CHAP: - - I-> Login (CSG,NSG=0,1 T=0) - InitiatorName=iqn.1999-07.com.os:hostid.77 - TargetName=iqn.1999-07.com.example:diskarray.sn.88 - AuthMethod=KRB5,CHAP,None - - T-> Login-PR (CSG,NSG=0,0 T=0) - AuthMethod=CHAP - - I-> Login (CSG,NSG=0,0 T=0) - CHAP_A=<A1,A2> - - - - - - - - -Satran, et al. Standards Track [Page 226] - -RFC 3720 iSCSI April 2004 - - - T-> Login (CSG,NSG=0,0 T=0) - CHAP_A=<A1> - CHAP_I=<I> - CHAP_C=<C> - - I-> Login (CSG,NSG=0,1 T=1) - CHAP_N=<N> - CHAP_R=<R> - - If the initiator authentication is successful, the target - proceeds: - - T-> Login (CSG,NSG=0,1 T=1) - - I-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - T-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - And at the end: - - I-> Login (CSG,NSG=1,3 T=1) - optional iSCSI parameters - - T-> Login (CSG,NSG=1,3 T=1) "login accept" - - In the next example, the initiator does not offer any security - parameters. It therefore may offer iSCSI parameters on the Login PDU - with the T bit set to 1, and the target may respond with a final - Login Response PDU immediately: - - I-> Login (CSG,NSG=1,3 T=1) - InitiatorName=iqn.1999-07.com.os:hostid.77 - TargetName=iqn.1999-07.com.example:diskarray.sn.88 - ... iSCSI parameters - - T-> Login (CSG,NSG=1,3 T=1) "login accept" - ... ISCSI parameters - - In the next example, the initiator does offer security - parameters on the Login PDU, but the target does not choose - any (i.e., chooses the "None" values): - - I-> Login (CSG,NSG=0,1 T=1) - InitiatorName=iqn.1999-07.com.os:hostid.77 - TargetName=iqn.1999-07.com.example:diskarray.sn.88 - AuthMethod=KRB5,SRP,None - - - -Satran, et al. Standards Track [Page 227] - -RFC 3720 iSCSI April 2004 - - - - T-> Login-PR (CSG,NSG=0,1 T=1) - AuthMethod=None - - I-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - T-> Login (CSG,NSG=1,0 T=0) - ... iSCSI parameters - - And at the end: - - I-> Login (CSG,NSG=1,3 T=1) - optional iSCSI parameters - - T-> Login (CSG,NSG=1,3 T=1) "login accept" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 228] - -RFC 3720 iSCSI April 2004 - - -Appendix D. SendTargets Operation - - 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. - - 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. - - 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 (target name and - IP address-port pairs and portal group tags) for the targets on the - target network entity which the requesting initiator is authorized to - access. - - 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 as it sees fit. - - 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 or operational session. - - The value must be one of: - - All - - The initiator is requesting that information on all relevant - targets known to the implementation be returned. This value - MUST be supported on a discovery session, and MUST NOT be - supported on an operational session. - - - - - - -Satran, et al. Standards Track [Page 229] - -RFC 3720 iSCSI April 2004 - - - <iSCSI-target-name> - - If an iSCSI target name is specified, the session should respond - with addresses for only the named target, if possible. This - value MUST be supported on discovery sessions. A discovery - session MUST be capable of returning addresses for those - targets that would have been returned had value=All had been - designated. - - <nothing> - - The session should only respond with addresses for the target 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. - - 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 - the TargetName text key, followed by a list of TargetAddress text - 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. - - For the format of the TargetName, see Section 12.4 TargetName. - - In a discovery session, a target 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. - - A SendTargets response MUST NOT contain target names if there are no - targets for the requesting initiator to access. - - Each target record returned includes zero or more TargetAddress - fields. - - Each target record starts with one text key of the form: - - TargetName=<target-name-goes-here> - - Followed by zero or more address keys of the form: - - TargetAddress=<hostname-or-ipaddress>[:<tcp-port>], - <portal-group-tag> - - The hostname-or-ipaddress contains a domain name, IPv4 address, or - IPv6 address, as specified for the TargetAddress key. - - - -Satran, et al. Standards Track [Page 230] - -RFC 3720 iSCSI April 2004 - - - 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). - - Each TargetAddress belongs to a portal group, identified by its - numeric portal group tag (as in Section 12.9 TargetPortalGroupTag). - 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. - - Multiple-connection sessions can span iSCSI addresses that belong to - the same portal group. - - Multiple-connection sessions cannot span iSCSI addresses that belong - to different portal groups. - - 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. - - A SendTargets text response can be longer than a single Text Response - PDU, and makes use of the long text responses as specified. - - After obtaining a list of targets from the discovery target 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: - - This example is the SendTargets response from a single target that - has no other interface ports. - - Initiator sends text request that contains: - - SendTargets=All - - Target sends a text response that contains: - - TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 - - All the target had to return in the simple case was the target name. - It is assumed by the initiator that the IP address and TCP port for - this target are the same as used on the current connection to the - default iSCSI target. - - - - - -Satran, et al. Standards Track [Page 231] - -RFC 3720 iSCSI April 2004 - - - The next example has two internal iSCSI targets, each accessible via - two different ports with different IP addresses. The following is - the text response: - - TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 - TargetAddress=10.1.0.45:3000,1 TargetAddress=10.1.1.45:3000,2 - TargetName=iqn.1993-11.com.example:diskarray.sn.1234567 - TargetAddress=10.1.0.45:3000,1 TargetAddress=10.1.1.45:3000,2 - - 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 - own portal group tag; they do not support spanning - multiple-connection sessions with each other. Keep in mind that the - 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. - - In the above example, a DNS host name or an IPv6 address could have - been returned instead of an IPv4 address. - - The next text response shows a target that supports spanning sessions - across multiple addresses, and further illustrates the use of the - portal group tags: - - TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 - - TargetAddress=10.1.0.45:3000,1 TargetAddress=10.1.1.46:3000,1 - TargetAddress=10.1.0.47:3000,2 TargetAddress=10.1.1.48:3000,2 - TargetAddress=10.1.1.49:3000,3 - - 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. - - 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. - - - - - - - - - - -Satran, et al. Standards Track [Page 232] - -RFC 3720 iSCSI April 2004 - - -Appendix E. Algorithmic Presentation of Error Recovery Classes - - This appendix illustrates the error recovery classes using a - pseudo-programming-language. The procedure names are chosen to be - obvious to most implementers. Each of the recovery classes described - has initiator procedures as well as target procedures. These - algorithms focus on outlining the mechanics of error recovery - classes, and do not exhaustively describe all other aspects/cases. - Examples of this approach are: - - - - Handling for only certain Opcode types is shown. - - - Only certain reason codes (e.g., Recovery in Logout command) - are outlined. - - - Resultant cases, such as recovery of Synchronization on a - header digest error are considered out-of-scope in these - algorithms. In this particular example, a header digest error - may lead to connection recovery if some type of sync and - steering layer is not implemented. - - These algorithms strive to convey the iSCSI error recovery concepts - in the simplest terms, and are not designed to be optimal. - -E.1. General Data Structure and Procedure Description - - This section defines the procedures and data structures that are - commonly used by all the error recovery algorithms. The structures - may not be the exhaustive representations of what is required for a - typical implementation. - - Data structure definitions - - struct TransferContext { - int TargetTransferTag; - int ExpectedDataSN; - }; - - struct TCB { /* task control block */ - Boolean SoFarInOrder; - int ExpectedDataSN; /* used for both R2Ts, and Data */ - int MissingDataSNList[MaxMissingDPDU]; - Boolean FbitReceived; - Boolean StatusXferd; - Boolean CurrentlyAllegiant; - int ActiveR2Ts; - int Response; - char *Reason; - - - -Satran, et al. Standards Track [Page 233] - -RFC 3720 iSCSI April 2004 - - - struct TransferContext - TransferContextList[MaxOutStandingR2T]; - int InitiatorTaskTag; - int CmdSN; - - int SNACK_Tag; - - }; - - struct Connection { - struct Session SessionReference; - Boolean SoFarInOrder; - int CID; - int State; - - int CurrentTimeout; - int ExpectedStatSN; - int MissingStatSNList[MaxMissingSPDU]; - Boolean PerformConnectionCleanup; - }; - - struct Session { - int NumConnections; - int CmdSN; - int Maxconnections; - int ErrorRecoveryLevel; - struct iSCSIEndpoint OtherEndInfo; - struct Connection ConnectionList[MaxSupportedConns]; - }; - - Procedure descriptions - - Receive-a-In-PDU(transport connection, inbound PDU); - check-basic-validity(inbound PDU); - Start-Timer(timeout handler, argument, timeout value); - Build-And-Send-Reject(transport connection, bad PDU, reason code); - -E.2. Within-command Error Recovery Algorithms - -E.2.1. Procedure Descriptions - - Recover-Data-if-Possible(last required DataSN, task control - block); - Build-And-Send-DSnack(task control block); - Build-And-Send-RDSnack(task control block); - Build-And-Send-Abort(task control block); - SCSI-Task-Completion(task control block); - Build-And-Send-A-Data-Burst(transport connection, data-descriptor, - task control block); - - - -Satran, et al. Standards Track [Page 234] - -RFC 3720 iSCSI April 2004 - - - Build-And-Send-R2T(transport connection, data-descriptor, - task control block); - Build-And-Send-Status(transport connection, task control block); - Transfer-Context-Timeout-Handler(transfer context); - - - Notes: - - - One procedure used in this section: Handle-Status-SNACK- - request is defined in Within-connection recovery algorithms. - - - The Response processing pseudo-code, shown in the target - algorithms, applies to all solicited PDUs that carry StatSN - - SCSI Response, Text Response etc. - -E.2.2. Initiator Algorithms - -Recover-Data-if-Possible(LastRequiredDataSN, TCB) -{ - if (operational ErrorRecoveryLevel > 0) { - if (# of missing PDUs is trackable) { - Note the missing DataSNs in TCB. - if (the task spanned a change in - MaxRecvDataSegmentLength) { - if (TCB.StatusXferd is TRUE) - drop the status PDU; - Build-And-Send-RDSnack(TCB); - } else { - Build-And-Send-DSnack(TCB); - } - } else { - TCB.Reason = "Protocol service CRC error"; - } - } else { - TCB.Reason = "Protocol service CRC error"; - } - if (TCB.Reason == "Protocol service CRC error") { - Clear the missing PDU list in the TCB. - if (TCB.StatusXferd is not TRUE) - Build-And-Send-Abort(TCB); - } -} - -Receive-a-In-PDU(Connection, CurrentPDU) -{ - check-basic-validity(CurrentPDU); - if (Header-Digest-Bad) discard, return; - Retrieve TCB for CurrentPDU.InitiatorTaskTag. - - - -Satran, et al. Standards Track [Page 235] - -RFC 3720 iSCSI April 2004 - - - if ((CurrentPDU.type == Data) - or (CurrentPDU.type = R2T)) { - if (Data-Digest-Bad for Data) { - send-data-SNACK = TRUE; - LastRequiredDataSN = CurrentPDU.DataSN; - } else { - if (TCB.SoFarInOrder = TRUE) { - if (current DataSN is expected) { - Increment TCB.ExpectedDataSN. - } else { - - TCB.SoFarInOrder = FALSE; - send-data-SNACK = TRUE; - } - } else { - if (current DataSN was considered missing) { - remove current DataSN from missing PDU list. - } else if (current DataSN is higher than expected) -{ - send-data-SNACK = TRUE; - } else { - discard, return; - } - Adjust TCB.ExpectedDataSN if appropriate. - } - LastRequiredDataSN = CurrentPDU.DataSN - 1; - } - if (send-data-SNACK is TRUE and - task is not already considered failed) { - Recover-Data-if-Possible(LastRequiredDataSN, TCB); - } - if (missing data PDU list is empty) { - TCB.SoFarInOrder = TRUE; - } - if (CurrentPDU.type == R2T) { - Increment ActiveR2Ts for this task. - - Create a data-descriptor for the data burst. - Build-And-Send-A-Data-Burst(Connection, data-descriptor, - - TCB); - } - } else if (CurrentPDU.type == Response) { - if (Data-Digest-Bad) { - send-status-SNACK = TRUE; - } else { - TCB.StatusXferd = TRUE; - Store the status information in TCB. - - - -Satran, et al. Standards Track [Page 236] - -RFC 3720 iSCSI April 2004 - - - if (ExpDataSN does not match) { - TCB.SoFarInOrder = FALSE; - Recover-Data-if-Possible(current DataSN, TCB); - } - if (missing data PDU list is empty) { - TCB.SoFarInOrder = TRUE; - } - } - } else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT - SHOWN */ - } - if ((TCB.SoFarInOrder == TRUE) and - (TCB.StatusXferd == TRUE)) { - SCSI-Task-Completion(TCB); - } -} - -E.2.3. Target Algorithms - -Receive-a-In-PDU(Connection, CurrentPDU) -{ - check-basic-validity(CurrentPDU); - if (Header-Digest-Bad) discard, return; - Retrieve TCB for CurrentPDU.InitiatorTaskTag. - if (CurrentPDU.type == Data) { - Retrieve TContext from CurrentPDU.TargetTransferTag; - if (Data-Digest-Bad) { - Build-And-Send-Reject(Connection, CurrentPDU, - Payload-Digest-Error); - Note the missing data PDUs in MissingDataRange[]. - send-recovery-R2T = TRUE; - } else { - if (current DataSN is not expected) { - Note the missing data PDUs in MissingDataRange[]. - send-recovery-R2T = TRUE; - } - if (CurrentPDU.Fbit == TRUE) { - if (current PDU is solicited) { - Decrement TCB.ActiveR2Ts. - } - if ((current PDU is unsolicited and - data received is less than I/O length and - data received is less than FirstBurstLength) - or (current PDU is solicited and the length of - this burst is less than expected)) { - send-recovery-R2T = TRUE; - Note the missing data in MissingDataRange[]. - } - - - -Satran, et al. Standards Track [Page 237] - -RFC 3720 iSCSI April 2004 - - - } - } - Increment TContext.ExpectedDataSN. - if (send-recovery-R2T is TRUE and - task is not already considered failed) { - if (operational ErrorRecoveryLevel > 0) { - Increment TCB.ActiveR2Ts. - Create a data-descriptor for the data burst - from MissingDataRange. - Build-And-Send-R2T(Connection, data-descriptor, TCB); - } else { - if (current PDU is the last unsolicited) - TCB.Reason = "Not enough unsolicited data"; - else - TCB.Reason = "Protocol service CRC error"; - } - } - if (TCB.ActiveR2Ts == 0) { - Build-And-Send-Status(Connection, TCB); - } - } else if (CurrentPDU.type == SNACK) { - snack-failure = FALSE; - if (operational ErrorRecoveryLevel > 0) { - if (CurrentPDU.type == Data/R2T) { - if (the request is satisfiable) { - - if (request for Data) { - Create a data-descriptor for the data burst - from BegRun and RunLength. - Build-And-Send-A-Data-Burst(Connection, - - data-descriptor, TCB); - } else { /* R2T */ - Create a data-descriptor for the data burst - from BegRun and RunLength. - Build-And-Send-R2T(Connection, data-descriptor, - TCB); - } - } else { - snack-failure = TRUE; - } - } else if (CurrentPDU.type == status) { - Handle-Status-SNACK-request(Connection, CurrentPDU); - } else if (CurrentPDU.type == DataACK) { - Consider all data upto CurrentPDU.BegRun as - acknowledged. - Free up the retransmission resources for that data. - } else if (CurrentPDU.type == R-Data SNACK) { - - - -Satran, et al. Standards Track [Page 238] - -RFC 3720 iSCSI April 2004 - - - Create a data descriptor for a data burst covering - all unacknowledged data. - Build-And-Send-A-Data-Burst(Connection, - data-descriptor, TCB); - TCB.SNACK_Tag = CurrentPDU.SNACK_Tag; - if (there's no more data to send) { - Build-And-Send-Status(Connection, TCB); - } - } - } else { /* operational ErrorRecoveryLevel = 0 */ - snack-failure = TRUE; - - } - if (snack-failure == TRUE) { - Build-And-Send-Reject(Connection, CurrentPDU, - SNACK-Reject); - if (TCB.StatusXferd != TRUE) { - TCB.Reason = "SNACK Rejected"; - Build-And-Send-Status(Connection, TCB); - } - } - - } else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT SHOWN */ - } -} - -Transfer-Context-Timeout-Handler(TContext) -{ - Retrieve TCB and Connection from TContext. - Decrement TCB.ActiveR2Ts. - if (operational ErrorRecoveryLevel > 0 and - task is not already considered failed) { - Note the missing data PDUs in MissingDataRange[]. - Create a data-descriptor for the data burst - from MissingDataRange[]. - Build-And-Send-R2T(Connection, data-descriptor, TCB); - } else { - TCB.Reason = "Protocol service CRC error"; - if (TCB.ActiveR2Ts = 0) { - Build-And-Send-Status(Connection, TCB); - } - } -} - - - - - - - - -Satran, et al. Standards Track [Page 239] - -RFC 3720 iSCSI April 2004 - - -E.3. Within-connection Recovery Algorithms - -E.3.1. Procedure Descriptions - -Procedure descriptions: -Recover-Status-if-Possible(transport connection, - currently received PDU); -Evaluate-a-StatSN(transport connection, currently received PDU); -Retransmit-Command-if-Possible(transport connection, CmdSN); -Build-And-Send-SSnack(transport connection); -Build-And-Send-Command(transport connection, task control block); -Command-Acknowledge-Timeout-Handler(task control block); -Status-Expect-Timeout-Handler(transport connection); -Build-And-Send-Nop-Out(transport connection); -Handle-Status-SNACK-request(transport connection, status SNACK -PDU); -Retransmit-Status-Burst(status SNACK, task control block); -Is-Acknowledged(beginning StatSN, run length); - -Implementation-specific tunables: -InitiatorProactiveSNACKEnabled - - Notes: - - - The initiator algorithms only deal with unsolicited Nop-In PDUs - for generating status SNACKs. A solicited Nop-In PDU has an - assigned StatSN, which, when out of order, could trigger the - out of order StatSN handling in Within-command algorithms, - again leading to Recover-Status-if-Possible. - - - - The pseudo-code shown may result in the retransmission of - unacknowledged commands in more cases than necessary. This - will not, however, affect the correctness of the operation - because the target is required to discard the duplicate CmdSNs. - - - The procedure Build-And-Send-Async is defined in the Connection - recovery algorithms. - - - The procedure Status-Expect-Timeout-Handler describes how - initiators may proactively attempt to retrieve the Status if - they so choose. This procedure is assumed to be triggered much - before the standard ULP timeout. - - - - - - - - -Satran, et al. Standards Track [Page 240] - -RFC 3720 iSCSI April 2004 - - -E.3.2. Initiator Algorithms - -Recover-Status-if-Possible(Connection, CurrentPDU) -{ - if ((Connection.state == LOGGED_IN) and - connection is not already considered failed) { - if (operational ErrorRecoveryLevel > 0) { - if (# of missing PDUs is trackable) { - Note the missing StatSNs in Connection - that were not already requested with SNACK; - Build-And-Send-SSnack(Connection); - } else { - Connection.PerformConnectionCleanup = TRUE; - } - } else { - Connection.PerformConnectionCleanup = TRUE; - } - if (Connection.PerformConnectionCleanup == TRUE) { - Start-Timer(Connection-Cleanup-Handler, Connection, 0); - } - } -} - -Retransmit-Command-if-Possible(Connection, CmdSN) -{ - - if (operational ErrorRecoveryLevel > 0) { - Retrieve the InitiatorTaskTag, and thus TCB for the CmdSN. - Build-And-Send-Command(Connection, TCB); - } -} - -Evaluate-a-StatSN(Connection, CurrentPDU) -{ - send-status-SNACK = FALSE; - if (Connection.SoFarInOrder == TRUE) { - if (current StatSN is the expected) { - Increment Connection.ExpectedStatSN. - } else { - Connection.SoFarInOrder = FALSE; - send-status-SNACK = TRUE; - } - } else { - if (current StatSN was considered missing) { - remove current StatSN from the missing list. - } else { - if (current StatSN is higher than expected){ - send-status-SNACK = TRUE; - - - -Satran, et al. Standards Track [Page 241] - -RFC 3720 iSCSI April 2004 - - - } else { - send-status-SNACK = FALSE; - discard the PDU; - } - } - Adjust Connection.ExpectedStatSN if appropriate. - if (missing StatSN list is empty) { - Connection.SoFarInOrder = TRUE; - } - } - return send-status-SNACK; -} - -Receive-a-In-PDU(Connection, CurrentPDU) -{ - check-basic-validity(CurrentPDU); - if (Header-Digest-Bad) discard, return; - Retrieve TCB for CurrentPDU.InitiatorTaskTag. - if (CurrentPDU.type == Nop-In) { - if (the PDU is unsolicited) { - if (current StatSN is not expected) { - Recover-Status-if-Possible(Connection, - CurrentPDU); - } - if (current ExpCmdSN is not Session.CmdSN) { - Retransmit-Command-if-Possible(Connection, - CurrentPDU.ExpCmdSN); - } - } - } else if (CurrentPDU.type == Reject) { - if (it is a data digest error on immediate data) { - Retransmit-Command-if-Possible(Connection, - CurrentPDU.BadPDUHeader.CmdSN); - } - } else if (CurrentPDU.type == Response) { - send-status-SNACK = Evaluate-a-StatSN(Connection, - CurrentPDU); - if (send-status-SNACK == TRUE) - Recover-Status-if-Possible(Connection, CurrentPDU); - } else { /* REST UNRELATED TO WITHIN-CONNECTION-RECOVERY, - * NOT SHOWN */ - } -} - -Command-Acknowledge-Timeout-Handler(TCB) -{ - Retrieve the Connection for TCB. - Retransmit-Command-if-Possible(Connection, TCB.CmdSN); - - - -Satran, et al. Standards Track [Page 242] - -RFC 3720 iSCSI April 2004 - - -} - -Status-Expect-Timeout-Handler(Connection) -{ - if (operational ErrorRecoveryLevel > 0) { - Build-And-Send-Nop-Out(Connection); - } else if (InitiatorProactiveSNACKEnabled){ - if ((Connection.state == LOGGED_IN) and - connection is not already considered failed) { - Build-And-Send-SSnack(Connection); - } - } -} - -E.3.3. Target Algorithms - -Handle-Status-SNACK-request(Connection, CurrentPDU) -{ - if (operational ErrorRecoveryLevel > 0) { - if (request for an acknowledged run) { - Build-And-Send-Reject(Connection, CurrentPDU, - Protocol-Error); - } else if (request for an untransmitted run) { - discard, return; - } else { - Retransmit-Status-Burst(CurrentPDU, TCB); - } else { - Build-And-Send-Async(Connection, DroppedConnection, - DefaultTime2Wait, - DefaultTime2Retain); - } -} - -E.4. Connection Recovery Algorithms - -E.4.1. Procedure Descriptions - -Build-And-Send-Async(transport connection, reason code, - minimum time, maximum time); -Pick-A-Logged-In-Connection(session); -Build-And-Send-Logout(transport connection, logout connection - identifier, reason code); -PerformImplicitLogout(transport connection, logout connection - identifier, target information); -PerformLogin(transport connection, target information); -CreateNewTransportConnection(target information); -Build-And-Send-Command(transport connection, task control block); -Connection-Cleanup-Handler(transport connection); - - - -Satran, et al. Standards Track [Page 243] - -RFC 3720 iSCSI April 2004 - - -Connection-Resource-Timeout-Handler(transport connection); -Quiesce-And-Prepare-for-New-Allegiance(session, task control -block); -Build-And-Send-Logout-Response(transport connection, - CID of connection in recovery, reason -code); -Build-And-Send-TaskMgmt-Response(transport connection, - task mgmt command PDU, response code); -Establish-New-Allegiance(task control block, transport -connection); -Schedule-Command-To-Continue(task control block); - -Notes: - - Transport exception conditions, such as unexpected connection - termination, connection reset, and hung connection while the - connection is in the full-feature phase, are all assumed to be - asynchronously signaled to the iSCSI layer using the - Transport_Exception_Handler procedure. - -E.4.2. Initiator Algorithms - - Receive-a-In-PDU(Connection, CurrentPDU) { - check-basic-validity(CurrentPDU); - if (Header-Digest-Bad) discard, return; - - Retrieve TCB from CurrentPDU.InitiatorTaskTag. - if (CurrentPDU.type == Async) { - if (CurrentPDU.AsyncEvent == ConnectionDropped) { - Retrieve the AffectedConnection for - CurrentPDU.Parameter1. - AffectedConnection.CurrentTimeout = - CurrentPDU.Parameter3; - AffectedConnection.State = CLEANUP_WAIT; - Start-Timer(Connection-Cleanup-Handler, - AffectedConnection, - CurrentPDU.Parameter2); - } else if (CurrentPDU.AsyncEvent == LogoutRequest)) { - AffectedConnection = Connection; - AffectedConnection.State = LOGOUT_REQUESTED; - AffectedConnection.PerformConnectionCleanup = TRUE; - AffectedConnection.CurrentTimeout = - CurrentPDU.Parameter3; - Start-Timer(Connection-Cleanup-Handler, - AffectedConnection, 0); - } else if (CurrentPDU.AsyncEvent == SessionDropped)) { - for (each Connection) { - Connection.State = CLEANUP_WAIT; - Connection.CurrentTimeout = CurrentPDU.Parameter3; - - - -Satran, et al. Standards Track [Page 244] - -RFC 3720 iSCSI April 2004 - - - Start-Timer(Connection-Cleanup-Handler, - Connection, CurrentPDU.Parameter2); - } - Session.state = FAILED; - } - - } else if (CurrentPDU.type == LogoutResponse) { - Retrieve the CleanupConnection for CurrentPDU.CID. - if (CurrentPDU.Response = failure) { - CleanupConnection.State = CLEANUP_WAIT; - } else { - CleanupConnection.State = FREE; - } - } else if (CurrentPDU.type == LoginResponse) { - if (this is a response to an implicit Logout) { - Retrieve the CleanupConnection. - if (successful) { - CleanupConnection.State = FREE; - Connection.State = LOGGED_IN; - } else { - CleanupConnection.State = CLEANUP_WAIT; - DestroyTransportConnection(Connection); - } - } - } else { /* REST UNRELATED TO CONNECTION-RECOVERY, - - * NOT SHOWN */ - } - if (CleanupConnection.State == FREE) { - for (each command that was active on CleanupConnection) { - /* Establish new connection allegiance */ - NewConnection = Pick-A-Logged-In-Connection(Session); - Build-And-Send-Command(NewConnection, TCB); - } - } } - - Connection-Cleanup-Handler(Connection) { - Retrieve Session from Connection. - if (Connection can still exchange iSCSI PDUs) { - NewConnection = Connection; - } else { - Start-Timer(Connection-Resource-Timeout-Handler, - Connection, Connection.CurrentTimeout); - if (there are other logged-in connections) { - NewConnection = Pick-A-Logged-In- - Connection(Session); - } else { - NewConnection = - - - -Satran, et al. Standards Track [Page 245] - -RFC 3720 iSCSI April 2004 - - - CreateTransportConnection(Session.OtherEndInfo); - Initiate an implicit Logout on NewConnection for - Connection.CID. - return; - } - } - Build-And-Send-Logout(NewConnection, Connection.CID, - RecoveryRemove); } - - Transport_Exception_Handler(Connection) { - Connection.PerformConnectionCleanup = TRUE; - if (the event is an unexpected transport disconnect) { - Connection.State = CLEANUP_WAIT; - - Connection.CurrentTimeout = DefaultTime2Retain; - Start-Timer(Connection-Cleanup-Handler, Connection, - DefaultTime2Wait); - - } else { - Connection.State = FREE; - } } - -E.4.3. Target Algorithms - - Receive-a-In-PDU(Connection, CurrentPDU) - { - check-basic-validity(CurrentPDU); - if (Header-Digest-Bad) discard, return; - else if (Data-Digest-Bad) { - Build-And-Send-Reject(Connection, CurrentPDU, - Payload-Digest-Error); - discard, return; - } - Retrieve TCB and Session. - if (CurrentPDU.type == Logout) { - if (CurrentPDU.ReasonCode = RecoveryRemove) { - Retrieve the CleanupConnection from CurrentPDU.CID). - for (each command active on CleanupConnection) { - Quiesce-And-Prepare-for-New-Allegiance(Session, - TCB); - TCB.CurrentlyAllegiant = FALSE; - } - Cleanup-Connection-State(CleanupConnection); - if ((quiescing successful) and (cleanup successful)) { - Build-And-Send-Logout-Response(Connection, - CleanupConnection.CID, Success); - } else { - Build-And-Send-Logout-Response(Connection, - - - -Satran, et al. Standards Track [Page 246] - -RFC 3720 iSCSI April 2004 - - - CleanupConnection.CID, Failure); - } - } - } else if ((CurrentPDU.type == Login) and - operational ErrorRecoveryLevel == 2) { - Retrieve the CleanupConnection from CurrentPDU.CID). - for (each command active on CleanupConnection) { - Quiesce-And-Prepare-for-New-Allegiance(Session, TCB); - TCB.CurrentlyAllegiant = FALSE; - } - Cleanup-Connection-State(CleanupConnection); - if ((quiescing successful) and (cleanup successful)) { - Continue with the rest of the Login processing; - } else { - Build-And-Send-Login-Response(Connection, - CleanupConnection.CID, Target Error); - } - } - - } else if (CurrentPDU.type == TaskManagement) { - if (CurrentPDU.function == "TaskReassign") { - if (Session.ErrorRecoveryLevel < 2) { - Build-And-Send-TaskMgmt-Response(Connection, - CurrentPDU, "Allegiance reassignment - not supported"); - } else if (task is not found) { - Build-And-Send-TaskMgmt-Response(Connection, - CurrentPDU, "Task not in task set"); - } else if (task is currently allegiant) { - Build-And-Send-TaskMgmt-Response(Connection, - CurrentPDU, "Task still allegiant"); - } else { - Establish-New-Allegiance(TCB, Connection); - TCB.CurrentlyAllegiant = TRUE; - Schedule-Command-To-Continue(TCB); - } - } - } else { /* REST UNRELATED TO CONNECTION-RECOVERY, - * NOT SHOWN */ - } - } - - Transport_Exception_Handler(Connection) - { - Connection.PerformConnectionCleanup = TRUE; - if (the event is an unexpected transport disconnect) { - Connection.State = CLEANUP_WAIT; - Start-Timer(Connection-Resource-Timeout-Handler, - - - -Satran, et al. Standards Track [Page 247] - -RFC 3720 iSCSI April 2004 - - - Connection, - - (DefaultTime2Wait+DefaultTime2Retain)); - if (this Session has full-feature phase connections - left) - { - DifferentConnection = - Pick-A-Logged-In-Connection(Session); - Build-And-Send-Async(DifferentConnection, - DroppedConnection, DefaultTime2Wait, - DefaultTime2Retain); - } - } else { - Connection.State = FREE; - } - } - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 248] - -RFC 3720 iSCSI April 2004 - - -Appendix F. Clearing Effects of Various Events on Targets - -F.1. Clearing Effects on iSCSI Objects - - The following tables describe the target behavior on receiving the - events specified in the rows of the table. The second table is an - extension of the first table and defines clearing actions for more - objects on the same events. The legend is: - - Y = Yes (cleared/discarded/reset on the event specified in the - row). Unless otherwise noted, the clearing action is only - applicable for the issuing initiator port. - N = No (not affected on the event specified in the row, i.e., - stays at previous value). - NA = Not Applicable or Not Defined. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 249] - -RFC 3720 iSCSI April 2004 - - - +-----+-----+-----+-----+-----+ - |IT(1)|IC(2)|CT(5)|ST(6)|PP(7)| - +---------------------+-----+-----+-----+-----+-----+ - |connection failure(8)|Y |Y |N |N |Y | - +---------------------+-----+-----+-----+-----+-----+ - |connection state |NA |NA |Y |N |NA | - |timeout (9) | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |session timeout/ |Y |Y |Y |Y |Y(14)| - |closure/reinstatement| | | | | | - |(10) | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |session continuation |NA |NA |N(11)|N |NA | - |(12) | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |successful connection|Y |Y |Y |N |Y(13)| - |close logout | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |session failure (18) |Y |Y |N |N |Y | - +---------------------+-----+-----+-----+-----+-----+ - |successful recovery |Y |Y |N |N |Y(13)| - |Logout | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |failed Logout |Y |Y |N |N |Y | - +---------------------+-----+-----+-----+-----+-----+ - |connection Login |NA |NA |NA |Y(15)|NA | - |(leading) | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |connection Login |NA |NA |N(11)|N |Y | - |(non-leading) | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |target cold reset(16)|Y |Y |Y |Y |Y | - +---------------------+-----+-----+-----+-----+-----+ - |target warm reset(16)|Y |Y |Y |Y |Y | - +---------------------+-----+-----+-----+-----+-----+ - |LU reset(19) |Y |Y |Y |Y |Y | - +---------------------+-----+-----+-----+-----+-----+ - |powercycle(16) |Y |Y |Y |Y |Y | - +---------------------+-----+-----+-----+-----+-----+ - - 1. Incomplete TTTs - Target Transfer Tags on which the target is - still expecting PDUs to be received. Examples include TTTs received - via R2T, NOP-IN, etc. - - 2. Immediate Commands - immediate commands, but waiting for - execution on a target. For example, Abort Task Set. - - - - - -Satran, et al. Standards Track [Page 250] - -RFC 3720 iSCSI April 2004 - - - 5. Connection Tasks - tasks that are active on the iSCSI connection - in question. - - 6. Session Tasks - tasks that are active on the entire iSCSI - session. A union of "connection tasks" on all participating - connections. - - 7. Partial PDUs (if any) - PDUs that are partially sent and waiting - for transport window credit to complete the transmission. - - 8. Connection failure is a connection exception condition - one of - the transport connections shutdown, transport connections reset, or - transport connections timed out, which abruptly terminated the iSCSI - full-feature phase connection. A connection failure always takes the - connection state machine to the CLEANUP_WAIT state. - - 9. Connection state timeout happens if a connection spends more time - that agreed upon during Login negotiation in the CLEANUP_WAIT state, - and this takes the connection to the FREE state (M1 transition in - connection cleanup state diagram). - - 10. These are defined in Section 5.3.5 Session Reinstatement, - Closure, and Timeout. - - 11. This clearing effect is "Y" only if it is a connection - reinstatement and the operational ErrorRecoveryLevel is less than 2. - - 12. Session continuation is defined in Section 5.3.6 Session - Continuation and Failure. - - 13. This clearing effect is only valid if the connection is being - logged out on a different connection and when the connection being - logged out on the target may have some partial PDUs pending to be - sent. In all other cases, the effect is "NA". - - 14. This clearing effect is only valid for a "close the session" - logout in a multi-connection session. In all other cases, the effect - is "NA". - - 15. Only applicable if this leading connection login is a session - reinstatement. If this is not the case, it is "NA". - - 16. This operation affects all logged-in initiators. - - 18. Session failure is defined in Section 5.3.6 Session Continuation - and Failure. - - - - - -Satran, et al. Standards Track [Page 251] - -RFC 3720 iSCSI April 2004 - - - 19. This operation affects all logged-in initiators and the clearing - effects are only applicable to the LU being reset. - - +-----+-----+-----+-----+-----+ - |DC(1)|DD(2)|SS(3)|CS(4)|DS(5)| - +---------------------+-----+-----+-----+-----+-----+ - |connection failure |N |Y |N |N |N | - +---------------------+-----+-----+-----+-----+-----+ - |connection state |Y |NA |Y |N |NA | - |timeout | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |session timeout/ |Y |Y |Y(7) |Y |NA | - |closure/reinstatement| | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |session continuation |N(11)|NA*12|NA |N |NA*13| - +---------------------+-----+-----+-----+-----+-----+ - |successful connection|Y |Y |Y |N |NA | - |close Logout | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |session failure |N |Y |N |N |N | - +---------------------+-----+-----+-----+-----+-----+ - |successful recovery |Y |Y |Y |N |N | - |Logout | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |failed Logout |N |Y(9) |N |N |N | - +---------------------+-----+-----+-----+-----+-----+ - |connection Login |NA |NA |N(8) |N(8) |NA | - |(leading | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |connection Login |N(11)|NA*12|N(8) |N |NA*13| - |(non-leading) | | | | | | - +---------------------+-----+-----+-----+-----+-----+ - |target cold reset |Y |Y |Y |Y(10)|NA | - +---------------------+-----+-----+-----+-----+-----+ - |target warm reset |Y |Y |N |N |NA | - +---------------------+-----+-----+-----+-----+-----+ - |LU reset |N |Y |N |N |N | - +---------------------+-----+-----+-----+-----+-----+ - |powercycle |Y |Y |Y |Y(10)|NA | - +---------------------+-----+-----+-----+-----+-----+ - - 1. Discontiguous Commands - commands allegiant to the connection in - question and waiting to be reordered in the iSCSI layer. All "Y"s in - this column assume that the task causing the event (if indeed the - event is the result of a task) is issued as an immediate command, - because the discontiguities can be ahead of the task. - - - - - -Satran, et al. Standards Track [Page 252] - -RFC 3720 iSCSI April 2004 - - - 2. Discontiguous Data - data PDUs received for the task in question - and waiting to be reordered due to prior discontiguities in DataSN. - - 3. StatSN - - 4. CmdSN - - 5. DataSN - - 7. It clears the StatSN on all the connections. - - 8. This sequence number is instantiated on this event. - - 9. A logout failure drives the connection state machine to the - CLEANUP_WAIT state, similar to the connection failure event. Hence, - it has a similar effect on this and several other protocol aspects. - - 10. This is cleared by virtue of the fact that all sessions with all - initiators are terminated. - - 11. This clearing effect is "Y" if it is a connection reinstatement. - - 12. This clearing effect is "Y" only if it is a connection - reinstatement and the operational ErrorRecoveryLevel is 2. - - 13. This clearing effect is "N" only if it is a connection - reinstatement and the operational ErrorRecoveryLevel is 2. - -F.2. Clearing Effects on SCSI Objects - - The only iSCSI protocol action that can effect clearing actions on - SCSI objects is the "I_T nexus loss" notification (Section 4.3.5.1 - Loss of Nexus notification). [SPC3] describes the clearing effects - of this notification on a variety of SCSI attributes. In addition, - SCSI standards documents (such as [SAM2] and [SBC]) define additional - clearing actions that may take place for several SCSI objects on SCSI - events such as LU resets and power-on resets. - - Since iSCSI defines a target cold reset as a protocol-equivalent to a - target power-cycle, the iSCSI target cold reset must also be - considered as the power-on reset event in interpreting the actions - defined in the SCSI standards. - - When the iSCSI session is reconstructed (between the same SCSI ports - with the same nexus identifier) reestablishing the same I_T nexus, - all SCSI objects that are defined to not clear on the "I_T nexus - loss" notification event, such as persistent reservations, are - automatically associated to this new session. - - - -Satran, et al. Standards Track [Page 253] - -RFC 3720 iSCSI April 2004 - - -Acknowledgements - - This protocol was developed by a design team that, in addition to the - authors, included Daniel Smith, Ofer Biran, Jim Hafner and John - Hufferd (IBM), Mark Bakke (Cisco), Randy Haagens (HP), Matt Wakeley - (Agilent, now Sierra Logic), Luciano Dalle Ore (Quantum), and Paul - Von Stamwitz (Adaptec, now TrueSAN Networks). - - Furthermore, a large group of people contributed to this work through - their review, comments, and valuable insights. We are grateful to - all of them. We especially thank those people who found the time and - patience to take part in our weekly phone conferences and - intermediate meetings in Almaden and Haifa, which helped shape this - document: Prasenjit Sarkar, Meir Toledano, John Dowdy, Steve Legg, - Alain Azagury (IBM), Dave Nagle (CMU), David Black (EMC), John Matze - (Veritas - now Okapi Software), Steve DeGroote, Mark Schrandt - (Cisco), Gabi Hecht (Gadzoox), Robert Snively and Brian Forbes - (Brocade), Nelson Nachum (StorAge), and Uri Elzur (Broadcom). Many - others helped edit and improve this document within the IPS working - group. We are especially grateful to David Robinson and Raghavendra - Rao (Sun), Charles Monia, Joshua Tseng (Nishan), Somesh Gupta - (Silverback), Michael Krause, Pierre Labat, Santosh Rao, Matthew - Burbridge, Bob Barry, Robert Elliott, Nick Martin (HP), Stephen - Bailey (Sandburst), Steve Senum, Ayman Ghanem, Dave Peterson (Cisco), - Barry Reinhold (Trebia Networks), Bob Russell (UNH), Eddy Quicksall - (iVivity, Inc.), Bill Lynn and Michael Fischer (Adaptec), Vince - Cavanna, Pat Thaler (Agilent), Jonathan Stone (Stanford), Luben - Tuikov (Splentec), Paul Koning (EqualLogic), Michael Krueger - (Windriver), Martins Krikis (Intel), Doug Otis (Sanlight), John - Marberg (IBM), Robert Griswold and Bill Moody (Crossroads), Bill - Studenmund (Wasabi Systems), Elizabeth Rodriguez (Brocade) and Yaron - Klein (Sanrad). The recovery chapter was enhanced with the help of - Stephen Bailey (Sandburst), Somesh Gupta (Silverback), and Venkat - Rangan (Rhapsody Networks). Eddy Quicksall contributed some examples - and began the Definitions section. Michael Fischer and Bob Barry - started the Acronyms section. Last, but not least, we thank Ralph - Weber for keeping us in line with T10 (SCSI) standardization. - - We would like to thank Steve Hetzler for his unwavering support and - for coming up with such a good name for the protocol, and Micky - Rodeh, Jai Menon, Clod Barrera, and Andy Bechtolsheim for helping - make this work happen. - - In addition to this document, we recommend you acquaint yourself with - the following in order to get a full understanding of the iSCSI - specification: "iSCSI Naming & Discovery"[RFC3721], "Bootstrapping - Clients using the iSCSI Protocol" [BOOT], "Securing Block Storage - Protocols over IP" [RFC3723] documents, "iSCSI Requirements and - - - -Satran, et al. Standards Track [Page 254] - -RFC 3720 iSCSI April 2004 - - - Design Considerations" [RFC3347] and "SCSI Command Ordering - Considerations with iSCSI" [CORD]. - - The "iSCSI Naming & Discovery" document is authored by: - - Mark Bakke (Cisco), Jim Hafner, John Hufferd, Kaladhar Voruganti - (IBM), and Marjorie Krueger (HP). - - The "Bootstrapping Clients using the iSCSI Protocol" document is - authored by: - - Prasenjit Sarkar (IBM), Duncan Missimer (HP), and Costa - Sapuntzakis (Cisco). - - The "Securing Block Storage Protocols over IP" document is authored - by: - - Bernard Aboba (Microsoft), Joshua Tseng (Nishan), Jesse Walker - (Intel), Venkat Rangan (Rhapsody Networks), and Franco - Travostino (Nortel Networks). - - The "iSCSI Requirements and Design Considerations" document is - authored by: - - Marjorie Krueger, Randy Haagens (HP), Costa Sapuntzakis, and Mark - Bakke (Cisco). - - The "SCSI Command Ordering Considerations with iSCSI" document is - authored by: - - Mallikarjun Chadalapaka, Rob Elliot (HP) - - We are grateful to all of them for their good work and for helping us - correlate this document with the ones they produced. - - - - - - - - - - - - - - - - - -Satran, et al. Standards Track [Page 255] - -RFC 3720 iSCSI April 2004 - - -Authors' Addresses - - Julian Satran - IBM Research Laboratory in Haifa - Haifa University Campus - Mount Carmel - Haifa 31905, Israel - - Phone +972.4.829.6264 - EMail: Julian_Satran@il.ibm.com - - - Kalman Meth - IBM Research Laboratory in Haifa - Haifa University Campus - Mount Carmel - Haifa 31905, Israel - - Phone +972.4.829.6341 - EMail: meth@il.ibm.com - - - Costa Sapuntzakis - Stanford University - 353 Serra Mall Dr #407 - Stanford, CA 94305 - - Phone: +1.650.723.2458 - EMail: csapuntz@alum.mit.edu - - - Efri Zeidner - XIV Ltd. - 1 Azrieli Center, - Tel-Aviv 67021, Israel - - Phone: +972.3.607.4722 - EMail: efri@xiv.co.il - - - Mallikarjun Chadalapaka - Hewlett-Packard Company - 8000 Foothills Blvd. - Roseville, CA 95747-5668, USA - - Phone: +1.916.785.5621 - EMail: cbm@rose.hp.com - - - - - - -Satran, et al. Standards Track [Page 256] - -RFC 3720 iSCSI April 2004 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2004). This document is subject - to the rights, licenses and restrictions contained in BCP 78, and - except as set forth therein, the authors retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, - INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE - INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED - WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at ietf- - ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - -Satran, et al. Standards Track [Page 257] - diff --git a/utils/open-isns/doc/rfc3722.txt b/utils/open-isns/doc/rfc3722.txt deleted file mode 100644 index 0eb44ff..0000000 --- a/utils/open-isns/doc/rfc3722.txt +++ /dev/null @@ -1,451 +0,0 @@ - - - - - - -Network Working Group M. Bakke -Request for Comments: 3722 Cisco -Category: Standards Track April 2004 - - - String Profile for Internet Small Computer - Systems Interface (iSCSI) Names - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2004). All Rights Reserved. - -Abstract - - This document describes how to prepare internationalized iSCSI names - to increase the likelihood that name input and comparison work in - ways that make sense for typical users throughout the world. - - The Internet Small Computer Systems Interface (iSCSI) protocol - provides a way for hosts to access SCSI devices over an IP network. - The iSCSI end-points, called initiators and targets, each have a - globally-unique name that must be transcribable, as well as easily - compared. - -1. Introduction - - The iSCSI protocol [RFC3720] provides a way for hosts to access SCSI - [SAM2] devices over an IP network. The iSCSI end-points, called - initiators and targets, each have a globally-unique name, defined in - [RFC3721]. - - An iSCSI name is a string of UTF-8 [RFC3629] characters that includes - a type designator, a naming authority based on domain names, and a - unique part within the naming authority. The unique part may be - generated based on anything the naming authority deems useful, and - may include user input. - - These names may need to be transcribed (sent between two - administrators via email, voice, paper, etc), so a case-insensitive - comparison would be desirable. However, these names must often be - - - -Bakke Standards Track [Page 1] - -RFC 3722 String Profile for iSCSI Names April 2004 - - - compared by initiator and target implementations, most of which are - done in simple, embedded software. This makes case-sensitive - comparison highly desirable for these implementors. - - However, a completely case-sensitive implementation would result in - identifiers such as "example-name" and "Example-Name" being - different, which could lead to confusion as these names are - transcribed. - - The goal, then, is to generate iSCSI names that can be transcribed - and entered by users, and also compared byte-for-byte, with minimal - confusion. To attain these goals, iSCSI names are generalized using - a normalized character set (converted to lower case or equivalent), - with no white space allowed, and very limited punctuation. - - For those using only ASCII characters (U+0000 to U+007F), the - following characters are allowed: - - - ASCII dash character ('-' = U+002d) - - ASCII dot character ('.' = U+002e) - - ASCII colon character (':' = U+003a) - - ASCII lower-case characters ('a'..'z' = U+0061..U+007a) - - ASCII digit characters ('0'..'9' = U+0030..U+0039) - - In addition, any upper-case characters input via a user interface - MUST be mapped to their lower-case equivalents. - - This document specifies the valid character set for iSCSI names, - along with the rules for normalizing and generating iSCSI names based - on user input or other information that contains international - characters. - - In particular, it defines the following, as required by [RFC3454]: - - - The intended applicability of the profile: internationalized iSCSI - names. - - - The character repertoire that is the input and output to - stringprep: Unicode 3.2, specified in section 3. - - - The mappings used: specified in section 4. - - - The Unicode normalization used: specified in section 5. - - - The characters that are prohibited as output: specified in section - 6. - - This profile MUST be used with the iSCSI protocol. - - - -Bakke Standards Track [Page 2] - -RFC 3722 String Profile for iSCSI Names April 2004 - - -2. Terminology - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in [RFC2119]. - - Examples in this document use the notation for code points and names - from the Unicode Standard [Unicode3.2] and ISO/IEC 10646 [ISO10646]. - For example, the letter "a" may be represented as either "U+0061" or - "LATIN SMALL LETTER A". In the lists of prohibited characters, the - "U+" is left off to make the lists easier to read. The comments for - character ranges are shown in square brackets (such as "[SYMBOLS]") - and do not come from the standards. - -3. Character Repertoire - - This profile uses Unicode 3.2, as defined in [RFC3454] Appendix A. - -4. Mapping - - This profile specifies mapping using the following tables from - [RFC3454]. The following mapping tables MUST be used when generating - iSCSI names from Unicode characters. - - Table B.1 - Table B.2 - -5. Normalization - - Unicode normalization form KC MUST be used with this profile, as - described in [RFC3454]. - -6. Prohibited Output - - This profile specifies prohibiting using the following tables from - [RFC3454]. Characters appearing within these tables MUST NOT be used - within an iSCSI name. - - Table C.1.1 - Table C.1.2 - Table C.2.1 - Table C.2.2 - Table C.3 - Table C.4 - Table C.5 - Table C.6 - - - - - -Bakke Standards Track [Page 3] - -RFC 3722 String Profile for iSCSI Names April 2004 - - - Table C.7 - Table C.8 - Table C.9 - - Important note: this profile MUST be used with the iSCSI protocol. - The iSCSI protocol has additional naming rules that are checked - outside of this profile. - - In addition, this profile adds the following prohibitions. The full - set of prohibited characters are those from the tables above plus - those listed individually below. - -6.1. Inappropriate Characters from Common Input Mechanisms - - u+3002 is used as if it were u+002e in many domain name input - mechanisms used by applications, particularly in Asia. The character - u+3002 MUST NOT be used in an iSCSI name. - - 3002; ideographic full stop - -6.2. Currently-prohibited ASCII characters - - Some of the ASCII characters that are currently prohibited in iSCSI - names by [RFC3721] are also used in protocol elements such as URIs. - Some examples are described in [RFC2396] and [RFC2732]. Note that - there are many other RFCs that define additional URI schemes. - - The other characters in the range U+0000 to U+007F that are not - currently allowed are prohibited in iSCSI names to reserve them for - future use in protocol elements. Note that the dash (U+002D), dot - (U+002E), and colon (U+003A) are not prohibited. - - The following characters MUST NOT be used in iSCSI names: - - 0000-002C; [ASCII CONTROL CHARACTERS and SPACE through ,] - 002F; [ASCII /] - 003B-0040; [ASCII ; through @] - 005B-0060; [ASCII [ through `] - 007B-007F; [ASCII { through DEL] - -7. Bidirectional Characters - - This profile specifies checking bidirectional strings as described in - [RFC3454] section 6. - - - - - - - -Bakke Standards Track [Page 4] - -RFC 3722 String Profile for iSCSI Names April 2004 - - -8. Unassigned Code Points in Internationalized Domain Names - - If the processing in [RFC3720] specifies that a list of unassigned - code points be used, the system uses table A.1 from [RFC3454] as its - list of unassigned code points. - -9. Security Considerations - - ISO/IEC 10646 has many characters that look similar. In many cases, - users of security protocols might do visual matching, such as when - comparing the names of trusted third parties. This profile does - nothing to map similar-looking characters together. - - iSCSI names may be used by an initiator to verify that a target it - has discovered is the correct one, and by a target to verify that an - initiator is to be allowed access. If these names are interpreted - and compared differently by different iSCSI implementations, an - initiator could gain access to the wrong target, or could be denied - access to a legitimate target. - -10. IANA Considerations - - This is a profile of stringprep. It has been registered in the IANA - "Stringprep Profiles" registry. This process is described in the - IANA Considerations section of [RFC3454]. - -11. Summary - - This document describes a stringprep profile to be used with programs - generating names for iSCSI initiators and targets. - -12. Acknowledgements - - This document was produced as a result of discussions on iSCSI name - formats with Joe Czap, Jim Hafner, Howard Hall, Jack Harwood, John - Hufferd, Marjorie Krueger, Lawrence Lamers, Todd Sperry, Joshua - Tseng, and Kaladhar Voruganti, as well as discussions on the - normalization of names into identifiers with Paul Hoffman and Marc - Blanchet. - - Thanks also to Bob Snively for suggesting the use of the nameprep - process for iSCSI name normalization. - - Most of this document was copied from the stringprep profile for - Internationalized Domain Names [RFC3491], written by Paul Hoffman and - Marc Blanchet. - - - - - -Bakke Standards Track [Page 5] - -RFC 3722 String Profile for iSCSI Names April 2004 - - -13. References - -13.1. Normative References - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ("stringprep")", RFC 3454, - December 2002. - - [RFC3720] Satran, J., Meth, K., Sapuntzakis, C. Chadalapaka, M. - and E. Zeidner, "Internet Small Computer Systems - Interface (iSCSI)", RFC 3720, April 2004. - -13.2. Informative References - - [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform - Resource Identifiers", RFC 2396, August 1998. - - [RFC2732] Hinden, R., Carpenter, B. and L. Masinter, "Format for - Literal IPv6 Addresses in URL's", RFC 2732, December - 1999. - - [RFC3491] Hoffman, P. and M. Blanchet, "Nameprep: A Stringprep - Profile for Internationalized Domain Names", RFC 3491, - March 2003. - [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. - - [RFC3721] Bakke, M., Hafner, J., Hufferd, J., Voruganti, K. and M. - Krueger, "Internet Small Computer Systems Interface - (iSCSI) Naming and Discovery", RFC 3721, April 2004. - - [SAM2] ANSI T10. "SCSI Architectural Model 2", March 2000. - - [Unicode3.2] The Unicode Standard, Version 3.2.0: The Unicode - Consortium. The Unicode Standard, Version 3.2.0 is - defined by The Unicode Standard, Version 3.0 (Reading, - MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), as - amended by the Unicode Standard Annex #27: Unicode 3.1 - (http://www.unicode.org/unicode/reports/tr27/) and by - the Unicode Standard Annex #28: Unicode 3.2 - (http://www.unicode.org/unicode/reports/tr28/). - - - - - - - -Bakke Standards Track [Page 6] - -RFC 3722 String Profile for iSCSI Names April 2004 - - - [ISO10646] ISO/IEC 10646-1:2000. International Standard -- - Information technology -- Universal Multiple-Octet Coded - Character Set (UCS) -- Part 1: Architecture and Basic - Multilingual Plane. - -14. Author's Address - - Mark Bakke - Cisco Systems, Inc. - 6450 Wedgwood Road - Maple Grove, MN - USA 55311 - - Voice: +1 763-398-1000 - EMail: mbakke@cisco.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Bakke Standards Track [Page 7] - -RFC 3722 String Profile for iSCSI Names April 2004 - - -15. Full Copyright Statement - - Copyright (C) The Internet Society (2004). This document is subject - to the rights, licenses and restrictions contained in BCP 78, and - except as set forth therein, the authors retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, - INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE - INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED - WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at ietf- - ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - -Bakke Standards Track [Page 8] - diff --git a/utils/open-isns/doc/rfc4018.txt b/utils/open-isns/doc/rfc4018.txt deleted file mode 100644 index 15df58d..0000000 --- a/utils/open-isns/doc/rfc4018.txt +++ /dev/null @@ -1,1291 +0,0 @@ - - - - - - -Network Working Group M. Bakke -Request for Comments: 4018 Cisco -Category: Standards Track J. Hufferd - K. Voruganti - IBM - M. Krueger - HP - T. Sperry - Adaptec - April 2005 - - - Finding Internet Small Computer Systems Interface (iSCSI) Targets - and Name Servers by Using Service Location Protocol version 2 (SLPv2) - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2005). - -Abstract - - The iSCSI protocol provides a way for hosts to access SCSI devices - over an IP network. This document defines the use of the Service - Location Protocol (SLP) by iSCSI hosts, devices, and management - services, along with the SLP service type templates that describe the - services they provide. - -Table of Contents - - 1. Introduction................................................ 2 - 2. Notation Conventions........................................ 2 - 3. Terminology................................................. 3 - 4. Using SLP for iSCSI Service Discovery....................... 4 - 5. iSCSI SLP Templates......................................... 11 - 6. Security Considerations..................................... 18 - 7. IANA Considerations......................................... 19 - 8. Summary..................................................... 19 - 9. Normative References........................................ 19 - 10. Informative References...................................... 20 - 11. Acknowledgements............................................ 21 - - - -Bakke & Hufferd Standards Track [Page 1] - -RFC 4018 iSCSI and SLPv2 April 2005 - - -1. Introduction - - iSCSI [RFC3720] is a protocol used to transport SCSI [SAM2] commands, - data, and status across an IP network. This protocol is connection- - oriented and is currently defined over TCP. iSCSI uses a client- - server relationship. The client end of the connection is an - initiator, and it sends SCSI commands; the server end of the - connection is called a target, and it receives and executes the - commands. - - There are several methods an iSCSI initiator can use to find the - targets to which it should connect. Two of these methods can be - accomplished without the use of SLP: - - - Each target and its address can be statically configured on the - initiator. - - - Each address providing targets can be configured on the initiator; - iSCSI provides a mechanism by which the initiator can query the - address for a list of targets. - - The above methods are further defined in "iSCSI Naming and Discovery - Requirements" [RFC3721]. - - Each of the above methods requires a small amount of configuration to - be done on each initiator. The ability to discover targets and name - services without having to configure initiators is a desirable - feature. The Service Location Protocol (SLP) [RFC2608] is an IETF - standards track protocol providing several features that will - simplify locating iSCSI services. This document describes how SLP - can be used in iSCSI environments to discover targets, addresses - providing targets, and storage management servers. - -2. Notation Conventions - - In this document, the key words "MUST", "MUST NOT", "REQUIRED", - "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", - and "OPTIONAL" are to be interpreted as described in [RFC2119]. - - - - - - - - - - - - - -Bakke & Hufferd Standards Track [Page 2] - -RFC 4018 iSCSI and SLPv2 April 2005 - - -3. Terminology - - Here are some definitions that may aid readers who are unfamiliar - with SLP, SCSI, or iSCSI. Some of these definitions have been - reproduced from [RFC2608] and "Finding an RSIP Server with SLP" - [RFC3105]. - - User Agent (UA) A process working on the client's behalf - to establish contact with some service. - The UA retrieves service information from - the Service Agents or Directory Agents. - - Service Agent (SA) A process working on behalf of one or more - services to advertise the services and - their capabilities. - - Directory Agent (DA) A process that collects service - advertisements. There can only be one DA - present per given host. - - Scope A named set of services, typically making - up a logical administrative group. - - Service Advertisement A URL, attributes, and a lifetime - (indicating how long the advertisement is - valid) providing service access - information and capabilities description - for a particular service. - - Initiator A logical entity, typically within a host, - that sends SCSI commands to targets to be - executed. An initiator is usually present - in the form of a device driver. - - Target A logical entity, typically within a - storage controller or gateway that - receives SCSI commands from an initiator - and executes them. A target includes one - or more Logical Units (LUs); each LU is a - SCSI device, such as a disk or tape drive. - - iSCSI Name A UTF-8 character string that serves as a - unique identifier for iSCSI initiators and - targets. Its format and usage is further - defined in [RFC3721]. - - iSCSI Client A logical entity, typically a host that - includes at least one iSCSI Initiator. - - - -Bakke & Hufferd Standards Track [Page 3] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - iSCSI Server A logical entity, typically a storage - controller or gateway that includes at - least one iSCSI Target. - - Storage Management Server An addressable entity that provides - management services that benefit an iSCSI - environment. "Storage management server" - is used as a generic term and does not - indicate a specific protocol or service. - -4. Using SLP for iSCSI Service Discovery - - Two entities are involved in iSCSI discovery. The end result is that - an iSCSI initiator (e.g., a host) discovers iSCSI targets, usually - provided by storage controllers or gateways. - - iSCSI targets are registered with SLP as a set of service URLs, one - for each address on which the target may be accessed. Initiators - discover these targets by using SLP service requests. Targets that - do not directly support SLP or that are under the control of a - management service may be registered by a proxy service agent as part - of the software providing this service. - - iSCSI entities may also use SLP to discover higher-level management - services when these are needed. - - This section first describes the use of SLP for discovery of targets - by iSCSI initiators, it then describes the use of SLP to discover - storage management servers. - - This document assumes that SLPv2 will be used for discovering iSCSI- - related services; no attempt is made to include support for SLPv1. - -4.1. Discovering iSCSI Targets with SLP - - The following diagram shows the relationship among iSCSI clients, - servers, initiators, and targets. An iSCSI client includes at least - one iSCSI initiator, and an SLP user agent (UA). An iSCSI server - includes at least one iSCSI target an SLP service agent (SA). Some - entities, such as extended copy engines, include both initiators and - targets. These include both an SA, for its targets to be discovered, - and a UA, for its initiator(s) to discover other targets. - - - - - - - - - -Bakke & Hufferd Standards Track [Page 4] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - +---------------------------------+ - | iSCSI Client | - | +-----------+ | - | | iSCSI | | - | | initiator | | - | | "myhost" | | - | +-----------+ | - | | - +--------------------------+------+ - | iSCSI Driver | UA | - +--------------------------+------+ - | TCP/UDP/IP | - +----------------+----------------+ - | Interface 1 | Interface 2 | - +----------------+----------------+ - | | - +------------+ | | +------------+ - | SLP DA | | | | SLP DA | - | (optional) |----+ IP Networks +----| (optional) | - +------------+ | | +------------+ - | | - +-----------------+-----------------| - | Interface 1 | Interface 2 | - | 192.0.2.131 | 192.0.2.3 | - +-----------------+-----------------+ - | TCP/UDP/IP | - +---------------------------+-------+ - | iSCSI Driver | SA | - +---------------------------+-------| - | | - | +--------+ +--------+ +---------+ | - | | iSCSI | | iSCSI | | iSCSI | | - | | target | | target | | target | | - | | "one" | | "two" | | "three" | | - | +--------+ +--------+ +---------+ | - | iSCSI Server | - +-----------------------------------+ - - In the above drawing, the iSCSI server has three iSCSI targets that - the client could discover, named "one", "two" and "three". The iSCSI - client has an iSCSI initiator with the name "myhost". The iSCSI - client may use the initiator name in its SLP Service Requests as a - filter to discover only targets that are configured to accept iSCSI - connections from "myhost". - - Each iSCSI target and initiator has a unique name, called an iSCSI - Name. This identifier is the same regardless of the network path - (through adapter cards, networks, and interfaces on the storage - - - -Bakke & Hufferd Standards Track [Page 5] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - device) over which the target is discovered and accessed. For this - example, the iSCSI names "one", "two", and "three" are used for the - targets; the initiator uses the name "myhost". An actual iSCSI name - would incorporate more structure, including a naming authority, and - is not described here. - - Each of the iSCSI targets in the drawing can appear at two addresses, - since two network interfaces are present. Each target would have two - service URLs, unless a single service URL included a DNS host name - mapping to both addresses. - - An iSCSI target URL consists of its fully qualified host name or IP - address, the TCP port on which it is listening, and its iSCSI name. - An iSCSI server must register each of its individual targets at each - of its network addresses. - - The iSCSI server constructs a service advertisement of the type - "service:iscsi:target" for each of the service URLs it wishes to - register. The advertisement contains a lifetime, along with other - attributes that are defined in the service template. - - If the server in the above drawing is listening at TCP port 3260 for - both network addresses, the service URLs registered would be - - - 192.0.2.131:3260/one - - - 192.0.2.131:3260/two - - - 192.0.2.131:3260/three - - - 192.0.2.3:3260/one - - - 192.0.2.3:3260/two - - - 192.0.2.3:3260/three - - The remainder of the discovery procedure is identical to that used by - any client/server pair implementing SLP: - - 1. If an SLP DA is found, the SA contacts the DA and registers the - service advertisement. Whether or not one or more SLPv2 DAs are - discovered, the SA maintains the advertisement itself and answers - multicast UA queries directly. - - 2. When the iSCSI initiator requires contact information for an - iSCSI target, the UA either contacts the DA by using unicast or - the SA by using multicast. If a UA is configured with the - address of the SA, it may avoid multicast and may contact an SA - - - -Bakke & Hufferd Standards Track [Page 6] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - by using unicast. The UA includes a query based on the - attributes to indicate the characteristics of the target(s) it - requires. - - 3. Once the UA has the host name or address of the iSCSI server, as - well as the port number and iSCSI Target Name, it can begin the - normal iSCSI login to the target. - - As information contained in the iSCSI target template may exceed - common network datagram sizes, the SLP implementation for both UAs - and SAs supporting this template MUST implement SLP over TCP. - -4.1.1. Finding Targets Based on Initiator Credentials - - To be allowed access to an iSCSI target, an initiator must be - authenticated. The initiator may be required by the target to - produce one or more of the following credentials: - - - An iSCSI Initiator Name - - - An IP address - - - A CHAP, SRP, or Kerberos credential - - - Any combination of the above - - Most iSCSI targets allow access to only one or two initiators. In - the ideal discovery scenario, an initiator would send an SLP request - and receive responses ONLY for targets to which the initiator is - guaranteed a successful login. To achieve this goal, the iSCSI - target template contains the following attributes, each of which - allows a list of values: - - 1. auth-name: This attribute contains the list of initiator names - allowed to access this target, or the value "any", indicating - that no specific initiator name is required. - - 2. auth-addr: This attribute contains the list of host names - and/or IP addresses that will be allowed access to this target, - or the value "any", indicating that no specific address or - host name is required. If a large number of addresses is to - be allowed (perhaps a subnet), this attribute may contain the - value "any". - - - - - - - - -Bakke & Hufferd Standards Track [Page 7] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - 3. auth-cred: This attribute contains a list of "method/identifier" - credentials that will be allowed access to the target, provided - they can produce the correct password or other verifier during - the login process. If no specific credentials are required, the - value "any" is used. - - The list of valid method strings for auth-cred are defined in - [RFC3720], section 11.1, "AuthMethod". The identifier used after the - "/" is defined by the specific AuthMethod, also in [RFC3720]. - Examples showing initiator searches based on auth-xxxx attributes are - shown in the target-specific template section below. - - Also note that the auth-xxxx attributes are considered security - policy information. If these attributes are distributed, IPsec MUST - be implemented as specified in the Security Implementation section - below. - -4.1.2. Supporting Access by Multiple Identities to the Same Target - - If a target is to allow access to multiple host identities, more than - one combination of auth-xxxx attributes will have to be allowed. In - some of these cases, it is not possible to express the entire set of - valid combinations of auth-xxxx attributes within a single registered - service URL. For example, if a target can be addressed by - - auth-name=myhost1 AND auth-cred=CHAP/user1 (identity1) - - OR - - auth-name-myhost2 AND auth-cred=CHAP/user2 (identity2) - - the above cannot be specified in a single registered service URL, - since (auth-name=myhost1, auth-name=myhost2, auth-cred=CHAP/user1, - auth-cred=CHAP/user2) would allow either auth-name to be used with - either auth-cred. This necessitates the ability to register a target - and address under more than one service URL; one for (identity1) and - one for (identity2). - - Because service URLs must be unique, (identity1) and (identity2) must - each be registered under a unique service URL. For systems that - support the configuration of multiple identities to access a target, - the service URL must contain an additional, opaque string defining - the identity. This appears after the iSCSI name in the URL string - and is separated by a "/". Each registered (target-address, target- - name, initiator-identity) tuple can then register a set of auth-xxxx - attributes. - - - - - -Bakke & Hufferd Standards Track [Page 8] - -RFC 4018 iSCSI and SLPv2 April 2005 - - -4.1.3. Using SLP in a Non-multicast Environment - - In some networks, the use of multicast for discovery purposes is - either unavailable or not allowed. These include public or service- - provider networks that are placed between an iSCSI client and a - server. These are probably most common between two iSCSI gateways, - one at a storage service provider site, and one at a customer site. - - In these networks, an initiator may allow the addresses of one or - more SAs to be configured instead of or in addition to its DA - configuration. The initiator would then make unicast SLP service - requests directly to these SAs, without the use of multicast to - discover them first. - - This functionality is well within the scope of the current SLP - protocol. The main consequence for implementors is that an initiator - configured to make direct unicast requests to an SA will have to add - this to the SLP API, if it is following the service location API - defined in [RFC2614]. - -4.2. Discovering Storage Management Services with SLP - - Storage management servers can be built to manage and control access - to targets in a variety of ways. They can provide extended services - beyond discovery, which could include storage allocation and - management. None of these services are defined here; the intent of - this document is to allow these services to be discovered by both - clients and servers, in addition to the target discovery already - being performed. - - The following drawing shows an iSCSI client, an iSCSI server, and a - storage management server. To simplify the drawing, the second IP - network is not shown but is assumed to exist. The storage management - server would use its own protocol (smsp) to provide capabilities to - iSCSI clients and servers; these clients and servers can both use SLP - to discover the storage management server. - - - - - - - - - - - - - - - -Bakke & Hufferd Standards Track [Page 9] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - +---------------------------+ - | iSCSI Client | - | | - | +-----------+ | - | | iSCSI | | - | | initiator | | - | +-----------+ | - | | - +---------------+------+----+ +------------+ - | iSCSI Driver | smsp | UA | | SLP DA | - +---------------+------+----+ | | - | TCP/UDP/IP | | (optional) | - +---------------+------+----+ +------------+ - | | - | IP Network | - ------------------------------------------ - | | - | | - +---------------+-----------+ +---------------------+ - | TCP/UDP/IP | | TCP/UDP/IP | - +---------------+------+----+ +---------------------+ - | iSCSI Driver | smsp | UA | | SA | smsp | - +---------------+------+----+ +---------------------+ - | | | | - | +--------+ +--------+ | | storage mgmt server | - | | iSCSI | | iSCSI | | | | - | | target | | target | | +---------------------+ - | | 1 | | 2 | | - | +--------+ +--------+ | - | | - | iSCSI Server | - +---------------------------+ - - Note the difference between the storage management server model and - the previously defined target discovery model. When target discovery - was used, the iSCSI Server implemented an SA, to be discovered by the - initiator's UA. In the storage management server model, the iSCSI - clients and servers both implement UAs, and the management server - implements the SA. - - A storage management server's URL contains the domain name or IP - address and TCP or UDP port number. No other information is - required. - - The storage management server constructs a service advertisement of - the type "service:iscsi:sms" for each of the addresses at which it - appears. The advertisement contains the URL and a lifetime, along - with other attributes that are defined in the service template. - - - -Bakke & Hufferd Standards Track [Page 10] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - The remainder of the discovery procedure is identical to that used to - discover iSCSI targets, except that both initiators and targets would - normally be "clients" of the storage management service. - - Targets that support a storage management service implement a UA in - addition to the SA. A target may alternatively just implement the UA - and allow the storage management service to advertise its targets - appropriately by providing an SA and registering the appropriate - service:iscsi:target registrations on the target's behalf: The target - device would not have to advertise its own targets. This has no - impact on the initiator. - - This allows the initiators' discovery of targets to be completely - interoperable regardless of which storage management service is used, - or whether one is used at all, or whether the target registrations - are provided directly by the target or by the management service. - -4.3. Internationalization Considerations - - SLP allows internationalized strings to be registered and retrieved. - Attributes in the template that are not marked with an 'L' (literal) - will be registered in a localized manner. An "en" (English) - localization MUST be registered, and others MAY be registered. - - Attributes that include non-ASCII characters will be encoded by using - UTF-8, as discussed in [RFC3722] and [RFC3491]. - -5. iSCSI SLP Templates - - Three templates are provided: an iSCSI target template, a management - service template, and an abstract template to encapsulate the two. - -5.1. The iSCSI Abstract Service Type Template - - This template defines the abstract service "service:iscsi". It is - used as a top-level service to encapsulate all other iSCSI-related - services. - - Name of submitter: Mark Bakke - Language of service template: en - Security Considerations: See section 6. - - Template Text: - -------------------------template begins here----------------------- - template-type=iscsi - template-version=1.0 - - template-description= - - - -Bakke & Hufferd Standards Track [Page 11] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - This is an abstract service type. The purpose of the iscsi - service type is to encompass all of the services used to support - the iSCSI protocol. - - template-url-syntax= - url-path= ; Depends on the concrete service type. - - --------------------------template ends here------------------------ - -5.2. The iSCSI Target Concrete Service Type Template - - This template defines the service "service:iscsi:target". An entity - containing iSCSI targets that wishes them discovered via SLP would - register each of them, with each of their addresses, as this service - type. - - Initiators (and perhaps management services) wishing to discover - targets in this way will generally use one of the following queries: - - 1. Find a specific target, given its iSCSI Target Name: - - Service: service:iscsi:target - Scope: initiator-scope-list - Query: (iscsi-name=iqn.2001-04.com.example:sn.456) - - 2. Find all of the iSCSI Target Names that may allow access to a - given initiator: - - Service: service:iscsi:target - Scope: initiator-scope-list - Query: (auth-name=iqn.1998-03.com.example:hostid.045A7B) - - 3. Find all of the iSCSI Target Names that may allow access to - any initiator: - - Service: service:iscsi:target - Scope: initiator-scope-list - Query: (auth-name=any) - - 4. Find all of the iSCSI Target Names that may allow access to - this initiator, or that will allow access to any initiator: - - Service: service:iscsi:target - Scope: initiator-scope-list - Query: &(auth-name=iqn.1998-03.com.example:hostid.045A7B) - (auth-name=any) - - - - - -Bakke & Hufferd Standards Track [Page 12] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - 5. Find all of the iSCSI Target Names that may allow access to - a given CHAP user name: - - Service: service:iscsi:target - Scope: initiator-scope-list - Query: (auth-cred=chap/my-user-name) - - 6. Find all of the iSCSI Target Names that may allow access to a - given initiator that supports two IP addresses, a CHAP credential - and SRP credential, and an initiator name: - - Service: service:iscsi:target - Scope: initiator-scope-list - Query: &(|(auth-name=iqn.com.example:host47)(auth-name=any) - |(auth-addr=192.0.2.3)(auth-addr=192.0.2.131)(auth-addr=any) - |(auth-cred=chap/foo)(auth-cred=srp/my-user-name) - (auth-cred=any)) - - 7. Find the iSCSI Target Names from which the given initiator is - allowed to boot: - - Service: service:iscsi:target - Scope: initiator-scope-list - Query: (boot-list=iqn.1998-03.com.example:hostid.045A7B) - - 8. In addition, a management service may wish to discover all - targets: - - Service: service:iscsi:target - Scope: management-server-scope-list - Query: <empty-string> - - More details on booting from an iSCSI target are defined in [BOOT]. - - Name of submitter: Mark Bakke - Language of service template: en - Security Considerations: see section 6. - - Template Text: - -------------------------template begins here----------------------- - template-type=iscsi:target - template-version=1.0 - - template-description= - - This is a concrete service type. The iscsi:target service type is - used to register individual target addresses to be discovered - by others. UAs will generally search for these by including one of - - - -Bakke & Hufferd Standards Track [Page 13] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - the following: - - - the iSCSI target name - - iSCSI initiator identifiers (iSCSI name, credential, IP address) - - the service URL - - template-url-syntax= - url-path = hostport "/" iscsi-name [ "/" identity ] - hostport = host [ ":" port ] - host = hostname / hostnumber ; DNS name or IP address - hostname = *( domainlabel "." ) toplabel - alphanum = ALPHA / DIGIT - domainlabel = alphanum / alphanum *[alphanum / "-"] alphanum - toplabel = ALPHA / ALPHA *[ alphanum / "-" ] alphanum - hostnumber = ipv4-number / ipv6-addr ; IPv4 or IPv6 address - ipv4-number = 1*3DIGIT 3("." 1*3DIGIT) - ipv6-addr = "[" ipv6-number "]" - ipv6-number = 6( h16 ":" ) ls32 - / "::" 5( h16 ":" ) ls32 - / [ h16 ] "::" 4( h16 ":" ) ls32 - / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32 - / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 - / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 - / [ *4( h16 ":" ) h16 ] "::" ls32 - / [ *5( h16 ":" ) h16 ] "::" h16 - / [ *6( h16 ":" ) h16 ] "::" - ls32 = ( h16 ":" h16 ) / ipv4-number - ; least-significant 32 bits of ipv6 address - h16 = 1*4HEXDIG - port = 1*DIGIT - iscsi-name = iscsi-char ; iSCSI target name - identity = iscsi-char ; optional identity string - iscsi-char = ALPHA / DIGIT / escaped / ":" / "-" / "." - ; Intended to allow UTF-8 encoded strings - escaped = 1*("\" HEXDIG HEXDIG) - ; - ; The iscsi-name part of the URL is required and must be the iSCSI - ; name of the target being registered. - ; A device representing multiple targets must individually - ; register each target/address combination with SLP. - ; The identity part of the URL is optional, and is used to - ; indicate an identity that is allowed to access this target. - ; - ; Example (split into two lines for clarity): - ; service:iscsi:target://192.0.2.3:3260/ - ; iqn.2001-04.com.example:sn.45678 - ; - ; IPv6 addresses are also supported; they use the notation - - - -Bakke & Hufferd Standards Track [Page 14] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - ; specified above and in [RFC3513], section 2.2 - - iscsi-name = string - # The iSCSI Name of this target. - # This must match the iscsi-name in the url-path. - - portal-group = integer - # The iSCSI portal group tag for this address. Addresses sharing - # the same iscsi-name and portal-group tag can be used within the - # same iSCSI session. Portal groups are described in [RFC3720]. - - transports = string M L - tcp - # This is a list of transport protocols that the registered - # entity supports. iSCSI is currently supported over TCP, - # but it is anticipated that it could be supported over other - # transports, such as SCTP, in the future. - tcp - - mgmt-entity = string O - # The fully qualified domain name, or IP address in dotted-decimal - # notation, of the management interface of the entity containing - # this target. - # - - alias = string O - # The alias string contains a descriptive name of the target. - - auth-name = string M X - # A list of iSCSI Initiator Names that can access this target. - # Normal iSCSI names will be 80 characters or less; max length - # is 255. - # Normally, only one or a few values will be in the list. - # Using the equivalence search on this will evaluate to "true" - # if any one of the items in this list matches the query. - # If this list contains the default name "any", any initiator - # is allowed to access this target, provided it matches - # the other auth-xxx attributes. - # - # This attribute contains security policy information. If this - # attribute is distributed via an Attribute Reply message, - # IPsec MUST be implemented. - - auth-addr = string M X - # A list of initiator IP addresses (or host names) which will - # be allowed access to this target. If this list contains the - # default name "any", any IP address is allowed access to this - # target, provided it matches the other auth-xxx attributes. - - - -Bakke & Hufferd Standards Track [Page 15] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - # - # This attribute contains security policy information. If this - # attribute is distributed via an Attribute Reply message, - # IPsec MUST be implemented. - - auth-cred = string M X - # A list of credentials which will be allowed access to the target - # (provided they can provide the correct password or other - # authenticator). Entries in this list are of the form - # "method/identifier", where the currently defined methods are - # "chap" and "srp", both of which take usernames as their - # identifiers. - # - # This attribute contains security policy information. If this - # attribute is distributed via an Attribute Reply message, - # IPsec MUST be implemented. - - boot-list = string M O - # A list of iSCSI Initiator Names that can boot from this target. - # This list works precisely like the auth-name attribute. A name - # appearing in this list must either appear in the access-list, - # or the access-list must contain the initiator name "iscsi". - # Otherwise, an initiator will be unable to find its boot - # target. If boot-list contains the name "iscsi", any host can boot - # from it, but I am not sure if this is useful to anyone. If this - # attribute is not registered, this target is not "bootable". - # - # Note that the LUN the host boots from is not specified here; a - # host will generally attempt to boot from LUN 0. - # - # It is quite possible that other attributes will need to be defined - # here for booting as well. - # - # This attribute contains security policy information. If this - # attribute is distributed via an Attribute Reply message, - # IPsec MUST be implemented. - - --------------------------template ends here------------------------ - -5.3. iSCSI Storage Management Service Templates - - This template defines the service "service:iscsi:sms". An entity - supporting one or more iSCSI management service protocols may - register itself with SLP as this service type. iSCSI clients and - servers wishing to discover storage management services using SLP - will usually search for them by the protocol(s) they support: - - - - - -Bakke & Hufferd Standards Track [Page 16] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - Service: service:iscsi:sms - Scope: initiator-scope-list - Query: (protocols=isns) - - Name of submitter: Mark Bakke - Language of service template: en - Security Considerations: see section 6. - - Template Text: - -------------------------template begins here----------------------- - template-type=iscsi:sms - template-version=1.0 - - template-description= - This is a concrete service type. The iscsi:sms service type - provides the capability for entities supporting iSCSI to discover - appropriate management services. - - template-url-syntax= - url-path = ; The URL of the management service [RFC2608]. - - protocols = string M - # The list of protocols supported by this name service. This - # list may be expanded in the future. There is no default. - # - # "isns" - This management service supports the use of the iSNS - # protocol for access management, health monitoring, and - # discovery management services. This protocol is defined - # in [ISNS]. - isns - - transports = string M L - tcp - # This is a list of transport protocols that the registered - # entity supports. - tcp, udp - - server-priority = integer - # The priority a client should give this server, when choosing - # between multiple servers with the same protocol type. - # When multiple servers are discovered for a given protocol type, - # this parameter indicates their relative precedence. Server - # precedence is protocol-specific; for some protocols, the primary - # server may have the highest server-priority value, while for - - - - - - - -Bakke & Hufferd Standards Track [Page 17] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - # others it may have the lowest. For example, with iSNS, the primary - # server has the lowest value (value 0). - - --------------------------template ends here------------------------ - -6. Security Considerations - - The SLPv2 security model as specified in [RFC2608] does not provide - confidentiality but does provide an authentication mechanism for UAs - to ensure that service advertisements only come from trusted SAs, - with the exception that it does not provide a mechanism to - authenticate "zero-result responses". See [RFC3723] for a discussion - of the SLPv2 [RFC2608] security model. - - Once a target or management server is discovered, authentication and - authorization are handled by the iSCSI protocol, or by the management - server's protocol. It is the responsibility of the providers of - these services to ensure that an inappropriately advertised or - discovered service does not compromise their security. - - When no security is used for SLPv2, there is a risk of distribution - of false discovery information. The primary countermeasure for this - risk is authentication. When this risk is a significant concern, - IPsec SAs and iSCSI in-band authentication SHOULD be used for iSCSI - traffic subject to this risk to ensure that iSCSI traffic only flows - between endpoints that have participated in IKE authentication and - iSCSI in-band authentication. For example, if an attacker - distributes discovery information falsely claiming that it is an - iSCSI target, it will lack the secret information necessary to - complete IKE authentication or iSCSI in-band authentication - successfully and therefore will be prevented from falsely sending or - receiving iSCSI traffic. - - A risk remains of a denial of service attack based on repeated use of - false discovery information that will cause initiation of IKE - negotiation. The countermeasures for this are administrative - configuration of each iSCSI Target to limit the peers it is willing - to communicate with (i.e., by IP address range and/or DNS domain), - and maintenance of a negative authentication cache to avoid - repeatedly contacting an iSCSI Target that fails to authenticate. - These three measures (i.e., IP address range limits, DNS domain - limits, negative authentication cache) MUST be implemented. - - The auth-name, auth-addr, auth-cred, and boot-list attributes - comprise security policy information. When these are distributed, - IPsec MUST be implemented. - - - - - -Bakke & Hufferd Standards Track [Page 18] - -RFC 4018 iSCSI and SLPv2 April 2005 - - -6.1. Security Implementation - - Security for SLPv2 in an IP storage environment is specified in - [RFC3723]. IPsec is mandatory-to-implement for IPS clients and - servers. Thus, all IP storage clients, including those invoking SLP, - can be assumed to support IPsec. SLP servers, however, cannot be - assumed to implement IPsec, since there is no such requirement in - standard SLP. In particular, SLP Directory Agents (DA) may be - running on machines other than those running the IPS protocols. - - IPsec SHOULD be implemented for SLPv2 as specified in [RFC3723]; this - includes ESP with a non-null transform to provide both authentication - and confidentiality. - - When SLPv2 can be used to distribute auth-name, auth-addr, auth-cred, - and boot-list information (see section 5.2 above), IPsec MUST be - implemented, as these items are considered sensitive security policy - information. If IPsec is not implemented, auth-name, auth-addr, - auth-cred, and boot-list information MUST NOT be distributed via - SLPv2 and MUST NOT be used if discovered via SLPv2. - - Because the IP storage services have their own authentication - capabilities when located, SLPv2 authentication is OPTIONAL to - implement and use (as discussed in more detail in [RFC3723]). - -7. IANA Considerations - - This document describes three SLP Templates. They have been reviewed - and approved by the IESG and registered in the IANA's "SVRLOC - Templates" registry. This process is described in the IANA - Considerations section of [RFC2609]. - -8. Summary - - This document describes how SLP can be used by iSCSI initiators to - find iSCSI targets and storage management servers. Service type - templates for iSCSI targets and storage management servers are - presented. - -9. Normative References - - [RFC2608] Guttman, E., Perkins, C., Veizades, J., and M. Day, - "Service Location Protocol, Version 2", RFC 2608, June - 1999. - - [RFC2609] Guttman, E., Perkins, C., and J. Kempf, "Service - Templates and Service: Schemes", RFC 2609, June 1999. - - - - -Bakke & Hufferd Standards Track [Page 19] - -RFC 4018 iSCSI and SLPv2 April 2005 - - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC3491] Hoffman, P. and M. Blanchet, "Nameprep: A Stringprep - Profile for Internationalized Domain Names (IDN)", RFC - 3491, March 2003. - - [RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version 6 - (IPv6) Addressing Architecture", RFC 3513, April 2003. - - [RFC3720] Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, M., - and E. Zeidner, "Internet Small Computer Systems - Interface (iSCSI)", RFC 3720, April 2004. - - [RFC3722] Bakke, M., "String Profile for Internet Small Computer - Systems Interface (iSCSI) Names", RFC 3722, April 2004. - - [RFC3723] Aboba, B., Tseng, J., Walker, J., Rangan, V., and F. - Travostino, "Securing Block Storage Protocols over IP", - RFC 3723, April 2004. - -10. Informative References - - [RFC2614] Kempf, J. and E. Guttman, "An API for Service Location", - RFC 2614, June 1999. - - [SAM2] ANSI T10. "SCSI Architectural Model 2", March 2000. - - [RFC3721] Bakke, M., Hafner, J., Hufferd, J., Voruganti, K., and M. - Krueger, "Internet Small Computer Systems Interface - (iSCSI) Naming and Discovery", RFC 3721, April 2004. - - [ISNS] Tseng, J., Gibbons, K., Travostino, F., Du Laney, C. and - J. Souza, "Internet Storage Name Service", Work in - Progress, February 2004. - - [BOOT] Sarkar, P., Missimer, D. and C. Sapuntzakis, "A Standard - for Bootstrapping Clients using the iSCSI Protocol", Work - in Progress, March 2004. - - [RFC3105] Kempf, J. and G. Montenegro, "Finding an RSIP Server with - SLP", RFC 3105, October 2001. - - - - - - - - - -Bakke & Hufferd Standards Track [Page 20] - -RFC 4018 iSCSI and SLPv2 April 2005 - - -11. Acknowledgements - - This document was produced by the iSCSI Naming and Discovery team, - including Joe Czap, Jim Hafner, John Hufferd, and Kaladhar Voruganti - (IBM), Howard Hall (Pirus), Jack Harwood (EMC), Yaron Klein (Sanrad), - Marjorie Krueger (HP), Lawrence Lamers (San Valley), Todd Sperry - (Adaptec), and Joshua Tseng (Nishan). Thanks also to Julian Satran - (IBM) for suggesting the use of SLP for iSCSI discovery, and to Matt - Peterson (Caldera) and James Kempf (Sun) for reviewing the document - from an SLP perspective. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Bakke & Hufferd Standards Track [Page 21] - -RFC 4018 iSCSI and SLPv2 April 2005 - - -Authors' Addresses - - Mark Bakke - Cisco Systems, Inc. - 7900 International Drive, Suite 400 - Bloomington, MN - USA 55425 - - EMail: mbakke@cisco.com - - - Kaladhar Voruganti - IBM Almaden Research Center - 650 Harry Road - San Jose, CA 95120 - - EMail: kaladhar@us.ibm.com - - - John L. Hufferd - IBM Storage Systems Group - 5600 Cottle Road - San Jose, CA 95193 - - Phone: +1 408 997-6136 - EMail: jlhufferd@comcast.net - - - Marjorie Krueger - Hewlett-Packard Corporation - 8000 Foothills Blvd - Roseville, CA 95747-5668, USA - - Phone: +1 916 785-2656 - EMail: marjorie_krueger@hp.com - - - Todd Sperry - Adaptec, Inc. - 691 South Milpitas Boulevard - Milpitas, Ca. 95035 - - Phone: +1 408 957-4980 - EMail: todd_sperry@adaptec.com - - - - - - - -Bakke & Hufferd Standards Track [Page 22] - -RFC 4018 iSCSI and SLPv2 April 2005 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2005). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, - INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE - INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED - WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at ietf- - ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - -Bakke & Hufferd Standards Track [Page 23] - diff --git a/utils/open-isns/doc/rfc4171.txt b/utils/open-isns/doc/rfc4171.txt deleted file mode 100644 index c02487c..0000000 --- a/utils/open-isns/doc/rfc4171.txt +++ /dev/null @@ -1,6891 +0,0 @@ - - - - - - -Network Working Group J. Tseng -Request for Comments: 4171 Riverbed Technology -Category: Standards Track K. Gibbons - McDATA Corporation - F. Travostino - Nortel - C. Du Laney - Rincon Research Corporation - J. Souza - Microsoft - September 2005 - - - Internet Storage Name Service (iSNS) - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2005). - -Abstract - - This document specifies the Internet Storage Name Service (iSNS) - protocol, used for interaction between iSNS servers and iSNS clients, - which facilitates automated discovery, management, and configuration - of iSCSI and Fibre Channel devices (using iFCP gateways) on a TCP/IP - network. iSNS provides intelligent storage discovery and management - services comparable to those found in Fibre Channel networks, - allowing a commodity IP network to function in a capacity similar to - that of a storage area network. iSNS facilitates a seamless - integration of IP and Fibre Channel networks due to its ability to - emulate Fibre Channel fabric services and to manage both iSCSI and - Fibre Channel devices. iSNS thereby provides value in any storage - network comprised of iSCSI devices, Fibre Channel devices (using iFCP - gateways), or any combination thereof. - - - - - - - - - -Tseng, et al. Standards Track [Page 1] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -Table of Contents - - 1. Introduction................................................... 6 - 1.1. Conventions Used in This Document........................ 6 - 1.2. Purpose of This Document................................. 6 - 2. iSNS Overview.................................................. 6 - 2.1. iSNS Architectural Components ........................... 7 - 2.1.1. iSNS Protocol (iSNSP) ........................... 7 - 2.1.2. iSNS Client...................................... 7 - 2.1.3. iSNS Server...................................... 7 - 2.1.4. iSNS Database ................................... 7 - 2.1.5. iSCSI............................................ 7 - 2.1.6. iFCP............................................. 7 - 2.2. iSNS Functional Overview................................. 8 - 2.2.1. Name Registration Service........................ 8 - 2.2.2. Discovery Domain and Login Control Service....... 8 - 2.2.3. State Change Notification Service............... 10 - 2.2.4. Open Mapping between - Fibre Channel and iSCSI Devices................. 11 - 2.3. iSNS Usage Model........................................ 11 - 2.3.1. iSCSI Initiator................................. 12 - 2.3.2. iSCSI Target.................................... 12 - 2.3.3. iSCSI-FC Gateway................................ 12 - 2.3.4. iFCP Gateway.................................... 12 - 2.3.5. Management Station.............................. 12 - 2.4. Administratively Controlled iSNS Settings............... 13 - 2.5. iSNS Server Discovery .................................. 14 - 2.5.1. Service Location Protocol (SLP)................. 14 - 2.5.2. Dynamic Host Configuration Protocol (DHCP)...... 14 - 2.5.3. iSNS Heartbeat Message.......................... 14 - 2.6. iSNS and Network Address Translation (NAT).............. 14 - 2.7. Transfer of iSNS Database Records between iSNS Servers.. 15 - 2.8. Backup iSNS Servers..................................... 17 - 2.9. Transport Protocols..................................... 19 - 2.9.1. Use of TCP for iSNS Communication............... 19 - 2.9.2. Use of UDP for iSNS Communication............... 20 - 2.9.3. iSNS Multicast and Broadcast Messages........... 20 - 2.10. Simple Network Management Protocol (SNMP) Requirements.. 21 - 3. iSNS Object Model............................................. 21 - 3.1. Network Entity Object .................................. 22 - 3.2. Portal Object .......................................... 22 - 3.3. Storage Node Object..................................... 22 - 3.4. Portal Group Object..................................... 23 - 3.5. FC Device Object........................................ 24 - 3.6. Discovery Domain Object................................. 24 - 3.7. Discovery Domain Set Object............................. 24 - 3.8. iSNS Database Model..................................... 24 - 4. iSNS Implementation Requirements.............................. 25 - - - -Tseng, et al. Standards Track [Page 2] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - 4.1. iSCSI Requirements...................................... 25 - 4.1.1. Required Attributes for Support of iSCSI........ 26 - 4.1.2. Examples: iSCSI Object Model Diagrams........... 28 - 4.1.3. Required Commands and - Response Messages for Support of iSCSI.......... 30 - 4.2. iFCP Requirements....................................... 31 - 4.2.1. Required Attributes for Support of iFCP......... 31 - 4.2.2. Example: iFCP Object Model Diagram.............. 32 - 4.2.3. Required Commands and - Response Messages for Support of iFCP........... 34 - 5. iSNSP Message Format.......................................... 35 - 5.1. iSNSP PDU Header........................................ 35 - 5.1.1. iSNSP Version................................... 36 - 5.1.2. iSNSP Function ID............................... 36 - 5.1.3. iSNSP PDU Length................................ 36 - 5.1.4. iSNSP Flags..................................... 36 - 5.1.5. iSNSP Transaction ID............................ 36 - 5.1.6. iSNSP Sequence ID............................... 37 - 5.2. iSNSP Message Segmentation and Reassembly............... 37 - 5.3. iSNSP PDU Payload....................................... 37 - 5.3.1. Attribute Value 4-Byte Alignment................ 38 - 5.4. iSNSP Response Status Codes............................. 39 - 5.5. Authentication for iSNS Multicast and Broadcast Messages 39 - 5.6. Registration and Query Messages......................... 41 - 5.6.1. Source Attribute................................ 42 - 5.6.2. Message Key Attributes.......................... 42 - 5.6.3. Delimiter Attribute............................. 42 - 5.6.4. Operating Attributes............................ 43 - 5.6.5. Registration and Query Request Message Types ... 44 - 5.7. Response Messages....................................... 66 - 5.7.1. Status Code..................................... 66 - 5.7.2. Message Key Attributes in Response.............. 66 - 5.7.3. Delimiter Attribute in Response................. 67 - 5.7.4. Operating Attributes in Response................ 67 - 5.7.5. Registration and Query Response Message Type.... 67 - 5.8. Vendor-Specific Messages................................ 72 - 6. iSNS Attributes............................................... 73 - 6.1. iSNS Attribute Summary.................................. 73 - 6.2. Entity Identifier-Keyed Attributes...................... 76 - 6.2.1. Entity Identifier (EID)......................... 76 - 6.2.2. Entity Protocol................................. 76 - 6.2.3. Management IP Address .......................... 77 - 6.2.4. Entity Registration Timestamp .................. 77 - 6.2.5. Protocol Version Range.......................... 77 - 6.2.6. Registration Period............................. 78 - 6.2.7. Entity Index.................................... 78 - 6.2.8. Entity Next Index............................... 79 - 6.2.9. Entity ISAKMP Phase-1 Proposals................. 79 - - - -Tseng, et al. Standards Track [Page 3] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - 6.2.10. Entity Certificate.............................. 79 - 6.3. Portal-Keyed Attributes................................. 80 - 6.3.1. Portal IP Address............................... 80 - 6.3.2. Portal TCP/UDP Port............................. 80 - 6.3.3. Portal Symbolic Name............................ 80 - 6.3.4. Entity Status Inquiry Interval.................. 81 - 6.3.5. ESI Port........................................ 82 - 6.3.6. Portal Index.................................... 82 - 6.3.7. SCN Port........................................ 82 - 6.3.8. Portal Next Index............................... 83 - 6.3.9. Portal Security Bitmap.......................... 83 - 6.3.10. Portal ISAKMP Phase-1 Proposals................. 84 - 6.3.11. Portal ISAKMP Phase-2 Proposals................. 84 - 6.3.12. Portal Certificate.............................. 84 - 6.4. iSCSI Node-Keyed Attributes............................. 84 - 6.4.1. iSCSI Name...................................... 85 - 6.4.2. iSCSI Node Type................................. 85 - 6.4.3. iSCSI Node Alias................................ 86 - 6.4.4. iSCSI Node SCN Bitmap .......................... 86 - 6.4.5. iSCSI Node Index................................ 87 - 6.4.6. WWNN Token...................................... 87 - 6.4.7. iSCSI Node Next Index .......................... 89 - 6.4.8. iSCSI AuthMethod................................ 89 - 6.5. Portal Group (PG) Object-Keyed Attributes............... 89 - 6.5.1. Portal Group iSCSI Name......................... 90 - 6.5.2. PG Portal IP Addr............................... 90 - 6.5.3. PG Portal TCP/UDP Port.......................... 90 - 6.5.4. Portal Group Tag (PGT).......................... 90 - 6.5.5. Portal Group Index.............................. 90 - 6.5.6. Portal Group Next Index......................... 91 - 6.6. FC Port Name-Keyed Attributes .......................... 91 - 6.6.1. FC Port Name (WWPN)............................. 91 - 6.6.2. Port ID (FC_ID)................................. 91 - 6.6.3. FC Port Type.................................... 92 - 6.6.4. Symbolic Port Name.............................. 92 - 6.6.5. Fabric Port Name (FWWN)......................... 92 - 6.6.6. Hard Address.................................... 92 - 6.6.7. Port IP Address................................. 92 - 6.6.8. Class of Service (COS).......................... 93 - 6.6.9. FC-4 Types...................................... 93 - 6.6.10. FC-4 Descriptor................................. 93 - 6.6.11. FC-4 Features .................................. 93 - 6.6.12. iFCP SCN Bitmap................................. 93 - 6.6.13. Port Role....................................... 94 - 6.6.14. Permanent Port Name (PPN)....................... 95 - 6.7. Node-Keyed Attributes .................................. 95 - 6.7.1. FC Node Name (WWNN)............................. 95 - 6.7.2. Symbolic Node Name.............................. 95 - - - -Tseng, et al. Standards Track [Page 4] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - 6.7.3. Node IP Address................................. 95 - 6.7.4. Node IPA........................................ 96 - 6.7.5. Proxy iSCSI Name................................ 96 - 6.8. Other Attributes........................................ 96 - 6.8.1. FC-4 Type Code.................................. 96 - 6.8.2. iFCP Switch Name................................ 96 - 6.8.3. iFCP Transparent Mode Commands.................. 97 - 6.9. iSNS Server-Specific Attributes......................... 97 - 6.9.1. iSNS Server Vendor OUI.......................... 98 - 6.10. Vendor-Specific Attributes.............................. 98 - 6.10.1. Vendor-Specific Server Attributes............... 98 - 6.10.2. Vendor-Specific Entity Attributes............... 98 - 6.10.3. Vendor-Specific Portal Attributes............... 99 - 6.10.4. Vendor-Specific iSCSI Node Attributes........... 99 - 6.10.5. Vendor-Specific FC Port Name Attributes......... 99 - 6.10.6. Vendor-Specific FC Node Name Attributes......... 99 - 6.10.7. Vendor-Specific Discovery Domain Attributes..... 99 - 6.10.8. Vendor-Specific Discovery Domain Set Attributes. 99 - 6.10.9. Other Vendor-Specific Attributes................ 99 - 6.11. Discovery Domain Registration Attributes............... 100 - 6.11.1. DD Set ID Keyed Attributes..................... 100 - 6.11.2. DD ID Keyed Attributes......................... 101 - 7. Security Considerations...................................... 103 - 7.1. iSNS Security Threat Analysis ......................... 103 - 7.2. iSNS Security Implementation and Usage Requirements.... 104 - 7.3. Discovering Security Requirements of Peer Devices...... 105 - 7.4. Configuring Security Policies of iFCP/iSCSI Devices.... 106 - 7.5. Resource Issues........................................ 107 - 7.6. iSNS Interaction with IKE and IPSec.................... 107 - 8. IANA Considerations.......................................... 107 - 8.1. Registry of Block Storage Protocols.................... 107 - 8.2. Registry of Standard iSNS Attributes .................. 108 - 8.3. Block Structure Descriptor (BSD) Registry.............. 108 - 9. Normative References......................................... 109 - 10. Informative References....................................... 110 - Appendix A: iSNS Examples........................................ 112 - A.1. iSCSI Initialization Example........................... 112 - A.1.1. Simple iSCSI Target Registration............... 112 - A.1.2. Target Registration and DD Configuration....... 114 - A.1.3. Initiator Registration and Target Discovery.... 117 - Acknowledgements................................................. 121 - - - - - - - - - - -Tseng, et al. Standards Track [Page 5] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -1. Introduction - -1.1. Conventions Used in This Document - - "iSNS" refers to the storage network model and associated services - covered in the text of this document. - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in [RFC2119]. - - All frame formats are in big endian network byte order. - - All unused fields and bitmaps, including those that are RESERVED, - SHOULD be set to zero when sending and ignored when receiving. - -1.2. Purpose of This Document - - This is a standards track document containing normative text - specifying the iSNS Protocol, used by iSCSI and iFCP devices to - communicate with the iSNS server. This document focuses on the - interaction between iSNS servers and iSNS clients; interactions among - multiple authoritative primary iSNS servers are a potential topic for - future work. - -2. iSNS Overview - - iSNS facilitates scalable configuration and management of iSCSI and - Fibre Channel (FCP) storage devices in an IP network by providing a - set of services comparable to that available in Fibre Channel - networks. iSNS thus allows a commodity IP network to function at a - level of intelligence comparable to a Fibre Channel fabric. iSNS - allows the administrator to go beyond a simple device-by-device - management model, where each storage device is manually and - individually configured with its own list of known initiators and - targets. Using the iSNS, each storage device subordinates its - discovery and management responsibilities to the iSNS server. The - iSNS server thereby serves as the consolidated configuration point - through which management stations can configure and manage the entire - storage network, including both iSCSI and Fibre Channel devices. - - iSNS can be implemented to support iSCSI and/or iFCP protocols as - needed; an iSNS implementation MAY provide support for one or both of - these protocols as desired by the implementor. Implementation - requirements within each of these protocols are further discussed in - Section 5. Use of iSNS is OPTIONAL for iSCSI and REQUIRED for iFCP. - - - - - -Tseng, et al. Standards Track [Page 6] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -2.1. iSNS Architectural Components - -2.1.1. iSNS Protocol (iSNSP) - - The iSNS Protocol (iSNSP) is a flexible and lightweight protocol that - specifies how iSNS clients and servers communicate. It is suitable - for various platforms, including switches and targets as well as - server hosts. - -2.1.2. iSNS Client - - iSNS clients initiate transactions with iSNS servers using the iSNSP. - iSNS clients are processes that are co-resident in the storage - device, and that can register device attribute information, download - information about other registered clients in a common Discovery - Domain (DD), and receive asynchronous notification of events that - occur in their DD(s). Management stations are a special type of iSNS - client that have access to all DDs stored in the iSNS. - -2.1.3. iSNS Server - - iSNS servers respond to iSNS protocol queries and requests, and - initiate iSNS protocol State Change Notifications. Properly - authenticated information submitted by a registration request is - stored in an iSNS database. - -2.1.4. iSNS Database - - The iSNS database is the information repository for the iSNS - server(s). It maintains information about iSNS client attributes. A - directory-enabled implementation of iSNS may store client attributes - in an LDAP directory infrastructure. - -2.1.5. iSCSI - - iSCSI (Internet SCSI) is an encapsulation of SCSI for a new - generation of storage devices interconnected with TCP/IP [iSCSI]. - -2.1.6. iFCP - - iFCP (Internet FCP) is a gateway-to-gateway protocol designed to - interconnect existing Fibre Channel and SCSI devices using TCP/IP. - iFCP maps the existing FCP standard and associated Fibre Channel - services to TCP/IP [iFCP]. - - - - - - - -Tseng, et al. Standards Track [Page 7] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -2.2. iSNS Functional Overview - - There are four main functions of the iSNS: - - 1) A Name Service Providing Storage Resource Discovery - - 2) Discovery Domain (DD) and Login Control Service - - 3) State Change Notification Service - - 4) Open Mapping of Fibre Channel and iSCSI Devices - -2.2.1. Name Registration Service - - The iSNS provides a registration function to allow all entities in a - storage network to register and query the iSNS database. Both - targets and initiators can register in the iSNS database, as well as - query for information about other initiators and targets. This - allows, for example, a client initiator to obtain information about - target devices from the iSNS server. This service is modeled on the - Fibre Channel Generic Services Name Server described in FC-GS-4, with - extensions, operating within the context of an IP network. - - The naming registration service also provides the ability to obtain a - network-unique Domain ID for iFCP gateways when one is required. - -2.2.2. Discovery Domain and Login Control Service - - The Discovery Domain (DD) Service facilitates the partitioning of - Storage Nodes into more manageable groupings for administrative and - login control purposes. It allows the administrator to limit the - login process of each host to the more appropriate subset of targets - registered in the iSNS. This is particularly important for reducing - the number of unnecessary logins (iSCSI logins or Fibre Channel Port - Logins), and for limiting the amount of time that the host spends - initializing login relationships as the size of the storage network - scales up. Storage Nodes must be in at least one common enabled DD - in order to obtain information about each other. Devices can be - members of multiple DDs simultaneously. - - Login Control allows targets to delegate their access - control/authorization policies to the iSNS server. This is - consistent with the goal of centralizing management of those storage - devices using the iSNS server. The target node or device downloads - the list of authorized initiators from the iSNS. Each node or device - is uniquely identified by an iSCSI Name or FC Port Name. Only - - - - - -Tseng, et al. Standards Track [Page 8] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - initiators that match the required identification and authorization - provided by the iSNS will be allowed access by that target Node - during session establishment. - - Placing Portals of a Network Entity into Discovery Domains allows - administrators to indicate the preferred IP Portal interface through - which storage traffic should access specific Storage Nodes of that - Network Entity. If no Portals of a Network Entity have been placed - into a DD, then queries scoped to that DD SHALL report all Portals of - that Network Entity. If one or more Portals of a Network Entity have - been placed into a DD, then queries scoped to that DD SHALL report - only those Portals that have been explicitly placed in the DD. - - DDs can be managed offline through a separate management workstation - using the iSNSP or SNMP. If the target opts to use the Login Control - feature of the iSNS, the target delegates management of access - control policy (i.e., the list of initiators allowed to log in to - that target) to the management workstations that are managing the - configuration in the iSNS database. - - If administratively authorized, a target can upload its own Login - Control list. This is accomplished using the DDReg message and - listing the iSCSI name of each initiator to be registered in the - target's DD. - - An implementation MAY decide that newly registered devices that have - not explicitly been placed into a DD by the management station will - be placed into a "default DD" contained in a "default DDS" whose - initial DD Set Status value is "enabled". This makes them visible to - other devices in the default DD. Other implementations MAY decide - that they are registered with no DD, making them inaccessible to - source-scoped iSNSP messages. - - The iSNS server uses the Source Attribute of each iSNSP message to - determine the originator of the request and to scope the operation to - a set of Discovery Domains. In addition, the Node Type (specified in - the iFCP or iSCSI Node Type bitmap field) may also be used to - determine authorization for the specified iSNS operation. For - example, only Control Nodes are authorized to create or delete - discovery domains. - - Valid and active Discovery Domains (DDs) belong to at least one - active Discovery Domain Set (DDS). Discovery Domains that do not - belong to an activated DDS are not enabled. The iSNS server MUST - maintain the state of DD membership for all Storage Nodes, even for - those that have been deregistered. DD membership is persistent - regardless of whether a Storage Node is actively registered in the - iSNS database. - - - -Tseng, et al. Standards Track [Page 9] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -2.2.3. State Change Notification Service - - The State Change Notification (SCN) service allows the iSNS Server to - issue notifications about network events that affect the operational - state of Storage Nodes. The iSNS client may register for - notifications on behalf of its Storage Nodes for notification of - events detected by the iSNS Server. SCNs notify iSNS clients of - explicit or implicit changes to the iSNS database; they do not - necessarily indicate the state of connectivity to peer storage - devices in the network. The response of a storage device to receipt - of an SCN is implementation-specific; the policy for responding to - SCNs is outside of the scope of this document. - - There are two types of SCN registrations: regular registrations and - management registrations. Management registrations result in - management SCNs, whereas regular registrations result in regular - SCNs. The type of registration and SCN message is indicated in the - SCN bitmap (see Sections 6.4.4 and 6.6.12). - - A regular SCN registration indicates that the Discovery Domain - Service SHALL be used to control the distribution of SCN messages. - Receipt of regular SCNs is limited to the discovery domains in which - the SCN-triggering event takes place. Regular SCNs do not contain - information about discovery domains. - - A management SCN registration can only by requested by Control Nodes. - Management SCNs resulting from management registrations are not bound - by the Discovery Domain service. Authorization to request management - SCN registrations may be administratively controlled. - - The iSNS server SHOULD be implemented with hardware and software - resources sufficient to support the expected number of iSNS clients. - However, if resources are unexpectedly exhausted, then the iSNS - server MAY refuse SCN service by returning an SCN Registration - Rejected (Status Code 17). The rejection might occur in situations - where the network size or current number of SCN registrations has - passed an implementation-specific threshold. A client not allowed to - register for SCNs may decide to monitor its sessions with other - storage devices directly. - - - The specific notification mechanism by which the iSNS server learns - of the events that trigger SCNs is implementation-specific, but can - include examples such as explicit notification messages from an iSNS - client to the iSNS server, or a hardware interrupt to a switch-hosted - iSNS server as a result of link failure. - - - - - -Tseng, et al. Standards Track [Page 10] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -2.2.4. Open Mapping between Fibre Channel and iSCSI Devices - - The iSNS database stores naming and discovery information about both - Fibre Channel and iSCSI devices. This allows the iSNS server to - store mappings of a Fibre Channel device to a proxy iSCSI device - "image" in the IP network. Similarly, mappings of an iSCSI device to - a "proxy WWN" can be stored under the WWNN Token field for that iSCSI - device. - - Furthermore, through use of iSCSI-FC gateways, Fibre Channel-aware - management stations can interact with the iSNS server to retrieve - information about Fibre Channel devices, and use this information to - manage Fibre Channel and iSCSI devices. This allows management - functions such as Discovery Domains and State Change Notifications to - be applied seamlessly to both iSCSI and Fibre Channel devices, - facilitating integration of IP networks with Fibre Channel devices - and fabrics. - - Note that Fibre Channel attributes are stored as iFCP attributes, and - that the ability to store this information in the iSNS server is - useful even if the iFCP protocol is not implemented. In particular, - tag 101 can be used to store a "Proxy iSCSI Name" for Fibre Channel - devices registered in the iSNS server. This field is used to - associate the FC device with an iSCSI registration entry that is used - for the Fibre Channel device to communicate with iSCSI devices in the - IP network. Conversely, tag 37 (see Section 6.1) contains a WWNN - Token field, which can be used to store an FC Node Name (WWNN) value - used by iSCSI-FC gateways to represent an iSCSI device in the Fibre - Channel domain. - - By storing the mapping between Fibre Channel and iSCSI devices in the - iSNS server, this information becomes open to any authorized iSNS - client wishing to retrieve and use this information. In many cases, - this provides advantages over storing the information internally - within an iSCSI-FC gateway, where the mapping is inaccessible to - other devices except by proprietary mechanisms. - -2.3. iSNS Usage Model - - The following is a high-level description of how each type of device - in a storage network can utilize iSNS. Each type of device interacts - with the iSNS server as an iSNS client and must register itself in - the iSNS database in order to access services provided by the iSNS. - - - - - - - - -Tseng, et al. Standards Track [Page 11] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -2.3.1. iSCSI Initiator - - An iSCSI initiator will query the iSNS server to discover the - presence and location of iSCSI target devices. It may also request - state change notifications (SCNs) so that it can be notified of new - targets that appear on the network after the initial bootup and - discovery. SCNs can also inform the iSCSI initiator of targets that - have been removed from or no longer available in the storage network, - so that incomplete storage sessions can be gracefully terminated and - resources for non-existent targets can be reallocated. - -2.3.2. iSCSI Target - - An iSCSI target allows itself to be discovered by iSCSI initiators by - registering its presence in the iSNS server. It may also register - for SCNs in order to detect the addition or removal of initiators for - resource allocation purposes. The iSCSI target device may also - register for Entity Status Inquiry (ESI) messages, which allow the - iSNS to monitor the target device's availability in the storage - network. - -2.3.3. iSCSI-FC Gateway - - An iSCSI-FC gateway bridges devices in a Fibre Channel network to an - iSCSI/IP network. It may use the iSNS server to store FC device - attributes discovered in the FC name server, as well as mappings of - FC device identifiers to iSCSI device identifiers. iSNS has the - capability to store all attributes of both iSCSI and Fibre Channel - devices; iSCSI devices are managed through direct interaction using - iSNS, while FC devices can be indirectly managed through iSNS - interactions with the iSCSI-FC gateway. This allows both iSCSI and - Fibre Channel devices to be managed in a seamless management - framework. - -2.3.4. iFCP Gateway - - An iFCP gateway uses iSNS to emulate the services provided by a Fibre - Channel name server for FC devices in its gateway region. iSNS - provides basic discovery and zoning configuration information to be - enforced by the iFCP gateway. When queried, iSNS returns information - on the N_Port network address used to establish iFCP sessions between - FC devices supported by iFCP gateways. - -2.3.5. Management Station - - A management station uses iSNS to monitor storage devices and to - enable or disable storage sessions by configuring discovery domains. - A management station usually interacts with the iSNS server as a - - - -Tseng, et al. Standards Track [Page 12] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Control Node endowed with access to all iSNS database records and - with special privileges to configure discovery domains. Through - manipulation of discovery domains, the management station controls - the scope of device discovery for iSNS clients querying the iSNS - server. - -2.4. Administratively Controlled iSNS Settings - - Some important operational settings for the iSNS server are - configured using administrative means, such as a configuration file, - a console port, an SNMP, or another implementation-specific method. - These administratively-controlled settings cannot be configured using - the iSNS Protocol, and therefore the iSNS server implementation MUST - provide for such an administrative control interface. - - The following is a list of parameters that are administratively - controlled for the iSNS server. In the absence of alternative - settings provided by the administrator, the following specified - default settings MUST be used. - - Setting Default Setting - ------- --------------- - ESI Non-Response Threshold 3 (see 5.6.5.13) - Management SCNs (Control Nodes only) enabled (see 5.6.5.8) - Default DD/DDS disabled - DD/DDS Modification - - Control Node enabled - - iSCSI Target Node Type disabled - - iSCSI Initiator Node Type disabled - - iFCP Target Port Role disabled - - iFCP Initiator Port Role disabled - Authorized Control Nodes N/A - - ESI Non-Response Threshold: determines the number of ESI messages - sent without receiving a response before the network - entity is deregistered from the iSNS database. - - Management SCN for Control Node: determines whether a registered - Control Node is permitted to register to receive - Management SCNs. - - Default DD/DDS: determines whether a newly registered device not - explicitly placed into a discovery domain (DD) and - discovery domain set (DDS) is placed into a default - DD/DDS. - - DD/DDS Modification: determines whether the specified type of Node is - allowed to add, delete or update DDs and DDSs. - - - -Tseng, et al. Standards Track [Page 13] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Authorized Control Nodes: a list of Nodes identified by iSCSI Name or - FC Port Name WWPN that are authorized to register as - Control Nodes. - -2.5. iSNS Server Discovery - -2.5.1. Service Location Protocol (SLP) - - The Service Location Protocol (SLP) provides a flexible and scalable - framework for providing hosts with access to information about the - existence, location, and configuration of networked services, - including the iSNS server. SLP can be used by iSNS clients to - discover the IP address or FQDN of the iSNS server. To implement - discovery through SLP, a Service Agent (SA) should be cohosted in the - iSNS server, and a User Agent (UA) should be in each iSNS client. - Each client multicasts a discovery message requesting the IP address - of the iSNS server(s). The SA responds to this request. Optionally, - the location of the iSNS server can be stored in the SLP Directory - Agent (DA). - - Note that a complete description and specification of SLP can be - found in [RFC2608], and is beyond the scope of this document. A - service template for using SLP to locate iSNS servers can be found in - [iSCSI-SLP]. - -2.5.2. Dynamic Host Configuration Protocol (DHCP) - - The IP address of the iSNS server can be stored in a DHCP server to - be downloaded by iSNS clients using a DHCP option. The DHCP option - number to be used for distributing the iSNS server location is found - in [iSNSOption]. - -2.5.3. iSNS Heartbeat Message - - The iSNS heartbeat message is described in Section 5.6.5.14. It - allows iSNS clients within the broadcast or multicast domain of the - iSNS server to discover the location of the active iSNS server and - any backup servers. - -2.6. iSNS and Network Address Translation (NAT) - - The existence of NAT will have an impact upon information retrieved - from the iSNS server. If the iSNS client exists in an addressing - domain different from that of the iSNS server, then IP address - information stored in the iSNS server may not be correct when - interpreted in the domain of the iSNS client. - - - - - -Tseng, et al. Standards Track [Page 14] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - There are several possible approaches to allow operation of iSNS - within a NAT network. The first approach is to require use of the - canonical TCP port number by both targets and initiators when - addressing targets across a NAT boundary, and for the iSNS client not - to query for nominal IP addresses. Rather, the iSNS client queries - for the DNS Fully Qualified Domain Name stored in the Entity - Identifier field when seeking addressing information. Once - retrieved, the DNS name can be interpreted in each address domain and - mapped to the appropriate IP address by local DNS servers. - - A second approach is to deploy a distributed network of iSNS servers. - Local iSNS servers are deployed inside and outside NAT boundaries, - with each local server storing relevant IP addresses for their - respective NAT domains. Updates among the network of decentralized, - local iSNS servers are handled using LDAP and appropriate NAT - translation rules implemented within the update mechanism in each - server. - - Finally, note that it is possible for an iSNS server in the private - addressing domain behind a NAT boundary to exclusively support iSNS - clients that are operating in the global IP addressing domain. If - this is the case, the administrator only needs to ensure that the - appropriate mappings are configured on the NAT gateways to allow the - iSNS clients to initiate iSNSP sessions to the iSNS server. All - registered addresses contained in the iSNS server are thus public IP - addresses for use outside the NAT boundary. Care should be taken to - ensure that there are no iSNS clients querying the server from inside - the NAT boundary. - -2.7. Transfer of iSNS Database Records between iSNS Servers - - Transfer of iSNS database records between iSNS servers has important - applications, including the following: - - 1) An independent organization needs to transfer storage information - to a different organization. Each organization independently - maintains its own iSNS infrastructure. To facilitate discovery - of storage assets of the peer organization using IP, iSNS - database records can be transferred between authoritative iSNS - servers from each organization. This allows storage sessions to - be established directly between devices residing in each - organization's storage network infrastructure over a common IP - network. - - 2) Multiple iSNS servers are desired for redundancy. Backup servers - need to maintain copies of the primary server's dynamically - changing database. - - - - -Tseng, et al. Standards Track [Page 15] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - To support the above applications, information in an iSNS server can - be distributed to other iSNS servers either using the iSNS protocol, - or through out-of-band mechanisms using non-iSNS protocols. The - following examples illustrate possible methods for transferring data - records between iSNS servers. In the first example, a back-end LDAP - information base is used to support the iSNS server, and the data is - transferred using the LDAP protocol. Once the record transfer of the - remote device is completed, it becomes visible and accessible to - local devices using the local iSNS server. This allows local devices - to establish sessions with remote devices (provided that firewall - boundaries can be negotiated). - - +-------------------------+ +-------------------------+ - |+------+ iSNSP | | iSNSP +-----+ | - ||dev A |<----->+------+ | | +------+<----->|dev C| | - |+------+ | | | | | | +-----+ | - |+------+ iSNSP |local | | | |remote| iSNSP +-----+ | - ||dev B |<----->| iSNS | | | | iSNS |<----->|dev D| | - |+------+ |server| | | |server| +-----+ | - |........ +--+---+ | WAN | +---+--+ | - |.dev C'. | | Link | | | - |........ | ============= | | - | | | | | | - | +--+---+ | | +---+--+ | - | | local|<--- <--- <--- <-|remote| | - | | LDAP | | LDAP: | | LDAP | | - | +------+ Xfer "dev C"| +------+ | - +-------------------------+ +-------------------------+ - Enterprise Enterprise - Network A Network B - - In the above diagram, two business partners wish to share storage - "dev C". Using LDAP, the record for "dev C" can be transferred from - Network B to Network A. Once accessible to the local iSNS server in - Network A, local devices A and B can now discover and connect to "dev - C". - - - - - - - - - - - - - - - -Tseng, et al. Standards Track [Page 16] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - +-------------------------+ +-------------------------+ - |+------+ iSNSP | | iSNSP +-----+ | - ||dev A |<----->+------+ | | +------+<----->|dev C| | - |+------+ | | | | | | +-----+ | - |+------+ iSNSP |local | | | |remote| iSNSP +-----+ | - ||dev B |<----->| iSNS | | | | iSNS |<----->|dev D| | - |+------+ |server| | | |server| +-----+ | - |........ +------+ | WAN | +---+--+ | - |.dev C'. ^ | Link | | | - |........ | ============= v | - | | | | |SNMP | - | | | | | | - | +--+----+ | | v | - | | SNMP |<--- <--- <--- <---- | - | | Mgmt | | SNMP: Xfer "dev C" | - | |Station| | | | - | +-------+ | | | - +-------------------------+ +-------------------------+ - Enterprise Enterprise - Network A Network B - - The above diagram illustrates a second example of how iSNS records - can be shared. This method uses an SNMP-based management station to - retrieve (GET) the desired record for "dev C" manually, and then to - store (SET) it on the local iSNS server directly. Once the record is - transferred to the local iSNS server in Network A, "dev C" becomes - visible and accessible (provided that firewall boundaries can be - negotiated) to other devices in Network A. - - Other methods, including proprietary protocols, can be used to - transfer device records between iSNS servers. Further discussion and - explanation of these methodologies is beyond the scope of this - document. - -2.8. Backup iSNS Servers - - This section offers a broad framework for implementation and - deployment of iSNS backup servers. Server failover and recovery are - topics of continuing research, and adequate resolution of issues such - as split brain and primary server selection is dependent on the - specific implementation requirements and deployment needs. The - failover mechanisms discussed in this document focus on the - interaction between iSNS clients and iSNS servers. Specifically, - what is covered in this document includes the following: - - - iSNS client behavior and the iSNS protocol interaction between the - client and multiple iSNS servers, some of which are backup - servers. - - - -Tseng, et al. Standards Track [Page 17] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - - Required failover behaviors of the collection of iSNS servers that - includes active and backup servers. - - However, note that this document does not specify the complete - functional failover requirements of each iSNS server. In particular, - it does not specify the complete set of protocol interactions among - the iSNS servers that are required to achieve stable failover - operation in an interoperable manner. - - For the purposes of this discussion, the specified backup mechanisms - pertain to interaction among different logical iSNS servers. Note - that it is possible to create multiple physical iSNS servers to form - a single logical iSNS server cluster, and thus to distribute iSNS - transaction processing among multiple physical servers. However, a - more detailed discussion of the interactions between physical servers - within a logical iSNS server cluster is beyond the scope of this - document. - - Multiple logical iSNS servers can be used to provide redundancy in - the event that the active iSNS server fails or is removed from the - network. The methods described in Section 2.7 above can be used to - transfer name server records to backup iSNS servers. Each backup - server maintains a redundant copy of the name server database found - in the primary iSNS server, and can respond to iSNS protocol messages - in the same way as the active server. Each backup server SHOULD - monitor the health and status of the active iSNS server, including - checking to make sure its own database is synchronized with the - active server's database. How each backup server accomplishes this - is implementation-dependent, and may (or may not) include using the - iSNS protocol. If the iSNS protocol is used, then the backup server - MAY register itself in the active server's iSNS database as a Control - Node, allowing it to receive state-change notifications. - - Generally, the administrator or some automated election process is - responsible for initial and subsequent designation of the primary - server and each backup server. - - A maximum of one logical backup iSNS server SHALL exist at any - individual IP address, in order to avoid conflicts from multiple - servers listening on the same canonical iSNS TCP or UDP port number. - - The iSNS heartbeat can also be used to coordinate the designation and - selection of primary and backup iSNS servers. - - Each backup server MUST note its relative precedence in the active - server's list of backup servers. If its precedence is not already - known, each backup server MAY learn it from the iSNS heartbeat - message, by noting the position of its IP address in the ordered list - - - -Tseng, et al. Standards Track [Page 18] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - of backup server IP addresses. For example, if it is the first - backup listed in the heartbeat message, then its backup precedence is - 1. If it is the third backup server listed, then its backup - precedence is 3. - - If a backup server establishes that it has lost connectivity to the - active server and other backup servers of higher precedence, then it - SHOULD assume that it is the active server. The method of - determining whether connectivity has been lost is implementation- - specific. One possible approach is to assume that if the backup - server does not receive iSNS heartbeat messages for a period of time, - then connectivity to the active server has been lost. Alternatively, - the backup server may establish TCP connections to the active server - and other backup servers, with loss of connectivity determined - through non-response to periodic echo or polling messages (using - iSNSP, SNMP, or other protocols). - - When a backup server becomes the active server, it SHALL assume all - active server responsibilities, including (if used) transmission of - the iSNS heartbeat message. If transmitting the iSNS heartbeat, the - backup server replaces the active Server IP Address and TCP/UDP Port - entries with its own IP address and TCP/UDP Port, and begins - incrementing the counter field from the last known value from the - previously-active iSNS server. However, it MUST NOT change the - original ordered list of backup server IP Address and TCP/UDP Port - entries. If the primary backup server or other higher-precedence - backup server returns, then the existing active server is responsible - for ensuring that the new active server's database is up-to-date - before demoting itself to its original status as backup. - - Since the primary and backup iSNS servers maintain a coordinated - database, no re-registration by an iSNS Client is required when a - backup server takes the active server role. Likewise, no re- - registration by an iSNS Client is required when the previous primary - server returns to the active server role. - -2.9. Transport Protocols - - The iSNS Protocol is transport-neutral. Query and registration - messages are transported over TCP or UDP. iSNS heartbeat messages - are transported using IP multicast or broadcast. - -2.9.1. Use of TCP for iSNS Communication - - It MUST be possible to use TCP for iSNS communication. The iSNS - server MUST accept TCP connections for client registrations. To - receive Entity Status Inquiry (ESI) (see Section 5.6.5.13) monitoring - the use of TCP, the client registers the Portal ESI Interval and the - - - -Tseng, et al. Standards Track [Page 19] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - port number of the TCP port that will be used to receive ESI - messages. The iSNS server initiates the TCP connection used to - deliver the ESI message. This TCP connection does not need to be - continuously open. - - To receive SCN notifications using TCP, the client registers the - iSCSI or iFCP SCN Bitmap and the port number of the TCP port in the - Portal used to receive SCNs. The iSNS server initiates the TCP - connection used to deliver the SCN message. This TCP connection does - not need to be continuously open. - - It is possible for an iSNS client to use the same TCP connection for - SCN, ESI, and iSNS queries. Alternatively, separate connections may - be used. - -2.9.2. Use of UDP for iSNS Communication - - The iSNS server MAY accept UDP messages for client registrations. - The iSNS server MUST accept registrations from clients requesting - UDP-based ESI and SCN messages. - - To receive UDP-based ESI monitoring messages, the client registers - the port number of the UDP port in at least one Portal to be used to - receive and respond to ESI messages from the iSNS server. If a - Network Entity has multiple Portals with registered ESI UDP Ports, - then ESI messages SHALL be delivered to every Portal registered to - receive such messages. - - To receive UDP-based SCN notification messages, the client registers - the port number of the UDP port in at least one Portal to be used to - receive SCN messages from the iSNS server. If a Network Entity has - multiple Portals with registered SCN UDP Ports, then SCN messages - SHALL be delivered to each Portal registered to receive such - messages. - - When using UDP to transport iSNS messages, each UDP datagram MUST - contain exactly one iSNS PDU (see Section 5). - -2.9.3. iSNS Multicast and Broadcast Messages - - iSNS multicast messages are transported using IP multicast or - broadcast. The iSNS heartbeat is the only iSNS multicast or - broadcast message. This message is originated by the iSNS server and - sent to all iSNS clients that are listening on the IP multicast - address allocated for the iSNS heartbeat. - - - - - - -Tseng, et al. Standards Track [Page 20] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -2.10. Simple Network Management Protocol (SNMP) Requirements - - The iSNS Server may be managed via the iSNS MIB [iSNSMIB] using an - SNMP management framework [RFC3411]. For a detailed overview of the - documents that describe the current Internet-Standard Management - Framework, please refer to Section 7 of RFC 3410 [RFC3410]. The iSNS - MIB provides the ability to configure and monitor an iSNS server - without using the iSNS protocol directly. SNMP management frameworks - have several requirements for object indexing in order for objects to - be accessed or added. - - SNMP uses an Object Identifier (OID) for object identification. The - size of each OID is restricted to a maximum of 128 sub-identifiers. - Both the iSCSI and iFCP protocol contain identifiers, such as the - iSCSI Name, that are greater the 128 characters in length. Using - such identifiers as an index would result in more than 128 sub- - identifiers per OID. In order to support objects that have key - identifiers whose maximum length is longer than the maximum SNMP- - supported length, the iSNS server provides secondary non-zero integer - index identifiers. These indexes SHALL be persistent for as long as - the server is active. Furthermore, index values for recently - deregistered objects SHOULD NOT be reused in the short term. Object - attributes, including indexes, are described in detail in Section 6. - - For SNMP based management applications to create a new entry in a - table of objects, a valid OID must be available to specify the table - row. The iSNS server supports this by providing, for each type of - object that can be added via SNMP, an object attribute that returns - the next available non-zero integer index. This allows an SNMP - client to request an OID to be used for registering a new object in - the server. Object attributes, including next available index - attributes, are described in detail in Section 6. - -3. iSNS Object Model - - iSNS provides the framework for the registration, discovery, and - management of iSCSI devices and Fibre Channel-based devices (using - iFCP). This architecture framework provides elements needed to - describe various storage device objects and attributes that may exist - on an IP storage network. Objects defined in this architecture - framework include Network Entity, Portal, Storage Node, FC Device, - Discovery Domain, and Discovery Domain Set. Each of these objects is - described in greater detail in the following sections. - - - - - - - - -Tseng, et al. Standards Track [Page 21] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -3.1. Network Entity Object - - The Network Entity object is a container of Storage Node objects and - Portal objects. It represents the infrastructure supporting access - to a unique set of one or more Storage Nodes. The Entity Identifier - attribute uniquely distinguishes a Network Entity, and is the key - used to register a Network Entity object in an iSNS server. All - Storage Nodes and Portals contained within a single Network Entity - object operate as a cohesive unit. - - Note that it is possible for a single physical device or gateway to - be represented by more than one logical Network Entity in the iSNS - database. For example, one of the Storage Nodes on a physical device - may be accessible from only a subset of the network interfaces (i.e., - Portals) available on that device. In this case, a logical network - entity (i.e., a "shadow entity") is created and used to contain the - Portals and Storage Nodes that can operate cooperatively. No object - (Portals, Storage Nodes, etc.) can be contained in more than one - logical Network Entity. - - Similarly, it is possible for a logical Network Entity to be - supported by more than one physical device or gateway. For example, - multiple FC-iSCSI gateways may be used to bridge FC devices in a - single Fibre Channel network. Collectively, the multiple gateways - can be used to support a single logical Network Entity that is used - to contain all the devices in that Fibre Channel network. - -3.2. Portal Object - - The Portal object is an interface through which access to Storage - Nodes within the Network Entity can be obtained. The IP address and - TCP/UDP Port number attributes uniquely distinguish a Portal object, - and combined are the key used to register a Portal object in an iSNS - server. A Portal is contained in one and only one Network Entity, - and may be contained in one or more DDs (see Section 3.6). - -3.3. Storage Node Object - - The Storage Node object is the logical endpoint of an iSCSI or iFCP - session. In iFCP, the session endpoint is represented by the World - Wide Port Name (WWPN). In iSCSI, the session endpoint is represented - by the iSCSI Name of the device. For iSCSI, the iSCSI Name attribute - uniquely distinguishes a Storage Node, and is the key used to - register a Storage Node object in an iSNS Server. For iFCP, the FC - Port Name (WWPN) attribute uniquely distinguishes a Storage Node, and - is the key used to register a Storage Node object in the iSNS Server. - Storage Node is contained in only one Network Entity object and may - be contained in one or more DDs (see Section 3.6). - - - -Tseng, et al. Standards Track [Page 22] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -3.4. Portal Group Object - - The Portal Group (PG) object represents an association between a - Portal and an iSCSI Node. Each Portal and iSCSI Storage Node - registered in an Entity can be associated using a Portal Group (PG) - object. The PG Tag (PGT), if non-NULL, indicates that the associated - Portal provides access to the associated iSCSI Storage Node in the - Entity. All Portals that have the same PGT value for a specific - iSCSI Storage Node allow coordinated access to that node. - - A PG object MAY be registered when a Portal or iSCSI Storage Node is - registered. Each Portal to iSCSI Node association is represented by - one and only one PG object. In order for a Portal to provide access - to an iSCSI Node, the PGT of the PG object MUST be non-NULL. If the - PGT value registered for a specified Portal and iSCSI Node is NULL, - or if no PGT value is registered, then the Portal does not provide - access to that iSCSI Node in the Entity. - - The PGT value indicates whether access to an iSCSI Node can be - coordinated across multiple Portals. All Portals that have the same - PGT value for a specific iSCSI Node can provide coordinated access to - that iSCSI Node. According to the iSCSI Specification, coordinated - access to an iSCSI node indicates the capability of coordinating an - iSCSI session with connections that span these Portals [iSCSI]. - - The PG object is uniquely distinguished by the iSCSI Name, Portal IP - Address, and Portal TCP Port values of the associated Storage Node - and Portal objects. These are represented in the iSNS Server by the - PG iSCSI Name, PG Portal IP Address, and PG Portal TCP/UDP Port - attributes, respectively. The PG object is also uniquely - distinguished in the iSNS Server by the PG Index value. - - A new PG object can only be registered by referencing its associated - iSCSI Storage Node or Portal object. A pre-existing PG object can be - modified or queried by using its Portal Group Index as message key, - or by referencing its associated iSCSI Storage Node or Portal object. - A 0-length Tag, Length, Value TLV is used to register a PGT NULL - value. - - The PG object is deregistered if and only if its associated iSCSI - Node and Portal objects are both removed. - - - - - - - - - - -Tseng, et al. Standards Track [Page 23] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -3.5. Device Object - - The FC Device represents the Fibre Channel Node. This object - contains information that may be useful in the management of the - Fibre Channel device. The FC Node Name (WWNN) attribute uniquely - distinguishes an FC Device, and is the key used to register an FC - Device object in the iSNS Server. - - The FC Device is contained in one or more Storage Node objects. - -3.6. Discovery Domain Object - - Discovery Domains (DD) are a security and management mechanism used - to administer access and connectivity to storage devices. For query - and registration purposes, they are considered containers for Storage - Node and Portal objects. A query by an iSNS client that is not from - a Control Node only returns information about objects with which it - shares at least one active DD. The only exception to this rule is - with Portals; if Storage Nodes of a Network Entity are registered in - the DD without Portals, then all Portals of that Network Entity are - implicit members of that DD. The Discovery Domain ID (DD_ID) - attribute uniquely distinguishes a Discovery Domain object, and is - the key used to register a Discovery Domain object in the iSNS - Server. - - A DD is considered active if it is a member of at least one active DD - Set. DDs that are not members of at least one enabled DDS are - considered disabled. A Storage Node can be a member of one or more - DDs. An enabled DD establishes connectivity among the Storage Nodes - in that DD. - -3.7. Discovery Domain Set Object - - The Discovery Domain Set (DDS) is a container object for Discovery - Domains (DDs). DDSs may contain one or more DDs. Similarly, each DD - can be a member of one or more DDSs. DDSs are a mechanism to store - coordinated sets of DD mappings in the iSNS server. Active DDs are - members of at least one active DD Set. Multiple DDSs may be - considered active at the same time. The Discovery Domain Set ID - (DDS_ID) attribute uniquely distinguishes a Discovery Domain Set - object, and is the key used to register a Discovery Domain Set object - in the iSNS Server. - -3.8. Database Model - - As presented to the iSNS client, each object of a specific type in - the iSNS database MUST have an implicit internal linear ordering - based on the key(s) for that object type. This ordering provides the - - - -Tseng, et al. Standards Track [Page 24] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - ability to respond to DevGetNext queries (see Section 5.6.5.3). The - ordering of objects in the iSNS database SHOULD NOT be changed with - respect to that implied ordering, as a consequence of object - insertions and deletions. That is, the relative order of surviving - object entries in the iSNS database SHOULD be preserved so that the - DevGetNext message encounters generally reasonable behavior. - - The following diagram shows the various objects described above and - their relationship to each other. - - +--------------+ +-----------+ - | NETWORK |1 *| | - | ENTITY |----| PORTAL | - | | | | - +--------------+ +-----------+ - |1 |1 |* - | | | - | |* | - | +----------+ | - | | PORTAL | | - | | GROUP | | - | +----------+ | - | |* | - | | | - |* |1 |* - +-----------+ +--------------+ +-----------+ +-----------+ - | FC |1 *| STORAGE |* *| DISCOVERY |* *| DISCOVERY | - | DEVICE |----| NODE |----| DOMAIN |----| DOMAIN | - | | | | | | | SET | - +-----------+ +--------------+ +-----------+ +-----------+ - - * represents 0 to many possible relationships - -4. iSNS Implementation Requirements - - This section details specific requirements for support of each of - these IP storage protocols. Implementation requirements for security - are described in Section 7. - -4.1. iSCSI Requirements - - Use of iSNS in support of iSCSI is OPTIONAL. iSCSI devices MAY be - manually configured with the iSCSI Name and IP address of peer - devices, without the aid or intervention of iSNS. iSCSI devices may - also use SLP [RFC2608] to discover peer iSCSI devices. However, iSNS - is useful for scaling a storage network to a larger number of iSCSI - devices. - - - - -Tseng, et al. Standards Track [Page 25] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -4.1.1. Required Attributes for Support of iSCSI - - The following attributes are available to support iSCSI. Attributes - indicated in the REQUIRED for Server column MUST be implemented by an - iSNS server used to support iSCSI. Attributes indicated in the - REQUIRED for Client column MUST be implemented by an iSCSI device - that elects to use the iSNS. Attributes indicated in the K (Key) - column uniquely identify the object type in the iSNS Server. A more - detailed description of each attribute is found in Section 6. - - REQUIRED for: - Object Attribute K Server Client - ------ --------- - ------ ------ - NETWORK ENTITY Entity Identifier * * * - Entity Protocol * * - Management IP Address * - Timestamp * - Protocol Version Range * - Registration Period * - Entity Index * - Entity IKE Phase-1 Proposal - Entity Certificate - - PORTAL IP Address * * * - TCP/UDP Port * * * - Portal Symbolic Name * - ESI Interval * - ESI Port * - Portal Index * - SCN Port * - Portal Security Bitmap * - Portal IKE Phase-1 Proposal - Portal IKE Phase-2 Proposal - Portal Certificate - - PORTAL GROUP PG iSCSI Name * * * - PG IP Address * * * - PG TCP/UDP Port * * * - PG Tag * * - PG Index * - - - - - - - - - - - -Tseng, et al. Standards Track [Page 26] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - STORAGE NODE iSCSI Name * * * - iSCSI Node Type * * - Alias * - iSCSI SCN Bitmap * - iSCSI Node Index * - WWNN Token - iSCSI AuthMethod - iSCSI Node Certificate - - DISCOVERY DOMAIN DD ID * * * - DD Symbolic Name * - DD Member iSCSI Node Index * - DD Member iSCSI Name * - DD Member Portal Index * - DD Member Portal IP Addr * - DD Member Portal TCP/UDP * - DD Features * - - DISCOVERY DOMAIN DDS Identifier * * - SET DDS Symbolic Name * - DDS Status * - - All iSCSI user-specified and vendor-specified attributes are OPTIONAL - to implement and use. - - - - - - - - - - - - - - - - - - - - - - - - - - - -Tseng, et al. Standards Track [Page 27] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -4.1.2. Examples: iSCSI Object Model Diagrams - - The following diagram models how a simple iSCSI-based initiator and - target is represented using database objects stored in the iSNS - server. In this implementation, each target and initiator is - attached to a single Portal. - - +----------------------------------------------------------------+ - | IP Network | - +------------+--------------------------------------+------------+ - | | - | | - +-----+------+------+-----+ +-----+------+------+-----+ - | | PORTAL | | | | PORTAL | | - | | -IP Addr 1 | | | | -IP Addr 2 | | - | | -TCP Port 1 | | | | -TCP Port 2 | | - | +-----+ +-----+ | | +-----+ +-----+ | - | | | | | | | | - | +-----+ +-----+ | | +-----+ +-----+ | - | | PORTAL GROUP| | | | PORTAL GROUP| | - | | -Prtl Tag 1 | | | | -Prtl Tag 2 | | - | +-----+ +-----+ | | +-----+ +-----+ | - | | | | | | | | - | +--------+ +--------+ | | +-------+ +--------+ | - | | | | | | | | - | | STORAGE NODE | | | | STORAGE NODE | | - | | -iSCSI Name | | | | -iSCSI Name | | - | | -Alias: "server1"| | | | -Alias: "disk1"| | - | | -Type: initiator | | | | -Type: target | | - | | | | | | | | - | +-------------------+ | | +------------------+ | - | | | | - | NETWORK ENTITY | | NETWORK ENTITY | - | -Entity ID (FQDN): | | -Entity ID (FQDN): | - | "strg1.example.com" | | "strg2.example.net" | - | -Protocol: iSCSI | | -Protocol: iSCSI | - | | | | - +-------------------------+ +-------------------------+ - - The object model can be expanded to describe more complex devices, - such as an iSCSI device with more than one storage controller, in - which each controller is accessible through any of multiple Portal - interfaces, possibly using multiple Portal Groups. The storage - controllers on this device can be accessed through alternate Portal - interfaces if any original interface should fail. The following - diagram describes such a device: - - - - - -Tseng, et al. Standards Track [Page 28] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - +---------------------------------------------------------------+ - | IP Network | - +-------------------+-----------------------+-------------------+ - | | - | | - +------------+------+------+---------+------+------+------------+ - | | PORTAL 1 | | PORTAL 2 | | - | | -IP Addr 1 | | -IP Addr 2 | | - | | -TCP Port 1 | | -TCP Port 2 | | - | +-----+ +-----+ +-----+ +-----+ | - | | | | | | - | +---------------+ +---------------------+ +---------------+ | - | +-------+ +----------------+ +-------------------+ +------+ | - | | | | | | | | - | +-------+ +-------+ +------+ +--------+ +--------+ +------+ | - | | | | | | | | - | | STORAGE NODE 1 | | STORAGE NODE 2 | | STORAGE NODE 3 | | - | | -iSCSI Name 1 | | -iSCSI Name 2 | | -iSCSI Name 3 | | - | | -Alias: "disk1"| | -Alias: "disk2"| | -Alias: "disk3"| | - | | -Type: target | | -Type: target | | -Type: target | | - | | | | | | | | - | +-----------------+ +-----------------+ +-----------------+ | - | | - | NETWORK ENTITY | - | -Entity ID (FQDN): "dev1.example.com" | - | -Protocol: iSCSI | - | | - | Portal Group Object Table | - | Storage-Node Portal Portal-Group-Tag | - | 1 1 10 | - | 1 2 NULL (no access permitted) | - | 2 1 20 | - | 2 2 20 | - | 3 1 30 | - | 3 2 10 | - | | - +---------------------------------------------------------------+ - - Storage Node 1 is accessible via Portal 1 with a PGT of 10. It does - not have a Portal Group Tag (PGT) assigned for Portal 2, so Storage - Node 1 cannot be accessed via Portal 2. - - Storage Node 2 can be accessed via both Portal 1 and Portal 2. Since - Storage Node 2 has the same PGT value assigned to both Portal 1 and - Portal 2, in this case 20, coordinated access via the Portals is - available [iSCSI]. - - - - - -Tseng, et al. Standards Track [Page 29] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Storage Node 3 can be accessed via Portal 1 or Portal 2. However, - since Storage Node 3 has different PGT values assigned to each - Portal, in this case 10 and 30, access is not coordinated [iSCSI]. - Because PGTs are assigned within the context of a Storage Node, the - PGT value of 10 used for Storage Node 1 and Storage Node 3 are not - interrelated. - -4.1.3. Required Commands and Response Messages for Support of iSCSI - - The following iSNSP messages and responses are available in support - of iSCSI. Messages indicated in the REQUIRED for Server column MUST - be implemented in iSNS servers used for iSCSI devices. Messages - indicated in the REQUIRED for Client column MUST be implemented in - iSCSI devices that elect to use the iSNS server. - - REQUIRED for: - Message Description Abbreviation Func_ID Server Client - ------------------- ------------ ------- ------ ------ - RESERVED 0x0000 - Device Attr Reg Request DevAttrReg 0x0001 * * - Dev Attr Query Request DevAttrQry 0x0002 * * - Dev Get Next Request DevGetNext 0x0003 * - Deregister Dev Request DevDereg 0x0004 * * - SCN Register Request SCNReg 0x0005 * - SCN Deregister Request SCNDereg 0x0006 * - SCN Event SCNEvent 0x0007 * - State Change Notification SCN 0x0008 * - DD Register DDReg 0x0009 * * - DD Deregister DDDereg 0x000A * * - DDS Register DDSReg 0x000B * * - DDS Deregister DDSDereg 0x000C * * - Entity Status Inquiry ESI 0x000D * - Name Service Heartbeat Heartbeat 0x000E - RESERVED 0x000F-0x00FF - Vendor Specific 0x0100-0x01FF - RESERVED 0x0200-0x7FFF - - The following are iSNSP response messages used in support of iSCSI: - - REQUIRED for: - Response Message Desc Abbreviation Func_ID Server Client - --------------------- ------------ ------- ------ ------ - RESERVED 0x8000 - Device Attr Register Rsp DevAttrRegRsp 0x8001 * * - Device Attr Query Rsp DevAttrQryRsp 0x8002 * * - Device Get Next Rsp DevGetNextRsp 0x8003 * - Device Dereg Rsp DevDeregRsp 0x8004 * * - SCN Register Rsp SCNRegRsp 0x8005 * - - - -Tseng, et al. Standards Track [Page 30] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - SCN Deregister Rsp SCNDeregRsp 0x8006 * - SCN Event Rsp SCNEventRsp 0x8007 * - SCN Response SCNRsp 0x8008 * - DD Register Rsp DDRegRsp 0x8009 * * - DD Deregister Rsp DDDeregRsp 0x800A * * - DDS Register Rsp DDSRegRsp 0x800B * * - DDS Deregister Rsp DDSDeregRsp 0x800C * * - Entity Stat Inquiry Rsp ESIRsp 0x800D * - RESERVED 0x800E-0x80FF - Vendor Specific 0x8100-0x81FF - RESERVED 0x8200-0xFFFF - -4.2. iFCP Requirements - - In iFCP, use of iSNS is REQUIRED. No alternatives exist for support - of iFCP Naming & Discovery functions. - -4.2.1. Required Attributes for Support of iFCP - - The following table displays attributes that are used by iSNS to - support iFCP. Attributes indicated in the REQUIRED for Server column - MUST be implemented by the iSNS server that supports iFCP. - Attributes indicated in the REQUIRED for Client column MUST be - supported by iFCP gateways. Attributes indicated in the K (Key) - column uniquely identify the object type in the iSNS Server. A more - detailed description of each attribute is found in Section 6. - - REQUIRED for: - Object Attribute K Server Client - ------ --------- - ------ ------ - NETWORK ENTITY Entity Identifier * * * - Entity Protocol * * - Management IP Address * - Timestamp * - Protocol Version Range * - Registration period - Entity Index - Entity IKE Phase-1 Proposal - Entity Certificate - - PORTAL IP Address * * * - TCP/UDP Port * * * - Symbolic Name * - ESI Interval * - ESI Port * - SCN Port * - Portal IKE Phase-1 Proposal - Portal IKE Phase-2 Proposal - - - -Tseng, et al. Standards Track [Page 31] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Portal Certificate - Security Bitmap * - - STORAGE NODE FC Port Name (WWPN) * * * - (FC Port) Port_ID * * - FC Port Type * * - Port Symbolic Name * - Fabric Port Name (FWWN) * - Hard Address * - Port IP Address * - Class of Service * - FC FC-4 Types * - FC FC-4 Descriptors * - FC FC-4 Features * - SCN Bitmap * - iFCP Port Role * - Permanent Port Name * - - FC DEVICE FC Node Name (WWNN) * * * - (FC Node) Node Symbolic Name * - Node IP Address * - Node IPA * - Proxy iSCSI Name - - DISCOVERY DOMAIN DD ID * * * - DD Symbolic Name * - DD Member FC Port Name * - DD Member Portal Index * - DD Member Portal IP Addr * - DD Member Portal TCP/UDP * - - DISCOVERY DOMAIN DDS ID * * - SET DDS Symbolic Name * - DDS Status * - - OTHER Switch Name - Preferred_ID - Assigned_ID - Virtual_Fabric_ID - - All iFCP user-specified and vendor-specified attributes are OPTIONAL - to implement and use. - -4.2.2. Example: iFCP Object Model Diagram - - The iFCP protocol allows native Fibre Channel devices or Fibre - Channel fabrics connected to an iFCP gateway to be directly - internetworked using IP. - - - -Tseng, et al. Standards Track [Page 32] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - When supporting iFCP, the iSNS server stores Fibre Channel device - attributes, iFCP gateway attributes, and Fibre Channel fabric switch - attributes that might also be stored in an FC name server. - - The following diagram shows a representation of a gateway supporting - multiple Fibre Channel devices behind it. The two Portal objects - represent IP interfaces on the iFCP gateway that can be used to - access any of the three Storage Node objects behind it. Note that - the FC Device object is not contained in the Network Entity object. - However, each FC Device has a relationship to one or more Storage - Node objects. - - +--------------------------------------------------------+ - | IP Network | - +--------+-----------------+-----------------------------+ - | | - +-+------+------+---+------+------+----------------------+ - | | PORTAL | | PORTAL | NETWORK ENTITY | - | | -IP Addr 1 | | -IP Addr 2 | -Entity ID (FQDN): | - | | -TCP Port 1 | | -TCP Port 2 | "gtwy1.example.com" | - | +-----+ +-----+ +-----+ +-----+ -Protocol: iFCP | - | | | | | | - | +-----+ +---------------+ +----------------------+ | - | +-----+ +---------------+ +-------------+ +------+ | - | | | | | | | | - | +-----+ +-----+ +----+ +------+ +----+ +------+ | - | |STORAGE NODE | |STORAGE NODE | |STORAGE NODE | | - | | -WWPN 1 | | -WWPN 2 | | -WWPN 3 | | - | | -Port ID 1 | | -Port ID 2 | | -Port ID 3 | | - | | -FWWN 1 | | -FWWN 2 | | -FWWN 3 | | - | | -FC COS | | -FC COS | | -FC COS | | - | +------+------+ +-------+-----+ +----+--------+ | - +--------|-------------------|------------|--------------+ - | | | - +------+------+ +---+------------+---+ - | FC DEVICE | | FC DEVICE | - | -WWNN 1 | | -WWNN 2 | - | | | | - +-------------+ +--------------------+ - - - - - - - - - - - - -Tseng, et al. Standards Track [Page 33] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -4.2.3. Required Commands and Response Messages for Support of iFCP - - The iSNSP messages and responses displayed in the following tables - are available to support iFCP gateways. Messages indicated in the - REQUIRED TO IMPLEMENT column MUST be supported by the iSNS server - used by iFCP gateways. Messages indicated in the REQUIRED TO USE - column MUST be supported by the iFCP gateways themselves. - - REQUIRED for: - Message Description Abbreviation Func ID Server Client - ------------------- ------------ ------- ------ ------ - RESERVED 0x0000 - Device Attr Reg Request DevAttrReg 0x0001 * * - Device Attr Query Request DevAttrQry 0x0002 * * - Device Get Next Request DevGetNext 0x0003 * - Device Dereg Request DevDereg 0x0004 * * - SCN Register Request SCNReg 0x0005 * - SCN Deregister Request SCNDereg 0x0006 * - SCN Event SCNEvent 0x0007 * - State Change Notification SCN 0x0008 * - DD Register DDReg 0x0009 * * - DD Deregister DDDereg 0x000A * * - DDS Register DDSReg 0x000B * * - DDS Deregister DDSDereg 0x000C * * - Entity Status Inquiry ESI 0x000D * - Name Service Heartbeat Heartbeat 0x000E * - Reserved Reserved 0x000F-0x0010 - Request FC_DOMAIN_ID RqstDomId 0x0011 - Release FC_DOMAIN_ID RlseDomId 0x0012 - Get FC_DOMAIN_IDs GetDomId 0x0013 - RESERVED 0x0014-0x00FF - Vendor Specific 0x0100-0x01FF - RESERVED 0x0200-0x7FFF - - The following are iSNSP response messages in support of iFCP: - - REQUIRED for: - Response Message Desc Abbreviation Func_ID Server Client - --------------------- ------------ ------- ------ ------ - RESERVED 0x8000 - Device Attr Reg Rsp DevAttrRegRsp 0x8001 * * - Device Attr Query Rsp DevAttrQryRsp 0x8002 * * - Device Get Next Rsp DevGetNextRsp 0x8003 * - Device Deregister Rsp DevDeregRsp 0x8004 * * - SCN Register Rsp SCNRegRsp 0x8005 * - SCN Deregister Rsp SCNDeregRsp 0x8006 * - SCN Event Rsp SCNEventRsp 0x8007 * - SCN Rsp SCNRsp 0x8008 * - - - -Tseng, et al. Standards Track [Page 34] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - DD Register Rsp DDRegRsp 0x8009 * * - DD Deregister Rsp DDDeregRsp 0x800A * * - DDS Register Rsp DDSRegRsp 0x800B * * - DDS Deregister Rsp DDSDeregRsp 0x800C * * - Entity Status Inquiry Rsp ESIRsp 0x800D * - NOT USED 0x800E - RESERVED 0x800F-0x8010 - Request FC_DOMAIN_ID Rsp RqstDomIdRsp 0x8011 - Release FC_DOMAIN_ID Rsp RlseDomIdRsp 0x8012 - Get FC_DOMAIN_IDs GetDomIdRsp 0x0013 - RESERVED 0x8014-0x80FF - Vendor Specific 0x8100-0x81FF - RESERVED 0x8200-0xFFFF - -5. iSNSP Message Format - - The iSNSP message format is similar to the format of other common - protocols such as DHCP, DNS and BOOTP. An iSNSP message may be sent - in one or more iSNS Protocol Data Units (PDU). Each PDU is 4-byte - aligned. The following describes the format of the iSNSP PDU: - - Byte MSb LSb - Offset 0 15 16 31 - +---------------------+----------------------+ - 0 | iSNSP VERSION | FUNCTION ID | 4 Bytes - +---------------------+----------------------+ - 4 | PDU LENGTH | FLAGS | 4 Bytes - +---------------------+----------------------+ - 8 | TRANSACTION ID | SEQUENCE ID | 4 Bytes - +---------------------+----------------------+ - 12 | | - | PDU PAYLOAD | N Bytes - | ... | - +--------------------------------------------+ - 12+N | AUTHENTICATION BLOCK (Multicast/Broadcast) | L Bytes - +--------------------------------------------+ - Total Length = 12 + N + L - -5.1. iSNSP PDU Header - - The iSNSP PDU header contains the iSNSP VERSION, FUNCTION ID, PDU - LENGTH, FLAGS, TRANSACTION ID, and SEQUENCE ID fields as defined - below. - - - - - - - - -Tseng, et al. Standards Track [Page 35] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -5.1.1. iSNSP Version - - The iSNSP version described in this document is 0x0001. All other - values are RESERVED. The iSNS server MAY reject messages for iSNSP - version numbers that it does not support. - -5.1.2. iSNSP Function ID - - The FUNCTION ID defines the type of iSNS message and the operation to - be executed. FUNCTION_ID values with the leading bit cleared - indicate query, registration, and notification messages, whereas - FUNCTION_ID values with the leading bit set indicate response - messages. - - See Section 4 under the appropriate protocol (i.e., iSCSI or iFCP) - for a mapping of the FUNCTION_ID value to the iSNSP Command or - Response message. All PDUs comprising an iSNSP message must have the - same FUNCTION_ID value. - -5.1.3. iSNSP PDU Length - - The iSNS PDU Length specifies the length of the PDU PAYLOAD field in - bytes. The PDU Payload contains TLV attributes for the operation. - - Additionally, response messages contain a success/failure code. The - PDU Length MUST be 4-byte aligned. - -5.1.4. iSNSP Flags - - The FLAGS field indicates additional information about the message - and the type of Network Entity that generated the message. The - following table displays the valid flags: - - Bit Position Enabled (1) means: - ------------ ----------------- - 16 Sender is the iSNS client - 17 Sender is the iSNS server - 18 Authentication block is present - 19 Replace flag (for DevAttrReg) - 20 Last PDU of the iSNS message - 21 First PDU of the iSNS message - 22-31 RESERVED - -5.1.5. iSNSP Transaction ID - - The TRANSACTION ID MUST be set to a unique value for each - concurrently outstanding request message. Replies MUST use the same - TRANSACTION ID value as the associated iSNS request message. If a - - - -Tseng, et al. Standards Track [Page 36] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - message is retransmitted, the original TRANSACTION ID value MUST be - used. All PDUs comprising an iSNSP message must have the same - TRANSACTION ID value. - -5.1.6. iSNSP Sequence ID - - The SEQUENCE ID has a unique value for each PDU within a single - transaction. The SEQUENCE_ID value of the first PDU transmitted in a - given iSNS message MUST be zero (0), and each SEQUENCE_ID value in - each PDU MUST be numbered sequentially in the order in which the PDUs - are transmitted. Note that the two-byte SEQUENCE ID allows for up to - 65536 PDUs per iSNS message. - -5.2. iSNSP Message Segmentation and Reassembly - - iSNS messages may be carried in one or more iSNS PDUs. If only one - iSNS PDU is used to carry the iSNS message, then bit 21 (First PDU) - and bit 20 in the FLAGS field (Last PDU) SHALL both be set. If - multiple PDUs are used to carry the iSNS message, then bit 21 SHALL - be set in the first PDU of the message, and bit 20 SHALL be set in - the last PDU. - - All PDUs comprising the same iSNSP message SHALL have the same - FUNCTION_ID and TRANSACTION_ID values. Each PDU comprising an iSNSP - message SHALL have a unique SEQUENCE_ID value. - -5.3. iSNSP PDU Payload - - The iSNSP PDU PAYLOAD is of variable length and contains attributes - used for registration and query operations. The attribute data items - use a format similar to that of other protocols, such as DHCP - [RFC2131] options. Each iSNS attribute is specified in the PDU - Payload using Tag-Length-Value (TLV) data format, as shown below: - - Byte MSb LSb - Offset 0 31 - +--------------------------------------------+ - 0 | Attribute Tag | 4 Bytes - +--------------------------------------------+ - 4 | Attribute Length (N) | 4 Bytes - +--------------------------------------------+ - 8 | | - | Attribute Value | N Bytes - | | - +--------------------------------------------+ - Total Length = 8 + N - - - - - -Tseng, et al. Standards Track [Page 37] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Attribute Tag: a 4-byte field that identifies the attribute as - defined in Section 6.1. This field contains the - tag value from the indicated table. - - Attribute Length: a 4-byte field that indicates the length, in bytes, - of the value field to follow in the TLV. For - variable-length attributes, the value field MUST - contain padding bytes, if necessary, in order to - achieve 4-byte alignment. A "zero-length TLV" - contains only the attribute tag and length fields. - - Attribute Value: a variable-length field containing the attribute - value and padding bytes (if necessary). - - The above format is used to identify each attribute in the PDU - Payload. Note that TLV boundaries need not be aligned with PDU - boundaries; PDUs may carry one or more TLVs, or any fraction thereof. - The Response Status Code, contained in response message PDU Payloads - and described below, is not in TLV format. PDU Payloads for messages - that do not contain iSNS attributes, such as the Name Service - Heartbeat, do not use the TLV format. - -5.3.1. Attribute Value 4-Byte Alignment - - All attribute values are aligned to 4-byte boundaries. For variable - length attributes, if necessary, the TLV length MUST be increased to - the next 4-byte boundary through padding with bytes containing zero - (0). If an attribute value is padded, a combination of the tag and - attribute value itself is used to determine the actual value length - and number of pad bytes. There is no explicit count of the number of - pad bytes provided in the TLV. - - - - - - - - - - - - - - - - - - - - -Tseng, et al. Standards Track [Page 38] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -5.4. iSNSP Response Status Codes - - All iSNSP response messages contain a 4-byte Status Code field as the - first field in the iSNSP PDU PAYLOAD. If the original iSNSP request - message was processed normally by the iSNS server, or by the iSNS - client for ESI and SCN messages, then this field SHALL contain a - status code of 0 (Successful). A non-zero status code indicates - rejection of the entire iSNS client request message. - - Status Code Status Description - ----------- ----------------- - 0 Successful - 1 Unknown Error - 2 Message Format Error - 3 Invalid Registration - 4 RESERVED - 5 Invalid Query - 6 Source Unknown - 7 Source Absent - 8 Source Unauthorized - 9 No Such Entry - 10 Version Not Supported - 11 Internal Error - 12 Busy - 13 Option Not Understood - 14 Invalid Update - 15 Message (FUNCTION_ID) Not Supported - 16 SCN Event Rejected - 17 SCN Registration Rejected - 18 Attribute Not Implemented - 19 FC_DOMAIN_ID Not Available - 20 FC_DOMAIN_ID Not Allocated - 21 ESI Not Available - 22 Invalid Deregistration - 23 Registration Feature Not Supported - 24 and above RESERVED - -5.5. Authentication for iSNS Multicast and Broadcast Messages - - For iSNS multicast and broadcast messages (see Section 2.9.3), the - iSNSP provides authentication capability. The following section - details the iSNS Authentication Block, which is identical in format - to the SLP authentication block [RFC2608]. iSNS unicast messages - SHOULD NOT include the authentication block, but rather should rely - upon IPSec security mechanisms. - - - - - - -Tseng, et al. Standards Track [Page 39] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - If a message contains an authentication block, then the - "Authentication block present" bit in the iSNSP PDU header FLAGS - field SHALL be enabled. - - If a PKI is available with an [X.509] Certificate Authority (CA), - then public key authentication of the iSNS server is possible. The - authentication block leverages the DSA with SHA-1 algorithm, which - can easily integrate into a public key infrastructure. - - The authentication block contains a digital signature for the - multicast message. The digital signature is calculated on a per-PDU - basis. The authentication block contains the following information: - - 1. A time stamp, to prevent replay attacks. - 2. A structured authenticator containing a signature calculated over - the time stamp and the message being secured. - 3. An indicator of the cryptographic algorithm that was used to - calculate the signature. - 4. An indicator of the keying material and algorithm parameters, - used to calculate the signature. - - The authentication block is described in the following figure: - - Byte MSb LSb - Offset 0 31 - +----------------------------------+ - 0 | BLOCK STRUCTURE DESCRIPTOR | 4 Bytes - +----------------------------------+ - 4 | AUTHENTICATION BLOCK LENGTH | 4 Bytes - +----------------------------------+ - 8 | TIMESTAMP | 8 Bytes - +----------------------------------+ - 16 | SPI STRING LENGTH | 4 Bytes - +----------------------------------+ - 20 | SPI STRING | N Bytes - +----------------------------------+ - 20 + N | STRUCTURED AUTHENTICATOR | M Bytes - +----------------------------------+ - Total Length = 20 + N + M - - BLOCK STRUCTURE DESCRIPTOR (BSD): Defines the structure and algorithm - to use for the STRUCTURED AUTHENTICATOR. BSD values from - 0x00000000 to 0x00007FFF are assigned by IANA, while - values 0x00008000 to 0x00008FFF are for private use. - - - - - - - -Tseng, et al. Standards Track [Page 40] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - AUTHENTICATION BLOCK LENGTH: Defines the length of the authentication - block, beginning with the BSD field and running through - the last byte of the STRUCTURED AUTHENTICATOR. - - TIMESTAMP: This is an 8-byte unsigned, fixed-point integer giving the - number of seconds since 00:00:00 GMT on January 1, 1970. - - SPI STRING LENGTH: The length of the SPI STRING field. - - SPI STRING (Security Parameters Index): Index to the key and - algorithm used by the message recipient to decode the - STRUCTURED AUTHENTICATOR field. - - STRUCTURED AUTHENTICATOR: Contains the digital signature. For the - default BSD value of 0x0002, this field SHALL contain the - binary ASN.1 encoding of output values from the DSA with - SHA-1 signature calculation as specified in Section 2.2.2 - of [RFC3279]. - -5.6. Registration and Query Messages - - The iSNSP registration and query message PDU Payloads contain a list - of attributes, and have the following format: - - +----------------------------------------+ - | Source Attribute (Requests Only) | - +----------------------------------------+ - | Message Key Attribute[1] (if present) | - +----------------------------------------+ - | Message Key Attribute[2] (if present) | - +----------------------------------------+ - | . . . | - +----------------------------------------+ - | - Delimiter Attribute - | - +----------------------------------------+ - | Operating Attribute[1] (if present) | - +----------------------------------------+ - | Operating Attribute[2] (if present) | - +----------------------------------------+ - | Operating Attribute[3] (if present) | - +----------------------------------------+ - | . . . | - +----------------------------------------+ - - Each Source, Message Key, Delimiter, and Operating attribute is - specified in the PDU Payload using the Tag-Length-Value (TLV) data - format. iSNS Registration and Query messages are sent by iSNS Clients - - - - -Tseng, et al. Standards Track [Page 41] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - to the iSNS server IP Address and well-known TCP/UDP Port. The iSNS - Responses will be sent to the iSNS Client IP address and TCP/UDP port - number from the original request message. - -5.6.1. Source Attribute - - The Source Attribute is used to identify the Storage Node to the iSNS - server for queries and other messages that require source - identification. The Source Attribute uniquely identifies the source - of the message. Valid Source Attribute types are shown below. - - Valid Source Attributes - ----------------------- - iSCSI Name - FC Port Name WWPN - - For a query operation, the Source Attribute is used to limit the - scope of the specified operation to the Discovery Domains of which - the source is a member. Special Control Nodes, identified by the - Source Attribute, may be administratively configured to perform the - specified operation on all objects in the iSNS database without - scoping to Discovery Domains. - - For messages that change the contents of the iSNS database, the iSNS - server MUST verify that the Source Attribute identifies either a - Control Node or a Storage Node that is a part of the Network Entity - containing the added, deleted, or modified objects. - -5.6.2. Message Key Attributes - - Message Key attributes are used to identify matching objects in the - iSNS database for iSNS query and registration messages. If present, - the Message Key MUST be a Registration or Query Key for an object as - described in Sections 5.6.5 and 6.1. A Message Key is not required - when a query spans the entire set of objects available to the Source - or a registration is for a new Entity. - - iSCSI Names used in the Message Key MUST be normalized according to - the stringprep template [STRINGPREP]. Entity Identifiers (EIDs) used - in the Message Key MUST be normalized according to the nameprep - template [NAMEPREP]. - -5.6.3. Delimiter Attribute - - The Delimiter Attribute separates the Message Key attributes from the - Operating Attributes in a PDU Payload. The Delimiter Attribute has a - tag value of 0 and a length value of 0. The Delimiter Attribute is - always 8 bytes long (a 4-byte tag field and a 4-byte length field, - - - -Tseng, et al. Standards Track [Page 42] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - all containing zeros). If a Message Key is not required for a - message, then the Delimiter Attribute immediately follows the Source - Attribute. - -5.6.4. Operating Attributes - - The Operating Attributes are a list of one or more key and non-key - attributes related to the actual iSNS registration or query operation - being performed. - - Operating Attributes include object key attributes and non-key - attributes. Object key attributes uniquely identify iSNS objects. - Key attributes MUST precede the non-key attributes of each object in - the Operating Attributes. The tag value distinguishes the attribute - as an object key attribute (i.e., tag=1, 16&17, 32, 64, and 96) or a - non-key attribute. iSCSI Names used in the Operating Attributes MUST - be normalized according to the stringprep template [STRINGPREP]. - Entity Identifiers (EIDs) used in the Operating Attributes MUST be - normalized according to the nameprep template [NAMEPREP]. - - The ordering of Operating Attributes in the message is important for - determining the relationships among objects and their ownership of - non-key attributes. iSNS protocol messages that violate these - ordering rules SHALL be rejected with the Status Code of 2 (Message - Format Error). See the message descriptions for proper operating - attribute ordering requirements. - - Some objects are keyed by more than one object key attribute value. - For example, the Portal object is keyed by attribute tags 16 and 17. - When describing an object keyed by more than one key attribute, every - object key attribute of that object MUST be listed sequentially by - tag value in the message before non-key attributes of that object and - key attributes of the next object. A group of key attributes of this - kind is treated as a single logical key attribute when identifying an - object. - - Non-key attributes that immediately follow key attributes MUST be - attributes of the object referenced by the key attributes. All non- - key attributes of an object MUST be listed before the object key - attributes introducing the next object. - - Objects MUST be listed in inheritance order, according to their - containment order. Storage Node and Portal objects and their - respective attributes MUST follow the Network Entity object to which - they have a relationship. Similarly, FC Device objects MUST follow - the Storage Node object to which they have a relationship. - - - - - -Tseng, et al. Standards Track [Page 43] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Vendor-specific objects defined by tag values in the range 1537-2048 - have the same requirements described above. - -5.6.4.1. Operating Attributes for Query and Get Next Requests - - In Query and Get Next request messages, TLV attributes with length - value of 0 are used to indicate which Operating Attributes are to be - returned in the corresponding response. Operating Attribute values - that match the TLV attributes in the original message are returned in - the response message. - -5.6.5. Registration and Query Request Message Types - - The following describes each query and message type. - -5.6.5.1. Device Attribute Registration Request (DevAttrReg) - - The DevAttrReg message type is 0x0001. The DevAttrReg message - provides the means for iSNS clients to update existing objects or - register new objects. The value of the replace bit in the FLAGs - field determines whether the DevAttrReg message updates or replaces - an existing registration. - - The Source Attribute identifies the Node initiating the registration - request. - - The Message Key identifies the object the DevAttrReg message acts - upon. It MUST contain the key attribute(s) identifying an object. - This object MUST contain all attributes and related subordinate - object attributes that will be included in the Operating Attributes - of the DevAttrReg PDU Payload. The key attribute(s) identifying this - object MUST also be included among the Operating Attributes. - - If the Message Key contains an EID and no pre-existing objects match - the Message Key, then the DevAttrReg message SHALL create a new - Entity with the specified EID and any new object(s) specified by the - Operating Attributes. The replace bit SHALL be ignored. - - If the Message Key does not contain an EID, and no pre-existing - objects match the Message Key, then the DevAttrReg message SHALL be - rejected with a status code of 3 (Invalid Registration). - - If the Message Key is not present, then the DevAttrReg message - implicitly registers a new Network Entity. In this case, the replace - bit SHALL be ignored; a new Network Entity SHALL be created. - Existing entities, their objects, and their relationships remain - unchanged. - - - - -Tseng, et al. Standards Track [Page 44] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - The replace bit determines the kind of operation conducted on the - object identified in the DevAttrReg Message Key. The replace bit - only applies to the DevAttrReg message; it is ignored for all other - message types. - - If the replace bit is set, then the objects, attributes, and - relationships specified in the Operating Attributes SHALL replace the - object identified by the Message Key. The object and all of its - subordinate objects SHALL be deregistered, and the appropriate SCNs - SHALL be sent by the iSNS server for the deregistered objects. The - objects listed in the Operating Attributes are then used to replace - the just-deregistered objects. Note that additional SCNs SHALL be - sent for the newly-registered objects, if appropriate. Existing - objects and relationships that are not identified or that are - subordinate to the object identified by the Message Key MUST NOT be - affected or changed. - - If the replace bit is not set, then the message updates the - attributes of the object identified by the Message Key and its - subordinate objects. Existing object containment relationships MUST - NOT be changed. For existing objects, key attributes MUST NOT be - modified, but new subordinate objects MAY be added. - - The Operating Attributes represent objects, attributes, and - relationships that are to be registered. Multiple related objects - and attributes MAY be registered in a single DevAttrReg message. The - ordering of the objects in this message indicates the structure of, - and associations among, the objects to be registered. At least one - object MUST be listed in the Operating Attributes. Additional - objects (if any) MUST be subordinate to the first object listed. Key - attributes MUST precede non-key attributes of each object. A given - object may only appear a maximum of once in the Operating Attributes - of a message. If the Node identified by the Source Attribute is not - a Control Node, then the objects in the operating attributes MUST be - members of the same Network Entity as the Source Node. - - For example, to establish relationships between a Network Entity - object and its Portal and Storage Node objects, the Operating - Attributes list the key and non-key attributes of the Network Entity - object, followed by the key and non-key attributes of each Portal and - Storage Node object to be linked to that Network Entity. Similarly, - an FC Device object that follows a Storage Node object is considered - subordinate to that Storage Node. - - New PG objects are registered when an associated Portal or iSCSI Node - object is registered. An explicit PG object registration MAY follow - a Portal or iSCSI Node object registration in a DevAttrReg message. - - - - -Tseng, et al. Standards Track [Page 45] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - When a Portal is registered, the Portal attributes MAY immediately be - followed by a PGT attribute. The PGT attribute SHALL be followed by - the set of PG iSCSI Names representing nodes that will be associated - to the Portal using the indicated PGT value. Additional sets of PGTs - and PG iSCSI Names to be associated to the registered Portal MAY - follow. Indicated PGT values are assigned to the PG object - associated with the newly registered Portal and to the iSCSI Storage - Node(s) referenced immediately following the PGT attribute in the - operating attributes. - - When an iSCSI Storage Node is registered, the Storage Node attributes - MAY immediately be followed by a PGT attribute. The PGT attribute - SHALL be followed by the set of PG Portal IP-Address, PG TCP/UDP Port - pairs representing Portal objects that will be associated with the - Storage Node using the indicated PGT value. Additional sets of PGTs - and PG Portal IP-Address PG TCP/UDP Port pairs to be associated with - the registered Storage Node MAY follow. Indicated PGT values are - assigned to the PG object associated with the newly registered iSCSI - Storage Node and Portal object(s) referenced immediately following - the PGT attribute in the operating attributes. - - If the PGT value is not included in the Storage Node or Portal object - registration, and if a PGT value was not previously registered for - the relationship, then the PGT for the corresponding PG object SHALL - be registered with a value of 0x00000001. If the PGT attribute is - included in the registration message as a 0-length TLV, then the PGT - value for the corresponding PG object SHALL be registered as NULL. A - 0-length TLV for the PGT in an update registration message overwrites - the previous PGT value with NULL, indicating that there is no - relationship between the Storage Node and Portal. - - A maximum of one Network Entity object can be created or updated with - a single DevAttrReg message. Consequently, the Operating Attributes - MUST NOT contain more than one Network Entity object. There is no - limit to the number of Portal, Storage Node, and FC Device objects - that can listed in the Operating Attributes, provided they are all - subordinate to the listed Network Entity object. - - If the Message Key and Operating Attributes do not contain an EID - attribute, or if the EID attribute has a length of 0, then a new - Network Entity object SHALL be created and the iSNS server SHALL - supply a unique EID value for it. The assigned EID value SHALL be - included in the DevAttrReg Response message. If the Message Key and - Operating Attributes contain an EID that does not match the EID of an - existing Network Entity in the iSNS database, then a new Network - Entity SHALL be created and assigned the value contained in that EID - attribute. Finally, if the Message Key and Operating Attributes - contain an EID that matches the EID of an existing object in the iSNS - - - -Tseng, et al. Standards Track [Page 46] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - database, then the objects, attributes, and relationships specified - in the Operating Attributes SHALL be appended to the existing Network - Entity identified by the EID. - - A registration message that creates a new Network Entity object MUST - contain at least one Portal or one Storage Node. If the message does - not, then it SHALL be considered invalid and result in a response - with Status Code of 3 (Invalid Registration). - - If an iSNS Server does not support a registration feature, such as - explicit PG object registration, then the server SHALL return a - Status Code of 23 (Registration Feature Not Supported). - - Note that the iSNS server may modify or reject the registration of - certain attributes, such as ESI Interval. In addition, the iSNS - server may assign values for additional Operating Attributes that are - not explicitly registered in the original DevAttrReg message, such as - the EID and WWNN Token. - -5.6.5.2. Device Attribute Query Request (DevAttrQry) - - The DevAttrQry message type is 0x0002. The DevAttrQry message - provides an iSNS client with the means to query the iSNS server for - object attributes. - - The Source Attribute identifies the Node initiating the request. For - non-Control Nodes initiating the DevAttrQry message, the query is - scoped to the Discovery Domains of which the initiating Node is a - member. The DevAttrQry message SHALL only return information on - Storage Nodes and their related parent and subordinate objects, where - the Storage Node has a common Discovery Domain with the Node - identified in the Source Attribute. - - The Message Key may contain key or non-key attributes or no - attributes at all. If multiple attributes are used as the Message - Key, then they MUST all be from the same object type (e.g., IP - address and TCP/UDP Port are attributes of the Portal object type). - A Message Key with non-key attributes may match multiple instances of - the specific object type. A Message Key with zero-length TLV(s) is - scoped to every object of the type indicated by the zero-length - TLV(s). An empty Message Key field indicates the query is scoped to - the entire database accessible by the source Node. - - The DevAttrQry response message returns attributes of objects listed - in the Operating Attributes that are related to the Message Key of - the original DevAttrQry message. The Operating Attributes of the - DevAttrQry message contain zero-length TLVs that specify the - attributes that are to be returned in the DevAttrQryRsp message. A - - - -Tseng, et al. Standards Track [Page 47] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Message Key containing zero-length TLVs indicates that the set of - attributes specified in the Operating Attributes are to be returned - for each object matching the type indicated by the Message Key. - - If the Message Key contains non-zero length TLVs, then Operating - Attributes for the object matching the Message Key SHALL be returned - in the DevAttrQryRsp message. Each attribute type (i.e., zero-length - TLV) in the Operating Attributes indicates an attribute from the - object matching the Message Key, or from other objects in the same - Entity having a relationship to the object matching the Message Key, - is to be returned in the response. The ordering of the object keys - and associated attributes returned in the DevAttrQry response message - SHALL be the same as in the original query message. If no objects - match the Message Key, then the DevAttrQryRsp message SHALL NOT - return any operating attributes. Such a message and its - corresponding response SHALL NOT be considered an error. - - The Portal Group object determines whether a relationship exists - between a given Storage Node and Portal object. If the PGT of the - Portal Group is not NULL, then a relationship exists between the - indicated Storage Node and Portal; if the PGT is NULL, then no - relationship exists. Therefore, the value (NULL or not NULL) of the - PGT attribute of each Portal Group object determines the structure - and ordering of the DevAttrQry response to a query for Storage Nodes - and Portals. - - For example, an iSNS database contains a Network Entity having two - Portals and two Nodes. Each Storage Node has two Portal Groups, one - with a NULL PGT value for one Portal and another with a non-NULL PGT - value for the other Portal. The DevAttrQry message contains a - Message Key entry matching one of the Nodes, and Operating Attributes - with zero-length TLVs listing first the Node attributes, Portal - attributes, and then the PG attributes. The response message SHALL - therefore return first the matching Node object, then the requested - attributes of the one Portal object that can be used to access the - Storage Node (as indicated by the PGT), and finally the requested - attributes of the PG object used to access that Storage Node. The - order in which each object's attributes are listed is the same as the - ordering of the object's attributes in the Operating Attributes of - the original request message. - - If the Message Key Attribute contains zero-length TLV(s), then the - query returns requested attributes for all objects matching the - Message Key type (DD restrictions SHALL apply for non-Control Nodes). - If multiple objects match the Message Key type, then the attributes - for each object matching the Message Key MUST be listed before the - attributes for the next matching object are listed in the query - - - - -Tseng, et al. Standards Track [Page 48] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - response. In other words, the process described above must be - iterated in the message response for each object that matches the - Message Key type specified by the zero-length TLV(s). - - For example, an iSNS database contains only one Network Entity having - two Portals and three Nodes. All PG objects in the Entity have a PGT - value of 0x00000001. In the DevAttrQry message, the Message Key - contains a zero-length TLV specifying a Node type, and Operating - Attributes listing first the Node attributes, and then the Portal - attributes. The response message will return, in the following - order, the attributes for the first, next, and last Node objects, - each followed by attributes for both Portals. If that same - DevAttrQry message had instead contained a zero-length TLV specifying - the Network Entity type, then the response message would have - returned attributes for all three Node objects, followed by - attributes for the two Portals. - - If there is no Message Key Attribute, then the query returns all - attributes in the iSNS database (once again, DD restrictions SHALL - apply for non-Control Nodes). All attributes matching the type - specified by each zero-length TLV in the Operating Attributes SHALL - be listed. All attributes of each type SHALL be listed before the - attributes matching the next zero-length TLV are listed. - - For example, an iSNS database contains two Entities, each having two - Nodes and two Portals. The DevAttrQry message contains no Message - Key attribute, and Operating Attributes list first the Portal - attributes, and then the Node attributes. The Operating Attributes - of the response message will return attributes from each of the four - Portals, followed by attributes from each of the four nodes. - - If a DevAttrQry message requests an attribute for which the iSNS - server has no value, then the server SHALL NOT return the requested - attribute in the query response. Such query and response messages - SHALL NOT be considered errors. - - Registration and query messages for iSNS server-specific attributes - (i.e., tags in the range 132 to 384) SHALL be formatted using the - identifying key attribute of the Storage Node originating the query - (i.e., iSCSI Name or FC Port Name WWPN) for both the Source Attribute - and Message Key attribute. Operating Attributes SHALL include the - TLV of the server-specific attribute being requested. - - DD membership can be discovered through the DevAttrQry message by - including either DD member attributes (i.e., DD Member iSCSI Index, - DD Member iSCSI Node, DD Member iFCP Node, DD Member Portal Index, DD - Member Portal IP Addr, and DD Member Portal TCP/UDP) or the object - key of the Storage Node or Portal (i.e., iSCSI Name, iSCSI Index, - - - -Tseng, et al. Standards Track [Page 49] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Portal IP Addr, Portal TCP/UDP Port, and Portal Index) in the - Operating Attributes. Using DD member attributes SHALL return both - registered and unregistered member Storage Nodes and/or Portals of a - DD. DevAttrQry messages using the Storage Node and/or Portal object - key SHALL return only member Storage Nodes or Portals that are - currently registered in the iSNS database. - - The DevAttrQry message SHALL support the following minimum set of - Message Key Attributes: - - Valid Message Key Attributes for Queries - ---------------------------------------- - Entity Identifier - Entity Protocol - Portal IP-Address & Portal TCP/UDP Port - Portal Index - iSCSI Node Type - iSCSI Name - iSCSI Index - PG Index - FC Port Name WWPN - FC Port Type - FC-4 Type - Discovery Domain ID - Discovery Domain Set ID - Source Attribute (for server-specific attributes) - Switch Name (FC Device WWNN--for Virtual_Fabric_ID queries) - -5.6.5.3. Device Get Next Request (DevGetNext) - - The DevGetNext message type is 0x0003. This message provides the - iSNS client with the means to retrieve each and every instance of an - object type exactly once. - - The Source Attribute identifies the Node initiating the DevGetNext - request, and is used to scope the retrieval process to the Discovery - Domains of which the initiating Node is a member. - - The Message Key Attribute may be an Entity Identifier (EID), iSCSI - Name, iSCSI Index, Portal IP Address and TCP/UDP Port, Portal Index, - PG Index, FC Node Name WWNN, or FC Port Name WWPN. If the TLV length - of the Message Key Attribute(s) is zero, then the first object entry - in the iSNS database matching the Message Key type SHALL be returned - in the Message Key of the corresponding DevGetNextRsp message. If - non-zero-length TLV attributes are contained in the Message Key, then - the DevGetNext response message SHALL return the next object stored - after the object identified by the Message Key in the original - DevGetNext request message. - - - -Tseng, et al. Standards Track [Page 50] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - If the Message Key provided matches the last object instance in the - iSNS database, then the Status Code of 9 (No Such Entry) SHALL be - returned in the response. - - The Operating Attributes can be used to specify the scope of the - DevGetNext request, and to specify the attributes of the next object, - which are to be returned in the DevGetNext response message. All - Operating Attributes MUST be attributes of the object type identified - by the Message Key. For example, if the Message Key is an Entity_ID - attribute, then the Operating Attributes MUST NOT contain attributes - of Portals. - - Non-zero-length TLV attributes in the Operating Attributes are used - to scope the DevGetNext message. Only the next object with attribute - values that match the non-zero-length TLV attributes SHALL be - returned in the DevGetNext response message. - - Zero-length TLV attributes MUST be listed after non-zero-length - attributes in the Operating Attributes of the DevGetNext request - message. Zero-length TLV attributes specify the attributes of the - next object which are to be returned in the DevGetNext response - message. - - Note that there are no specific requirements concerning the order in - which object entries are retrieved from the iSNS database; the - retrieval order of object entries using the DevGetNext message is - implementation specific. - - The iSNS client is responsible for ensuring that information acquired - through use of the DevGetNext message is accurate and up-to-date. - There is no assurance that the iSNS database will not change between - successive DevGetNext request messages. If the Message Key provided - does not match an existing database entry, then attributes for the - next object key following the provided Message Key SHALL be returned. - For example, an object entry may have been deleted between successive - DevGetNext messages. This may result in a DevGetNext request in - which the Message Key does not match an existing object entry. In - this case, attributes for the next object stored in the iSNS database - are returned. - -5.6.5.4. Device Deregister Request (DevDereg) - - The DevDereg message type is 0x0004. This message is used to remove - object entries from the iSNS database. One or more objects may be - removed through a single DevDereg message. Note that deregistered - Storage Node objects will retain membership in their Discovery - Domain(s) until explicit deregistration of the membership(s) or - Discovery Domain(s). - - - -Tseng, et al. Standards Track [Page 51] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Upon receiving the DevDereg, the iSNS server removes all objects - identified by the Operating Attribute(s), and all subordinate objects - that are solely dependent on those identified objects. For example, - removal of a Network Entity also results in removal of all associated - Portal, Portal Group, Storage Node, and FC Device objects associated - with that Network Entity. FC Device objects SHALL not be - deregistered in this manner unless all Storage Nodes associated with - them have been deregistered. - - The DevDereg request PDU Payload contains a Source Attribute and - Operating Attribute(s); there are no Message Key Attributes. If the - Node identified by the Source Attribute is not a Control Node, then - it MUST be from the same Network Entity as the object(s) identified - for removal by the Operating Attribute(s). Valid Operating - Attributes are shown below: - - Valid Operating Attributes for DevDereg - --------------------------------------- - Entity Identifier - Portal IP-Address & Portal TCP/UDP Port - Portal Index - iSCSI Name - iSCSI Index - FC Port Name WWPN - FC Node Name WWNN - - The removal of the object may result in SCN messages to the - appropriate iSNS clients. - - Attempted deregistration of non-existing entries SHALL not be - considered an error. - - If all Nodes and Portals associated with a Network Entity are - deregistered, then the Network Entity SHALL also be removed. - - If both the Portal and iSCSI Storage Node objects associated with a - Portal Group object are removed, then that Portal Group object SHALL - also be removed. The Portal Group object SHALL remain registered as - long as either of its associated Portal or iSCSI Storage Node objects - remain registered. If a deleted Storage Node or Portal object is - subsequently re-registered, then a relationship between the re- - registered object and an existing Portal or Storage Node object - registration, indicated by the PG object, SHALL be restored. - - - - - - - - -Tseng, et al. Standards Track [Page 52] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -5.6.5.5. SCN Register Request (SCNReg) - - The SCNReg message type is 0x0005. The State Change Notification - Registration Request (SCNReg) message allows an iSNS client to - register a Storage Node to receive State Change Notification (SCN) - messages. - - The SCN notifies the Storage Node of changes to any Storage Nodes - within any DD of which it is a member. If the Storage Node is a - Control Node, it SHALL receive SCN notifications for changes in the - entire network. Note that whereas SCNReg sets the SCN Bitmap field, - the DevAttrReg message registers the UDP or TCP Port used by each - Portal to receive SCN messages. If no SCN Port fields of any Portals - of the Storage Node are registered to receive SCN messages, then the - SCNReg message SHALL be rejected with Status Code 17 (SCN - Registration Rejected). - - The SCNReg request PDU Payload contains a Source Attribute, a Message - Key Attribute, and an Operating Attribute. Valid Message Key - Attributes for a SCNReg are shown below: - - Valid Message Key Attributes for SCNReg - --------------------------------------- - iSCSI Name - FC Port Name WWPN - - The node with the iSCSI Name or FC Port Name WWPN attribute that - matches the Message Key in the SCNReg message is registered to - receive SCNs using the specified SCN bitmap. A maximum of one Node - SHALL be registered for each SCNReg message. - - The SCN Bitmap is the only operating attribute of this message, and - it always overwrites the previous contents of this field in the iSNS - database. The bitmap indicates the SCN event types for which the - Node is registering. - - Note that the settings of this bitmap determine whether the SCN - registration is for regular SCNs or management SCNs. Control Nodes - MAY conduct registrations for management SCNs; iSNS clients that are - not supporting Control Nodes MUST NOT conduct registrations for - management SCNs. Control Nodes that register for management SCNs - receive a copy of every SCN message generated by the iSNS server. It - is recommended that management registrations be used only when needed - in order to conserve iSNS server resources. In addition, a Control - Node that conducts such registrations should be prepared to receive - the anticipated volume of SCN message traffic. - - - - - -Tseng, et al. Standards Track [Page 53] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -5.6.5.6. SCN Deregister Request (SCNDereg) - - The SCNDereg message type is 0x0006. The SCNDereg message allows an - iSNS client to stop receiving State Change Notification (SCN) - messages. - - The SCNDereg request message PDU Payload contains a Source Attribute - and Message Key Attribute(s). Valid Message Key Attributes for a - SCNDereg are shown below: - - Valid Message Key Attributes for SCNDereg - ----------------------------------------- - iSCSI Name - FC Port Name WWPN - - The node with an iSCSI Name or FC Port Name WWPN attribute that - matches the Message Key Attributes in the SCNDereg message is - deregistered for SCNs. The SCN bitmap field of such Nodes are - cleared. A maximum of one Node SHALL be deregistered for each - SCNDereg message. - - There are no Operating Attributes in the SCNDereg message. - -5.6.5.7. SCN Event (SCNEvent) - - The SCNEvent message type is 0x0007. The SCNEvent is a message sent - by an iSNS client to request generation of a State Change - Notification (SCN) message by the iSNS server. The SCN, sent by the - iSNS server, then notifies iFCP, iSCSI, and Control Nodes within the - affected DD of the change indicated in the SCNEvent. - - Most SCNs are automatically generated by the iSNS server when Nodes - are registered or deregistered from the directory database. SCNs are - also generated when a network management application or Control Node - makes changes to the DD membership in the iSNS server. However, an - iSNS client can trigger an SCN by using SCNEvent. - - The SCNEvent message PDU Payload contains a Source Attribute, a - Message Key Attribute, and an Operating Attribute. Valid Key - Attributes for a SCNEvent are shown below: - - Valid Message Key Attributes for SCNEvent - ----------------------------------------- - iSCSI Name - FC Port Name WWPN - - - - - - -Tseng, et al. Standards Track [Page 54] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - The Operating Attributes section SHALL contain the SCN Event Bitmap - attribute. The bitmap indicates the event that caused the SCNEvent - to be generated. - -5.6.5.8. State Change Notification (SCN) - - The SCN message type is 0x0008. The SCN is a message generated by - the iSNS server, notifying a registered Storage Node of changes. - There are two types of SCN registrations: regular registrations and - management registrations. Regular SCNs notify iSNS clients of events - within the discovery domain. Management SCNs notify Control Nodes - that register for management SCNs of events occurring anywhere in the - network. - - If no active TCP connection to the SCN recipient exists, then the SCN - message SHALL be sent to one Portal of the registered Storage Node - that has a registered TCP or UDP Port value in the SCN Port field. - If more than one Portal of the Storage Node has a registered SCN Port - value, then the SCN SHALL be delivered to any one of the indicated - Portals, provided that the selected Portal is not the subject of the - SCN. - - The types of events that can trigger an SCN message, and the amount - of information contained in the SCN message, depend on the registered - SCN Event Bitmap for the Storage Node. The iSCSI Node SCN Bitmap is - described in Section 6.4.4. The iFCP SCN Bitmap is described in - Section 6.6.12. - - - - - - - - - - - - - - - - - - - - - - - - -Tseng, et al. Standards Track [Page 55] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - The format of the SCN PDU Payload is shown below: - - +----------------------------------------+ - | Destination Attribute | - +----------------------------------------+ - | Timestamp | - +----------------------------------------+ - | Source SCN Bitmap 1 | - +----------------------------------------+ - | Source Attribute [1] | - +----------------------------------------+ - | Source Attribute [2](if present) | - +----------------------------------------+ - | Source Attribute [3](if present) | - +----------------------------------------+ - | Source Attribute [n](if present) | - +----------------------------------------+ - | Source SCN Bitmap 2 (if present) | - +----------------------------------------+ - | . . . | - +----------------------------------------+ - - All PDU Payload attributes are in TLV format. - - The Destination Attribute is the Node identifier that is receiving - the SCN. The Destination Attribute can be an iSCSI Name or FC Port - Name. - - The Timestamp field, using the Timestamp TLV format, described in - Section 6.2.4, indicates the time the SCN was generated. - - The Source SCN Bitmap field indicates the type of SCN notification - (i.e., regular or management SCN), and the type of event that caused - the SCN to be generated; it does not necessarily correlate with the - original SCN bitmap registered in the iSNS server. - - Following the timestamp, the SCN message SHALL list the SCN bitmap, - followed by the key attribute (i.e., iSCSI Name or FC Port Name) of - the Storage Node affected by the SCN event. If the SCN is a - Management SCN, then the SCN message SHALL also list the DD_ID and/or - DDS_ID of the Discovery Domains and Discovery Domain Sets (if any) - that caused the change in state for that Storage Node. These - additional attributes (i.e., DD_ID and/or DDS_ID) shall immediately - follow the iSCSI Name or FC Port Name and precede the next SCN bitmap - for the next notification message (if any). The SCN bitmap is used - as a delineator for SCN messages providing multiple state change - notifications. - - - - -Tseng, et al. Standards Track [Page 56] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - For example, a regular SCN for notifying an iSNS client of a new - Portal available for a particular iSCSI target would contain the SCN - bitmap followed by the iSCSI Name of the target device as the source - attribute. If the SCN were a management SCN, then the iSCSI Name - would be followed by the DD_ID(s) of the shared Discovery Domains - that allow the destination Storage Node to have visibility to the - affected Storage Node. If a Discovery Domain Set (DDS) was enabled - in order to provide this visibility, then the appropriate DDS_ID - would be included as well. - - A management SCN is also generated to notify a Control Node of the - creation, deletion, or modification of a Discovery Domain or - Discovery Domain Set. In this case, the DD_ID and/or DDS_ID of the - affected Discovery Domain and/or Discovery Domain Set would follow - the SCN bitmap. - - For example, a management SCN to notify a Control Node of a new DD - within a Discovery Domain Set would contain both the DD_ID and the - DDS_ID of the affected Discovery Domain and Discovery Domain Set - among the Source Attributes. - - See Sections 6.4.4 and 6.6.12 for additional information on the SCN - Bitmap. - -5.6.5.9. DD Register (DDReg) - - The DDReg message type is 0x0009. This message is used to create a - new Discovery Domain (DD), to update an existing DD Symbolic Name - and/or DD Features attribute, and to add DD members. - - DDs are uniquely defined using DD_IDs. DD registration attributes - are described in Section 6.11. - - The DDReg message PDU Payload contains the Source Attribute and - optional Message Key and Operating Attributes. - - The Message Key, if used, contains the DD_ID of the Discovery Domain - to be registered. If the Message Key contains a DD_ID of an existing - DD entry in the iSNS database, then the DDReg message SHALL attempt - to update the existing entry. If the DD_ID in the Message Key (if - used) does not match an existing DD entry, then the iSNS server SHALL - reject the DDReg message with a status code of 3 (Invalid - Registration). If the DD_ID is included in both the Message Key and - Operating Attributes, then the DD_ID value in the Message Key MUST be - the same as the DD_ID value in the Operating Attributes. - - - - - - -Tseng, et al. Standards Track [Page 57] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - A DDReg message with no Message Key SHALL result in the attempted - creation of a new Discovery Domain (DD). If the DD_ID attribute - (with non-zero length) is included among the Operating Attributes in - the DDReg message, then the new Discovery Domain SHALL be assigned - the value contained in that DD_ID attribute. Otherwise, if the DD_ID - attribute is not contained among the Operating Attributes of the - DDReg message, or if the DD_ID is an operating attribute with a TLV - length of 0, then the iSNS server SHALL assign a DD_ID value. The - assigned DD_ID value is then returned in the DDReg Response message. - The Operating Attributes can also contain the DD Member iSCSI Node - Index, DD Member iSCSI Name, DD Member FC Port Name, DD Member Portal - IP Address, DD Member Portal TCP/UDP Port Number, or DD Member Portal - Index of members to be added to the DD. It may also contain the - DD_Symbolic_Name and/or DD_Features of the DD. - - This message SHALL add any DD members listed as Operating Attributes - to the Discovery Domain specified by the DD_ID. If the DD_Features - attribute is an Operating Attribute, then it SHALL be stored in the - iSNS server as the feature list for the specified DD. If the - DD_Symbolic_Name is an operating attribute and its value is unique - (i.e., it does not match the registered DD_Symbolic_Name for another - DD), then the value SHALL be stored in the iSNS database as the - DD_Symbolic_Name for the specified Discovery Domain. If the value - for the DD_Symbolic_Name is not unique, then the iSNS server SHALL - reject the attempted DD registration with a status code of 3 (Invalid - Registration). - - When creating a new DD, if the DD_Symbolic_Name is not included in - the Operating Attributes, or if it is included with a zero-length - TLV, then the iSNS server SHALL provide a unique DD_Symbolic_Name - value for the created DD. The assigned DD_Symbolic_Name value SHALL - be returned in the DDRegRsp message. - - When creating a new DD, if the DD_Features attribute is not included - in the Operating Attributes, then the iSNS server SHALL assign the - default value. The default value for DD_Features is 0. - - DD Member iSCSI Name, DD Member iFCP Node, DD Member Portal IP - Address, and DD Member TCP/UDP Port Number attributes included in the - Operating Attributes need not match currently existing iSNS database - entries. This allows, for example, a Storage Node to be added to a - DD even if the Storage Node is not currently registered in the iSNS - database. A Storage Node or Portal can thereby be added to a DD at - the time of the DDs creation, even if the Storage Node or Portal is - not currently active in the storage network. - - - - - - -Tseng, et al. Standards Track [Page 58] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - If the Operating Attributes contain a DD Member iSCSI Name value for - a Storage Node that is currently not registered in the iSNS database, - then the iSNS server MUST allocate an unused iSCSI Node Index for - that Storage Node. The assigned iSCSI Node Index SHALL be returned - in the DDRegRsp message as the DD Member iSCSI Node Index. The - allocated iSCSI Node Index value SHALL be assigned to the Storage - Node if and when it registers in the iSNS database. - - If the Operating Attributes contain a DD Member Portal IP Addr and DD - Member Portal TCP/UDP value for a Portal that is not currently - registered in the iSNS database, then the iSNS server MUST allocate - an unused Portal Index value for that Portal. The assigned Portal - Index value SHALL be returned in the DDRegRsp message as the DD - Member Portal Index. The allocated Portal Index value SHALL be - assigned to the Portal if and when it registers in the iSNS database. - - DD Member iSCSI Node Index and DD Member Portal Index attributes that - are provided in the Operating Attributes MUST match a corresponding - iSCSI Node Index or Portal Index of an existing Storage Node or - Portal entry in the iSNS database. Furthermore, the DD Member iSCSI - Node Index and DD Member Portal Index SHALL NOT be used to add - Storage Nodes or Portals to a DD unless those Storage Nodes or - Portals are actively registered in the iSNS database. - -5.6.5.10. DD Deregister (DDDereg) - - The DDDereg message type is 0x000A. This message allows an iSNS - client to deregister an existing Discovery Domain (DD) and to remove - members from an existing DD. - - DDs are uniquely identified using DD_IDs. DD registration attributes - are described in Section 6.11. - - The DDDereg message PDU Payload contains a Source Attribute, Message - Key Attribute, and optional Operating Attributes. - - The Message Key Attribute for a DDDereg message is the DD ID for the - Discovery Domain being removed or having members removed. If the DD - ID matches an existing DD and there are no Operating Attributes, then - the DD SHALL be removed and a success Status Code returned. Any - existing members of that DD SHALL remain in the iSNS database without - membership in the just-removed DD. - - If the DD ID matches an existing DD and there are Operating - Attributes matching DD members, then the DD members identified by the - Operating Attributes SHALL be removed from the DD and a successful - Status Code returned. - - - - -Tseng, et al. Standards Track [Page 59] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - If a DD Member iSCSI Name identified in the Operating Attributes - contains an iSCSI Name for a Storage Node that is not currently - registered in the iSNS database or contained in another DD, then the - association between that Storage Node and its pre-assigned iSCSI Node - Index SHALL be removed. The pre-assigned iSCSI Node Index value no - longer has an association to a specific iSCSI Name and can now be - re-assigned. - - If a DD Member Portal IP Address and DD Member TCP/UDP Port - identified in the Operating Attributes reference a Portal that is not - currently registered in the iSNS database or contained in another DD, - then the association between that Portal and its pre-assigned Portal - Index SHALL be removed. The pre-assigned Portal Index value can now - be reassigned. - - The attempted deregistration of non-existent DD entries SHALL not be - considered an error. - -5.6.5.11. DDS Register (DDSReg) - - The DDSReg message type is 0x000B. This message allows an iSNS - client to create a new Discovery Domain Set (DDS), to update an - existing DDS Symbolic Name and/or DDS Status, or to add DDS members. - - DDSs are uniquely defined using DDS_IDs. DDS registration attributes - are described in Section 6.11.1. - - The DDSReg message PDU Payload contains the Source Attribute and, - optionally, Message Key and Operating Attributes. - - The Message Key, if used, contains the DDS_ID of the Discover Domain - Set to be registered or modified. If the Message Key contains a - DDS_ID of an existing DDS entry in the iSNS database, then the DDSReg - message SHALL attempt to update the existing entry. If the DDS_ID in - the Message Key (if used) does not match an existing DDS entry, then - the iSNS server SHALL reject the DDSReg message with a status code of - 3 (Invalid Registration). If the DDS_ID is included in both the - Message Key and Operating Attributes, then the DDS_ID value in the - Message Key MUST be the same as the DDS_ID value in the Operating - Attributes. - - A DDSReg message with no Message Key SHALL result in the attempted - creation of a new Discovery Domain Set (DDS). If the DDS_ID - attribute (with non-zero length) is included among the Operating - Attributes in the DDSReg message, then the new Discovery Domain Set - SHALL be assigned the value contained in that DDS_ID attribute. - Otherwise, if the DDS_ID attribute is not contained among the - Operating Attributes of the DDSReg message, or if the DDS_ID is an - - - -Tseng, et al. Standards Track [Page 60] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - operating attribute with a TLV length of 0, then the iSNS server - SHALL assign a DDS_ID value. The assigned DDS_ID value is then - returned in the DDSReg Response message. The Operating Attributes - can also contain the DDS_Symbolic_Name, the DDS Status, and the - DD_IDs of Discovery Domains to be added to the DDS. - - When creating a new DDS, if the DDS Symbolic Name is included in the - Operating Attributes and its value is unique (i.e., it does not match - the registered DDS Symbolic Name for another DDS), then the value - SHALL be stored in the iSNS database as the DDS Symbolic Name for - that DDS. If the value for the DDS Symbolic Name is not unique, then - the iSNS server SHALL reject the attempted DDS registration with a - status code of 3 (Invalid Registration). - - When creating a new DDS, if the DDS Symbolic Name is not included in - the Operating Attributes, or if it is included with a zero-length - TLV, then the iSNS server SHALL provide a unique DDS Symbolic Name - value for the created DDS. The assigned DDS Symbolic Name value - SHALL be returned in the DDSRegRsp message. - - This message SHALL add any DD_IDs listed as Operating Attributes to - the Discovery Domain Set specified by the DDS_ID Message Key - Attribute. In addition, if the DDS_Symbolic_Name is an operating - attribute and the value is unique, then it SHALL be stored in the - iSNS database as the DDS_Symbolic_Name for the specified Discovery - Domain Set. - - If a DD_ID listed in the Operating Attributes does not match an - existing DD, then a new DD using the DD_ID SHALL be created. In this - case for the new DD, the iSNS server SHALL assign a unique value for - the DD Symbolic Name and SHALL set the DD Features attribute to the - default value of 0. These assigned values SHALL be returned in the - DDSRegRsp message. - -5.6.5.12. DDS Deregister (DDSDereg) - - The DDSDereg message type is 0x000C. This message allows an iSNS - client to deregister an existing Discovery Domain Set (DDS) or to - remove some DDs from an existing DDS. - - The DDSDereg message PDU Payload contains a Source Attribute, a - Message Key Attribute, and optional Operating Attributes. - - The Message Key Attribute for a DDSDereg message is the DDS ID for - the DDS being removed or having members removed. If the DDS ID - matches an existing DDS and there are no Operating Attributes, then - - - - - -Tseng, et al. Standards Track [Page 61] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - the DDS SHALL be removed and a success Status Code returned. Any - existing members of that DDS SHALL remain in the iSNS database - without membership in the just-removed DDS. - - If the DDS ID matches an existing DDS, and there are Operating - Attributes matching DDS members, then the DDS members SHALL be - removed from the DDS and a success Status Code returned. - - The attempted deregistration of non-existent DDS entries SHALL not be - considered an error. - -5.6.5.13. Entity Status Inquiry (ESI) - - The ESI message type is 0x000D. This message is sent by the iSNS - server, and is used to verify that an iSNS client Portal is reachable - and available. The ESI message is sent to the ESI UDP port provided - during registration, or to the TCP connection used for ESI - registration, depending on which communication type that is being - used. - - The ESI message PDU Payload contains the following attributes in TLV - format and in the order listed: the current iSNS timestamp, the EID, - the Portal IP Address, and the Portal TCP/UDP Port. The format of - this message is shown below: - - +----------------------------------------+ - | Timestamp | - +----------------------------------------+ - | Entity_ID | - +----------------------------------------+ - | Portal IP Address | - +----------------------------------------+ - | Portal TCP/UDP Port | - +----------------------------------------+ - - The ESI response message PDU Payload contains a status code, followed - by the Attributes from the original ESI message. - - If the Portal fails to respond to an administratively-determined - number of consecutive ESI messages, then the iSNS server SHALL remove - that Portal from the iSNS database. If there are no other remaining - ESI-monitored Portals for the associated Network Entity, then the - Network Entity SHALL also be removed. The appropriate State Change - Notifications, if any, SHALL be triggered. - - - - - - - -Tseng, et al. Standards Track [Page 62] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -5.6.5.14. Name Service Heartbeat (Heartbeat) - - This message, if used, is only sent by the active iSNS server. It - allows iSNS clients and backup servers listening to a broadcast or - multicast address to discover the IP address of the primary and - backup iSNS servers. It also allows concerned parties to monitor the - health and status of the primary iSNS server. - - This message is NOT in TLV format. There is no response message to - the Name Service Heartbeat. - - MSb LSb - 0 31 - +------------------------------------------------+ - | Active Server IP-Address | 16 Bytes - +------------------------------------------------+ - | iSNS TCP Port | iSNS UDP Port | 4 Bytes - +------------------------------------------------+ - | Interval | 4 Bytes - +------------------------------------------------+ - | Counter | 4 Bytes - +------------------------------------------------+ - | RESERVED | Backup Servers | 4 Bytes - +------------------------------------------------+ - | Primary Backup Server IP Address(if any) | 16 Bytes - +------------------------------------------------+ - |Backup TCP Port(if any)|Backup UDP Port(if any) | 4 Bytes - +------------------------------------------------+ - | 2nd Backup Server IP Address(if any) | 16 Bytes - +------------------------------------------------+ - |Backup TCP Port(if any)|Backup UDP Port(if any) | 4 Bytes - +------------------------------------------------+ - | . . . | - +------------------------------------------------+ - | VENDOR SPECIFIC | - +------------------------------------------------+ - - The heartbeat PDU Payload contains the following: - - Active Server IP Address: the IP Address of the active iSNS server in - IPv6 format. When this field contains an IPv4 - value, it is stored as an IPv4-mapped IPv6 address. - That is, the most significant 10 bytes are set to - 0x00, with the next two bytes set to 0xFFFF - [RFC2373]. When this field contains an IPv6 value, - the entire 16-byte field is used. - - Active TCP Port: the TCP Port of the server currently in use. - - - -Tseng, et al. Standards Track [Page 63] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Active UDP Port: the UDP Port of the server currently in use, - otherwise 0. - - Interval: the interval, in seconds, of the heartbeat. - - Counter: a count that begins at 0 when this server becomes - active. The count increments by one for each - heartbeat sent since this server became active. - - Backup Servers: the number of iSNS backup servers. The IP address, - TCP Port, and UDP Port of each iSNS backup server - follow this field. Note that if backup servers are - used, then the active iSNS server SHOULD be among - the list of backup servers. - - The content of the remainder of this message after the list of backup - servers is vendor-specific. Vendors may use additional fields to - coordinate between multiple iSNS servers, and/or to identify vendor- - specific features. - -5.6.5.15. Request FC_DOMAIN_ID (RqstDomId) - - The RqstDomId message type is 0x0011. This message is used for iFCP - Transparent Mode to allocate non-overlapping FC_DOMAIN_ID values - between 1 and 239. The iSNS server becomes the address assignment - authority for the entire iFCP fabric. To obtain multiple - FC_DOMAIN_ID values, this request must be repeated to the iSNS server - multiple times. iSNS clients that acquire FC_DOMAIN_ID values from - an iSNS server MUST register for ESI monitoring from that iSNS - server. - - The RqstDomId PDU Payload contains three TLV attributes in the - following order: the requesting Switch Name (WWN) as the Source - Attribute, the Virtual_Fabric_ID as the Message Key Attribute, and - Preferred ID as the operating attribute. The Virtual_Fabric_ID is a - string identifying the domain space for which the iSNS server SHALL - allocate non-overlapping integer FC_DOMAIN_ID values between 1 and - 239. The Preferred_ID is the nominal FC_DOMAIN_ID value requested by - the iSNS client. If the Preferred_ID value is available and has not - already been allocated for the Virtual_Fabric_ID specified in the - message, the iSNS server SHALL return the requested Preferred_ID - value as the Assigned_ID to the requesting client. - - The RqstDomId response contains a Status Code, and the TLV attribute - Assigned ID, which contains the integer value in the space requested. - If no further unallocated values are available from this space, the - iSNS server SHALL respond with the Status Code 18 "FC_DOMAIN_ID Not - Available". - - - -Tseng, et al. Standards Track [Page 64] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Once a FC_DOMAIN_ID value has been allocated to an iSNS client by the - iSNS server for a given Virtual_Fabric_ID, that FC_DOMAIN_ID value - SHALL NOT be reused until it has been deallocated, or until ESI - monitoring detects that the iSNS client no longer exists on the - network and objects for that client are removed from the iSNS - database. - - The iSNS server and client SHALL use TCP to transmit and receive - RqstDomId, RqstDomIdRsp, RlseDomId, and RlseDomIdRsp messages. - -5.6.5.16. Release FC_DOMAIN_ID (RlseDomId) - - The RlseDomId message type is 0x0012. This message may be used by - iFCP Transparent Mode to release integer identifier values used to - assign 3-byte Fibre Channel PORT_ID values. - - The RlseDomId message contains three TLV attributes in the following - order: the requesting EID as the Source Attribute, the - Virtual_Fabric_ID as the Message Key Attribute, and Assigned_ID as - the operating attribute. Upon receiving the RlseDomId message, the - iSNS server SHALL deallocate the FC_DOMAIN_ID value contained in the - Assigned_ID attribute for the Virtual_Fabric_ID attribute specified. - Upon deallocation, that FC_DOMAIN_ID value can then be requested by - and assigned to a different iSNS client. - - The iSNS server and client SHALL use TCP to transmit and receive - RqstDomId, RqstDomIdRsp, RlseDomId, and RlseDomIdRsp messages. - -5.6.5.17. Get FC_DOMAIN_IDs (GetDomId) - - The GetDomId message type is 0x0013. This message is used to learn - the currently-allocated FC_DOMAIN_ID values for a given - Virtual_Fabric_ID. - - The GetDomId message PDU Payload contains a Source Attribute and - Message Key Attribute. - - The Message Key Attribute for the GetDomId message is the - Virtual_Fabric_ID. The response to this message returns all the - FC_DOMAIN_ID values that have been allocated for the - Virtual_Fabric_ID specified. - - - - - - - - - - -Tseng, et al. Standards Track [Page 65] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -5.7. Messages - - The iSNSP response message PDU Payloads contain a Status Code, - followed by a list of attributes, and have the following format: - - MSb LSb - 0 31 - +----------------------------------------+ - | 4-byte STATUS CODE | - +----------------------------------------+ - | Message Key Attribute[1] (if present) | - +----------------------------------------+ - | Message Key Attribute[2] (if present) | - +----------------------------------------+ - | . . . | - +----------------------------------------+ - | - Delimiter Attribute - (if present) | - +----------------------------------------+ - | Operating Attribute[1] (if present) | - +----------------------------------------+ - | Operating Attribute[2] (if present) | - +----------------------------------------+ - | Operating Attribute[3] (if present) | - +----------------------------------------+ - | . . . | - +----------------------------------------+ - - The iSNSP Response messages SHALL be sent to the iSNS Client IP - Address and the originating TCP/UDP Port that was used for the - associated registration and query message. - -5.7.1. Status Code - - The first field in an iSNSP response message PDU Payload is the - Status Code for the operation that was performed. The Status Code - encoding is defined in Section 5.4. - -5.7.2. Message Key Attributes in Response - - Depending on the specific iSNSP request, the response message MAY - contain Message Key Attributes. Message Key Attributes generally - contain the interesting key attributes that are affected by the - operation specified in the original iSNS registration or query - message. - - - - - - - -Tseng, et al. Standards Track [Page 66] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -5.7.3. Delimiter Attribute in Response - - The Delimiter Attribute separates the key and Operating Attributes in - a response message, if they exist. The Delimiter Attribute has a tag - value of 0 and a length value of 0. The Delimiter Attribute is - effectively 8 bytes long: a 4-byte tag containing 0x00000000, and a 4 - Byte length field containing 0x00000000. - -5.7.4. Operating Attributes in Response - - The Operating Attributes in a response are the results related to the - iSNS registration or query operation being performed. Some response - messages will not have Operating Attributes. - -5.7.5. Registration and Query Response Message Types - - The following sections describe each query and message type. - -5.7.5.1. Device Attribute Registration Response (DevAttrRegRsp) - - The DevAttrRegRsp message type is 0x8001. The DevAttrRegRsp message - contains the results for the DevAttrReg message with the same - TRANSACTION ID. - - The Message Key in the DevAttrRegRsp message SHALL return the Message - Key in the original registration message. If the iSNS server - assigned the Entity Identifier for a Network Entity, then the Message - Key Attribute field SHALL contain the assigned Entity Identifier. - - The Operating Attributes of the DevAttrRegRsp message SHALL contain - the affected object's key and non-key attributes that have been - explicitly modified or created by the original DevAttrReg message. - Among the Operating Attributes, each modified or added non-key - attribute SHALL be listed after its key attribute(s) in the - DevAttrRegRsp message. Implicitly registered attributes MUST NOT be - returned in the DevAttrRegRsp message. Implicitly registered - attributes are those that are assigned a fixed default value or - secondary index value by the iSNS server. - - Implicitly registered PG objects (i.e., PG objects that are not - explicitly included in the registration or replace message) MUST NOT - have their key or non-key attributes returned in the DevAttrRegRsp - message. However, explicitly registered PG objects (i.e., those with - PGT values that are explicitly included in the registration or - replace message) SHALL have their PGT values returned in the - DevAttrRegRsp message. - - - - - -Tseng, et al. Standards Track [Page 67] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - For example, three Portals are registered in the original DevAttrReg - request message. Due to lack of resources, the iSNS server needs to - modify the registered ESI Interval value of one of those Portals. To - accomplish this, the iSNS server returns the key attributes - identifying the Portal, followed by the non-key modified ESI Interval - attribute value, as Operating Attributes of the corresponding - DevAttrRegRsp message. - - If the iSNS server rejects a registration due to invalid attribute - values or types, then the indicated status code SHALL be 3 (Invalid - Registration). If this occurs, then the iSNS server MAY include the - list of invalid attributes in the Operating Attributes of the - DevAttrRsp message. - - Some attributes values (e.g., ESI Interval, Registration Period) in - the original registration message MAY be modified by the iSNS server. - This can occur only for a limited set of attribute types, as - indicated in the table in Section 6.1. When this occurs, the - registration SHALL be considered a success (with status code 0), and - the changed value(s) indicated in the Operating Attributes of the - DevAttrRsp message. - -5.7.5.2. Device Attribute Query Response (DevAttrQryRsp) - - The DevAttrQryRsp message type is 0x8002. The DevAttrQryRsp message - contains the results for the DevAttrQry message with the same - TRANSACTION ID. - - The Message Key in the DevAttrQryRsp message SHALL return the Message - Key in the original query message. - - If no Operating Attributes are included in the original query, then - all Operating Attributes SHALL be returned in the response. - - For a successful query result, the DevAttrQryRsp Operating Attributes - SHALL contain the results of the original DevAttrQry message. - -5.7.5.3. Device Get Next Response (DevGetNextRsp) - - The DevGetNextRsp message type is 0x8003. The DevGetNextRsp message - contains the results for the DevGetNext message with the same - TRANSACTION ID. - - The Message Key Attribute field returns the object keys for the next - object after the Message Key Attribute in the original DevGetNext - message. - - - - - -Tseng, et al. Standards Track [Page 68] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - The Operating Attribute field returns the Operating Attributes of the - next object as requested in the original DevGetNext message. The - values of the Operating Attributes are those associated with the - object identified by the Message Key Attribute field of the - DevGetNextRsp message. - -5.7.5.4. Deregister Device Response (DevDeregRsp) - - The DevDeregRsp message type is 0x8004. This message is the response - to the DevDereg request message. - - This message response does not contain a Message Key, but MAY contain - Operating Attributes. - - In the event of an error, this response message contains the - appropriate status code as well as a list of objects from the - original DevDereg message that were not successfully deregistered - from the iSNS database. This list of objects is contained in the - Operating Attributes of the DevDeregRsp message. Note that an - attempted deregistration of a non-existent object does not constitute - an error, and non-existent entries SHALL not be returned in the - DevDeregRsp message. - -5.7.5.5. SCN Register Response (SCNRegRsp) - - The SCNRegRsp message type is 0x8005. This message is the response - to the SCNReg request message. - - The SCNRegRsp message does not contain any Message Key or Operating - Attributes. - -5.7.5.6. SCN Deregister Response (SCNDeregRsp) - - The SCNDeregRsp message type is 0x8006. This message is the response - to the SCNDereg request message. - - The SCNDeregRsp message does not contain any Message Key or Operating - Attributes. - -5.7.5.7. SCN Event Response (SCNEventRsp) - - The SCNEventRsp message type is 0x8007. This message is the response - to the SCNEvent request message. - - The SCNEventRsp message does not contain any Message Key or Operating - Attributes. - - - - - -Tseng, et al. Standards Track [Page 69] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -5.7.5.8. SCN Response (SCNRsp) - - The SCNRsp message type is 0x8008. This message is sent by an iSNS - client, and provides confirmation that the SCN message was received - and processed. - - The SCNRsp response contains the SCN Destination Attribute - representing the Node identifier that received the SCN. - -5.7.5.9. DD Register Response (DDRegRsp) - - The DDRegRsp message type is 0x8009. This message is the response to - the DDReg request message. - - The Message Key in the DDRegRsp message SHALL return the Message Key - in the original query message. If the original DDReg message did not - have a Message Key, then the DDRegRsp message SHALL not have a - Message Key. - - If the DDReg operation is successful, the DD ID of the DD created or - updated SHALL be returned as an operating attribute of the message. - - If the DD Symbolic Name attribute or DD Features attribute was - assigned or updated during the DDReg operation, then any new values - SHALL be returned as an operating attribute of the DDRegRsp message. - - If the iSNS server rejects a DDReg due to invalid attribute values or - types, then the indicated status code SHALL be 3 (Invalid - Registration). If this occurs, then the iSNS server MAY include the - list of invalid attributes in the Operating Attributes of the - DDRegRsp message. - -5.7.5.10. DD Deregister Response (DDDeregRsp) - - The DDDeregRsp message type is 0x800A. This message is the response - to the DDDereg request message. - - The DDDeregRsp message does not contain any Message Key or Operating - Attributes. - - - - - - - - - - - - -Tseng, et al. Standards Track [Page 70] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -5.7.5.11. DDS Register Response (DDSRegRsp) - - The DDSRegRsp message type is 0x800B. This message is the response - to the DDSReg request message. - - The Message Key in the DDSRegRsp message SHALL contain the Message - Key of the original DDSReg message. If the original DDSReg message - did not have a Message Key, then the DDSRegRsp message SHALL NOT have - a Message Key. - - If the DDSReg operation is successful, the DDS ID of the DDS created - or updated SHALL be returned as an operating attribute of the - message. - - If the DDS Symbolic Name attribute or DDS Status attribute was - assigned or updated during the DDSRegRsp operation, then any new - values SHALL be returned as an operating attribute of the DDSRegRsp - message. - - If the iSNS server rejects a DDSReg due to invalid attribute values - or types, then the indicated status code SHALL be 3 (Invalid - Registration). If this occurs, then the iSNS server MAY include the - list of invalid attributes in the Operating Attributes of the - DDSRegRsp message. - -5.7.5.12. DDS Deregister Response (DDSDeregRsp) - - The DDSDeregRsp message type is 0x800C. This message is the response - to the DDSDereg request message. - - The DDSDeregRsp message does not contain any Message Key or Operating - Attributes. - -5.7.5.13. Entity Status Inquiry Response (ESIRsp) - - The ESIRsp message type is 0x800D. This message is sent by an iSNS - client and provides confirmation that the ESI message was received - and processed. - - The ESIRsp response message PDU Payload contains the attributes from - the original ESI message. These attributes represent the Portal that - is responding to the ESI. The ESIRsp Attributes are in the order - they were provided in the original ESI message. - - Upon receiving the ESIRsp from the iSNS client, the iSNS server SHALL - update the timestamp attribute for that Network Entity and Portal. - - - - - -Tseng, et al. Standards Track [Page 71] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -5.7.5.14. Request FC_DOMAIN_ID Response (RqstDomIdRsp) - - The RqstDomIdRsp message type is 0x8011. This message provides the - response for RqstDomId. - - The RqstDomId response contains a Status Code and the TLV attribute - Assigned ID, which contains the integer value in the space requested. - If no further unallocated values are available from this space, the - iSNS server SHALL respond with the Status Code 19 "FC_DOMAIN_ID Not - Available". - - Once a FC_DOMAIN_ID value is allocated by the iSNS server, it SHALL - NOT be reused until it has been deallocated by the iSNS client to - which the value was assigned, or until the ESI message detects that - the iSNS client no longer exists on the network. - - The iSNS server and client SHALL use TCP to transmit and receive - RqstDomId, RqstDomIdRsp, RlseDomId, and RlseDomIdRsp messages. - -5.7.5.15. Release FC_DOMAIN_ID Response (RlseDomIdRsp) - - The RlseDomIdRsp message type is 0x8012. This message provides the - response for RlseDomId. The response contains an Error indicating - whether the request was successful. If the Assigned_ID value in the - original RlseDomId message is not allocated, then the iSNS server - SHALL respond with this message using the Status Code 20 - "FC_DOMAIN_ID Not Allocated". - - The iSNS server and client SHALL use TCP to transmit and receive - RqstDomId, RqstDomIdRsp, RlseDomId, and RlseDomIdRsp messages. - -5.7.5.16. Get FC_DOMAIN_IDs Response (GetDomIdRsp) - - The GetDomIdRsp message type is 0x8013. This message is used to - determine which FC_DOMAIN_ID values have been allocated for the - Virtual_Fabric_ID specified in the original GetDomId request message. - - The GetDomId response message PDU Payload contains a Status Code - indicating whether the request was successful, and a list of the - Assigned IDs from the space requested. The Assigned_ID attributes - are listed in TLV format. - -5.8. Vendor-Specific Messages - - Vendor-specific iSNSP messages have a functional ID of between 0x0100 - and 0x01FF, whereas vendor-specific responses have a functional ID of - between 0x8100 and 0x81FF. The first Message Key Attribute in a - - - - -Tseng, et al. Standards Track [Page 72] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - vendor-specific message SHALL be the company OUI (tag=256) - identifying the original creator of the proprietary iSNSP message. - The contents of the remainder of the message are vendor-specific. - -6. iSNS Attributes - - Attributes can be stored in the iSNS server using iSNSP registration - messages, and they can be retrieved using iSNSP query messages. - Unless otherwise indicated, these attributes are supplied by iSNS - clients using iSNSP registration messages. - -6.1. iSNS Attribute Summary - - The complete registry of iSNS attributes is maintained by IANA, and - the following table summarizes the initial set of iSNS attributes - available at the time of publication of this document. - - Attributes Length Tag Reg Key Query Key - ---------- ------ --- ------- --------- - Delimiter 0 0 N/A N/A - Entity Identifier (EID) 4-256 1 1 1|2|16&17|32|64 - Entity Protocol 4 2 1 1|2|16&17|32|64 - Management IP Address 16 3 1 1|2|16&17|32|64 - Timestamp 8 4 -- 1|2|16&17|32|64 - Protocol Version Range 4 5 1 1|2|16&17|32|64 - Registration Period 4 6 1 1|2|16&17|32|64 - Entity Index 4 7 1 1|2|16&17|32|64 - Entity Next Index 4 8 -- 1|2|16&17|32|64 - Entity ISAKMP Phase-1 var 11 1 1|2|16&17|32|64 - Entity Certificate var 12 1 1|2|16&17|32|64 - Portal IP Address 16 16 1 1|16&17|32|64 - Portal TCP/UDP Port 4 17 1 1|16&17|32|64 - Portal Symbolic Name 4-256 18 16&17 1|16&17|32|64 - ESI Interval 4 19 16&17 1|16&17|32|64 - ESI Port 4 20 16&17 1|16&17|32|64 - Portal Index 4 22 16&17 1|16&17|32|64 - SCN Port 4 23 16&17 1|16&17|32|64 - Portal Next Index 4 24 -- 1|16&17|32|64 - Portal Security Bitmap 4 27 16&17 1|16&17|32|64 - Portal ISAKMP Phase-1 var 28 16&17 1|16&17|32|64 - Portal ISAKMP Phase-2 var 29 16&17 1|16&17|32|64 - Portal Certificate var 31 16&17 1|16&17|32|64 - iSCSI Name 4-224 32 1 1|16&17|32|33 - iSCSI Node Type 4 33 32 1|16&17|32 - iSCSI Alias 4-256 34 32 1|16&17|32 - iSCSI SCN Bitmap 4 35 32 1|16&17|32 - iSCSI Node Index 4 36 32 1|16&17|32 - WWNN Token 8 37 32 1|16&17|32 - - - -Tseng, et al. Standards Track [Page 73] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - iSCSI Node Next Index 4 38 -- 1|16&17|32 - iSCSI AuthMethod var 42 32 1|16&17|32 - PG iSCSI Name 4-224 48 32|16&17 1|16&17|32|52 - PG Portal IP Addr 16 49 32|16&17 1|16&17|32|52 - PG Portal TCP/UDP Port 4 50 32|16&17 1|16&17|32|52 - PG Tag (PGT) 4 51 32|16&17 1|16&17|32|52 - PG Index 4 52 32|16&17 1|16&17|32|52 - PG Next Index 4 53 -- 1|16&17|32|52 - FC Port Name WWPN 8 64 1 1|16&17|64|66|96|128 - Port ID 4 65 64 1|16&17|64 - FC Port Type 4 66 64 1|16&17|64 - Symbolic Port Name 4-256 67 64 1|16&17|64 - Fabric Port Name 8 68 64 1|16&17|64 - Hard Address 4 69 64 1|16&17|64 - Port IP-Address 16 70 64 1|16&17|64 - Class of Service 4 71 64 1|16&17|64 - FC-4 Types 32 72 64 1|16&17|64 - FC-4 Descriptor 4-256 73 64 1|16&17|64 - FC-4 Features 128 74 64 1|16&17|64 - iFCP SCN bitmap 4 75 64 1|16&17|64 - Port Role 4 76 64 1|16&17|64 - Permanent Port Name 8 77 -- 1|16&17|64 - FC-4 Type Code 4 95 -- 1|16&17|64 - FC Node Name WWNN 8 96 64 1|16&17|64|96 - Symbolic Node Name 4-256 97 96 64|96 - Node IP-Address 16 98 96 64|96 - Node IPA 8 99 96 64|96 - Proxy iSCSI Name 4-256 101 96 64|96 - Switch Name 8 128 128 128 - Preferred ID 4 129 128 128 - Assigned ID 4 130 128 128 - Virtual_Fabric_ID 4-256 131 128 128 - iSNS Server Vendor OUI 4 256 -- SOURCE Attribute - Vendor-Spec iSNS Srvr 257-384 -- SOURCE Attribute - Vendor-Spec Entity 385-512 1 1|2|16&17|32|64 - Vendor-Spec Portal 513-640 16&17 1|16&17|32|64 - Vendor-Spec iSCSI Node 641-768 32 16&17|32 - Vendor-Spec FC Port Name 769-896 64 1|16&17|64 - Vendor-Spec FC Node Name 897-1024 96 64|96 - Vendor-Specific DDS 1025-1280 2049 2049 - Vendor-Specific DD 1281-1536 2065 2065 - Other Vendor-Specific 1537-2048 - DD_Set ID 4 2049 2049 1|32|64|2049|2065 - DD_Set Sym Name 4-256 2050 2049 2049 - DD_Set Status 4 2051 2049 2049 - DD_Set_Next_ID 4 2052 -- 2049 - DD_ID 4 2065 2049 1|32|64|2049|2065 - DD_Symbolic Name 4-256 2066 2065 2065 - - - -Tseng, et al. Standards Track [Page 74] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - DD_Member iSCSI Index 4 2067 2065 2065 - DD_Member iSCSI Name 4-224 2068 2065 2065 - DD_Member FC Port Name 8 2069 2065 2065 - DD_Member Portal Index 4 2070 2065 2065 - DD_Member Portal IP Addr 16 2071 2065 2065 - DD_Member Portal TCP/UDP 4 2072 2065 2065 - DD_Features 4 2078 2065 2065 - DD_ID Next ID 4 2079 -- 2065 - - The following are descriptions of the columns used in the above - table: - - Length: indicates the attribute length in bytes used for the TLV - format. Variable-length identifiers are NULL-terminated - and 4-byte aligned (NULLs are included in the length). - - Tag: the IANA-assigned integer tag value used to identify the - attribute. All undefined tag values are reserved. - - Reg Key: indicates the tag values for the object key in DevAttrReg - messages for registering a new attribute value in the - database. These tags represent attributes defined as - object keys in Section 4. - - Query Key: indicates the possible tag values for the Message Key and - object key that are used in the DevAttrQry messages for - retrieving a stored value from the iSNS database. - - The following is a summary of iSNS attribute tag values available for - future allocation by IANA at the time of publication: - - Tag Values Reg Key Query Key - ---------- ------- --------- - 9-10, 13-15 1 1|2|16&17|32|64 - 21, 25-26, 30 16&17 1|16&17|32|64 - 39-41, 44-47 32 1|16&17|32 - 54-63 32|16&17 1|16&17|32|52 - 78-82, 85-94 64 1|16&17|64 - 102-127 96 64|96 - 132-255 -- SOURCE Attribute - 2053-2064 2049 2049 - 2073-2077 2065 2065 - 2080-65535 To be assigned To be assigned - - Registration and query keys for attributes with tags in the range - 2080 to 65535 are to be documented in the RFC introducing the new - iSNS attributes. IANA will maintain registration of these values as - required by the new RFC. - - - -Tseng, et al. Standards Track [Page 75] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - New iSNS attributes with any of the above tag values MAY also be - designated as "read-only" attributes. The new RFC introducing these - attributes as "read-only" SHALL document them as such, and IANA will - record their corresponding Registration Keys (Reg Keys) as "--". - -6.2. Entity Identifier-Keyed Attributes - - The following attributes are stored in the iSNS server using the - Entity Identifier attribute as the key. - -6.2.1. Entity Identifier (EID) - - The Entity Identifier (EID) is variable-length UTF-8 encoded NULL- - terminated text-based description for a Network Entity. This key - attribute uniquely identifies each Network Entity registered in the - iSNS server. The attribute length varies from 4 to 256 bytes - (including the NULL termination), and is a unique value within the - iSNS server. - - If the iSNS client does not provide an EID during registration, the - iSNS server SHALL generate one that is unique within the iSNS - database. If an EID is to be generated, then the EID attribute value - in the registration message SHALL be empty (0 length). The generated - EID SHALL be returned in the registration response. - - In environments where the iSNS server is integrated with a DNS - infrastructure, the Entity Identifier may be used to store the Fully - Qualified Domain Name (FQDN) of the iSCSI or iFCP device. FQDNs of - greater than 255 bytes MUST NOT be used. - - If FQDNs are not used, the iSNS server can be used to generate EIDs. - EIDs generated by the iSNS server MUST begin with the string "isns:". - iSNS clients MUST NOT generate and register EIDs beginning with the - string "isns:". - - This field MUST be normalized according to the nameprep template - [NAMEPREP] before it is stored in the iSNS database. - -6.2.2. Entity Protocol - - The Entity Protocol is a required 4-byte integer attribute that - indicates the block storage protocol used by the registered NETWORK - ENTITY. Values used for this attribute are assigned and maintained - by IANA. The initial set of protocols supported by iSNS is as - follows: - - - - - - -Tseng, et al. Standards Track [Page 76] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Value Entity Protocol Type - ----- -------------------- - 1 No Protocol - 2 iSCSI - 3 iFCP - All others To be assigned by IANA - - 'No Protocol' is used to indicate that the Network Entity does not - support an IP block storage protocol. A Control Node or monitoring - Node would likely (but not necessarily) use this value. - - This attribute is required during initial registration of the Network - Entity. - -6.2.3. Management IP Address - - This field contains the IP Address that may be used to manage the - Network Entity and all Storage Nodes contained therein via the iSNS - MIB [iSNSMIB]. Some implementations may also use this IP address to - support vendor-specific proprietary management protocols. The - Management IP Address is a 16-byte field that may contain an IPv4 or - IPv6 address. When this field contains an IPv4 value, it is stored - as an IPv4-mapped IPv6 address. That is, the most significant 10 - bytes are set to 0x00, with the next two bytes set to 0xFFFF - [RFC2373]. When this field contains an IPv6 value, the entire 16- - byte field is used. If this field is not set, then in-band - management through the IP address of one of the Portals of the - Network Entity is assumed. - -6.2.4. Entity Registration Timestamp - - This field indicates the most recent time when the Network Entity - registration occurred or when an associated object attribute was - updated or queried by the iSNS client registering the Network Entity. - The time format is, in seconds, the update period since the standard - base time of 00:00:00 GMT on January 1, 1970. This field cannot be - explicitly registered. This timestamp TLV format is also used in the - SCN and ESI messages. - -6.2.5. Protocol Version Range - - This field contains the minimum and maximum version of the block - storage protocol supported by the Network Entity. The most - significant two bytes contain the maximum version supported, and the - least significant two bytes contain the minimum version supported. - If a range is not registered, then the Network Entity is assumed to - - - - - -Tseng, et al. Standards Track [Page 77] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - support all versions of the protocol. The value 0xffff is a wildcard - that indicates no minimum or maximum. If the Network Entity does not - support a protocol, then this field SHALL be set to 0. - -6.2.6. Registration Period - - This 4-byte unsigned integer field indicates the maximum period, in - seconds, that the registration SHALL be maintained by the server - without receipt of an iSNS message from the iSNS client that - registered the Network Entity. Entities that are not registered for - ESI monitoring MUST have a non-zero Registration Period. If a - Registration Period is not requested by the iSNS client and Entity - Status Inquiry (ESI) messages are not enabled for that client, then - the Registration Period SHALL be set to a non-zero value by the iSNS - server. This implementation-specific value for the Registration - Period SHALL be returned in the registration response to the iSNS - client. The Registration Period may be set to zero, indicating its - non-use, only if ESI messages are enabled for that Network Entity. - - The registration SHALL be removed from the iSNS database if an iSNS - Protocol message is not received from the iSNS client before the - registration period has expired. Receipt of any iSNS Protocol - message from the iSNS client automatically refreshes the Entity - Registration Period and Entity Registration Timestamp. To prevent a - registration from expiring, the iSNS client should send an iSNS - Protocol message to the iSNS server at intervals shorter than the - registration period. Such a message can be as simple as a query for - one of its own attributes, using its associated iSCSI Name or FC Port - Name WWPN as the Source attribute. - - For an iSNS client that is supporting a Network Entity with multiple - Storage Node objects, receipt of an iSNS message from any Storage - Node of that Network Entity is sufficient to refresh the registration - for all Storage Node objects of the Network Entity. - - If ESI support is requested as part of a Portal registration, the ESI - Response message received from the iSNS client by the iSNS server - SHALL refresh the registration. - -6.2.7. Entity Index - - The Entity Index is an unsigned non-zero integer value that uniquely - identifies each Network Entity registered in the iSNS server. Upon - initial registration of a Network Entity, the iSNS server assigns an - unused value for the Entity Index. Each Network Entity in the iSNS - database MUST be assigned a value for the Entity Index that is not - - - - - -Tseng, et al. Standards Track [Page 78] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - assigned to any other Network Entity. Furthermore, Entity Index - values for recently deregistered Network Entities SHOULD NOT be - reused in the short term. - - The Entity Index MAY be used to represent the Network Entity in - situations when the Entity Identifier is too long or otherwise - inappropriate. An example of this is when SNMP is used for - management, as described in Section 2.10. - -6.2.8. Entity Next Index - - This is a virtual attribute containing a 4-byte integer value that - indicates the next available (i.e., unused) Entity Index value. This - attribute may only be queried; the iSNS server SHALL return an error - code of 3 (Invalid Registration) to any client that attempts to - register a value for this attribute. A Message Key is not required - when exclusively querying for this attribute. - - The Entity Next Index MAY be used by an SNMP client to create an - entry in the iSNS server. SNMP requirements are described in Section - 2.10. - -6.2.9. Entity ISAKMP Phase-1 Proposals - - This field contains the IKE Phase-1 proposal, listing in decreasing - order of preference the protection suites acceptable to protect all - IKE Phase-2 messages sent and received by the Network Entity. This - includes Phase-2 SAs from the iSNS client to the iSNS server as well - as to peer iFCP and/or iSCSI devices. This attribute contains the SA - payload, proposal payload(s), and transform payload(s) in the ISAKMP - format defined in [RFC2408]. - - This field should be used if the implementer wishes to define a - single phase-1 SA security configuration used to protect all phase-2 - IKE traffic. If the implementer desires to have a different phase-1 - SA security configuration to protect each Portal interface, then the - Portal Phase-1 Proposal (Section 6.3.10) should be used. - -6.2.10. Entity Certificate - - This attribute contains one or more X.509 certificates that are bound - to the Network Entity. This certificate is uploaded and registered - to the iSNS server by clients wishing to allow other clients to - authenticate themselves and to access the services offered by that - Network Entity. The format of the X.509 certificate is found in - [RFC3280]. This certificate MUST contain a Subject Name with an - empty sequence and MUST contain a SubjectAltName extension encoded - - - - -Tseng, et al. Standards Track [Page 79] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - with the dNSName type. The Entity Identifier (Section 6.2.1) of the - identified Entity MUST be stored in the SubjectAltName field of the - certificate. - -6.3. Portal-Keyed Attributes - - The following Portal attributes are registered in the iSNS database - using the combined Portal IP-Address and Portal TCP/UDP Port as the - key. Each Portal is associated with one Entity Identifier object - key. - -6.3.1. Portal IP Address - - This attribute is the IP address of the Portal through which a - Storage Node can transmit and receive storage data. The Portal IP - Address is a 16-byte field that may contain an IPv4 or IPv6 address. - When this field contains an IPv4 address, it is stored as an IPv4- - mapped IPv6 address. That is, the most significant 10 bytes are set - to 0x00, with the next 2 bytes set to 0xFFFF [RFC2373]. When this - field contains an IPv6 address, the entire 16-byte field is used. - The Portal IP Address and the Portal TCP/UDP Port number (see 6.3.2 - below) are used as a key to identify a Portal uniquely. It is a - required attribute for registration of a Portal. - -6.3.2. Portal TCP/UDP Port - - The TCP/UDP port of the Portal through which a Storage Node can - transmit and receive storage data. Bits 16 to 31 represents the - TCP/UDP port number. Bit 15 represents the port type. If bit 15 is - set, then the port type is UDP. Otherwise it is TCP. Bits 0 to 14 - are reserved. - - If the field value is 0, then the port number is the implied - canonical port number and type of the protocol indicated by the - associated Entity Type. - - The Portal IP Address and the Portal TCP/UDP Port number are used as - a key to identify a Portal uniquely. It is a required attribute for - registration of a Portal. - -6.3.3. Portal Symbolic Name - - A variable-length UTF-8 encoded NULL-terminated text-based - description of up to 256 bytes. The Portal Symbolic Name is a user- - readable description of the Portal entry in the iSNS server. - - - - - - -Tseng, et al. Standards Track [Page 80] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.3.4. Entity Status Inquiry Interval - - This field indicates the requested time, in seconds, between Entity - Status Inquiry (ESI) messages sent from the iSNS server to this - Network Entity. ESI messages can be used to verify that a Portal - registration continues to be valid. To request monitoring by the - iSNS server, an iSNS client registers a non-zero value for this - Portal attribute using a DevAttrReg message. The client MUST - register an ESI Port on at least one of its Portals to receive the - ESI monitoring. - - If the iSNS server does not receive an expected response to an ESI - message, it SHALL attempt an administratively configured number of - re-transmissions of the ESI message. The ESI Interval period begins - with the iSNS server's receipt of the last ESI Response. All re- - transmissions MUST be sent before twice the ESI Interval period has - passed. If no response is received from any of the ESI messages, - then the Portal SHALL be deregistered. Note that only Portals that - have registered a value in their ESI Port field can be deregistered - in this way. - - If all Portals associated with a Network Entity that have registered - for ESI messages are deregistered due to non-response, and if no - registrations have been received from the client for at least two ESI - Interval periods, then the Network Entity and all associated objects - (including Storage Nodes) SHALL be deregistered. - - If the iSNS server is unable to support ESI messages or the ESI - Interval requested, it SHALL either reject the ESI request by - returning an "ESI Not Available" Status Code or modify the ESI - Interval attribute by selecting its own suitable value and returning - that value in the Operating Attributes of the registration response - message. - - If at any time an iSNS client that is registered for ESI messages has - not received an ESI message to any of its Portals as expected, then - the client MAY attempt to query the iSNS server using a DevAttrQry - message using its Entity_ID as the key. If the query result is the - error "no such entry", then the client SHALL close all remaining TCP - connections to the iSNS server and assume that it is no longer - registered in the iSNS database. Such a client MAY attempt re- - registration. - - - - - - - - - -Tseng, et al. Standards Track [Page 81] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.3.5. ESI Port - - This field contains the TCP or UDP port used for ESI monitoring by - the iSNS server at the Portal IP Address. Bits 16 to 31 represent - the port number. If bit 15 is set, then the port type is UDP. - Otherwise, the port is TCP. Bits 0 to 14 are reserved. - - If the iSNS client registers a valid TCP or UDP port number in this - field, then the client SHALL allow ESI messages to be received at the - indicated TCP or UDP port. If a TCP port is registered and a pre- - existing TCP connection from that TCP port to the iSNS server does - not already exist, then the iSNS client SHALL accept new TCP - connections from the iSNS server at the indicated TCP port. - - The iSNS server SHALL return an error if a Network Entity is - registered for ESI monitoring and none of the Portals of that Network - Entity has an entry for the ESI Port field. If multiple Portals have - a registered ESI port, then the ESI message may be delivered to any - one of the indicated Portals. - -6.3.6. Portal Index - - The Portal Index is a 4-byte non-zero integer value that uniquely - identifies each Portal registered in the iSNS database. Upon initial - registration of a Portal, the iSNS server assigns an unused value for - the Portal Index of that Portal. Each Portal in the iSNS database - MUST be assigned a value for the Portal Index that is not assigned to - any other Portal. Furthermore, Portal Index values for recently - deregistered Portals SHOULD NOT be reused in the short term. - - The Portal Index MAY be used to represent a registered Portal in - situations where the Portal IP-Address and Portal TCP/UDP Port is - unwieldy to use. An example of this is when SNMP is used for - management, as described in Section 2.10. - -6.3.7. SCN Port - - This field contains the TCP or UDP port used by the iSNS client to - receive SCN messages from the iSNS server. When a value is - registered for this attribute, an SCN message may be received on the - indicated port for any of the Storage Nodes supported by the Portal. - Bits 16 to 31 contain the port number. If bit 15 is set, then the - port type is UDP. Otherwise, the port type is TCP. Bits 0 to 14 are - reserved. - - If the iSNS client registers a valid TCP or UDP port number in this - field, then the client SHALL allow SCN messages to be received at the - indicated TCP or UDP port. If a TCP port is registered and a pre- - - - -Tseng, et al. Standards Track [Page 82] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - existing TCP connection from that TCP port to the iSNS server does - not already exist, then the iSNS client SHALL accept new TCP - connections from the iSNS server at the indicated TCP port. - - The iSNS server SHALL return an error if an SCN registration message - is received and none of the Portals of the Network Entity has an - entry for the SCN Port. If multiple Portals have a registered SCN - Port, then the SCN SHALL be delivered to any one of the indicated - Portals of that Network Entity. - -6.3.8. Portal Next Index - - This is a virtual attribute containing a 4-byte integer value that - indicates the next available (i.e., unused) Portal Index value. This - attribute may only be queried; the iSNS server SHALL return an error - code of 3 (Invalid Registration) to any client that attempts to - register a value for this attribute. A Message Key is not required - when exclusively querying for this attribute. - - The Portal Next Index MAY be used by an SNMP client to create an - entry in the iSNS server. SNMP requirements are described in Section - 2.10. - -6.3.9. Portal Security Bitmap - - This 4-byte field contains flags that indicate security attribute - settings for the Portal. Bit 31 (Lsb) of this field must be 1 - (enabled) for this field to contain significant information. If Bit - 31 is enabled, this signifies that the iSNS server can be used to - store and distribute security policies and settings for iSNS clients - (i.e., iSCSI devices). Bit 30 must be 1 for bits 25-29 to contain - significant information. All other bits are reserved for non- - IKE/IPSec security mechanisms to be specified in the future. - - Bit Position Flag Description - ------------ ---------------- - 25 1 = Tunnel Mode Preferred; 0 = No Preference - 26 1 = Transport Mode Preferred; 0 = No Preference - 27 1 = Perfect Forward Secrecy (PFS) Enabled; - 0 = PFS Disabled - 28 1 = Aggressive Mode Enabled; 0 = Disabled - 29 1 = Main Mode Enabled; 0 = MM Disabled - 30 1 = IKE/IPSec Enabled; 0 = IKE/IPSec Disabled - 31 (Lsb) 1 = Bitmap VALID; 0 = INVALID - All others RESERVED - - - - - - -Tseng, et al. Standards Track [Page 83] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.3.10. Portal ISAKMP Phase-1 Proposals - - This field contains the IKE Phase-1 proposal listing in decreasing - order of preference of the protection suites acceptable to protect - all IKE Phase-2 messages sent and received by the Portal. This - includes Phase-2 SAs from the iSNS client to the iSNS server as well - as to peer iFCP and/or iSCSI devices. This attribute contains the SA - payload, proposal payload(s), and transform payload(s) in the ISAKMP - format defined in [RFC2408]. - - This field should be used if the implementer wishes to define phase-1 - SA security configuration on a per-Portal basis, as opposed to on a - per-Network Entity basis. If the implementer desires to have a - single phase-1 SA security configuration to protect all phase-2 - traffic regardless of the interface used, then the Entity Phase-1 - Proposal (Section 6.2.9) should be used. - -6.3.11. Portal ISAKMP Phase-2 Proposals - - This field contains the IKE Phase-2 proposal, in ISAKMP format - [RFC2408], listing in decreasing order of preference the security - proposals acceptable to protect traffic sent and received by the - Portal. This field is used only if bits 31, 30, and 29 of the - - Security Bitmap (see 6.3.9) are enabled. This attribute contains the - SA payload, proposal payload(s), and associated transform payload(s) - in the ISAKMP format defined in [RFC2408]. - -6.3.12. Portal Certificate - - This attribute contains one or more X.509 certificates that are a - credential of the Portal. This certificate is used to identify and - authenticate communications to the IP address and TCP/UDP Port - supported by the Portal. The format of the X.509 certificate is - specified in [RFC3280]. This certificate MUST contain a Subject Name - with an empty sequence and MUST contain a SubjectAltName extension - encoded with the iPAddress type. The Portal IP Address (Section - 6.3.1) of the identified Portal SHALL be stored in the SubjectAltName - field of the certificate. - -6.4. iSCSI Node-Keyed Attributes - - The following attributes are stored in the iSNS database using the - iSCSI Name attribute as the key. Each set of Node-Keyed attributes - is associated with one Entity Identifier object key. - - Although the iSCSI Name key is associated with one Entity Identifier, - it is unique across the entire iSNS database. - - - -Tseng, et al. Standards Track [Page 84] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.4.1. iSCSI Name - - This is a variable-length UTF-8 encoded NULL-terminated text-based - description of up to 224 bytes. This key attribute is required for - iSCSI Storage Nodes and is provided by the iSNS client. The - registered iSCSI Name MUST conform to the format described in [iSCSI] - for iSCSI Names. The maximum size for an iSCSI Name is 223 bytes. - Including the NULL character and 4-byte alignment (see Section - 5.3.1), the maximum iSCSI Name field size is 224 bytes. - - If an iSCSI Name is registered without an EID key, then a Network - Entity SHALL be created and an EID assigned. The assigned EID SHALL - be returned in the registration response as an operating attribute. - - This field MUST be normalized according to the stringprep template - [STRINGPREP] before it is stored in the iSNS database. - -6.4.2. iSCSI Node Type - - This required 32-bit field is a bitmap indicating the type of iSCSI - Storage Node. The bit positions are defined below. A set bit (1) - indicates that the Node has the corresponding characteristics. - - Bit Position Node Type - ------------ --------- - 29 Control - 30 Initiator - 31 (Lsb) Target - All others RESERVED - - If the Target bit is set to 1, then the Node represents an iSCSI - target. The Target bit MAY be set by iSNS clients using the iSNSP. - - If the Initiator bit is set to 1, then the Node represents an iSCSI - initiator. The Initiator bit MAY be set by iSNS clients using the - iSNSP. - - If the control bit is set to 1, then the Node represents a gateway, a - management station, a backup iSNS server, or another device that is - not an initiator or target, but that requires the ability to send and - receive iSNSP messages, including state change notifications. - Setting the control bit is an administrative task that MUST be - performed on the iSNS server; iSNS clients SHALL NOT be allowed to - change this bit using the iSNSP. - - - - - - - -Tseng, et al. Standards Track [Page 85] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - This field MAY be used by the iSNS server to distinguish among - permissions by different iSCSI Node types for accessing various iSNS - functions. More than one Node Type bit may be simultaneously - enabled. - -6.4.3. iSCSI Node Alias - - This is a variable-length UTF-8 encoded NULL-terminated text-based - description of up to 256 bytes. The Alias is a user-readable - description of the Node entry in the iSNS database. - -6.4.4. iSCSI Node SCN Bitmap - - The iSCSI Node SCN Bitmap indicates events for which the registering - iSNS client wishes to receive a notification message. The following - table displays events that result in notifications, and the bit field - in the SCN Bitmap that, when enabled, results in the corresponding - notification. - - Note that this field is of dual use: it is used in the SCN - registration process to define interested events that will trigger an - SCN message, and it is also contained in each SCN message itself, to - indicate the type of event that triggered the SCN message. A set bit - (1) indicates the corresponding type of SCN. - - Bit Position Flag Description - ------------ ---------------- - 24 INITIATOR AND SELF INFORMATION ONLY - 25 TARGET AND SELF INFORMATION ONLY - 26 MANAGEMENT REGISTRATION/SCN - 27 OBJECT REMOVED - 28 OBJECT ADDED - 29 OBJECT UPDATED - 30 DD/DDS MEMBER REMOVED (Mgmt Reg/SCN only) - 31 (Lsb) DD/DDS MEMBER ADDED (Mgmt Reg/SCN only) - All others RESERVED - - DD/DDS MEMBER REMOVED indicates that an existing member of a - Discovery Domain and/or Discovery Domain Set has been removed. - - DD/DDS MEMBER ADDED indicates that a new member was added to an - existing DD and/or DDS. - - OBJECT REMOVED, OBJECT ADDED, and OBJECT UPDATED indicate a Network - Entity, Portal, Storage Node, FC Device, DD, and/or DDS object was - removed from, added to, or updated in the Discovery Domain or in the - iSNS database (Control Nodes only). - - - - -Tseng, et al. Standards Track [Page 86] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Regular SCNs provide information about objects that are updated in, - added to or removed from Discovery Domains of which the Storage Node - is a member. An SCN or SCN registration is considered a regular SCN - or regular SCN registration if the MANAGEMENT REGISTRATION/SCN flag - is cleared. All iSNS clients may register for regular SCNs. - - Management SCNs provide information about all changes to the network, - regardless of discovery domain membership. Registration for - management SCNs is indicated by setting bit 26 to 1. Only Control - Nodes may register for management SCNs. Bits 30 and 31 may only be - enabled if bit 26 is set to 1. - - TARGET AND SELF INFORMATION ONLY SCNs (bit 25) provides information - only about changes to target devices, or if the iSCSI Storage Node - itself has undergone a change. Similarly, INITIATOR AND SELF - INFORMATION ONLY SCNs (bit 24) provides information only about - changes to initiator Nodes, or to the target itself. - -6.4.5. iSCSI Node Index - - The iSCSI Node Index is a 4-byte non-zero integer value used as a key - that uniquely identifies each iSCSI Storage Node registered in the - iSNS database. Upon initial registration of the iSCSI Storage Node, - the iSNS server assigns an unused value for the iSCSI Node Index. - Each iSCSI Node MUST be assigned a value for the iSCSI Node Index - that is not assigned to any other iSCSI Storage Node. Furthermore, - iSCSI Node Index values for recently deregistered iSCSI Storage Nodes - SHOULD NOT be reused in the short term. - - The iSCSI Node Index may be used as a key to represent a registered - Node in situations where the iSCSI Name is too long to be used as a - key. An example of this is when SNMP is used for management, as - described in Section 2.10. - - The value assigned for the iSCSI Node Index SHALL persist as long as - the iSCSI Storage Node is registered in the iSNS database or a member - of a Discovery Domain. An iSCSI Node Index value that is assigned - for a Storage Node SHALL NOT be used for any other Storage Node as - long as the original node is registered in the iSNS database or a - member of a Discovery Domain. - -6.4.6. WWNN Token - - This field contains a globally unique 64-bit integer value that can - be used to represent the World Wide Node Name of the iSCSI device in - a Fibre Channel fabric. This identifier is used during the device - registration process and MUST conform to the requirements in [FC-FS]. - - - - -Tseng, et al. Standards Track [Page 87] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - The FC-iSCSI gateway uses the value found in this field to register - the iSCSI device in the Fibre Channel name server. It is stored in - the iSNS server to prevent conflict when "proxy" WWNN values are - assigned to iSCSI initiators establishing storage sessions to devices - in the FC fabric. - - If the iSNS client does not assign a value for WWNN Token, then the - iSNS server SHALL provide a value for this field upon initial - registration of the iSCSI Storage Node. The process by which the - WWNN Token is assigned by the iSNS server MUST conform to the - following requirements: - - 1. The assigned WWNN Token value MUST be unique among all WWN - entries in the existing iSNS database, and among all devices that - can potentially be registered in the iSNS database. - - 2. Once the value is assigned, the iSNS server MUST persistently - save the mapping between the WWNN Token value and registered - iSCSI Name. That is, successive re-registrations of the iSCSI - Storage Node keyed by the same iSCSI Name maintain the original - mapping to the associated WWNN Token value in the iSNS server. - Similarly, the mapping SHALL be persistent across iSNS server - reboots. Once assigned, the mapping can only be changed if a - DevAttrReg message from an authorized iSNS client explicitly - provides a different WWNN Token value. - - 3. Once a WWNN Token value has been assigned and mapped to an iSCSI - name, that WWNN Token value SHALL NOT be reused or mapped to any - other iSCSI name. - - 4. The assigned WWNN Token value MUST conform to the formatting - requirements of [FC-FS] for World Wide Names (WWNs). - - An iSNS client, such as an FC-iSCSI gateway or the iSCSI initiator, - MAY register its own WWNN Token value or overwrite the iSNS Server- - supplied WWNN Token value, if it wishes to supply its own iSCSI-FC - name mapping. This is accomplished using the DevAttrReg message with - the WWNN Token (tag=37) as an operating attribute. Once overwritten, - the new WWNN Token value MUST be stored and saved by the iSNS server, - and all requirements specified above continue to apply. If an iSNS - client attempts to register a value for this field that is not unique - in the iSNS database or that is otherwise invalid, then the - registration SHALL be rejected with an Status Code of 3 (Invalid - Registration). - - - - - - - -Tseng, et al. Standards Track [Page 88] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - There MAY be matching records in the iSNS database for the Fibre - Channel device specified by the WWNN Token. These records may - contain device attributes for that FC device registered in the Fibre - Channel fabric name server. - -6.4.7. iSCSI Node Next Index - - This is a virtual attribute containing a 4-byte integer value that - indicates the next available (i.e., unused) iSCSI Node Index value. - This attribute may only be queried; the iSNS server SHALL return an - error code of 3 (Invalid Registration) to any client that attempts to - register a value for this attribute. A Message Key is not required - when exclusively querying for this attribute. - - The iSCSI Node Next Index MAY be used by an SNMP client to create an - entry in the iSNS server. SNMP requirements are described in Section - 2.10. - -6.4.8. iSCSI AuthMethod - - This attribute contains a NULL-terminated string of UTF-8 text - listing the iSCSI authentication methods enabled for this iSCSI - Storage Node, in order of preference. The text values used to - identify iSCSI authentication methods are embedded in this string - attribute and delineated by a comma. The text values are identical - to those found in the main iSCSI document [iSCSI]; additional - vendor-specific text values are also possible. - - Text Value Description Reference - ---------- ----------- --------- - KB5 Kerberos V5 [RFC1510] - SPKM1 Simple Public Key GSS-API [RFC2025] - SPKM2 Simple Public Key GSS-API [RFC2025] - SRP Secure Remote Password [RFC2945] - CHAP Challenge Handshake Protocol [RFC1994] - none No iSCSI Authentication - -6.5. Portal Group (PG) Object-Keyed Attributes - - The following attributes are used to associate Portal and iSCSI - Storage Node objects. PG objects are stored in the iSNS database - using the PG iSCSI Name, the PG Portal IP Address, and the PG Portal - TCP/UDP Port as keys. New PG objects are implicitly or explicitly - created at the time that the corresponding Portal and/or iSCSI - Storage Node objects are registered. Section 3.4 has a general - discussion of PG usage. For further details on use of Portal Groups, - see [iSCSI]. - - - - -Tseng, et al. Standards Track [Page 89] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.5.1. Portal Group iSCSI Name - - This is the iSCSI Name for the iSCSI Storage Node that is associated - with the PG object. This name MAY represent an iSCSI Storage Node - not currently registered in the server. - -6.5.2. PG Portal IP Addr - - This is the Portal IP Address attribute for the Portal that is - associated with the PG object. This Portal IP Address MAY be that of - a Portal that is not currently registered in the server. - -6.5.3. PG Portal TCP/UDP Port - - This is the Portal TCP/UDP Port attribute for the Portal that is - associated with the PG object. This Portal TCP/UDP Port MAY be that - of a Portal that is not currently registered in the server. - -6.5.4. Portal Group Tag (PGT) - - This field is used to group Portals in order to coordinate - connections in a session across Portals to a specified iSCSI Node. - The PGT is a value in the range of 0-65535, or NULL. A NULL PGT - value is registered by using 0 for the length in the TLV during - registration. The two least significant bytes of the value contain - the PGT for the object. The two most significant bytes are reserved. - If a PGT value is not explicitly registered for an iSCSI Storage Node - and Portal pair, then the PGT value SHALL be implicitly registered as - 0x00000001. - -6.5.5. Portal Group Index - - The PG Index is a 4-byte non-zero integer value used as a key that - uniquely identifies each PG object registered in the iSNS database. - Upon initial registration of a PG object, the iSNS server MUST assign - an unused value for the PG Index. Furthermore, PG Index values for - recently deregistered PG objects SHOULD NOT be reused in the short - term. - - The PG Index MAY be used as the key to reference a registered PG in - situations where a unique index for each PG object is required. It - MAY also be used as the message key in an iSNS message to query or - update a pre-existing PG object. An example of this is when SNMP is - used for management, as described in Section 2.10. The value - assigned for the PG Index SHALL persist as long as the server is - active. - - - - - -Tseng, et al. Standards Track [Page 90] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.5.6. Portal Group Next Index - - The PG Next Index is a virtual attribute containing a 4-byte integer - value that indicates the next available (i.e., unused) PG Index - value. This attribute may only be queried; the iSNS server SHALL - return an error code of 3 (Invalid Registration) to any client that - attempts to register a value for this attribute. A Message Key is - not required when exclusively querying for this attribute. - - The Portal Group Next Index MAY be used by an SNMP client to create - an entry in the iSNS server. SNMP requirements are described in - Section 2.10. - -6.6. FC Port Name-Keyed Attributes - - The following attributes are registered in the iSNS database using - the FC Port World Wide Name (WWPN) attribute as the key. Each set of - FC Port-Keyed attributes is associated with one Entity Identifier - object key. - - Although the FC Port World Wide Name is associated with one Entity - Identifier, it is also globally unique. - -6.6.1. FC Port Name (WWPN) - - This 64-bit identifier uniquely defines the FC Port, and it is the - World Wide Port Name (WWPN) of the corresponding Fibre Channel - device. This attribute is the key for the iFCP Storage Node. This - globally unique identifier is used during the device registration - process, and it uses a value conforming to IEEE EUI-64 [EUI-64]. - -6.6.2. Port ID (FC_ID) - - The Port Identifier is a Fibre Channel address identifier assigned to - an N_Port or NL_Port during fabric login. The format of the Port - Identifier is defined in [FC-FS]. The least significant 3 bytes - contain this address identifier. The most significant byte is - RESERVED. - - - - - - - - - - - - - -Tseng, et al. Standards Track [Page 91] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.6.3. FC Port Type - - Indicates the type of FC port. Encoded values for this field are - listed in the following table: - - Type Description - ---- ----------- - 0x0000 Unidentified/Null Entry - 0x0001 Fibre Channel N_Port - 0x0002 Fibre Channel NL_Port - 0x0003 Fibre Channel F/NL_Port - 0x0004-0080 RESERVED - 0x0081 Fibre Channel F_Port - 0x0082 Fibre Channel FL_Port - 0x0083 RESERVED - 0x0084 Fibre Channel E_Port - 0x0085-00FF RESERVED - 0xFF11 RESERVED - 0xFF12 iFCP Port - 0xFF13-FFFF RESERVED - -6.6.4. Symbolic Port Name - - This is a variable-length UTF-8 encoded NULL-terminated text-based - description of up to 256 bytes that is associated with the iSNS- - registered FC Port Name in the network. - -6.6.5. Fabric Port Name (FWWN) - - This 64-bit identifier uniquely defines the fabric port. If the port - of the FC Device is attached to a Fibre Channel fabric port with a - registered Port Name, then that fabric Port Name SHALL be indicated - in this field. - -6.6.6. Hard Address - - This field is the requested hard address 24-bit NL Port Identifier, - included in the iSNSP for compatibility with Fibre Channel Arbitrated - Loop devices and topologies. The least significant 3 bytes of this - field contain the address. The most significant byte is RESERVED. - -6.6.7. Port IP Address - - The Fibre Channel IP address associated with the FC Port. When this - field contains an IPv4 value, it is stored as an IPv4-mapped IPv6 - address. That is, the most significant 10 bytes are set to 0x00, - with the next two bytes set to 0xFFFF [RFC2373]. When an IPv6 value - is contained in this field, then the entire 16-byte field is used. - - - -Tseng, et al. Standards Track [Page 92] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.6.8. Class of Service (COS) - - This 32-bit bit-map field indicates the Fibre Channel Class of - Service types that are supported by the registered port. In the - following table, a set bit (1) indicates a Class of Service - supported. - - Bit Position Description - ------------ ----------- - 29 Fibre Channel Class 2 Supported - 28 Fibre Channel Class 3 Supported - -6.6.9. FC-4 Types - - This 32-byte field indicates the FC-4 protocol types supported by the - associated port. This field can be used to support Fibre Channel - devices and is consistent with FC-GS-4. - -6.6.10. FC-4 Descriptor - - This is a variable-length UTF-8 encoded NULL-terminated text-based - description of up to 256 bytes that is associated with the iSNS- - registered device port in the network. This field can be used to - support Fibre Channel devices and is consistent with FC-GS-4. - -6.6.11. FC-4 Features - - This is a 128-byte array, 4 bits per type, for the FC-4 protocol - types supported by the associated port. This field can be used to - support Fibre Channel devices and is consistent with FC-GS-4. - -6.6.12. iFCP SCN Bitmap - - This field indicates the events the iSNS client is interested in. - These events can cause SCNs to be generated. SCNs provide - information about objects that are updated in, added to or removed - from Discovery Domains of which the source and destination are a - member. Management SCNs provide information about all changes to the - network. A set bit (1) indicates the type of SCN for the bitmap as - follows: - - - - - - - - - - - -Tseng, et al. Standards Track [Page 93] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Bit Position Flag Description - ------------ ---------------- - 24 INITIATOR AND SELF INFORMATION ONLY - 25 TARGET AND SELF INFORMATION ONLY - 26 MANAGEMENT REGISTRATION/SCN - 27 OBJECT REMOVED - 28 OBJECT ADDED - 29 OBJECT UPDATED - 30 DD/DDS MEMBER REMOVED (Mgmt Reg/SCN only) - 31 (Lsb) DD/DDS MEMBER ADDED (Mgmt Reg/SCN only) - All others RESERVED - - Further information on the use of the bit positions specified above - can be found in Section 6.4.4. - -6.6.13. Port Role - - This required 32-bit field is a bitmap indicating the type of iFCP - Storage Node. The bit fields are defined below. A set bit indicates - the Node has the corresponding characteristics. - - Bit Position Node Type - ------------ --------- - 29 Control - 30 FCP Initiator - 31 (Lsb) FCP Target - All Others RESERVED - - If the 'Target' bit is set to 1, then the port represents an FC - target. Setting of the 'Target' bit MAY be performed by iSNS clients - using the iSNSP. - - If the 'Initiator' bit is set to 1, then the port represents an FC - initiator. Setting of the 'Initiator' bit MAY be performed by iSNS - clients using the iSNSP. - - If the 'Control' bit is set to 1, then the port represents a gateway, - a management station, an iSNS backup server, or another device. - - This is usually a special device that is neither an initiator nor a - target, which requires the ability to send and receive iSNSP - messages, including state-change notifications. Setting the control - bit is an administrative task that MUST be administratively - configured on the iSNS server; iSNS clients SHALL NOT be allowed to - change this bit using the iSNSP. - - - - - - -Tseng, et al. Standards Track [Page 94] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - This field MAY be used by the iSNS server to distinguish among - permissions by different iSNS clients. For example, an iSNS server - implementation may be administratively configured to allow only - targets to receive ESIs, or to permit only Control Nodes to add, - modify, or delete discovery domains. - -6.6.14. Permanent Port Name (PPN) - - The Permanent Port Name can be used to support Fibre Channel devices - and is consistent with the PPN description in FC-GS-4 [FC-GS-4]. The - format of the PPN is identical to the FC Port Name WWPN attribute - format. - -6.7. Node-Keyed Attributes - - The following attributes are registered in the iSNS database using - the FC Node Name (WWNN) attribute as the key. Each set of FC Node- - Keyed attributes represents a single device and can be associated - with many FC Ports. - - The FC Node Name is unique across the entire iSNS database. - -6.7.1. FC Node Name (WWNN) - - The FC Node Name is a 64-bit identifier that is the World Wide Node - Name (WWNN) of the corresponding Fibre Channel device. This - attribute is the key for the FC Device. This globally unique - identifier is used during the device registration process, and it - uses a value conforming to IEEE EUI-64 [EUI-64]. - -6.7.2. Symbolic Node Name - - This is a variable-length UTF-8 encoded NULL-terminated text-based - description of up to 256 bytes that is associated with the iSNS- - registered FC Device in the network. - -6.7.3. Node IP Address - - This IP address is associated with the device Node in the network. - This field is included for compatibility with Fibre Channel. When - this field contains an IPv4 value, it is stored as an IPv4-mapped - IPv6 address. That is, the most significant 10 bytes are set to - 0x00, with the next two bytes set to 0xFFFF [RFC2373]. When an IPv6 - value is contained in this field, the entire 16-byte field is used. - - - - - - - -Tseng, et al. Standards Track [Page 95] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.7.4. Node IPA - - This field is the 8-byte Fibre Channel Initial Process Associator - (IPA) associated with the device Node in the network. The initial - process associator is used for communication between Fibre Channel - devices. - -6.7.5. Proxy iSCSI Name - - This is a variable-length UTF-8 encoded NULL-terminated text-based - field that contains the iSCSI Name used to represent the FC Node in - the IP network. It is used as a pointer to the matching iSCSI Name - entry in the iSNS server. Its value is usually registered by an FC- - iSCSI gateway connecting the IP network to the fabric containing the - FC device. - - Note that if this field is used, there SHOULD be a matching entry in - the iSNS database for the iSCSI device specified by the iSCSI name. - The database entry should include the full range of iSCSI attributes - needed for discovery and management of the "iSCSI proxy image" of the - FC device. - -6.8. Other Attributes - - The following are not attributes of the previously-defined objects. - -6.8.1. FC-4 Type Code - - This is a 4-byte field used to provide a FC-4 type during a FC-4 Type - query. The FC-4 types are consistent with the FC-4 Types as defined - in FC-FS. Byte 0 contains the FC-4 type. All other bytes are - reserved. - -6.8.2. iFCP Switch Name - - The iFCP Switch Name is a 64-bit World Wide Name (WWN) identifier - that uniquely identifies a distinct iFCP gateway in the network. - This globally unique identifier is used during the switch - registration/FC_DOMAIN_ID assignment process. The iFCP Switch Name - value used MUST conform to the requirements stated in [FC-FS] for - World Wide Names. The iSNS server SHALL track the state of all - FC_DOMAIN_ID values that have been allocated to each iFCP Switch - Name. If a given iFCP Switch Name is deregistered from the iSNS - database, then all FC_DOMAIN_ID values allocated to that iFCP Switch - Name SHALL be returned to the unused pool of values. - - - - - - -Tseng, et al. Standards Track [Page 96] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.8.3. iFCP Transparent Mode Commands - -6.8.3.1. Preferred ID - - This is a 4-byte unsigned integer field, and it is the requested - value that the iSNS client wishes to use for the FC_DOMAIN_ID. The - iSNS server SHALL grant the iSNS client the use of the requested - value as the FC_DOMAIN_ID, if the requested value has not already - been allocated. If the requested value is not available, the iSNS - server SHALL return a different value that has not been allocated. - -6.8.3.2. Assigned ID - - This is a 4-byte unsigned integer field that is used by an iFCP - gateway to reserve its own unique FC_DOMAIN_ID value from the range 1 - to 239. When a FC_DOMAIN_ID is no longer required, it SHALL be - released by the iFCP gateway using the RlseDomId message. The iSNS - server MUST use the Entity Status Inquiry message to determine - whether an iFCP gateway is still present on the network. - -6.8.3.3. Virtual_Fabric_ID - - This is a variable-length UTF-8 encoded NULL-terminated text-based - field of up to 256 bytes. The Virtual_Fabric_ID string is used as a - key attribute to identify a range of non-overlapping FC_DOMAIN_ID - values to be allocated using RqstDomId. Each Virtual_Fabric_ID - string submitted by an iSNS client SHALL have its own range of non- - overlapping FC_DOMAIN_ID values to be allocated to iSNS clients. - - -6.9. iSNS Server-Specific Attributes - - Access to the following attributes may be administratively - controlled. These attributes are specific to the iSNS server - instance; the same value is returned for all iSNS clients accessing - the iSNS server. Only query messages may be performed on these - attributes. Attempted registrations of values for these attributes - SHALL return a status code of 3 (Invalid Registration). - - A query for an iSNS Server-Specific attribute MUST contain the - identifying key attribute (i.e., iSCSI Name or FC Port Name WWPN) of - the Node originating the registration or query message as the Source - and Message Key attributes. The Operating Attributes are the - server-specific attributes being registered or queried. - - - - - - - -Tseng, et al. Standards Track [Page 97] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.9.1. iSNS Server Vendor OUI - - This attribute is the OUI (Organizationally Unique Identifier) - [802-1990] identifying the specific vendor implementing the iSNS - server. This attribute can only be queried; iSNS clients SHALL NOT be - allowed to register a value for the iSNS Server Vendor OUI. - -6.10. Vendor-Specific Attributes - - iSNS server implementations MAY define vendor-specific attributes for - private use. These attributes MAY be used to store optional data - that is registered and/or queried by iSNS clients in order to gain - optional capabilities. Note that any implementation of vendor- - specific attributes in the iSNS server SHALL NOT impose any form of - mandatory behavior on the part of the iSNS client. - - The tag values used for vendor-specific and user-specific use are - defined in Section 6.1. To avoid misinterpreting proprietary - attributes, the vendor's own OUI (Organizationally Unique Identifier) - MUST be placed in the upper three bytes of the attribute value field - itself. - - The OUI is defined in IEEE Std 802-1990 and is the same constant used - to generate 48 bit Universal LAN MAC addresses. A vendor's own iSNS - implementation will then be able to recognize the OUI in the - attribute field and be able to execute vendor-specific handling of - the attribute. - -6.10.1. Vendor-Specific Server Attributes - - Attributes with tags in the range 257 to 384 are vendor-specific or - site-specific attributes of the iSNS server. Values for these - attributes are administratively set by the specific vendor providing - the iSNS server implementation. Query access to these attributes may - be administratively controlled. These attributes are unique for each - logical iSNS server instance. Query messages for these attributes - SHALL use the key identifier (i.e., iSCSI Name or FC Port Name WWPN) - for both the Source attribute and Message Key attribute. These - attributes can only be queried; iSNS clients SHALL NOT be allowed to - register a value for server attributes. - -6.10.2. Vendor-Specific Entity Attributes - - Attributes in the range 385 to 512 are vendor-specific or site- - specific attributes used to describe the Network Entity object. - These attributes are keyed by the Entity Identifier attribute - (tag=1). - - - - -Tseng, et al. Standards Track [Page 98] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.10.3. Vendor-Specific Portal Attributes - - Attributes in the range 513 to 640 are vendor-specific or site- - specific attributes used to describe the Portal object. These - attributes are keyed by the Portal IP-Address (tag=16) and Portal - TCP/UDP Port (tag=17). - -6.10.4. Vendor-Specific iSCSI Node Attributes - - Attributes in the range 641 to 768 are vendor-specific or site- - specific attributes used to describe the iSCSI Node object. These - attributes are keyed by the iSCSI Name (tag=32). - -6.10.5. Vendor-Specific FC Port Name Attributes - - Attributes in the range 769 to 896 are vendor-specific or site- - specific attributes used to describe the N_Port Port Name object. - These attributes are keyed by the FC Port Name WWPN (tag=64). - -6.10.6. Vendor-Specific FC Node Name Attributes - - Attributes in the range 897 to 1024 are vendor-specific or site- - specific attributes used to describe the FC Node Name object. These - attributes are keyed by the FC Node Name WWNN (tag=96). - -6.10.7. Vendor-Specific Discovery Domain Attributes - - Attributes in the range 1025 to 1280 are vendor-specific or site- - specific attributes used to describe the Discovery Domain object. - These attributes are keyed by the DD_ID (tag=104). - -6.10.8. Vendor-Specific Discovery Domain Set Attributes - - Attributes in the range 1281 to 1536 are vendor-specific or site- - specific attributes used to describe the Discovery Domain Set object. - These attributes are keyed by the DD Set ID (tag=101) - -6.10.9. Other Vendor-Specific Attributes - - Attributes in the range 1537 to 2048 can be used for key and non-key - attributes that describe new vendor-specific objects specific to the - vendor's iSNS server implementation. - - - - - - - - - -Tseng, et al. Standards Track [Page 99] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.11. Discovery Domain Registration Attributes - -6.11.1. DD Set ID Keyed Attributes - -6.11.1.1. Discovery Domain Set ID (DDS ID) - - The DDS ID is an unsigned non-zero integer identifier used in the - iSNS directory database as a key to indicate a Discovery Domain Set - uniquely. A DDS is a collection of Discovery Domains that can be - enabled or disabled by a management station. This value is used as a - key for DDS attribute queries. When a Discovery Domain is - registered, it is initially not in any DDS. - - If the iSNS client does not provide a DDS_ID in a DDS registration - request message, the iSNS server SHALL generate a DDS_ID value that - is unique within the iSNS database for that new DDS. The created DDS - ID SHALL be returned in the response message. The DDS ID value of 0 - is reserved, and the DDS ID value of 1 is used for the default DDS - (see Section 2.2.2). - -6.11.1.2. Discovery Domain Set Symbolic Name - - A variable-length UTF-8 encoded NULL-terminated text-based field of - up to 256 bytes. This is a user-readable field used to assist a - network administrator in tracking the DDS function. When a client - registers a DDS symbolic name, the iSNS server SHALL verify it is - unique. If the name is not unique, then the DDS registration SHALL - be rejected with an "Invalid Registration" Status Code. The invalid - attribute(s), in this case the DDS symbolic name, SHALL be included - in the response. - -6.11.1.3. Discovery Domain Set Status - - The DDS_Status field is a 32-bit bitmap indicating the status of the - DDS. Bit 0 of the bitmap indicates whether the DDS is Enabled (1) or - Disabled (0). The default value for the DDS Enabled flag is Disabled - (0). - - Bit Position DDS Status - ------------ --------- - 31 (Lsb) DDS Enabled (1) / DDS Disabled (0) - All others RESERVED - -6.11.1.4. Discovery Domain Set Next ID - - This is a virtual attribute containing a 4-byte integer value that - indicates the next available (i.e., unused) Discovery Domain Set - Index value. This attribute may only be queried; the iSNS server - - - -Tseng, et al. Standards Track [Page 100] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - SHALL return an error code of 3 (Invalid Registration) to any client - that attempts to register a value for this attribute. A Message Key - is not required when exclusively querying for this attribute. - - The Discovery Domain Set Next Index MAY be used by an SNMP client to - create an entry in the iSNS server. SNMP requirements are described - in Section 2.10. - -6.11.2. DD ID Keyed Attributes - -6.11.2.1. Discovery Domain ID (DD ID) - - The DD ID is an unsigned non-zero integer identifier used in the iSNS - directory database as a key to identify a Discovery Domain uniquely. - This value is used as the key for any DD attribute query. If the - iSNS client does not provide a DD_ID in a DD registration request - message, the iSNS server SHALL generate a DD_ID value that is unique - within the iSNS database for that new DD (i.e., the iSNS client will - be registered in a new DD). The created DD ID SHALL be returned in - the response message. The DD ID value of 0 is reserved, and the DD - ID value of 1 is used for the default DD (see Section 2.2.2). - -6.11.2.2. Discovery Domain Symbolic Name - - A variable-length UTF-8 encoded NULL-terminated text-based field of - up to 256 bytes. When a client registers a DD symbolic name, the - iSNS server SHALL verify it is unique. If the name is not unique, - then the DD registration SHALL be rejected with an "Invalid - Registration" Status Code. The invalid attribute(s), in this case - the DD symbolic name, SHALL be included in the response. - -6.11.2.3. Discovery Domain Member: iSCSI Node Index - - This is the iSCSI Node Index of a Storage Node that is a member of - the DD. The DD may have a list of 0 to n members. The iSCSI Node - Index is one alternative representation of membership in a Discovery - Domain, the other alternative being the iSCSI Name. The Discovery - Domain iSCSI Node Index is a 4-byte non-zero integer value. - - The iSCSI Node Index can be used to represent a DD member in - situations where the iSCSI Name is too long to be used. An example - of this is when SNMP is used for management, as described in Section - 2.10. - - The iSCSI Node Index and the iSCSI Name stored as a member in a DD - SHALL be consistent with the iSCSI Node Index and iSCSI Name - attributes registered for the Storage Node object in the iSNS server. - - - - -Tseng, et al. Standards Track [Page 101] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -6.11.2.4. Discovery Domain Member: iSCSI Name - - A variable-length UTF-8 encoded NULL-terminated text-based field of - up to 224 bytes. It indicates membership for the specified iSCSI - Storage Node in the Discovery Domain. Note that the referenced - Storage Node does not need to be actively registered in the iSNS - database before the iSNS client uses this attribute. There is no - limit to the number of members that may be in a DD. Membership is - represented by the iSCSI Name of the iSCSI Storage Node. - -6.11.2.5. Discovery Domain Member: FC Port Name - - This 64-bit identifier attribute indicates membership for an iFCP - Storage Node (FC Port) in the Discovery Domain. Note that the - referenced Storage Node does not need to be actively registered in - the iSNS database before the iSNS client uses this attribute. There - is no limit to the number of members that may be in a DD. Membership - is represented by the FC Port Name (WWPN) of the iFCP Storage Node. - -6.11.2.6. Discovery Domain Member: Portal Index - - This attribute indicates membership in the Discovery Domain for a - Portal. It is an alternative representation for Portal membership to - the Portal IP Address and Portal TCP/UDP Port. The referenced Portal - MUST be actively registered in the iSNS database before the iSNS - client uses this attribute. - -6.11.2.7. Discovery Domain Member: Portal IP Address - - This attribute and the Portal TCP/UDP Port attribute indicate - membership in the Discovery Domain for the specified Portal. Note - that the referenced Portal does not need to be actively registered in - the iSNS database before the iSNS client uses this attribute. - -6.11.2.8. Discovery Domain Member: Portal TCP/UDP Port - - This attribute and the Portal IP Address attribute indicate - membership in the Discovery Domain for the specified Portal. Note - that the referenced Portal does not need to be actively registered in - the iSNS database before the iSNS client uses this attribute. - -6.11.2.9. Discovery Domain Features - - The Discovery Domain Features is a bitmap indicating the features of - this DD. The bit positions are defined below. A bit set to 1 - indicates the DD has the corresponding characteristics. - - - - - -Tseng, et al. Standards Track [Page 102] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Bit Position DD Feature - ------------ ---------- - 31 (Lsb) Boot List Enabled (1)/Boot List Disabled (0) - All others RESERVED - - Boot List: this feature indicates that the target(s) in this DD - provides boot capabilities for the member initiators, as described in - [iSCSI-boot]. - -6.11.2.10. Discovery Domain Next ID - - This is a virtual attribute containing a 4-byte integer value that - indicates the next available (i.e., unused) Discovery Domain Index - value. This attribute may only be queried; the iSNS server SHALL - return an error code of 3 (Invalid Registration) to any client that - attempts to register a value for this attribute. A Message Key is - not required when exclusively querying for this attribute. - -7. Security Considerations - -7.1. iSNS Security Threat Analysis - - When the iSNS protocol is deployed, the interaction between iSNS - server and iSNS clients is subject to the following security threats: - - a) An attacker could alter iSNS protocol messages, such as to direct - iSCSI and iFCP devices to establish connections with rogue peer - devices, or to weaken/eliminate IPSec protection for iSCSI or - iFCP traffic. - - b) An attacker could masquerade as the real iSNS server using false - iSNS heartbeat messages. This could cause iSCSI and iFCP devices - to use rogue iSNS servers. - - c) An attacker could gain knowledge about iSCSI and iFCP devices by - snooping iSNS protocol messages. Such information could aid an - attacker in mounting a direct attack on iSCSI and iFCP devices, - such as a denial-of-service attack or outright physical theft. - - To address these threats, the following capabilities are needed: - - a) Unicast iSNS protocol messages may need to be authenticated. In - addition, to protect against threat c), confidentiality support - is desirable and is REQUIRED when certain functions of iSNS - server are utilized. - - - - - - -Tseng, et al. Standards Track [Page 103] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - b) Multicast iSNS protocol messages such as the iSNS heartbeat - message may need to be authenticated. These messages need not be - confidential since they do not leak critical information. - -7.2. iSNS Security Implementation and Usage Requirements - - If the iSNS server is used to distribute authorizations for - communications between iFCP and iSCSI peer devices, IPsec ESP with - null transform MUST be implemented, and non-null transform MAY be - implemented. If a non-null transform is implemented, then the DES - encryption algorithm SHOULD NOT be used. - - If the iSNS server is used to distribute security policy for iFCP and - iSCSI devices, then authentication, data integrity, and - confidentiality MUST be supported and used. Where confidentiality is - desired or required, IPSec ESP with non-null transform SHOULD be - used, and the DES encryption algorithm SHOULD NOT be used. - - If the iSNS server is used to provide the boot list for clients, as - described in Section 6.11.2.9, then the iSCSI boot client SHOULD - implement a secure iSNS connection. - - In order to protect against an attacker masquerading as an iSNS - server, client devices MUST support the ability to authenticate - broadcast or multicast messages such as the iSNS heartbeat. The iSNS - authentication block (which is identical in format to the SLP - authentication block) SHALL be used for this purpose. iSNS clients - MUST implement the iSNS authentication block and MUST support BSD - value 0x002. If the iSNS server supports broadcast or multicast iSNS - messages (i.e., the heartbeat), then the server MUST implement the - iSNS authentication block and MUST support BSD value 0x002. Note - that the authentication block is used only for iSNS broadcast or - multicast messages and MUST NOT be used in unicast iSNS messages. - - There is no requirement that the communicating identities in iSNS - protocol messages be kept confidential. Specifically, the identity - and location of the iSNS server is not considered confidential. - - For protecting unicast iSNS protocol messages, iSNS servers - supporting security MUST implement ESP in tunnel mode and MAY - implement transport mode. - - All iSNS implementations supporting security MUST support the replay - protection mechanisms of IPsec. - - iSNS security implementations MUST support both IKE Main Mode and - Aggressive Mode for authentication, negotiation of security - associations, and key management, using the IPSec DOI [RFC2407]. - - - -Tseng, et al. Standards Track [Page 104] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - Manual keying SHOULD NOT be used since it does not provide the - necessary rekeying support. Conforming iSNS security implementations - MUST support authentication using a pre-shared key, and MAY support - certificate-based peer authentication using digital signatures. Peer - authentication using the public key encryption methods outlined in - IKEs Sections 5.2 and 5.3 [RFC2409] SHOULD NOT be supported. - - Conforming iSNS implementations MUST support both IKE Main Mode and - Aggressive Mode. IKE Main Mode with pre-shared key authentication - SHOULD NOT be used when either of the peers use dynamically assigned - IP addresses. Although Main Mode with pre-shared key authentication - offers good security in many cases, situations where dynamically - assigned addresses are used force the use of a group pre-shared key, - which is vulnerable to man-in-the-middle attack. IKE Identity - Payload ID_KEY_ID MUST NOT be used. - - When digital signatures are used for authentication, either IKE Main - Mode or IKE Aggressive Mode MAY be used. In all cases, access to - locally stored secret information (pre-shared key or private key for - digital signing) MUST be suitably restricted, since compromise of the - secret information nullifies the security properties of the IKE/IPsec - protocols. - - When digital signatures are used to achieve authentication, an IKE - negotiator SHOULD use IKE Certificate Request Payload(s) to specify - the certificate authority (or authorities) that are trusted in - accordance with its local policy. IKE negotiators SHOULD check the - pertinent Certificate Revocation List (CRL) before accepting a PKI - certificate for use in IKE's authentication procedures. - - When the iSNS server is used without security, IP block storage - protocol implementations MUST support a negative cache for - authentication failures. This allows implementations to avoid - continually contacting discovered endpoints that fail authentication - within IPsec or at the application layer (in the case of iSCSI - Login). The negative cache need not be maintained within the IPsec - implementation, but rather within the IP block storage protocol - implementation. - -7.3. Discovering Security Requirements of Peer Devices - - Once communication between iSNS clients and the iSNS server has been - secured through use of IPSec, the iSNS client devices have the - capability to discover the security settings that they need to use - for their peer-to-peer communications using the iSCSI and/or iFCP - protocols. This provides a potential scaling advantage over device- - by-device configuration of individual security policies for each - iSCSI and iFCP device. - - - -Tseng, et al. Standards Track [Page 105] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - The iSNS server stores security settings for each iSCSI and iFCP - device interface. These security settings, which can be retrieved by - authorized hosts, include use or non-use of IPSec, IKE, Main Mode, - and Aggressive Mode. For example, IKE may not be enabled for a - particular interface of a peer device. If a peer device can learn of - this in advance by consulting the iSNS server, it will not need to - waste time and resources attempting to initiate an IKE phase 1 - session with that peer device interface. - - If iSNS is used for this purpose, then the minimum information that - should be learned from the iSNS server is the use or non-use of IKE - and IPSec by each iFCP or iSCSI peer device interface. This - information is encoded in the Security Bitmap field of each Portal of - the peer device, and is applicable on a per-interface basis for the - peer device. iSNS queries for acquiring security configuration data - about peer devices MUST be protected by IPSec/ESP authentication. - -7.4. Configuring Security Policies of iFCP/iSCSI Devices - - Use of iSNS for distribution of security policies offers the - potential to reduce the burden of manual device configuration, and to - decrease the probability of communications failures due to - incompatible security policies. If iSNS is used to distribute - security policies, then IPSec authentication, data integrity, and - confidentiality MUST be used to protect all iSNS protocol messages. - - The complete IKE/IPSec configuration of each iFCP and/or iSCSI device - can be stored in the iSNS server, including policies that are used - for IKE Phase 1 and Phase 2 negotiations between client devices. The - IKE payload format includes a series of one or more proposals that - the iSCSI or iFCP device will use when negotiating the appropriate - IPsec policy to use to protect iSCSI or iFCP traffic. - - In addition, the iSCSI Authentication Methods used by each iSCSI - device can also be stored in the iSNS server. The iSCSI AuthMethod - field (tag=42) contains a null-terminated string embedded with the - text values indicating iSCSI authentication methods to be used by - that iSCSI device. - - Note that iSNS distribution of security policy is not necessary if - the security settings can be determined by other means, such as - manual configuration or IPsec security policy distribution. If a - network entity has already obtained its security configuration via - other mechanisms, then it MUST NOT request security policy via iSNS. - - - - - - - -Tseng, et al. Standards Track [Page 106] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -7.5. Resource Issues - - The iSNS protocol is lightweight and will not generate a significant - amount of traffic. iSNS traffic is characterized by occasional - registration, notification, and update messages that do not consume - significant amounts of bandwidth. Even software-based IPSec - implementations should not have a problem handling the traffic loads - generated by the iSNS protocol. - - To fulfill iSNS security requirements, the only additional resources - needed beyond what is already required for iSCSI and iFCP involve the - iSNS server. Because iSCSI and iFCP end nodes are already required - to implement IKE and IPSec, these existing requirements can also be - used to fulfill IKE and IPSec requirements for iSNS clients. - -7.6. iSNS Interaction with IKE and IPSec - - When IPSec security is enabled, each iSNS client with at least one - Storage Node that is registered in the iSNS database SHALL maintain - at least one phase-1 security association with the iSNS server. All - iSNS protocol messages between iSNS clients and the iSNS server SHALL - be protected by a phase-2 security association. - - When a Network Entity is removed from the iSNS database, the iSNS - server SHALL send a phase-1 delete message to the associated iSNS - client IKE peer, and tear down all phase-1 and phase-2 SAs associated - with that iSNS client. - -8. IANA Considerations - - The well-known TCP and UDP port number for iSNS is 3205. - - The standards action of this RFC creates two registries to be - maintained by IANA in support of iSNSP and assigns initial values for - both registries. The first registry is of Block Storage Protocols - supported by iSNS. The second registry is a detailed registry of - standard iSNS attributes that can be registered to and queried from - the iSNS server. Note that this RFC uses the registry created for - Block Structure Descriptor (BSD) in Section 15 of Service Location - Protocol, Version 2 [RFC2608]. - -8.1. Registry of Block Storage Protocols - - In order to maintain a registry of block storage protocols supported - by iSNSP, IANA will assign a 32-bit unsigned integer number for each - block storage protocol supported by iSNS. This number is stored in - the iSNS database as the Entity Protocol. The initial set of values - to be maintained by IANA for Entity Protocol is indicated in the - - - -Tseng, et al. Standards Track [Page 107] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - table in Section 6.2.2. Additional values for new block storage - protocols to be supported by iSNS SHALL be assigned by the IPS WG - Chairperson, or by a Designated Expert [RFC2434] appointed by the - IETF Transport Area Director. - -8.2. Registry of Standard iSNS Attributes - - IANA is responsible for creating and maintaining the Registry of - Standard iSNS Attributes. The initial list of iSNS attributes is - described in Section 6. For each iSNS attribute this information - MUST include, its tag value, the attribute length, and the tag values - for the set of permissible registration and query keys that can be - used for that attribute. The initial list of iSNS attributes to be - maintained by IANA is indicated in Section 6.1. - - Additions of new standard attributes to the Registry of Standard iSNS - Attributes SHALL require IETF Consensus [RFC2434]. The RFC required - for this process SHALL specify use of tag values reserved for IANA - allocation in Section 6.1. The RFC SHALL specify as a minimum, the - new attribute tag value, attribute length, and the set of permissible - registration and query keys that can be used for the new attribute. - The RFC SHALL also include a discussion of the reasons for the new - attribute(s) and how the new attribute(s) are to be used. - - As part of the process of obtaining IETF Consensus, the proposed RFC - and its supporting documentation SHALL be made available to the IPS - WG mailing list or, if the IPS WG is disbanded at the time, to a - mailing list designated by the IETF Transport Area Director. The - review and comment period SHALL last at least three months before the - IPS WG Chair or a person designated by the IETF Transport Area - Director decides either to reject the proposal or to forward the - draft to the IESG for publication as an RFC. When the specification - is published as an RFC, then IANA will register the new iSNS - attribute(s) and make the registration available to the community. - -8.3. Block Structure Descriptor (BSD) Registry - - Note that IANA is already responsible for assigning and maintaining - values used for the Block Structure Descriptor for the iSNS - Authentication Block (see Section 5.5). Section 15 of [RFC2608] - describes the process for allocation of new BSD values. - - - - - - - - - - -Tseng, et al. Standards Track [Page 108] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -9. Normative References - - [iSCSI] Satran, J., Meth, K., Sapuntzakis, C., Chadalapaka, M., - and E. Zeidner, "Internet Small Computer Systems - Interface (iSCSI)", RFC 3720, April 2004. - - [iFCP] Monia, C., Mullendore, R., Travostino, F., Jeong, W., - and M. Edwards, "iFCP - A Protocol for Internet Fibre - Channel Storage Networking", RFC 4172, September 2005. - - [iSNSOption] Monia, C., Tseng, J., and K. Gibbons, The IPv4 Dynamic - Host Configuration Protocol (DHCP) Option for the - Internet Storage Name Service, RFC 4174, September 2005. - - [RFC2608] Guttman, E., Perkins, C., Veizades, J., and M. Day, - "Service Location Protocol, Version 2 ", RFC 2608, June - 1999. - - [iSCSI-SLP] Bakke, M., Hufferd, J., Voruganti, K., Krueger, M., and - T. Sperry, "Finding Internet Small Computer Systems - Interface (iSCSI) Targets and Name Servers by Using - Service Location Protocol version 2 (SLP), RFC 4018, - April 2005. - - [iSCSI-boot] Sarkar, P., Missimer, D., and C. Sapuntzakis, - "Bootstrapping Clients using the Internet Samll Computer - System Interface (iSCSI) Protocol", RFC 4173, September - 2005. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [STRINGPREP] Bakke, M., "String Profile for Internet Small Computer - Systems Interface (iSCSI) Names", RFC 3722, April 2004. - - [NAMEPREP] Hoffman, P. Nameprep: A Stringprep Profile for - Internationalized Domain Names, July 2002. - - [RFC2407] Piper, D., "The Internet IP Security Domain of - Interpretation for ISAKMP", RFC 2407, November 1998. - - [RFC2408] Maughan, D., Schertler, M., Schneider, M., and J. - Turner, "Internet Security Association and Key - Management Protocol (ISAKMP)", RFC 2408, November 1998. - - [RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange - (IKE)", RFC 2409, November 1998. - - - - -Tseng, et al. Standards Track [Page 109] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - [EUI-64] Guidelines for 64-bit Global Identifier (EUI-64) - Registration Authority, May 2001, IEEE - - [RFC3279] Bassham, L., Polk, W., and R. Housley, "Algorithms and - Identifiers for the Internet X.509 Public Key - Infrastructure Certificate and Certificate Revocation - List (CRL) Profile", RFC 3279, April 2002. - - [RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet - X.509 Public Key Infrastructure Certificate and - Certificate Revocation List (CRL) Profile", RFC 3280, - April 2002. - - [802-1990] IEEE Standards for Local and Metropolitan Area Networks: - Overview and Architecture, Technical Committee on - Computer Communications of the IEEE Computer Society, - May 31, 1990 - - [FC-FS] Fibre Channel Framing and Signaling Interface, NCITS - Working Draft Project 1331-D - -10. Informative References - - [iSNSMIB] Gibbons, K., et al., "Definitions of Managed Objects for - iSNS (Internet Storage name Service)", Work in Progress, - July 2003. - - [X.509] ITU-T Recommendation X.509 (1997 E): Information - Technology - Open Systems Interconnection - The - Directory: Authentication Framework, June 1997 - - [FC-GS-4] Fibre Channel Generic Services-4 (work in progress), - NCITS Working Draft Project 1505-D - - [RFC1510] Kohl, J. and C. Neuman, "The Kerberos Network - Authentication Service (V5)", RFC 1510, September 1993. - - [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism - (SPKM)", RFC 2025, October 1996. - - [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 2434, - October 1998. - - [RFC2945] Wu, T., "The SRP Authentication and Key Exchange - System", RFC 2945, September 2000. - - - - - -Tseng, et al. Standards Track [Page 110] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - [RFC1994] Simpson, W., "PPP Challenge Handshake Authentication - Protocol (CHAP)", RFC 1994, August 1996. - - [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC - 2131, March 1997. - - [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, - "Introduction and Applicability Statements for - Internet-Standard Management Framework", RFC 3410, - December 2002. - - [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An - Architecture for Describing Simple Network Management - Protocol (SNMP) Management Frameworks", STD 62, RFC - 3411, December 2002. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Tseng, et al. Standards Track [Page 111] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -Appendix A: iSNS Examples - -A.1. iSCSI Initialization Example - - This example assumes an SLP Service Agent (SA) has been implemented - on the iSNS host, and an SLP User Agent (UA) has been implemented on - the iSNS initiator. See [RFC2608] for further details on SAs and - UAs. This example also assumes that the target is configured to use - the iSNS server, and have its access control policy subordinated to - the iSNS server. - -A.1.1. Simple iSCSI Target Registration - - In this example, a simple target with a single iSCSI name registers - with the iSNS server. The target is represented in the iSNS by an - Entity containing one Storage Node, one Portal, and an implicitly - registered Portal Group that provides a relationship between the - Storage Node and Portal. The target has not been assigned a Fully - Qualified Domain Name (FQDN) by the administrator. In this example, - because a PG object is not explicitly registered, a Portal Group with - a PGT of 1 is implicitly registered. In this example SLP is used to - discover the location of the iSNS Server. An alternative is to use - the iSNS DHCP option [iSNSOption] to discover the iSNS server. - - +--------------------------+------------------+-------------------+ - | iSCSI Target Device | iSNS Server |Management Station | - +--------------------------+------------------+-------------------+ - |Discover iSNS--SLP------->| |/*mgmt station is | - | |<--SLP--iSNS Here:| administratively | - | | 192.0.2.100 | authorized to view| - | | | all DDs. Device | - | DevAttrReg--------->| | NAMEabcd was | - |Src:(tag=32) "NAMEabcd" | | previously placed | - |Key: <none present> | | into DDabcd along | - |Oper Attrs: | | with devpdq and | - |tag=1: NULL | | devrst. | - |tag=2: "iSCSI" | | | - |tag=16: 192.0.2.5 | | | - |tag=17: 5001 | | | - |tag=32: "NAMEabcd" | | | - |tag=33: target | | | - |tag=34: "disk 1" | | | - | |<---DevAttrRegRsp | | - | |SUCCESS | | - | |Key:(tag=1) "isns:0001" | - | |Oper Attrs: | | - | |tag=1: "isns:0001"| | - | |tag=2: "iSCSI" | | - - - -Tseng, et al. Standards Track [Page 112] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - | |tag=16: 192.0.2.5 | | - | |tag=17: 5001 | | - | |tag=32: "NAMEabcd"|/* previously | - | |tag=33: target | placed in a DD */ | - | |tag=34: "disk 1" | | - | | | | - | | SCN-------->| | - | |(or SNMP notification) | - | |dest:(tag=32):"MGMTname1" | - | |time:(tag=4): <current time> | - | |tag=35: "MGT-SCN, OBJ-ADD" | - | |tag=32: "NAMEabcd"| | - | | |<-------SCNRsp | - | DevAttrQry--------->| | | - |Src:(tag=32) "NAMEabcd" | | | - |Key:(tag=33) "initiator" | | | - |Oper Attrs: | | | - |tag=16: NULL | | | - |tag=17: NULL | | | - |tag=32: NULL | | | - |/*Query asks for all initr| | | - |devices' IP address, port |<---DevAttrQryRsp | | - |number, and Name*/ |SUCCESS | | - | |tag=16:192.0.2.1 | | - | |tag=17:50000 | | - | |tag=32:"devpdq" | | - | |tag=16:192.0.2.2 | | - | |tag=17:50000 | | - | |tag=32:"devrst" | | - |/*************************| |<-----DevAttrQry | - |Our target "NAMEabcd" | |src: "MGMTname1" | - |discovers two initiators | key:(tag=32)"NAMEabcd" - |in shared DDs. It will | |Op Attrs: | - |accept iSCSI logins from | |tag=16: NULL | - |these two identified | |tag=17: NULL | - |initiators presented by | |tag=32: NULL | - |iSNS | | | - |*************************/| DevAttrQryRsp--->| | - | |SUCCESS | | - | |tag=16: 192.0.2.5 | | - | |tag=17: 5001 | | - | |tag=32: "NAMEabcd"| | - +--------------------------+------------------+-------------------+ - - - - - - - - -Tseng, et al. Standards Track [Page 113] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -A.1.2. Target Registration and DD Configuration - - In this example, a more complex target, with two Storage Nodes and - two Portals using ESI monitoring, registers with the iSNS. This - target has been configured with a Fully Qualified Domain Name (FQDN) - in the DNS servers, and the user wishes to use this identifier for - the device. The target explicitly registers Portal Groups to - describe how each Portal provides access to each Storage Node. One - target Storage Node allows coordinated access through both Portals. - The other Storage Node allows access, but not coordinated access, - through both Portals. - - +--------------------------+------------------+-------------------+ - | iSCSI Target Device | iSNS Server |Management Station | - +--------------------------+------------------+-------------------+ - |Discover iSNS--SLP--> | |/*mgmt station is | - | |<--SLP--iSNS Here:| administratively | - | | 192.0.2.100 | authorized to view| - | DevAttrReg--> | | all DDs */ | - |Src: | | | - |tag=32: "NAMEabcd" | | | - |Msg Key: | | | - |tag=1: "jbod1.example.com"| | | - |Oper Attrs: | | | - |tag=1: "jbod1.example.com"| | | - |tag=2: "iSCSI" | | | - |tag=16: 192.0.2.4 | | | - |tag=17: 5001 | | | - |tag=19: 5 | | | - |tag=20: 5002 | | | - |tag=16: 192.0.2.5 | | | - |tag=17: 5001 | | | - |tag=19: 5 | | | - |tag=20: 5002 | | | - |tag=32: "NAMEabcd" | | | - |tag=33: "Target" | | | - |tag=34: "Storage Array 1" | | | - |tag=51: 10 | | | - |tag=49: 192.0.2.4 | | | - |tag=50: 5001 | | | - |tag=49: 192.0.2.5 | | | - |tag=50: 5001 | | | - |tag=32: "NAMEefgh" | | | - |tag=33: "Target" | | | - |tag=34: "Storage Array 2" |/*****************| | - |tag=51: 20 |jbod1.example.com is | - |tag=49: 192.0.2.4 |now registered in | | - |tag=50: 5001 |iSNS, but is not | | - - - -Tseng, et al. Standards Track [Page 114] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - |tag=51: 30 |in any DD. Therefore, | - |tag=49: 192.0.2.5 |no other devices | | - |tag=50: 5001 |can "see" it. | | - | |*****************/| | - | |<--DevAttrRegRsp | | - | |SUCCESS | | - | |Msg Key: | | - | |tag=1: "jbod1.example.com" | - | |Oper Attrs: | | - | |tag=1: "jbod1.example.com" | - | |tag=2: "iSCSI" | | - | |tag=16: 192.0.2.4 | | - | |tag=17: 5001 | | - | |tag=19: 5 | | - | |tag=20: 5002 | | - | |tag=16: 192.0.2.5 | | - | |tag=17: 5001 | | - | |tag=19: 5 | | - | |tag=20: 5002 | | - | |tag=32: "NAMEabcd"| | - | |tag=33: "Target" | | - | |tag=34: "Storage Array 1" | - | |tag=48: "NAMEabcd"| | - | |tag=49: 192.0.2.4 | | - | |tag=50: 5001 | | - | |tag=51: 10 | | - | |tag=48: "NAMEabcd"| | - | |tag=49: 192.0.2.5 | | - | |tag=50: 5001 | | - | |tag=51: 10 | | - | |tag=32: "NAMEefgh"| | - | |tag=33: "Target" | | - | |tag=34: "Storage Array 2" | - | |tag=43: X.509 cert| | - | |tag=48: "NAMEefgh"| | - | |tag=49: 192.0.2.4 | | - | |tag=50: 5001 | | - | |tag=51: 20 | | - | |tag=48: "NAMEefgh"| | - | |tag=49: 192.0.2.5 | | - | |tag=50: 5001 | | - | |tag=51: 30 | | - | | | | - | | SCN------> | | - | | (or SNMP notification) | - | |dest:(tag=32)"mgmt.example.com" | - | |time:(tag=4): <current time> | - | |tag=35: "MGT-SCN, OBJ-ADD" | - - - -Tseng, et al. Standards Track [Page 115] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - | |tag=32: "NAMEabcd"| | - | |tag=35: "MGT-SCN, OBJ-ADD" | - | |tag=32: "NAMEefgh"| | - | | |<--SCNRsp | - | | |SUCCESS | - | | tag=32:"mgmt.example.com"| - | | | | - | | |<--DevAttrQry | - | | |Src: | - | | tag=32:"mgmt.example.com" - | | |Msg Key: | - | | |tag=32: "NAMEabcd" | - | | |Oper Attrs: | - | | |tag=16: <0-length> | - | | |tag=17: <0-length> | - | | |tag=32: <0-length> | - | | | | - | | DevAttrQryRsp--> | | - | |SUCCESS | | - | |Msg Key: | | - | |tag=32: "NAMEabcd"| | - | |Oper Attrs: | | - | |tag=16: 192.0.2.4 | | - | |tag=17: 5001 | | - | |tag=32:"NAMEabcd" | | - | |tag=16: 192.0.2.5 | | - | |tag=17: 5001 | | - | |tag=32:"NAMEabcd" | | - | | |Src: | - | | tag=32:"mgmt.example.com" - | | |Msg Key: | - | | |tag=32: "NAMEefgh" | - | | |Oper Attrs: | - | | |tag=16: <0-length> | - | | |tag=17: <0-length> | - | | |tag=32: <0-length> | - | | | | - | | DevAttrQryRsp--> | | - | |SUCCESS | | - | |Msg Key: | | - | |tag=32: "NAMEefgh"| | - | |Oper Attrs: | | - | |tag=16: 192.0.2.4 | | - | |tag=17: 5001 | | - | |tag=32:"NAMEefgh" | | - | |tag=16: 192.0.2.5 |/**Mgmt Station ***| - | |tag=17: 5001 |displays device, | - | |tag=32:"NAMEefgh" |the operator decides - - - -Tseng, et al. Standards Track [Page 116] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - | | |to place "NAMEabcd"| - | | |into Domain "DDxyz"| - |/*************************| |******************/| - |Target is now registered | | | - |in iSNS. It is then placed| |<--DDReg | - |in a pre-existing DD with | |Src: | - |DD_ID 123 by a management | tag=32:"mgmt.example.com" - |station. | |Msg Key: | - |*************************/| |tag=2065: 123 | - | | |Oper Attrs: | - | | |tag=2068: "NAMEabcd" - | | DDRegRsp-----> | | - | |SUCCESS | | - | |Msg Key: | | - | |tag=2065: 123 | | - | |Oper Attrs: | | - | |tag=2065: 123 | | - +--------------------------+------------------+-------------------+ - -A.1.3. Initiator Registration and Target Discovery - - The following example illustrates a new initiator registering with - the iSNS, and discovering the target NAMEabcd from the example in - A.1.2. - - +--------------------------+------------------+-------------------+ - | iSCSI Initiator | iSNS |Management Station | - +--------------------------+------------------+-------------------+ - |Discover iSNS--SLP--> | |/*mgmt station is | - | |<--SLP--iSNS Here:| administratively | - | | 192.36.53.1 | authorized to view| - |DevAttrReg--> | | all DDs ********/ | - |Src: | | | - |tag=32: "NAMEijkl" | | | - |Msg Key: | | | - |tag=1: "svr1.example.com" | | | - |Oper Attrs: | | | - |tag=1: "svr1.example.com" | | | - |tag=2: "iSCSI" | | | - |tag=16: 192.20.3.1 |/*****************| | - |tag=17: 5001 |Device not in any | | - |tag=19: 5 |DD, so it is | | - |tag=20: 5002 |inaccessible by | | - |tag=32: "NAMEijkl" |other devices | | - |tag=33: "Initiator" |*****************/| | - |tag=34: "Server1" | | | - |tag=51: 11 | | | - |tag=49: 192.20.3.1 | | | - - - -Tseng, et al. Standards Track [Page 117] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - |tag=50: 5001 | | | - | |<--DevAttrRegRsp | | - | |SUCCESS | | - | |Msg Key: | | - | |tag=1: "svr1.example.com" | - | |Oper Attrs: | | - | |tag=1: "svr1.example.com" | - | |tag=2: "iSCSI" | | - | |tag=16: 192.20.3.1| | - | |tag=17: 5001 | | - | |tag=19: 5 | | - | |tag=20: 5002 | | - | |tag=32: "NAMEijkl"| | - | |tag=33: "Initiator" | - | |tag=34: "Server1" | | - | |tag=48: "NAMEijkl"| | - | |tag=49: 192.20.3.1| | - | |tag=50: 5001 | | - | |tag=51: 11 | | - | | | | - | | SCN------> | | - | | (or SNMP notification) | - | |dest:(tag=32)"mgmt.example.com" | - | |time:(tag=4): <current time> | - | |tag=35: "MGT-SCN, OBJ-ADD" | - | |tag=32: "NAMEijkl"| | - | | | | - | | |<------SCNRsp | - | | |SUCCESS | - | | tag=32:"mgmt.example.com" - | | | | - |SCNReg--> | | | - |Src: | | | - |tag=32: "NAMEijkl" | | | - |Msg Key: | | | - |tag=32: "NAMEijkl" | | | - |Oper Attrs: | | | - |tag=35: <TARG&SELF, OBJ-RMV/ADD/UPD> | | - | |<--SCNRegRsp | | - | |SUCCESS | | - | | | | - | | |<----DevAttrQry | - | | |Src: | - | | tag=32:"mgmt.example.com" - | | |Msg Key: | - | | |tag=32: "NAMEijkl" | - | | |Oper Attrs: | - | | |tag=16: <0-length> | - - - -Tseng, et al. Standards Track [Page 118] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - | | |tag=17: <0-length> | - | | |tag=32: <0-length> | - | | DevAttrQryRsp--->| | - | |SUCCESS | | - | |Msg Key: | | - | |tag=32: "NAMEijkl"| | - | |Oper Attrs: | | - | |tag=16:192.20.3.1 | | - | |tag=17: 5001 | | - | |tag=32:"NAMEijkl" | | - | | |/**Mgmt Station ***| - | | |displays device, the - | | |operator decides to| - | | |place "NAMEijkl" into - | | |pre-existing Disc | - | | |Domain "DDxyz" with| - | | |device NAMEabcd | - | | |******************/| - | | |<--DDReg | - | | |Src: | - | | tag=32:"mgmt.example.com" - | | |Msg Key: | - | | |tag=2065: 123 | - | | |Oper Attrs: | - | | |tag=2068: "NAMEijkl" - | | | | - | | DDRegRsp---->| | - | |SUCCESS | | - | |Msg Key: | | - | |tag=2065: 123 | | - | |Oper Attrs: | | - | |tag=2065: 123 |/******************| - | | |"NAMEijkl" has been| - | | |moved to "DDxyz" | - | | |******************/| - | | SCN------>| | - | |dest:(tag=32)"mgmt.example.com" | - | |time:(tag=4): <current time> | - | |tag=35: <MGT-SCN, DD/DDS-MBR-ADD> | - | |tag=2065: 123 | | - | |tag=2068: "NAMEijkl" | - | | | | - | | |<------SCNRsp | - | | |SUCCESS | - | | tag=32:"mgmt.example.com" - | |<-----SCN | | - | |dest:(tag=32)"NAMEijkl" | - | |time:(tag=4): <current time> | - - - -Tseng, et al. Standards Track [Page 119] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - | |tag=35: <TARG&SELF, OBJ-ADD> | - | |tag=32: "NAMEijkl"| | - | SCNRsp------> | | | - |SUCCESS | | | - |tag=32:"NAMEijkl" | | | - | | | | - | |/*****************| | - | |Note that NAMEabcd| | - | |also receives an | | - | |SCN that NAMEijkl | | - | |is in the same DD | | - | |*****************/| | - | (to "NAMEabcd")|<-----SCN | | - | |dest:(tag=32)"NAMEabcd" | - | |time:(tag=4): <current time> | - | |tag=35: <INIT&SELF, OBJ-ADD> | - | |tag=32: "NAMEijkl"| | - | SCNRsp------> | | | - |SUCCESS | | | - |tag=32:"NAMEabcd" | | | - | | | | - | DevAttrQry----------->| | | - |Src: | | | - |tag=32: "NAMEijkl" | | | - |Msg Key: | | | - |tag=33: "Target" | | | - |Oper Attrs: | | | - |tag=16: <0-length> | | | - |tag=17: <0-length> | | | - |tag=32: <0-length> | | | - |tag=34: <0-length> | | | - |tag=43: <0-length> | | | - |tag=48: <0-length> | | | - |tag=49: <0-length> | | | - |tag=50: <0-length> | | | - |tag=51: <0-length> | | | - | |<--DevAttrQryRsp | | - | |SUCCESS | | - | |Msg Key: | | - | |tag=33:"Target" | | - | |Oper Attrs: | | - | |tag=16: 192.0.2.4 | | - | |tag=17: 5001 | | - | |tag=32: "NAMEabcd"| | - | |tag=34: "Storage Array 1" | - | |tag=16: 192.0.2.5 | | - | |tag=17: 5001 | | - | |tag=32: "NAMEabcd"| | - - - -Tseng, et al. Standards Track [Page 120] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - - | |tag=34: "Storage Array 1" | - | |tag=43: X.509 cert| | - | |tag=48: "NAMEabcd"| | - | |tag=49: 192.0.2.4 | | - | |tag=50: 5001 | | - | |tag=51: 10 | | - | |tag=48: "NAMEabcd"| | - | |tag=49: 192.0.2.5 | | - | |tag=50: 5001 | | - | |tag=51: 10 | | - | | | | - |/***The initiator has discovered | | - |the target, and has everything | | - |needed to complete iSCSI login | | - |The same process occurs on the | | - |target side; the SCN prompts the | | - |target to download the list of | | - |authorized initiators from the | | - |iSNS (i.e., those initiators in the | | - |same DD as the target.************/ | | - +--------------------------+------------------+-------------------+ - -Acknowledgements - - Numerous individuals contributed to the creation of this document - through their careful review and submissions of comments and - recommendations. We acknowledge the following persons for their - technical contributions to this document: Mark Bakke (Cisco), John - Hufferd (IBM), Julian Satran (IBM), Kaladhar Voruganti(IBM), Joe Czap - (IBM), John Dowdy (IBM), Tom McSweeney (IBM), Jim Hafner (IBM), Chad - Gregory (Intel), Yaron Klein (Sanrad), Larry Lamers (Adaptec), Jack - Harwood (EMC), David Black (EMC), David Robinson (Sun), Alan Warwick - (Microsoft), Bob Snead (Microsoft), Fa Yoeu (Intransa), Joe White - (McDATA), Charles Monia (McDATA), Larry Hofer (McDATA), Ken Hirata - (Vixel), Howard Hall (Pirus), Malikarjun Chadalapaka (HP), Marjorie - Krueger (HP), Siva Vaddepuri (McDATA), and Vinai Singh (American - Megatrends). - - - - - - - - - - - - - - -Tseng, et al. Standards Track [Page 121] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -Authors' Addresses - - Josh Tseng - Riverbed Technology - 501 2nd Street, Suite 410 - San Francisco, CA 94107 - - Phone: (650)274-2109 - EMail: joshtseng@yahoo.com - - - Kevin Gibbons - McDATA Corporation - 4555 Great America Parkway - Santa Clara, CA 95054-1208 - - Phone: (408) 567-5765 - EMail: kevin.gibbons@mcdata.com - - - Franco Travostino - Nortel - 600 Technology Park Drive - Billerica, MA 01821 USA - - Phone: (978) 288-7708 - EMail: travos@nortel.com - - - Curt du Laney - Rincon Research Corporation - 101 North Wilmot Road, Suite 101 - Tucson AZ 85711 - - Phone: (520) 519-4409 - EMail: cdl@rincon.com - - - Joe Souza - Microsoft Corporation - One Microsoft Way - Redmond, WA 98052-6399 - - Phone: (425) 706-3135 - EMail: joes@exmsft.com - - - - - - -Tseng, et al. Standards Track [Page 122] - -RFC 4171 Internet Storage Name Service (iSNS) September 2005 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2005). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, - INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE - INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED - WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at ietf- - ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - -Tseng, et al. Standards Track [Page 123] - |