Improve docs for ASN.1 bitstrings and their usage
diff --git a/include/mbedtls/asn1write.h b/include/mbedtls/asn1write.h
index d62853e..083601a 100644
--- a/include/mbedtls/asn1write.h
+++ b/include/mbedtls/asn1write.h
@@ -189,16 +189,18 @@
const char *text, size_t text_len );
/**
- * \brief Write a bitstring tag (MBEDTLS_ASN1_BIT_STRING) and
- * value in ASN.1 format
- * Note: function works backwards in data buffer
+ * \brief Write a bitstring tag (#MBEDTLS_ASN1_BIT_STRING) and
+ * value in ASN.1 format.
*
- * \param p reference to current position pointer
- * \param start start of the buffer (for bounds-checking)
- * \param buf the bitstring
- * \param bits the total number of bits in the bitstring
+ * \note This function works backwards in data buffer.
*
- * \return the length written or a negative error code
+ * \param p The reference to the current position pointer.
+ * \param start The start of the buffer, for bounds-checking.
+ * \param buf The bitstring to write.
+ * \param bits The total number of bits in the bitstring.
+ *
+ * \return The number of bytes written to \p p on success.
+ * \return A negative error code on failure.
*/
int mbedtls_asn1_write_bitstring( unsigned char **p, unsigned char *start,
const unsigned char *buf, size_t bits );
diff --git a/include/mbedtls/x509_csr.h b/include/mbedtls/x509_csr.h
index 0c6ccad..a3c2804 100644
--- a/include/mbedtls/x509_csr.h
+++ b/include/mbedtls/x509_csr.h
@@ -205,6 +205,14 @@
* \param key_usage key usage flags to set
*
* \return 0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
+ *
+ * \note The <code>decipherOnly</code> flag from the Key Usage
+ * extension is represented by bit 8 (i.e.
+ * <code>0x8000</code>), which cannot typically be represented
+ * in an unsigned char. Therefore, the flag
+ * <code>decipherOnly</code> (i.e.
+ * #MBEDTLS_X509_KU_DECIPHER_ONLY) cannot be set using this
+ * function.
*/
int mbedtls_x509write_csr_set_key_usage( mbedtls_x509write_csr *ctx, unsigned char key_usage );