Documentation fix
Add relevant comments and explanations.
Fix indentation.
Add copyright notes.
diff --git a/include/mbedtls/pkcs11_client.h b/include/mbedtls/pkcs11_client.h
index 83aed51..978552d 100644
--- a/include/mbedtls/pkcs11_client.h
+++ b/include/mbedtls/pkcs11_client.h
@@ -2,7 +2,8 @@
* \file pkcs11_client.h
*
* \brief Generic wrapper for Cryptoki (PKCS#11) support
- *
+ */
+/*
* Copyright (C) 2017, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
@@ -87,36 +88,42 @@
* PKCS#11 token.
*
* \param ctx PK context, which must contain a transparent pk
- * object (type \c MBEDTLS_PK_RSA,
- * \c MBEDTLS_PK_RSASSA_PSS, \c MBEDTLS_PK_ECKEY or
- * \c MBEDTLS_PK_ECDSA).
- * \param flags Mask of \c MBEDTLS_PKCS11_FLAG_XXX and
- * \c MBEDTLS_PK_FLAG_XXX, applying as follows:
- * - \c MBEDTLS_PKCS11_FLAG_TOKEN: PKCS#11 \c CKA_TOKEN
+ * object (type #MBEDTLS_PK_RSA,
+ * #MBEDTLS_PK_RSASSA_PSS, #MBEDTLS_PK_ECKEY or
+ * #MBEDTLS_PK_ECDSA).
+ * \param flags Mask of #MBEDTLS_PKCS11_FLAG_XXX and
+ * #MBEDTLS_PK_FLAG_XXX, applying as follows:
+ * - #MBEDTLS_PKCS11_FLAG_TOKEN: PKCS#11 \c CKA_TOKEN
* flag: if set, import as token object; if clear,
* import as session object.
- * - \c MBEDTLS_PK_FLAG_EXTRACTABLE: PKCS#11
- * \c CKA_EXTRACTABLE flag: if set, the key will be
- * extractable at least in wrapped form; if clear,
- * the key will not be extractable at all.
- * - \c MBEDTLS_PK_FLAG_SENSITIVE: PKCS#11
- * \c CKA_SENSITIVE flag: if set, the key will be
- * not be extractable in plain form; if clear, the
- * key will be extractable at least in wrapped form.
- * - \c MBEDTLS_PK_FLAG_SIGN: if set, the private key
+ * - #MBEDTLS_PK_FLAG_EXTRACTABLE: PKCS#11
+ * \c CKA_EXTRACTABLE flag: if set, the private key
+ * will be extractable at least in wrapped form; if
+ * clear, the key will not be extractable at all.
+ * - #MBEDTLS_PK_FLAG_SENSITIVE: PKCS#11
+ * \c CKA_SENSITIVE flag: if set, the private key
+ * will not be extractable in plain form; if clear,
+ * the key will be extractable in plain form if
+ * #MBEDTLS_PK_FLAG_EXTRACTABLE is set.
+ * - #MBEDTLS_PK_FLAG_SIGN: if set, the private key
* will be authorized for signing.
- * - \c MBEDTLS_PK_FLAG_VERIFY: if set, the public key
+ * - #MBEDTLS_PK_FLAG_VERIFY: if set, the public key
* will be authorized for verification.
- * - \c MBEDTLS_PK_FLAG_DECRYPT: if set, the private key
+ * - #MBEDTLS_PK_FLAG_DECRYPT: if set, the private key
* will be authorized for signing.
- * - \c MBEDTLS_PK_FLAG_ENCRYPT: if set, the public key
+ * - #MBEDTLS_PK_FLAG_ENCRYPT: if set, the public key
* will be authorized for encryption.
*
- * \param hSession Cryptoki session.
+ * \param hSession Cryptoki session. The session must remain valid as long
+ * as the PK object is in use.
* \param hPublicKey If non-null, on output, Cryptoki handle of the public
- * key. If null, the public key is not imported.
+ * key. This handle must remain valid as long as the PK
+ * object is in use. If null, the public key is not
+ * imported.
* \param hPrivateKey If non-null, on output, Cryptoki handle of the private
- * key. If null, the private key is not imported.
+ * key. This handle must remain valid as long as the PK
+ * object is in use. If null, the private key is not
+ * imported.
*
* \return 0 on success,
* or MBEDTLS_ERR_PK_XXX error code.