1 files changed, 74 insertions, 0 deletions
diff --git a/src/plugins/lanplus/README.lanplus b/src/plugins/lanplus/README.lanplus
new file mode 100644
index 0000000..4406d5b
--- /dev/null
+++ b/src/plugins/lanplus/README.lanplus
@@ -0,0 +1,74 @@
+This interface exists to provide a means of connecting to an IPMIv2 enabled
+BMC.  In some places, the IPMIv2 specification is either unclear or
+inconsistent, and interpretations of the intent of the specification had to
+be made at the discretion of the implementor.  The purpose of this
+document is to make those decisions clear so that 1) they can be reviewed
+by others and 2) so that the rationale for those decisions can be made
+clear.
+
+* Though it's not stated explicitly with which algorithm the K1 and K2 keys
+should be generated, we chose to use the authentication algorithm.  The
+specification states that K1 and K2 are generated with an HMAC algorithm,
+and all of the authentication algorithms (except for "none") are HMAC
+algorithms, whereas the integrity algorithms are not all HMAC.  See section
+13.32 for details about K1 and K2, and section
+
+
+* The IPMIv2 specification describes a key, Kg, that is the "BMC key".
+This key functions as a global key that is required to be known in addition
+to the user's key, by authenticating users.  If the BMC has a null Kg, the
+users key, Kuid, is used in its place in algorithms where Kg is required,
+per the specification section 13.33.  A user can obtain the status of Kg by
+querying the BMC with the Get Channel Authentication Capabilities command.
+Currently, this implementation does not provide a way for a user to specify
+Kg for BMCs that require it.
+
+
+* The specification is unclear as to which key is used for HMAC based
+integrity checking.  One the one hand, section 13.28.4 states explicitly
+that HMAC integrity algorithms use the session integrity key as the HMAC
+key.  Confusing that matter is a statement in section 13.32 regarding the
+creation of additional keying material.  In this section it is stated that
+"all keying material for the RSP integrity and confidentiality algorithms
+will be generated by processing a pre-defined set of constants using HMAC
+per [RFC2104], keyed by sik".  And "For the mandatory-to-implement
+integrity and confidentiality algorithms defined in this specification,
+processing the first two (2) constants will generate the require amount of
+keying material."  We decided to use K1 as our HMAC key for the generation
+of authentication codes (integrity checking).  Furthermore, we are using
+all 20 bytes of K1.
+
+
+* IPMIv2 compliant BMCs are supposed to support 20 byte passwords, as well
+store metadata describing whether the password was stored as a 16 byte or
+20 byte class password.  We do not currently support 20 byte passwords.  It
+should be noted that there are obvious mistakes in the SET USER PASSWORD
+command specification, as it mentions the ability to query for 16/20 byte
+password status, but the packet format does not support this.
+
+
+* The IPMIv2 specification describes a type of login called a "role only
+login."  This feature allows a user to login providing only a requested
+privilege level and a password.  We do not currently support this feature.
+Supporting this feature would only require the ability to specify
+username/privilege lookups in the RAKP 1 message sent from ipmitool.  We
+currently specify the use of username only lookups for authentication.
+
+
+* In the IPMIv2 packet description in table 13-8 of the IPMv2
+specification, there are two fields that are rather ambiguous in meaning.
+The fields are "Pad Length" and "Next Header".  Although neither field is
+listed as belonging to the IPMIv2 packet format, we include/expect them
+both in our IPMIv2 packets.  Are rationale is 1) the Next Headers field's
+comment states what the value of that field should be for IPMIv2, and 2)
+for the most part the ASF and IPMIv2 fields seem to parallel each other,
+and we feel that the Pad Length and Next Header fields were left out of the
+IPMIv2 column by mistake.
+
+
+* The GET CHANNEL CIPHER SUITES command documentation seems to have
+mistakes.  The "start of record" byte is stated to be either 0x30 or 0x31,
+whereas the detailed description in table 22-18 leads us to believe that
+this byte should really be 0xC0 or 0xC1.  Also the description of bits 5:0
+in the start of record byte should probably be 00_0000 rather than 00_000.
+