update file header

add function header for IScsiCHAPCalculateResponse()
add function header IScsiCHAPAuthTarget()
update other functions' function headers

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6940 6f19259b-4bc3-4df7-8a09-765794883524

diff --git a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.c b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.c
index 0dcb9a8796249b16da649669cd91a23e62ec9332..ad68cd9d4c7436772f4837401df5917ebacfa605 100644 (file)
--- a/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.c
+++ b/MdeModulePkg/Universal/Network/IScsiDxe/IScsiCHAP.c
@@ -1,7 +1,7 @@
 /** @file\r
-  Challenge-Handshake Authentication Protocol (CHAP) Configuration\r
-\r
-Copyright (c) 2004 - 2008, Intel Corporation\r
+  This file is for Challenge-Handshake Authentication Protocol (CHAP) Configuration.\r
+ \r
+Copyright (c) 2004 - 2008, Intel Corporation.<BR>\r
 All rights reserved. This program and the accompanying materials\r
 are licensed and made available under the terms and conditions of the BSD License\r
 which accompanies this distribution.  The full text of the license may be found at\r
@@ -10,14 +10,6 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
 \r
-Module Name:\r
-\r
-  IScsiCHAP.c\r
-\r
-Abstract:\r
-\r
-  This file is for CHAP configuration\r
-\r
 **/\r
 \r
 #include "IScsiImpl.h"\r
@@ -25,6 +17,21 @@ Abstract:
 \r
 EFI_GUID  mIScsiCHAPAuthInfoGuid = ISCSI_CHAP_AUTH_INFO_GUID;\r
 \r
+/**\r
+  Initator caculates its own expected hash value. \r
+  \r
+  @param[in]   ChapIdentifier     ISCSI CHAP identifier sent by authenticator.  \r
+  @param[in]   ChapSecret         ISCSI CHAP secret of the authenticator.   \r
+  @param[in]   SecretLength       The length of ISCSI CHAP secret.\r
+  @param[in]   ChapChallenge      The challenge message sent by authenticator.  \r
+  @param[in]   ChallengeLength    The length of ISCSI CHAP challenge message.\r
+  @param[out]  ChapResponse       The calculation of the expected hash value.\r
+  \r
+  @retval EFI_SUCCESS             The expected hash value was caculatedly successfully.\r
+  @retval EFI_PROTOCOL_ERROR      The length of the secret should be at least the \r
+                                  length of the hash value for the hashing algorithm chosen.\r
+  @retval Others                  Some unexpected error happened.                                \r
+**/\r
 EFI_STATUS\r
 IScsiCHAPCalculateResponse (\r
   IN  UINT32  ChapIdentifier,\r
@@ -66,6 +73,17 @@ IScsiCHAPCalculateResponse (
   return Status;\r
 }\r
 \r
+/**\r
+  The initator checks the CHAP response replied by target against its own\r
+  calculation of the expected hash value. \r
+  \r
+  @param[in]   AuthData             ISCSI CHAP authentication data. \r
+  @param[in]   TargetResponse       The response from target.    \r
+\r
+  @retval EFI_SUCCESS               The response from target passed authentication.\r
+  @retval EFI_SECURITY_VIOLATION    The response from target was not expected value.\r
+  @retval Others                    Some unexpected error happened.\r
+**/\r
 EFI_STATUS\r
 IScsiCHAPAuthTarget (\r
   IN  ISCSI_CHAP_AUTH_DATA  *AuthData,\r
@@ -99,16 +117,13 @@ IScsiCHAPAuthTarget (
   This function checks the received iSCSI Login Response during the security\r
   negotiation stage.\r
   \r
-  @param  Conn[in]             The iSCSI connection.\r
-\r
-  @param  Transit[in]          The transit flag of the latest iSCSI Login Response.\r
+  @param[in] Conn             The iSCSI connection.\r
+  @param[in] Transit          The transit flag of the latest iSCSI Login Response.\r
 \r
   @retval EFI_SUCCESS          The Login Response passed the CHAP validation.\r
-\r
   @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.\r
-\r
   @retval EFI_PROTOCOL_ERROR   Some kind of protocol error happend.\r
-\r
+  @retval Others               Some unexpected error happend.\r
 **/\r
 EFI_STATUS\r
 IScsiCHAPOnRspReceived (\r
@@ -269,7 +284,7 @@ IScsiCHAPOnRspReceived (
     IScsiHexToBin (TargetRsp, &RspLen, Response);\r
 \r
     //\r
-    // Check the CHAP Name and Response replied by Target.\r
+    // Check the CHAP Response replied by Target.\r
     //\r
     Status = IScsiCHAPAuthTarget (AuthData, TargetRsp);\r
     break;\r
@@ -291,17 +306,13 @@ ON_EXIT:
   This function fills the CHAP authentication information into the login PDU\r
   during the security negotiation stage in the iSCSI connection login.\r
 \r
-  @param  Conn[in]             The iSCSI connection.\r
-\r
-  @param  Pdu[in]              The PDU to send out.\r
+  @param[in]  Conn             The iSCSI connection.\r
+  @param[in]  Pdu              The PDU to send out.\r
 \r
   @retval EFI_SUCCESS          All check passed and the phase-related CHAP\r
                                authentication info is filled into the iSCSI PDU.\r
-\r
   @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.\r
-\r
   @retval EFI_PROTOCOL_ERROR   Some kind of protocol error happend.\r
-\r
 **/\r
 EFI_STATUS\r
 IScsiCHAPToSendReq (\r