resource/csdk/libcoap-4.1.1/sec/netdtls.h

   1 //******************************************************************
   2 //
   3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21 #ifndef _NET_DTLS_H
  22 #define _NET_DTLS_H
  23
  24 #include "net.h"
  25 #include "address.h"
  26 #include "pdu.h"
  27 #include "dtls.h"
  28
  29 #define COAP_DTLS_DEFAULT_PORT  5684
  30
  31 /**
  32  * Data structure for holding the tinyDTLS interface
  33  * related info.
  34  */
  35 typedef struct coap_dtls_context_t {
  36     coap_queue_t *cachedqueue;          /**< pdu's are cached until DTLS session is formed */
  37     struct dtls_context_t *dtls_ctx;    /**< pointer to tinyDTLS context */
  38     struct pt_info_t *pt_info;          /**< used by callback during
  39                                              decryption to hold address/length */
  40     dtls_handler_t callbacks;           /**< pointer to callbacks needed by tinyDTLS */
  41 }coap_dtls_context_t;
  42
  43 /**
  44  * Data structure for holding the decrypted data address
  45  * and length provided by tinyDTLS callback interface.
  46  */
  47 typedef struct pt_info_t {
  48     uint8_t *pt;
  49     uint16_t ptlen;
  50 }pt_info_t;
  51
  52 /**
  53  * Declares DTLS errors and return values. Currently used internally only.
  54  */
  55 typedef enum
  56 {
  57     DTLS_OK = 0,
  58     DTLS_FAIL,
  59     DTLS_SESSION_INITIATED,
  60     DTLS_HS_MSG
  61 } dtls_ret;
  62
  63 /**
  64  * Open secure port and initialize tinyDTLS library.
  65  *
  66  * @param ctx - handle to global coap_context_t.
  67  *
  68  * @return A value less than zero on error, greater or
  69  *           equal otherwise.
  70  */
  71 int coap_dtls_init(coap_context_t *ctx);
  72
  73 /**
  74  * Closes secure port and de-inits tinyDTLS library.
  75  *
  76  * @param ctx - handle to global coap_context_t.
  77  *
  78  */
  79 void coap_dtls_deinit(coap_context_t *ctx);
  80
  81 /**
  82  * Performs DTLS encryption of the CoAP PDU. If a
  83  * DTLS session does not exist yet with the @dst,
  84  * a DTLS handshake will be started. In case where
  85  * a new DTLS handshake is started, pdu info is
  86  * cached to be send when session setup is finished.
  87  *
  88  * @param ctx    - handle to global coap_context_t.
  89  * @param dst    - address of the receiver of the pdu.
  90  * @param pdu    - pointer to CoAP pdu.
  91  * @param node   - address of the node holding pdu.
  92  * @param tid    - tid of the pdu.
  93  * @param cache_flag - output variable to indicate if pdu
  94  *                  is cached and inform the caller to
  95  *                  NOT free the memory holding pdu.
  96  *
  97  * @return A value less than zero on error, greater or
  98  *           equal otherwise.
  99  */
 100 int coap_dtls_encrypt(coap_context_t *ctx,
 101             OCDevAddr* dst,
 102             coap_pdu_t *pdu,
 103             coap_queue_t **node,
 104             coap_tid_t tid,
 105             uint8_t *cache_flag);
 106
 107 /**
 108  * Performs DTLS decryption of the CoAP PDU received on
 109  * secure port. This method performs in-place decryption
 110  * of the cipher-text buffer. If a DTLS handshake message
 111  * is received or decryption failure happens, this method
 112  * returns -1. If a valid application PDU is decrypted, it
 113  * returns the length of the decrypted pdu.
 114  *
 115  * @param ctx    - handle to global coap_context_t.
 116  * @param src    - address of the sender of the pdu.
 117  * @param ct     - pointer to the cipher text buffer.
 118  * @param ctlen  - length of the ciphertext buffer.
 119  * @param pt     - output variable to store the starting address
 120  *                  of decrypted plaintext.
 121  * @param ptlen  - output variable to store the length of
 122  *                  decrypted plaintext.
 123  *
 124  * @return A value less than zero on error, greater or
 125  *           equal otherwise.
 126  */
 127 int coap_dtls_decrypt(coap_context_t *ctx,
 128             OCDevAddr* src,
 129             uint8_t* ct,
 130             int ctlen,
 131             uint8_t** pt,
 132             int* ptlen);
 133
 134 #endif //_NET_DTLS_H
 135