le_iks_aesMilenage_interface.h

Go to the documentation of this file.
    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_iks_aesMilenage IoT Keystore AES Milenage API
   14  *
   15  * @ref le_iks_aesMilenage_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * This module provides APIs for performing Milenage authentication and key derivation using AES as
   20  * the PRP.
   21  *
   22  * <HR>
   23  *
   24  * Copyright (C) Sierra Wireless Inc.
   25  */
   26 /**
   27  * @file le_iks_aesMilenage_interface.h
   28  *
   29  * Legato @ref c_iks API
   30  *
   31  * Copyright (C) Sierra Wireless Inc.
   32  */
   33 
   34 #ifndef LE_IKS_AESMILENAGE_INTERFACE_H_INCLUDE_GUARD
   35 #define LE_IKS_AESMILENAGE_INTERFACE_H_INCLUDE_GUARD
   36 
   37 
   38 #include "legato.h"
   39 
   40 // Interface specific includes
   41 #include "le_iks_interface.h"
   42 
   43 // Internal includes for this interface
   44 #include "le_iks_aesMilenage_common.h"
   45 /** @addtogroup le_iks_aesMilenage le_iks_aesMilenage API Reference
   46  * @{
   47  * @file le_iks_aesMilenage_common.h
   48  * @file le_iks_aesMilenage_interface.h **/
   49 //--------------------------------------------------------------------------------------------------
   50 /**
   51  * Type for handler called when a server disconnects.
   52  */
   53 //--------------------------------------------------------------------------------------------------
   54 typedef void (*le_iks_aesMilenage_DisconnectHandler_t)(void *);
   55 
   56 //--------------------------------------------------------------------------------------------------
   57 /**
   58  *
   59  * Connect the current client thread to the service providing this API. Block until the service is
   60  * available.
   61  *
   62  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   63  * called before any other functions in this API.  Normally, ConnectService is automatically called
   64  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   65  *
   66  * This function is created automatically.
   67  */
   68 //--------------------------------------------------------------------------------------------------
   69 void le_iks_aesMilenage_ConnectService
   70 (
   71     void
   72 );
   73 
   74 //--------------------------------------------------------------------------------------------------
   75 /**
   76  *
   77  * Try to connect the current client thread to the service providing this API. Return with an error
   78  * if the service is not available.
   79  *
   80  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   81  * called before any other functions in this API.  Normally, ConnectService is automatically called
   82  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   83  *
   84  * This function is created automatically.
   85  *
   86  * @return
   87  *  - LE_OK if the client connected successfully to the service.
   88  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
   89  *    bound.
   90  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
   91  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
   92  */
   93 //--------------------------------------------------------------------------------------------------
   94 le_result_t le_iks_aesMilenage_TryConnectService
   95 (
   96     void
   97 );
   98 
   99 //--------------------------------------------------------------------------------------------------
  100 /**
  101  * Set handler called when server disconnection is detected.
  102  *
  103  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  104  * to continue without exiting, it should call longjmp() from inside the handler.
  105  */
  106 //--------------------------------------------------------------------------------------------------
  107 LE_FULL_API void le_iks_aesMilenage_SetServerDisconnectHandler
  108 (
  109     le_iks_aesMilenage_DisconnectHandler_t disconnectHandler,
  110     void *contextPtr
  111 );
  112 
  113 //--------------------------------------------------------------------------------------------------
  114 /**
  115  *
  116  * Disconnect the current client thread from the service providing this API.
  117  *
  118  * Normally, this function doesn't need to be called. After this function is called, there's no
  119  * longer a connection to the service, and the functions in this API can't be used. For details, see
  120  * @ref apiFilesC_client.
  121  *
  122  * This function is created automatically.
  123  */
  124 //--------------------------------------------------------------------------------------------------
  125 void le_iks_aesMilenage_DisconnectService
  126 (
  127     void
  128 );
  129 
  130 
  131 //--------------------------------------------------------------------------------------------------
  132 /**
  133  * Calculates the network authentication code MAC-A using the Milenage algorithm set with AES-128 as
  134  * the block cipher.  Implements the Milenage function f1.
  135  *
  136  * @return
  137  *      LE_OK if successful.
  138  *      LE_BAD_PARAMETER if either K or OPc reference is invalid
  139  *                       or if either K or OPc key type is invalid
  140  *                       or if either randPtr, amfPtr, sqnPtr, or macaPtr is NULL.
  141  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  142  *      LE_FAULT if there was an internal error.
  143  */
  144 //--------------------------------------------------------------------------------------------------
  145 le_result_t le_iks_aesMilenage_GetMacA
  146 (
  147     uint64_t kRef,
  148         ///< [IN] Reference to K.
  149     uint64_t opcRef,
  150         ///< [IN] Reference to OPc.
  151     const uint8_t* randPtr,
  152         ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
  153     size_t randSize,
  154         ///< [IN]
  155     const uint8_t* amfPtr,
  156         ///< [IN] Authentication management field, AMF.
  157         ///<   Assumed to be AMF_SIZE bytes.
  158     size_t amfSize,
  159         ///< [IN]
  160     const uint8_t* sqnPtr,
  161         ///< [IN] Sequence number, SQN.
  162         ///<   Assumed to be SQN_SIZE bytes.
  163     size_t sqnSize,
  164         ///< [IN]
  165     uint8_t* macaPtr,
  166         ///< [OUT] Buffer to hold the network authentication code.
  167         ///<   Assumed to be MACA_SIZE bytes.
  168     size_t* macaSizePtr
  169         ///< [INOUT]
  170 );
  171 
  172 //--------------------------------------------------------------------------------------------------
  173 /**
  174  * Calculates the re-synchronisation authentication code MAC-S using the Milenage algorithm set with
  175  * AES-128 as the block cipher.  Implements the Milenage function f1*.
  176  *
  177  * @return
  178  *      LE_OK if successful.
  179  *      LE_BAD_PARAMETER if either K or OPc reference is invalid
  180  *                       or if either K or OPc key type is invalid
  181  *                       or if either randPtr, amfPtr, sqnPtr, or macsPtr is NULL.
  182  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  183  *      LE_FAULT if there was an internal error.
  184  */
  185 //--------------------------------------------------------------------------------------------------
  186 le_result_t le_iks_aesMilenage_GetMacS
  187 (
  188     uint64_t kRef,
  189         ///< [IN] Reference to K.
  190     uint64_t opcRef,
  191         ///< [IN] Reference to OPc.
  192     const uint8_t* randPtr,
  193         ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
  194     size_t randSize,
  195         ///< [IN]
  196     const uint8_t* amfPtr,
  197         ///< [IN] Authentication management field, AMF.
  198         ///<   Assumed to be AMF_SIZE bytes.
  199     size_t amfSize,
  200         ///< [IN]
  201     const uint8_t* sqnPtr,
  202         ///< [IN] Sequence number, SQN.
  203         ///<    Assumed to be SQN_SIZE bytes.
  204     size_t sqnSize,
  205         ///< [IN]
  206     uint8_t* macsPtr,
  207         ///< [OUT] Buffer to hold the re-sync authentication code.
  208         ///<   Assumed to be MACS_SIZE bytes.
  209     size_t* macsSizePtr
  210         ///< [INOUT]
  211 );
  212 
  213 //--------------------------------------------------------------------------------------------------
  214 /**
  215  * Derives authentication response and keys using the Milenage algorithm set with AES-128 as the
  216  * block cipher.  Implements the Milenage functions f2, f3, f4, f5.
  217  *
  218  * @return
  219  *      LE_OK if successful.
  220  *      LE_BAD_PARAMETER if either K or OPc reference is invalid
  221  *                       or if either K or OPc key type is invalid
  222  *                       or if either randPtr, resPtr, ckPtr, ikPtr or akPtr is NULL.
  223  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  224  *      LE_FAULT if there was an internal error.
  225  */
  226 //--------------------------------------------------------------------------------------------------
  227 le_result_t le_iks_aesMilenage_GetKeys
  228 (
  229     uint64_t kRef,
  230         ///< [IN] Reference to K.
  231     uint64_t opcRef,
  232         ///< [IN] Reference to OPc.
  233     const uint8_t* randPtr,
  234         ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
  235     size_t randSize,
  236         ///< [IN]
  237     uint8_t* resPtr,
  238         ///< [OUT] Buffer to hold the authentication response RES.
  239         ///<   Assumed to be RES_SIZE bytes.
  240     size_t* resSizePtr,
  241         ///< [INOUT]
  242     uint8_t* ckPtr,
  243         ///< [OUT] Buffer to hold the confidentiality key CK.
  244         ///<   Assumed to be CK_SIZE bytes.
  245     size_t* ckSizePtr,
  246         ///< [INOUT]
  247     uint8_t* ikPtr,
  248         ///< [OUT] Buffer to hold the integrity key IK.
  249         ///<   Assumed to be IK_SIZE bytes.
  250     size_t* ikSizePtr,
  251         ///< [INOUT]
  252     uint8_t* akPtr,
  253         ///< [OUT] Buffer to hold the anonymity key AK.
  254         ///<   Assumed to be AK_SIZE bytes.
  255     size_t* akSizePtr
  256         ///< [INOUT]
  257 );
  258 
  259 //--------------------------------------------------------------------------------------------------
  260 /**
  261  * Derives the anonymity key for the re-synchronisation message using the Milenage algorithm set
  262  * with AES-128 as the block cipher.  Implements the Milenage functions f5*.
  263  *
  264  * @return
  265  *      LE_OK if successful.
  266  *      LE_BAD_PARAMETER if either K or OPc reference is invalid
  267  *                       or if either K or OPc key type is invalid
  268  *                       or if either randPtr or akPtr is NULL.
  269  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  270  *      LE_FAULT if there was an internal error.
  271  */
  272 //--------------------------------------------------------------------------------------------------
  273 le_result_t le_iks_aesMilenage_GetAk
  274 (
  275     uint64_t kRef,
  276         ///< [IN] Reference to K.
  277     uint64_t opcRef,
  278         ///< [IN] Reference to OPc.
  279     const uint8_t* randPtr,
  280         ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
  281     size_t randSize,
  282         ///< [IN]
  283     uint8_t* akPtr,
  284         ///< [OUT] Buffer to hold the anonymity key AK.
  285         ///<   Assumed to be AK_SIZE bytes.
  286     size_t* akSizePtr
  287         ///< [INOUT]
  288 );
  289 
  290 //--------------------------------------------------------------------------------------------------
  291 /**
  292  * Derive an OPc value from the specified K and the internal OP value.
  293  *
  294  * @note
  295  *      This function is generally not used in devices as most OPc values are derived in a factory
  296  *      or network setting.
  297  *
  298  * @return
  299  *      LE_OK if successful.
  300  *      LE_BAD_PARAMETER if OP reference is invalid
  301  *                       or if kPtr, opcPtr is NULL.
  302  *      LE_FAULT if there was an internal error.
  303  */
  304 //--------------------------------------------------------------------------------------------------
  305 le_result_t le_iks_aesMilenage_DeriveOpc
  306 (
  307     uint64_t opRef,
  308         ///< [IN] Reference to OP key.
  309     const uint8_t* kPtr,
  310         ///< [IN] K.
  311     size_t kSize,
  312         ///< [IN]
  313     uint8_t* opcPtr,
  314         ///< [OUT] Buffer to hold the OPc value.
  315     size_t* opcSizePtr
  316         ///< [INOUT]
  317 );
  318 
  319 /** @} **/
  320 
  321 #endif // LE_IKS_AESMILENAGE_INTERFACE_H_INCLUDE_GUARD
le_iks_aesMilenage_DisconnectHandler_t
void(* le_iks_aesMilenage_DisconnectHandler_t)(void *)
Definition: le_iks_aesMilenage_interface.h:54


le_result_t
le_result_t
Definition: le_basics.h:46


le_iks_aesMilenage_DisconnectService
void le_iks_aesMilenage_DisconnectService(void)


le_iks_aesMilenage_TryConnectService
le_result_t le_iks_aesMilenage_TryConnectService(void)


le_iks_aesMilenage_SetServerDisconnectHandler
LE_FULL_API void le_iks_aesMilenage_SetServerDisconnectHandler(le_iks_aesMilenage_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_iks_aesMilenage_GetMacS
le_result_t le_iks_aesMilenage_GetMacS(uint64_t kRef, uint64_t opcRef, const uint8_t *randPtr, size_t randSize, const uint8_t *amfPtr, size_t amfSize, const uint8_t *sqnPtr, size_t sqnSize, uint8_t *macsPtr, size_t *macsSizePtr)


le_iks_aesMilenage_GetMacA
le_result_t le_iks_aesMilenage_GetMacA(uint64_t kRef, uint64_t opcRef, const uint8_t *randPtr, size_t randSize, const uint8_t *amfPtr, size_t amfSize, const uint8_t *sqnPtr, size_t sqnSize, uint8_t *macaPtr, size_t *macaSizePtr)


le_iks_aesMilenage_ConnectService
void le_iks_aesMilenage_ConnectService(void)


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40



le_iks_aesMilenage_GetKeys
le_result_t le_iks_aesMilenage_GetKeys(uint64_t kRef, uint64_t opcRef, const uint8_t *randPtr, size_t randSize, uint8_t *resPtr, size_t *resSizePtr, uint8_t *ckPtr, size_t *ckSizePtr, uint8_t *ikPtr, size_t *ikSizePtr, uint8_t *akPtr, size_t *akSizePtr)


le_iks_interface.h


le_iks_aesMilenage_DeriveOpc
le_result_t le_iks_aesMilenage_DeriveOpc(uint64_t opRef, const uint8_t *kPtr, size_t kSize, uint8_t *opcPtr, size_t *opcSizePtr)


le_iks_aesMilenage_GetAk
le_result_t le_iks_aesMilenage_GetAk(uint64_t kRef, uint64_t opcRef, const uint8_t *randPtr, size_t randSize, uint8_t *akPtr, size_t *akSizePtr)


le_iks_aesMilenage_common.h