Improve interface documentation

1 files changed, 19 insertions, 5 deletions

diff --git a/include/ncrypto/ncrypto.h b/include/ncrypto/ncrypto.h
index 8da49c0..c9b7329 100644
--- a/include/ncrypto/ncrypto.h
+++ b/include/ncrypto/ncrypto.h
@@ -32,6 +32,19 @@ Red Hat author: Miloslav Trmač <mitr@redhat.com> */
 
 #include <pkcs11.h>
 
+/* In general, semantics aspects that are not documented here are same as in
+   PCKS#11. */
+
+ /* Symmetric keys */
+
+struct ncr_symm_key;
+
+CK_RV ncr_symm_key_create (struct ncr_symm_key **key, CK_KEY_TYPE type,
+			   const void *value, size_t value_size);
+CK_RV ncr_symm_key_destroy (struct ncr_symm_key *key);
+
+ /* Digests */
+
 struct ncr_digest_session;
 
 /* Session lifetime management. */
@@ -49,17 +62,18 @@ CK_RV ncr_digest_final (struct ncr_digest_session *sess, void *dest,
 CK_RV ncr_digest (struct ncr_digest_session *sess, void *dest,
 		  size_t *dest_size_ptr, const void *data, size_t data_size);
 
+/* You'll get better performance by keeping a long-term digest session than
+   repeatedly calling this function. */
 CK_RV ncr_digest_standalone (CK_MECHANISM_TYPE mech, void *dest,
 			     size_t *dest_size_ptr, const void *data,
 			     size_t data_size);
 
-struct ncr_symm_cipher_session;
+ /* Symmetric encryption */
 
-struct ncr_symm_key;
+struct ncr_symm_cipher_session;
 
-CK_RV ncr_symm_key_create (struct ncr_symm_key **key, CK_KEY_TYPE type,
-			   const void *value, size_t value_size);
-CK_RV ncr_symm_key_destroy (struct ncr_symm_key *key);
+/* Note that for *_ECB and *_CBC, the input must be block-aligned.  For *_CBC_PAD,
+   it does not have to be. */
 
 /* Session lifetime management. */
 CK_RV ncr_symm_cipher_alloc (struct ncr_symm_cipher_session **sess,