Make crypto structs opaque

It's important to be clear that the contents of the crypto structs are not
part of the API, and not guaranteed to be the same between versions. The
only guarantee is that the sizes of the structs will not shrink. If the
structs grow, this is an ABI break, but not an API break, as the
user-allocated object may not be big enough for the new larger struct. A
recompile of the application with the new header will fix this.

XXX This makes crypto structs partially opaque. I've left in a few things
that we could promise will always be present in the structs. If we choose
not to always promise these, we can change what's in the crypto_structs.h
file.

Author: Patater

include/psa/crypto_struct.h

@@ -0,0 +1,76 @@
+/**
+ * \file psa/crypto_struct.h
+ *
+ * \brief PSA cryptography module: Mbed TLS structured type implementations
+ *
+ * \note This file may not be included directly. Applications must
+ * include psa/crypto.h.
+ *
+ * This file contains the definitions of some data structures with
+ * implementation-specific sizes.
+ *
+ * In implementations with isolation between the application and the
+ * cryptography module, it is expected that the front-end and the back-end
+ * would have different versions of this file.
+ */
+/*
+ *  Copyright (C) 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)
+ */
+
+#ifndef PSA_CRYPTO_STRUCT_H
+#define PSA_CRYPTO_STRUCT_H
+
+struct psa_hash_operation_s
+{
+    psa_algorithm_t alg;
+    uint8_t reserved[217];
+};
+
+struct psa_mac_operation_s
+{
+    psa_algorithm_t alg;
+    uint8_t reserved[353];
+};
+
+struct psa_cipher_operation_s
+{
+    psa_algorithm_t alg;
+    uint8_t reserved[97];
+};
+
+struct psa_crypto_generator_s
+{
+    psa_algorithm_t alg;
+    size_t capacity;
+    uint8_t reserved[497];
+};
+
+#define PSA_CRYPTO_GENERATOR_INIT {0, 0, {0}}
+static inline struct psa_crypto_generator_s psa_crypto_generator_init( void )
+{
+    const struct psa_crypto_generator_s v = PSA_CRYPTO_GENERATOR_INIT;
+    return( v );
+}
+
+struct psa_key_policy_s
+{
+    psa_key_usage_t usage;
+    psa_algorithm_t alg;
+};
+
+#endif /* PSA_CRYPTO_STRUCT_H */

library/include/crypto_struct.h renamed to library/include/crypto_struct_impl.h

@@ -1,17 +1,19 @@
 /**
- * \file crypto_struct.h
+ * \file crypto_struct_impl.h
  *
- * \brief PSA cryptography module: Mbed TLS structured type implementations
- *
- * \note This file may not be included directly. Applications must
- * include psa/crypto.h.
+ * \brief Mbed Crypto structured type implementations
  *
  * This file contains the definitions of some data structures with
  * implementation-specific definitions.
  *
- * In implementations with isolation between the application and the
- * cryptography module, it is expected that the front-end and the back-end
- * would have different versions of this file.
+ * The definitions in this file provide the implementation-specific detail of
+ * the structs defined in psa/crypto_struct.h for use by the library itself
+ * (not users of the library). The implementation-specific detail here is free
+ * to change between versions of the library, so long as the size of the
+ * structs never decreases (unless an ABI break is tolerable). The size of the
+ * structs in psa/crypto_struct.h must be at least as big as those in this file
+ * in order for users of the library to be able to allocate sufficient memory
+ * for these structs.
  */
 /*
  *  Copyright (C) 2018, ARM Limited, All Rights Reserved
@@ -32,8 +34,8 @@
  *  This file is part of mbed TLS (https://tls.mbed.org)
  */
 
-#ifndef PSA_CRYPTO_STRUCT_H
-#define PSA_CRYPTO_STRUCT_H
+#ifndef MC_CRYPTO_STRUCT_IMPL_H
+#define MC_CRYPTO_STRUCT_IMPL_H
 
 /* Include the Mbed TLS configuration file, the way Mbed TLS does it
  * in each of its header files. */
@@ -43,6 +45,8 @@
 #include MBEDTLS_CONFIG_FILE
 #endif
 
+#include "utils.h"
+
 #include "mbedtls/cipher.h"
 #include "mbedtls/cmac.h"
 #include "mbedtls/gcm.h"
@@ -55,7 +59,7 @@
 #include "mbedtls/sha256.h"
 #include "mbedtls/sha512.h"
 
-struct psa_hash_operation_s
+typedef struct psa_hash_operation_impl_s
 {
     psa_algorithm_t alg;
     union
@@ -83,7 +87,11 @@ struct psa_hash_operation_s
         mbedtls_sha512_context sha512;
 #endif
     } ctx;
-};
+} psa_hash_operation_impl_t;
+
+STATIC_ASSERT(
+    sizeof(psa_hash_operation_t) >= sizeof(psa_hash_operation_impl_t),
+    psa_hash_operation_t_too_small);
 
 #if defined(MBEDTLS_MD_C)
 typedef struct
@@ -95,7 +103,7 @@ typedef struct
 } psa_hmac_internal_data;
 #endif /* MBEDTLS_MD_C */
 
-struct psa_mac_operation_s
+typedef struct psa_mac_operation_impl_s
 {
     psa_algorithm_t alg;
     unsigned int key_set : 1;
@@ -114,9 +122,13 @@ struct psa_mac_operation_s
         mbedtls_cipher_context_t cmac;
 #endif
     } ctx;
-};
+} psa_mac_operation_impl_t;
 
-struct psa_cipher_operation_s
+STATIC_ASSERT(
+    sizeof(psa_mac_operation_t) >= sizeof(psa_mac_operation_impl_t),
+    psa_mac_operation_t_too_small);
+
+typedef struct psa_cipher_operation_impl_s
 {
     psa_algorithm_t alg;
     unsigned int key_set : 1;
@@ -128,7 +140,11 @@ struct psa_cipher_operation_s
     {
         mbedtls_cipher_context_t cipher;
     } ctx;
-};
+} psa_cipher_operation_impl_t;
+
+STATIC_ASSERT(
+    sizeof(psa_cipher_operation_t) >= sizeof(psa_cipher_operation_impl_t),
+    psa_cipher_operation_t_too_small);
 
 #if defined(MBEDTLS_MD_C)
 typedef struct
@@ -177,7 +193,7 @@ typedef struct psa_tls12_prf_generator_s
 } psa_tls12_prf_generator_t;
 #endif /* MBEDTLS_MD_C */
 
-struct psa_crypto_generator_s
+typedef struct psa_crypto_generator_impl_s
 {
     psa_algorithm_t alg;
     size_t capacity;
@@ -193,19 +209,10 @@ struct psa_crypto_generator_s
         psa_tls12_prf_generator_t tls12_prf;
 #endif
     } ctx;
-};
+} psa_crypto_generator_impl_t;
 
-#define PSA_CRYPTO_GENERATOR_INIT {0, 0, {{0, 0}}}
-static inline struct psa_crypto_generator_s psa_crypto_generator_init( void )
-{
-    const struct psa_crypto_generator_s v = PSA_CRYPTO_GENERATOR_INIT;
-    return( v );
-}
-
-struct psa_key_policy_s
-{
-    psa_key_usage_t usage;
-    psa_algorithm_t alg;
-};
+STATIC_ASSERT(
+    sizeof(psa_crypto_generator_t) >= sizeof(psa_crypto_generator_impl_t),
+    psa_crypto_generator_t_too_small);
 
-#endif /* PSA_CRYPTO_STRUCT_H */
+#endif /* MC_CRYPTO_STRUCT_IMPL_H */