le_iks_aesMilenage_interface.h

    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 //--------------------------------------------------------------------------------------------------
   46 /**
   47  * Type for handler called when a server disconnects.
   48  */
   49 //--------------------------------------------------------------------------------------------------
   50 typedef void (*le_iks_aesMilenage_DisconnectHandler_t)(void *);
   51 
   52 //--------------------------------------------------------------------------------------------------
   53 /**
   54  *
   55  * Connect the current client thread to the service providing this API. Block until the service is
   56  * available.
   57  *
   58  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   59  * called before any other functions in this API.  Normally, ConnectService is automatically called
   60  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   61  *
   62  * This function is created automatically.
   63  */
   64 //--------------------------------------------------------------------------------------------------
   65 void le_iks_aesMilenage_ConnectService
   66 (
   67     void
   68 );
   69 
   70 //--------------------------------------------------------------------------------------------------
   71 /**
   72  *
   73  * Try to connect the current client thread to the service providing this API. Return with an error
   74  * if the service is not available.
   75  *
   76  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   77  * called before any other functions in this API.  Normally, ConnectService is automatically called
   78  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   79  *
   80  * This function is created automatically.
   81  *
   82  * @return
   83  *  - LE_OK if the client connected successfully to the service.
   84  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
   85  *    bound.
   86  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
   87  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
   88  */
   89 //--------------------------------------------------------------------------------------------------
   90 le_result_t le_iks_aesMilenage_TryConnectService
   91 (
   92     void
   93 );
   94 
   95 //--------------------------------------------------------------------------------------------------
   96 /**
   97  * Set handler called when server disconnection is detected.
   98  *
   99  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  100  * to continue without exiting, it should call longjmp() from inside the handler.
  101  */
  102 //--------------------------------------------------------------------------------------------------
  103 LE_FULL_API void le_iks_aesMilenage_SetServerDisconnectHandler
  104 (
  105     le_iks_aesMilenage_DisconnectHandler_t disconnectHandler,
  106     void *contextPtr
  107 );
  108 
  109 //--------------------------------------------------------------------------------------------------
  110 /**
  111  *
  112  * Disconnect the current client thread from the service providing this API.
  113  *
  114  * Normally, this function doesn't need to be called. After this function is called, there's no
  115  * longer a connection to the service, and the functions in this API can't be used. For details, see
  116  * @ref apiFilesC_client.
  117  *
  118  * This function is created automatically.
  119  */
  120 //--------------------------------------------------------------------------------------------------
  121 void le_iks_aesMilenage_DisconnectService
  122 (
  123     void
  124 );
  125 
  126 
  127 //--------------------------------------------------------------------------------------------------
  128 /**
  129  * Calculates the network authentication code MAC-A using the Milenage algorithm set with AES-128 as
  130  * the block cipher.  Implements the Milenage function f1.
  131  *
  132  * @return
  133  *      LE_OK if successful.
  134  *      LE_BAD_PARAMETER if either K or OPc reference is invalid
  135  *                       or if either K or OPc key type is invalid
  136  *                       or if either randPtr, amfPtr, sqnPtr, or macaPtr is NULL.
  137  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  138  *      LE_FAULT if there was an internal error.
  139  */
  140 //--------------------------------------------------------------------------------------------------
  141 le_result_t le_iks_aesMilenage_GetMacA
  142 (
  143     uint64_t kRef,
  144         ///< [IN] Reference to K.
  145     uint64_t opcRef,
  146         ///< [IN] Reference to OPc.
  147     const uint8_t* randPtr,
  148         ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
  149     size_t randSize,
  150         ///< [IN]
  151     const uint8_t* amfPtr,
  152         ///< [IN] Authentication management field, AMF.
  153         ///<   Assumed to be AMF_SIZE bytes.
  154     size_t amfSize,
  155         ///< [IN]
  156     const uint8_t* sqnPtr,
  157         ///< [IN] Sequence number, SQN.
  158         ///<   Assumed to be SQN_SIZE bytes.
  159     size_t sqnSize,
  160         ///< [IN]
  161     uint8_t* macaPtr,
  162         ///< [OUT] Buffer to hold the network authentication code.
  163         ///<   Assumed to be MACA_SIZE bytes.
  164     size_t* macaSizePtr
  165         ///< [INOUT]
  166 );
  167 
  168 //--------------------------------------------------------------------------------------------------
  169 /**
  170  * Calculates the re-synchronisation authentication code MAC-S using the Milenage algorithm set with
  171  * AES-128 as the block cipher.  Implements the Milenage function f1*.
  172  *
  173  * @return
  174  *      LE_OK if successful.
  175  *      LE_BAD_PARAMETER if either K or OPc reference is invalid
  176  *                       or if either K or OPc key type is invalid
  177  *                       or if either randPtr, amfPtr, sqnPtr, or macsPtr is NULL.
  178  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  179  *      LE_FAULT if there was an internal error.
  180  */
  181 //--------------------------------------------------------------------------------------------------
  182 le_result_t le_iks_aesMilenage_GetMacS
  183 (
  184     uint64_t kRef,
  185         ///< [IN] Reference to K.
  186     uint64_t opcRef,
  187         ///< [IN] Reference to OPc.
  188     const uint8_t* randPtr,
  189         ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
  190     size_t randSize,
  191         ///< [IN]
  192     const uint8_t* amfPtr,
  193         ///< [IN] Authentication management field, AMF.
  194         ///<   Assumed to be AMF_SIZE bytes.
  195     size_t amfSize,
  196         ///< [IN]
  197     const uint8_t* sqnPtr,
  198         ///< [IN] Sequence number, SQN.
  199         ///<    Assumed to be SQN_SIZE bytes.
  200     size_t sqnSize,
  201         ///< [IN]
  202     uint8_t* macsPtr,
  203         ///< [OUT] Buffer to hold the re-sync authentication code.
  204         ///<   Assumed to be MACS_SIZE bytes.
  205     size_t* macsSizePtr
  206         ///< [INOUT]
  207 );
  208 
  209 //--------------------------------------------------------------------------------------------------
  210 /**
  211  * Derives authentication response and keys using the Milenage algorithm set with AES-128 as the
  212  * block cipher.  Implements the Milenage functions f2, f3, f4, f5.
  213  *
  214  * @return
  215  *      LE_OK if successful.
  216  *      LE_BAD_PARAMETER if either K or OPc reference is invalid
  217  *                       or if either K or OPc key type is invalid
  218  *                       or if either randPtr, resPtr, ckPtr, ikPtr or akPtr is NULL.
  219  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  220  *      LE_FAULT if there was an internal error.
  221  */
  222 //--------------------------------------------------------------------------------------------------
  223 le_result_t le_iks_aesMilenage_GetKeys
  224 (
  225     uint64_t kRef,
  226         ///< [IN] Reference to K.
  227     uint64_t opcRef,
  228         ///< [IN] Reference to OPc.
  229     const uint8_t* randPtr,
  230         ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
  231     size_t randSize,
  232         ///< [IN]
  233     uint8_t* resPtr,
  234         ///< [OUT] Buffer to hold the authentication response RES.
  235         ///<   Assumed to be RES_SIZE bytes.
  236     size_t* resSizePtr,
  237         ///< [INOUT]
  238     uint8_t* ckPtr,
  239         ///< [OUT] Buffer to hold the confidentiality key CK.
  240         ///<   Assumed to be CK_SIZE bytes.
  241     size_t* ckSizePtr,
  242         ///< [INOUT]
  243     uint8_t* ikPtr,
  244         ///< [OUT] Buffer to hold the integrity key IK.
  245         ///<   Assumed to be IK_SIZE bytes.
  246     size_t* ikSizePtr,
  247         ///< [INOUT]
  248     uint8_t* akPtr,
  249         ///< [OUT] Buffer to hold the anonymity key AK.
  250         ///<   Assumed to be AK_SIZE bytes.
  251     size_t* akSizePtr
  252         ///< [INOUT]
  253 );
  254 
  255 //--------------------------------------------------------------------------------------------------
  256 /**
  257  * Derives the anonymity key for the re-synchronisation message using the Milenage algorithm set
  258  * with AES-128 as the block cipher.  Implements the Milenage functions f5*.
  259  *
  260  * @return
  261  *      LE_OK if successful.
  262  *      LE_BAD_PARAMETER if either K or OPc reference is invalid
  263  *                       or if either K or OPc key type is invalid
  264  *                       or if either randPtr or akPtr is NULL.
  265  *      LE_UNSUPPORTED if underlying resource does not support this operation.
  266  *      LE_FAULT if there was an internal error.
  267  */
  268 //--------------------------------------------------------------------------------------------------
  269 le_result_t le_iks_aesMilenage_GetAk
  270 (
  271     uint64_t kRef,
  272         ///< [IN] Reference to K.
  273     uint64_t opcRef,
  274         ///< [IN] Reference to OPc.
  275     const uint8_t* randPtr,
  276         ///< [IN] RAND challenge. Assumed to be RAND_SIZE bytes.
  277     size_t randSize,
  278         ///< [IN]
  279     uint8_t* akPtr,
  280         ///< [OUT] Buffer to hold the anonymity key AK.
  281         ///<   Assumed to be AK_SIZE bytes.
  282     size_t* akSizePtr
  283         ///< [INOUT]
  284 );
  285 
  286 #endif // LE_IKS_AESMILENAGE_INTERFACE_H_INCLUDE_GUARD
le_iks_aesMilenage_DisconnectService
void le_iks_aesMilenage_DisconnectService(void)
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_result_t
le_result_t
Definition: le_basics.h:45
le_iks_aesMilenage_DisconnectHandler_t
void(* le_iks_aesMilenage_DisconnectHandler_t)(void *)
Definition: le_iks_aesMilenage_interface.h:50
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_SetServerDisconnectHandler
LE_FULL_API void le_iks_aesMilenage_SetServerDisconnectHandler(le_iks_aesMilenage_DisconnectHandler_t disconnectHandler, void *contextPtr)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
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_ConnectService
void le_iks_aesMilenage_ConnectService(void)
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_TryConnectService
le_result_t le_iks_aesMilenage_TryConnectService(void)
le_iks_interface.h