arm_hal_aes.h

00001 /*
00002  * Copyright (c) 2014-2018, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 /**
00019  * \file arm_hal_aes.h
00020  * \brief AES Platform API
00021  */
00022 
00023 #ifndef ARM_HAL_AES_H_
00024 #define ARM_HAL_AES_H_
00025 
00026 /* The network library requires a simple AES implementation for its
00027  * IEEE 802.15.4 security. The expectation is that 802.15.4 devices will have
00028  * some hardware acceleration, which should be made available through this API.
00029  *
00030  * If no hardware acceleration is available, the API can be easily hooked up to
00031  * an external software library such as mbed TLS.
00032  *
00033  * To simplify porting, the API is used single-threaded, so that no special care
00034  * is needed to maintain global context or state in the hardware accelerator.
00035  */
00036 
00037 #include "ns_types.h"
00038 
00039 
00040 #ifdef __cplusplus
00041 extern "C" {
00042 #endif
00043 
00044 /* This API must be able to provide this many simultaneous contexts */
00045 #if 1 /* config option for 802.15.4-2015? */
00046 #define ARM_AES_MBEDTLS_CONTEXT_MIN 2 /**</ event loop and driver rx callback context */
00047 #else
00048 #define ARM_AES_MBEDTLS_CONTEXT_MIN 1 /**</ event loop use only */
00049 #endif
00050 
00051 typedef struct arm_aes_context arm_aes_context_t;
00052 
00053 /**
00054  * \brief Set the AES key
00055  *
00056  * This function sets the 128-bit AES key that will be used for future
00057  * calls to arm_aes_encrypt(). The key must be copied by the function.
00058  * Function must return unique pointer for every started AES context.
00059  *
00060  * \param key pointer to 128-bit AES key
00061  *
00062  * \return Pointer to aes context
00063  * \return NULL if aes context allocation fail
00064  */
00065 arm_aes_context_t *arm_aes_start(const uint8_t key[__static 16]);
00066 
00067 /**
00068  * \brief This function performs dst=E[preset key,src] (Simple ECB block).
00069  *
00070  * This function performs a single-block AES encryption, using the preset key.
00071  * It is called between arm_aes_start() and arm_aes_finish().
00072  * Note that src and dst pointers may be equal.
00073  *
00074  * \param aes_context Pointer for allocated
00075  * \param src pointer to 128-bit plaintext in
00076  * \param dst pointer for 128-bit ciphertext out
00077  */
00078 extern void arm_aes_encrypt(
00079     arm_aes_context_t *aes_context,
00080     const uint8_t src[__static 16],
00081     uint8_t dst[__static 16]);
00082 
00083 /**
00084  * \brief Finish AES operations
00085  *
00086  * This function is called to terminate a series of AES operations.
00087  * It may be a no-op, or it may disable AES hardware. Use of the preset key is
00088  * no longer valid after this call and aes context will be freed.
00089  */
00090 void arm_aes_finish(arm_aes_context_t *aes_context);
00091 
00092 #ifdef __cplusplus
00093 }
00094 #endif
00095 #endif /* ARM_HAL_AES_H_ */