Documentation fix
Add relevant comments and explanations.
Fix indentation.
Add copyright notes.
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index 43d001c..96d158b 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -513,7 +513,7 @@
* 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,
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.
diff --git a/library/ecdsa.c b/library/ecdsa.c
index 0f33b83..dba303b 100644
--- a/library/ecdsa.c
+++ b/library/ecdsa.c
@@ -289,9 +289,6 @@
/*
* 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 @@
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 @@
}
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 );
}
/*
diff --git a/library/pkcs11_client.c b/library/pkcs11_client.c
index 040b971..700587b 100644
--- a/library/pkcs11_client.c
+++ b/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 @@
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 @@
* 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 @@
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
diff --git a/programs/util/syslog2stderr.c b/programs/util/syslog2stderr.c
index 6a636ec..3e34985 100644
--- a/programs/util/syslog2stderr.c
+++ b/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>
diff --git a/tests/scripts/pkcs11-client-test.sh b/tests/scripts/pkcs11-client-test.sh
index aaf7d94..37e08c7 100755
--- a/tests/scripts/pkcs11-client-test.sh
+++ b/tests/scripts/pkcs11-client-test.sh
@@ -14,6 +14,8 @@
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