Changeset 73819 in vbox

Timestamp:

Aug 22, 2018 9:02:04 AM (7 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

124509

Message:

iprt/crypto: some documentation updates. bugref:9152

Location:

trunk/include/iprt/crypto

Files:

• digest.h (modified) (1 diff)
• pkix.h (modified) (4 diffs)

trunk/include/iprt/crypto/digest.h

@@ -206 +206 @@
  */
 RTDECL(int)             RTCrDigestClone(PRTCRDIGEST phDigest, RTCRDIGEST hSrc);
+/**
+ * Resets the digest to start calculating a new digest.
+ */
 RTDECL(int)             RTCrDigestReset(RTCRDIGEST hDigest);
+
+/**
+ * Retains a references to the digest.
+ *
+ * @returns New reference count. UINT32_MAX if invalid handle.
+ * @param   hDigest     Handle to the digest.
+ */
 RTDECL(uint32_t)        RTCrDigestRetain(RTCRDIGEST hDigest);
+/**
+ * Releases a references to the digest.
+ *
+ * @returns New reference count. UINT32_MAX if invalid handle.
+ * @param   hDigest     Handle to the digest.  NIL is ignored (returns 0).
+ */
 RTDECL(uint32_t)        RTCrDigestRelease(RTCRDIGEST hDigest);
+
+/**
+ * Updates the digest with more message data.
+ *
+ * @returns IPRT status code.
+ * @param   hDigest     Handle to the digest.
+ * @param   pvData      Pointer to the message data.
+ * @param   cbData      The number of bytes of data @a pvData points to.
+ */
 RTDECL(int)             RTCrDigestUpdate(RTCRDIGEST hDigest, void const *pvData, size_t cbData);
+
+/**
+ * Updates the digest with more message data from the given VFS file handle.
+ *
+ * @returns IPRT status code.
+ * @param   hDigest     Handle to the digest.
+ * @param   hVfsFile    Handle to the VFS file.
+ * @param   fRewindFile Rewind to the start of the file if @a true, start
+ *                      consumption at the current file position if @a false.
+ */
 RTDECL(int)             RTCrDigestUpdateFromVfsFile(RTCRDIGEST hDigest, RTVFSFILE hVfsFile, bool fRewindFile);
 

trunk/include/iprt/crypto/pkix.h

@@ -227 +227 @@
      * @param   pvState         The opaque provider state.
      * @param   hKey            The key handle associated with the state at init.
-     * @param   hDigest         The handle to the digest.  Call RTCrDigestFinal to
+     * @param   hDigest         The handle to the digest.  Calls RTCrDigestFinal to
      *                          complete and retreive the final hash value.
      * @param   pvSignature     The signature to validate.
@@ -251 +251 @@
      * @param   pvState         The opaque provider state.
      * @param   hKey            The key handle associated with the state at init.
-     * @param   hDigest         The handle to the digest.  Call RTCrDigestFinal to
+     * @param   hDigest         The handle to the digest.  Calls RTCrDigestFinal to
      *                          complete and retreive the final hash value.
      * @param   pvSignature     The output signature buffer.
@@ -335 +335 @@
  *
  * @param   hSignature      The signature schema provider handle.
- * @param   hDigest         The handle to the digest.  Call RTCrDigestFinal to
- *                          complete and retreive the final hash value.
+ * @param   hDigest         The handle to the digest.  All that must have been
+ *                          feed to it via RTCrDigestUpdate() and friends prior
+ *                          to calling this function.  The function will itself
+ *                          call RTCrDigestFinal() to complete and retreive the
+ *                          final hash value.
  * @param   pvSignature     The signature to validate.
  * @param   cbSignature     The size of the signature (in bytes).
@@ -360 +363 @@
  *
  * @param   hSignature      The signature schema provider handle.
- * @param   hDigest         The handle to the digest.  Call RTCrDigestFinal to
- *                          complete and retreive the final hash value.
+ * @param   hDigest         The handle to the digest.  All that must have been
+ *                          feed to it via RTCrDigestUpdate() and friends prior
+ *                          to calling this function.  The function will itself
+ *                          call RTCrDigestFinal() to complete and retreive the
+ *                          final hash value.
  * @param   pvSignature     The output signature buffer.
  * @param   pcbSignature    On input the variable pointed to holds the size of