Doxygen documentation.

git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@22320 ec53bebd-3082-4978-b11e-865c3cabbd6b

lib/hx509/cms.c

@@ -115,7 +115,7 @@ hx509_cms_wrap_ContentInfo(const heim_oid *oid,
  *
  * @param in the encoded buffer.
  * @param oid type of the content.
- * @param buf data to be wrapped.
+ * @param out data to be wrapped.
  * @param have_data since the data is optional, this flags show dthe
  * diffrence between no data and the zero length data.
  *
@@ -319,16 +319,20 @@ find_CMSIdentifier(hx509_context context,
 /**
  * Decode and unencrypt EnvelopedData.
  *
- * Separate data from the EnvelopedData.
+ * Extract data and parameteres from from the EnvelopedData. Also
+ * supports using detached EnvelopedData.
  *
- * @param context
+ * @param context A hx509 context.
- * @param certs
+ * @param certs Certificate that can decrypt the EnvelopedData
- * @param flags
+ * encryption key.
- * @param data
+ * @param flags HX509_CMS_UE flags to control the behavior.
- * @param length
+ * @param data pointer the structure the contains the DER/BER encoded
- * @param encryptedContent
+ * EnvelopedData stucture.
- * @param contentType
+ * @param length length of the data that data point to.
- * @param content
+ * @param encryptedContent in case of detached signature, this
+ * contains the actual encrypted data, othersize its should be NULL.
+ * @param contentType output type oid, should be freed with der_free_oid().
+ * @param content the data, free with der_free_octet_string().
  *
  * @ingroup hx509_cms
  */
@@ -505,6 +509,29 @@ out:
     return ret;
 }
 
+/**
+ * Encrypt end encode EnvelopedData.
+ *
+ * Encrypt and encode EnvelopedData. The data is encrypted with a
+ * random key and the the random key is encrypted with the
+ * certificates private key. This limits what private key type can be
+ * used to RSA.
+ *
+ * @param context A hx509 context.
+ * @param flags flags to control the behavior, no flags today
+ * @param cert Certificate to encrypt the EnvelopedData encryption key
+ * with.
+ * @param data pointer the data to encrypt.
+ * @param length length of the data that data point to.
+ * @param encryption_type Encryption cipher to use for the bulk data,
+ * use NULL to get default.
+ * @param contentType type of the data that is encrypted
+ * @param content the output of the function,
+ * free with der_free_octet_string().
+ *
+ * @ingroup hx509_cms
+ */
+
 int
 hx509_cms_envelope_1(hx509_context context,
 		     int flags,
@@ -698,13 +725,31 @@ find_attribute(const CMSAttributes *attr, const heim_oid *oid)
     return NULL;
 }
 
+/**
+ * Decode SignedData and verify that the signature is correct.
+ *
+ * @param context A hx509 context.
+ * @param ctx a hx509 version context
+ * @param data
+ * @param length length of the data that data point to.
+ * @param signedContent
+ * @param pool certificate pool to build certificates paths.
+ * @param contentType free with der_free_oid()
+ * @param content the output of the function, free with
+ * der_free_octet_string().
+ * @param signer_certs list of the cerficates used to sign this
+ * request, free with hx509_certs_free().
+ *
+ * @ingroup hx509_cms
+ */
+
 int
 hx509_cms_verify_signed(hx509_context context,
 			hx509_verify_ctx ctx,
 			const void *data,
 			size_t length,
 			const heim_octet_string *signedContent,
-			hx509_certs store,
+			hx509_certs pool,
 			heim_oid *contentType,
 			heim_octet_string *content,
 			hx509_certs *signer_certs)
@@ -762,8 +807,8 @@ hx509_cms_verify_signed(hx509_context context,
     if (ret)
 	goto out;
 
-    if (store) {
+    if (pool) {
-	ret = hx509_certs_merge(context, certs, store);
+	ret = hx509_certs_merge(context, certs, pool);
 	if (ret)
 	    goto out;
     }
@@ -1007,6 +1052,29 @@ add_one_attribute(Attribute **attr,
     return 0;
 }
 	
+/**
+ * Decode SignedData and verify that the signature is correct.
+ *
+ * @param context A hx509 context.
+ * @param flags
+ * @param eContentType the type of the data.
+ * @param data data to sign
+ * @param length length of the data that data point to.
+ * @param digest_alg digest algorithm to use, use NULL to get the
+ * default or the peer determined algorithm.
+ * @param cert certificate to use for sign the data.
+ * @param peer info about the peer the message to send the message to,
+ * like what digest algorithm to use.
+ * @param anchors trust anchors that the client will use, used to
+ * polulate the certificates included in the message
+ * @param pool certificates to use in try to build the path to the
+ * trust anchors.
+ * @param signed_data the output of the function, free with
+ * der_free_octet_string().
+ *
+ * @ingroup hx509_cms
+ */
+
 int
 hx509_cms_create_signed_1(hx509_context context,
 			  int flags,