Documentation fix

Add relevant comments and explanations.
Fix indentation.
Add copyright notes.

include/mbedtls/ecp.h

@@ -513,7 +513,7 @@ int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen,
  *                  The output is the group's OID wrapped as ASN.1.
  *
  * \param grp       ECP group used
- * \param buf       Buffer to write to
+ * \param p         Buffer to write to
  * \param size      Buffer size
  *
  * \return          Number of bytes written to \c buf,

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 @@ int mbedtls_pk_setup_pkcs11( mbedtls_pk_context *ctx,
  *                      PKCS#11 token. 
  *
  * \param ctx           PK context, which must contain a transparent pk
- *                      object (type \c MBEDTLS_PK_RSA,
+ *                      object (type #MBEDTLS_PK_RSA,
- *                      \c MBEDTLS_PK_RSASSA_PSS, \c MBEDTLS_PK_ECKEY or
+ *                      #MBEDTLS_PK_RSASSA_PSS, #MBEDTLS_PK_ECKEY or
- *                      \c MBEDTLS_PK_ECDSA).
+ *                      #MBEDTLS_PK_ECDSA).
- * \param flags         Mask of \c MBEDTLS_PKCS11_FLAG_XXX and
+ * \param flags         Mask of #MBEDTLS_PKCS11_FLAG_XXX and
- *                      \c MBEDTLS_PK_FLAG_XXX, applying as follows:
+ *                      #MBEDTLS_PK_FLAG_XXX, applying as follows:
- *                      - \c MBEDTLS_PKCS11_FLAG_TOKEN: PKCS#11 \c CKA_TOKEN
+ *                      - #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
+ *                      - #MBEDTLS_PK_FLAG_EXTRACTABLE: PKCS#11
- *                        \c CKA_EXTRACTABLE flag: if set, the key will be
+ *                        \c CKA_EXTRACTABLE flag: if set, the private key
- *                        extractable at least in wrapped form; if clear,
+ *                        will be extractable at least in wrapped form; if
- *                        the key will not be extractable at all.
+ *                        clear, the key will not be extractable at all.
- *                      - \c MBEDTLS_PK_FLAG_SENSITIVE: PKCS#11
+ *                      - #MBEDTLS_PK_FLAG_SENSITIVE: PKCS#11
- *                        \c CKA_SENSITIVE flag: if set, the key will be
+ *                        \c CKA_SENSITIVE flag: if set, the private key
- *                        not be extractable in plain form; if clear, the
+ *                        will not be extractable in plain form; if clear,
- *                        key will be extractable at least in wrapped form.
+ *                        the key will be extractable in plain form if
- *                      - \c MBEDTLS_PK_FLAG_SIGN: if set, the private key
+ *                        #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.

library/ecdsa.c

@@ -289,9 +289,6 @@ cleanup:
 /*
  * Convert a signature to a raw concatenation of {r, s}
  */
-/*int mbedtls_ecdsa_signature_to_raw( const unsigned char *sig,
-                            size_t ssize, uint16_t byte_len,
-                            unsigned char *buf, size_t* slen )*/
 int mbedtls_ecdsa_signature_to_raw( const unsigned char *sig,
                             size_t ssize, uint16_t byte_len,
                             unsigned char *buf, size_t bufsize,
@@ -305,7 +302,7 @@ int mbedtls_ecdsa_signature_to_raw( const unsigned char *sig,
 
     if( 2 * byte_len > bufsize )
     {
-        return MBEDTLS_ERR_ECP_BAD_INPUT_DATA;
+        return (MBEDTLS_ERR_ECP_BAD_INPUT_DATA);
     }
 
     mbedtls_mpi_init( &r );
@@ -326,29 +323,30 @@ int mbedtls_ecdsa_signature_to_raw( const unsigned char *sig,
     }
 
     if( ( ret = mbedtls_asn1_get_mpi( &p, end, &r ) ) != 0 ||
-            ( ret = mbedtls_asn1_get_mpi( &p, end, &s ) ) != 0 )
+        ( ret = mbedtls_asn1_get_mpi( &p, end, &s ) ) != 0 )
     {
         ret += MBEDTLS_ERR_ECP_BAD_INPUT_DATA;
         goto cleanup;
     }
     p = (unsigned char *) buf;
-    if( ( ret = mbedtls_mpi_write_binary(&r, p, byte_len) ) )
+    if( ( ret = mbedtls_mpi_write_binary( &r, p, byte_len) ) )
     {
         ret += MBEDTLS_ERR_ECP_BAD_INPUT_DATA;
         goto cleanup;
     }
     p += byte_len;
-    if( ( ret = mbedtls_mpi_write_binary(&s, p, byte_len) ) )
+    if( ( ret = mbedtls_mpi_write_binary( &s, p, byte_len) ) )
     {
         ret += MBEDTLS_ERR_ECP_BAD_INPUT_DATA;
         goto cleanup;
     }
     *buflen = 2*byte_len;
-    cleanup:
-        mbedtls_mpi_free( &r );
-        mbedtls_mpi_free( &s );
 
-        return( ret );
+cleanup:
+    mbedtls_mpi_free( &r );
+    mbedtls_mpi_free( &s );
+
+    return( ret );
 }
 
 /*

library/pkcs11_client.c

@@ -29,7 +29,6 @@
 
 #include <stdint.h>
 #include <string.h>
-#include <pkcs11.h>
 
 #include "mbedtls/pkcs11_client.h"
 
@@ -144,7 +143,7 @@ static int pkcs11_sign( void *ctx_arg,
     CK_RV rv;
     CK_MECHANISM mechanism = {0, NULL_PTR, 0};
     CK_ULONG ck_sig_len;
-
+    (void)(md_alg);
     /* This function takes size_t arguments but the underlying layer
        takes unsigned long. Either type may be smaller than the other.
        Legitimate values won't overflow either type but we still need
@@ -180,7 +179,8 @@ static int pkcs11_sign( void *ctx_arg,
          * each in the form of a big-endian byte sequence, with r and s
          * having the same length as the base point.
          *
-         * A standard ECDSA signature is encoded in ASN.1:
+         * This library encodes ECDSA signatures in ASN.1 as documented
+         * for mbedtls_ecdsa_write_signature:
          *   SEQUENCE {
          *     r INTEGER,
          *     s INTEGER
@@ -315,7 +315,7 @@ exit:
 static const mbedtls_pk_info_t mbedtls_pk_pkcs11_info =
     MBEDTLS_PK_OPAQUE_INFO_1( "pkcs11"
                               , pkcs11_pk_get_bitlen
-                              , pkcs11_pk_can_do //can_do
+                              , pkcs11_pk_can_do
                               , pkcs11_pk_signature_size
                               , pkcs11_verify
                               , pkcs11_sign

programs/util/syslog2stderr.c

@@ -1,3 +1,31 @@
+/** \brief Syslog to stderr wrapper for Unix-like systems
+ *
+ * By dynamically linking this module into an executable, any message sent to the system logs
+ * via the POSIX or Linux API is instead redirected to standard error.
+*
+* Compile this program with `cc -fPID -shared -o syslog2stderr.so syslog2stderr.c -ldl`
+* and load it dynamically when running `myprogram` with
+* `LD_PRELOAD=/path/to/syslog2stderr.so myprogram`.
+* On macOS, replace `LD_PRELOAD` by `DYLD_PRELOAD`.
+ */
+ /**  
+ *  Copyright (C) 2017-2018, ARM Limited, All Rights Reserved
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  This file is part of mbed TLS (https://tls.mbed.org)
+ */
 #include <dlfcn.h>
 #include <stdarg.h>
 #include <stdio.h>

tests/scripts/pkcs11-client-test.sh

@@ -14,6 +14,8 @@ elif [ -e ../../../library/aes.c ]; then
 else
   unset TOPDIR
 fi
+# The SoftHSM library sends error messages to the system logs. If possible, send
+# the messages to standard error instead, by overloading the logging functions.
 if [ -n "${TOPDIR+1}" ] &&
      make -C "$TOPDIR/programs" util/syslog2stderr.so >/dev/null 2>&1
 then