Documentation fixes
Added more elaborate comments and descriptions
diff --git a/include/mbedtls/pk_info.h b/include/mbedtls/pk_info.h
index a808c2c..d1d95ef 100644
--- a/include/mbedtls/pk_info.h
+++ b/include/mbedtls/pk_info.h
@@ -3,7 +3,10 @@
*
* \brief Public Key cryptography abstraction layer: object interface
*
- * Copyright (C) 2006-2017, ARM Limited, All Rights Reserved
+ * This file contains the info structure interface used by developers to
+ * provide engine-specific implementations of opaque key handling functions.
+ *
+ * Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -40,10 +43,16 @@
* Methods that opaque key pair objects must implement.
*
* Engines that interface with external cryptographic processors must
- * implement this interface. Platform-specific hardware accelerators
- * that can be used for all keys of a given type should use alternative
- * ("xxx_alt") interfaces instead. This interface allows using different
- * engines for each key.
+ * implement this interface. It allows using different engines for each key.
+ * Platform-specific hardware accelerators that can be used for all keys of
+ * a given type should not use this interface, but rather provide an
+ * alternative implementation of the respective cryptographic module - for
+ * example to use an RSA accelerator you can define MBEDTLS_RSA_ALT, and
+ * provide your own implementation of the RSA module.
+ *
+ * \warning: If you are using the PK interface to perform operations on
+ * keys, call the functions in pk.h. The interface in this file should only
+ * be used by implementers of opaque key engines.
*
* An engine for asymmetric cryptography must implement the interface
* described in this structure. The interface for the engine may be
@@ -68,14 +77,11 @@
* in the corresponding field. The corresponding function in pk.h will
* return MBEDTLS_ERR_PK_TYPE_MISMATCH in this case.
*
- * \note If you are using the PK interface to perform operations on
- * keys, call the functions in pk.h. The interface in this file should only
- * be used by implementers of opaque key engines.
*
* \warning: Do not declare this structure directly! It may be extended in
* future* versions of Mbed TLS. Call the macro
- * MBEDTLS_PK_OPAQUE_INFO_1() or MBEDTLS_PK_OPAQUE_INFO_ASYNC_1() instead.
- * These macros are guaranteed to take parameters with the same type
+ * MBEDTLS_PK_OPAQUE_INFO_1() instead.
+ * This macro is guaranteed to take parameters with the same type
* and semantics as previous versions and fill any new field of the
* structure with sensible values.
*/
@@ -105,7 +111,8 @@
* This function cannot fail. */
size_t (*get_bitlen)( const void *ctx );
- /** Tell if the context implements this type (e.g.\ ECKEY can do ECDSA).
+ /** Tell if the context implements the algorithm specified by
+ * the provided type (e.g.\ ECKEY can do ECDSA).
*
* mbedtls_pk_can_do() calls this function.
*