CryptoPkg: Add some comments for API usage clarification.

[mirror_edk2.git] / CryptoPkg / Include / Library / BaseCryptLib.h

diff --git a/CryptoPkg/Include/Library/BaseCryptLib.h b/CryptoPkg/Include/Library/BaseCryptLib.h
index bc36ac7fd1810636e9461ad7bbb1fc4a0a3f1822..d3b211bec5b67a90d3d8a8417a09e22040cc3dc6 100644 (file)
--- a/CryptoPkg/Include/Library/BaseCryptLib.h
+++ b/CryptoPkg/Include/Library/BaseCryptLib.h
@@ -4,7 +4,7 @@
   primitives (Hash Serials, HMAC, RSA, Diffie-Hellman, etc) for UEFI security\r
   functionality enabling.\r
 \r
-Copyright (c) 2009 - 2014, Intel Corporation. All rights reserved.<BR>\r
+Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.<BR>\r
 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
@@ -1631,6 +1631,8 @@ RsaGenerateKey (
 \r
 /**\r
   Validates key components of RSA context.\r
+  NOTE: This function performs integrity checks on all the RSA key material, so\r
+        the RSA key structure must contain all the private key data.\r
 \r
   This function validates key compoents of RSA context in following aspects:\r
   - Whether p is a prime\r
@@ -1859,7 +1861,7 @@ X509ConstructCertificate (
   If X509Stack is NULL, then return FALSE.\r
   If this interface is not supported, then return FALSE.\r
 \r
-  @param[in, out]  X509Stack  On input, pointer to an existing X509 stack object.\r
+  @param[in, out]  X509Stack  On input, pointer to an existing or NULL X509 stack object.\r
                               On output, pointer to the X509 stack object with new\r
                               inserted X509 certificate.\r
   @param           ...        A list of DER-encoded single certificate data followed\r
@@ -2053,6 +2055,35 @@ Pkcs7Verify (
   IN  UINTN        DataLength\r
   );\r
 \r
+/**\r
+  Extracts the attached content from a PKCS#7 signed data if existed. The input signed\r
+  data could be wrapped in a ContentInfo structure.\r
+\r
+  If P7Data, Content, or ContentSize is NULL, then return FALSE. If P7Length overflow,\r
+  then return FAlSE. If the P7Data is not correctly formatted, then return FALSE.\r
+\r
+  Caution: This function may receive untrusted input. So this function will do\r
+           basic check for PKCS#7 data structure.\r
+\r
+  @param[in]   P7Data       Pointer to the PKCS#7 signed data to process.\r
+  @param[in]   P7Length     Length of the PKCS#7 signed data in bytes.\r
+  @param[out]  Content      Pointer to the extracted content from the PKCS#7 signedData.\r
+                            It's caller's responsiblity to free the buffer.\r
+  @param[out]  ContentSize  The size of the extracted content in bytes.\r
+\r
+  @retval     TRUE          The P7Data was correctly formatted for processing.\r
+  @retval     FALSE         The P7Data was not correctly formatted for processing.\r
+\r
+*/\r
+BOOLEAN\r
+EFIAPI\r
+Pkcs7GetAttachedContent (\r
+  IN  CONST UINT8  *P7Data,\r
+  IN  UINTN        P7Length,\r
+  OUT VOID         **Content,\r
+  OUT UINTN        *ContentSize\r
+  );\r
+\r
 /**\r
   Verifies the validility of a PE/COFF Authenticode Signature as described in "Windows\r
   Authenticode Portable Executable Signature Format".\r
@@ -2333,4 +2364,4 @@ RandomBytes (
   IN   UINTN  Size\r
   );\r
 \r
-#endif // __BASE_CRYPT_LIB_H__
\ No newline at end of file
+#endif // __BASE_CRYPT_LIB_H__\r