gnutls_pkcs11_privkey_init: document limitation on created objecttmp-gnutls_3_5_x-backport-pkcs11-lock

Signed-off-by: Nikos Mavrogiannopoulos <nmav@gnutls.org>

2 files changed, 18 insertions, 3 deletions

diff --git a/lib/pkcs11_privkey.c b/lib/pkcs11_privkey.c
index 196d212553..4bf907ee6a 100644
--- a/lib/pkcs11_privkey.c
+++ b/lib/pkcs11_privkey.c
@@ -78,7 +78,13 @@ struct gnutls_pkcs11_privkey_st {
  * gnutls_pkcs11_privkey_init:
  * @key: A pointer to the type to be initialized
  *
- * This function will initialize an private key structure.
+ * This function will initialize an private key structure. This
+ * structure can be used for accessing an underlying PKCS#11 object.
+ *
+ * In versions of GnuTLS later than 3.5.11 the object is protected
+ * using locks and a single %gnutls_pkcs11_privkey_t can be re-used
+ * by many threads. However, for performance it is recommended to utilize
+ * one object per key per thread.
  *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.
@@ -386,7 +392,7 @@ _gnutls_pkcs11_privkey_sign_hash(gnutls_pkcs11_privkey_t key,
  *
  * Checks the status of the private key token.
  *
- * Returns: this function will return non-zero if the token 
+ * Returns: this function will return non-zero if the token
  * holding the private key is still available (inserted), and zero otherwise.
  * 
  * Since: 3.1.9
diff --git a/lib/privkey.c b/lib/privkey.c
index 76cef7ec79..2ea817cdad 100644
--- a/lib/privkey.c
+++ b/lib/privkey.c
@@ -300,7 +300,16 @@ _gnutls_privkey_get_public_mpis(gnutls_privkey_t key,
  * gnutls_privkey_init:
  * @key: A pointer to the type to be initialized
  *
- * This function will initialize a private key.
+ * This function will initialize a private key object. The object can
+ * be used to generate, import, and perform cryptographic operations
+ * on the associated private key.
+ *
+ * Note that when the underlying private key is a PKCS#11 key (i.e.,
+ * when imported with a PKCS#11 URI), the limitations of gnutls_pkcs11_privkey_init()
+ * apply to this object as well. In versions of GnuTLS later than 3.5.11 the object
+ * is protected using locks and a single %gnutls_privkey_t can be re-used
+ * by many threads. However, for performance it is recommended to utilize
+ * one object per key per thread.
  *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.