wolfio.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541
  1. /*!
  2. \brief This function is the receive embedded callback.
  3. \return Success This function returns the number of bytes read.
  4. \return WOLFSSL_CBIO_ERR_WANT_READ returned with a “Would block” message
  5. if the last error was SOCKET_EWOULDBLCOK or SOCKET_EAGAIN.
  6. \return WOLFSSL_CBIO_ERR_TIMEOUT returned with a “Socket timeout” message.
  7. \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset”
  8. message if the last error was SOCKET_ECONNRESET.
  9. \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message
  10. if the last error was SOCKET_EINTR.
  11. \return WOLFSSL_CBIO_ERR_WANT_READ returned with a “Connection refused”
  12. message if the last error was SOCKET_ECONNREFUSED.
  13. \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Connection aborted”
  14. message if the last error was SOCKET_ECONNABORTED.
  15. \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message
  16. if the last error was not specified.
  17. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  18. \param buf a char pointer representation of the buffer.
  19. \param sz the size of the buffer.
  20. \param ctx a void pointer to user registered context. In the default case
  21. the ctx is a socket descriptor pointer.
  22. _Example_
  23. \code
  24. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  25. WOLFSSL* ssl = wolfSSL_new(ctx);
  26. char* buf;
  27. int sz;
  28. void* ctx;
  29. int bytesRead = EmbedReceive(ssl, buf, sz, ctx);
  30. if(bytesRead <= 0){
  31. // There were no bytes read. Failure case.
  32. }
  33. \endcode
  34. \sa wolfSSL_dtls_get_current_timeout
  35. \sa TranslateReturnCode
  36. \sa RECV_FUNCTION
  37. */
  38. WOLFSSL_API int EmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx);
  39. /*!
  40. \brief This function is the send embedded callback.
  41. \return Success This function returns the number of bytes sent.
  42. \return WOLFSSL_CBIO_ERR_WANT_WRITE returned with a “Would block” message
  43. if the last error was SOCKET_EWOULDBLOCK or SOCKET_EAGAIN.
  44. \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset”
  45. message if the last error was SOCKET_ECONNRESET.
  46. \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message
  47. if the last error was SOCKET_EINTR.
  48. \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Socket EPIPE” message
  49. if the last error was SOCKET_EPIPE.
  50. \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message
  51. if the last error was not specified.
  52. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  53. \param buf a char pointer representing the buffer.
  54. \param sz the size of the buffer.
  55. \param ctx a void pointer to user registered context.
  56. _Example_
  57. \code
  58. WOLFSSL* ssl = wolfSSL_new(ctx);
  59. char* buf;
  60. int sz;
  61. void* ctx;
  62. int dSent = EmbedSend(ssl, buf, sz, ctx);
  63. if(dSent <= 0){
  64. // No byes sent. Failure case.
  65. }
  66. \endcode
  67. \sa TranslateReturnCode
  68. \sa SEND_FUNCTION
  69. \sa LastError
  70. \sa InitSSL_Ctx
  71. \sa LastError
  72. */
  73. WOLFSSL_API int EmbedSend(WOLFSSL* ssl, char* buf, int sz, void* ctx);
  74. /*!
  75. \brief This function is the receive embedded callback.
  76. \return Success This function returns the nb bytes read if the execution
  77. was successful.
  78. \return WOLFSSL_CBIO_ERR_WANT_READ if the connection refused or if a
  79. ‘would block’ error was thrown in the function.
  80. \return WOLFSSL_CBIO_ERR_TIMEOUT returned if the socket timed out.
  81. \return WOLFSSL_CBIO_ERR_CONN_RST returned if the connection reset.
  82. \return WOLFSSL_CBIO_ERR_ISR returned if the socket was interrupted.
  83. \return WOLFSSL_CBIO_ERR_GENERAL returned if there was a general error.
  84. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  85. \param buf a constant char pointer to the buffer.
  86. \param sz an int type representing the size of the buffer.
  87. \param ctx a void pointer to the WOLFSSL_CTX context.
  88. _Example_
  89. \code
  90. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( protocol method );
  91. WOLFSSL* ssl = WOLFSSL_new(ctx);
  92. char* buf;
  93. int sz = sizeof(buf)/sizeof(char);
  94. (void*)ctx;
  95. int nb = EmbedReceiveFrom(ssl, buf, sz, ctx);
  96. if(nb > 0){
  97. // nb is the number of bytes written and is positive
  98. }
  99. \endcode
  100. \sa TranslateReturnCode
  101. \sa RECVFROM_FUNCTION
  102. \sa Setsockopt
  103. */
  104. WOLFSSL_API int EmbedReceiveFrom(WOLFSSL* ssl, char* buf, int sz, void*);
  105. /*!
  106. \brief This function is the send embedded callback.
  107. \return Success This function returns the number of bytes sent.
  108. \return WOLFSSL_CBIO_ERR_WANT_WRITE returned with a “Would Block” message
  109. if the last error was either SOCKET_EWOULDBLOCK or SOCKET_EAGAIN error.
  110. \return WOLFSSL_CBIO_ERR_CONN_RST returned with a “Connection reset”
  111. message if the last error was SOCKET_ECONNRESET.
  112. \return WOLFSSL_CBIO_ERR_ISR returned with a “Socket interrupted” message
  113. if the last error was SOCKET_EINTR.
  114. \return WOLFSSL_CBIO_ERR_CONN_CLOSE returned with a “Socket EPIPE” message
  115. if the last error was WOLFSSL_CBIO_ERR_CONN_CLOSE.
  116. \return WOLFSSL_CBIO_ERR_GENERAL returned with a “General error” message
  117. if the last error was not specified.
  118. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  119. \param buf a char pointer representing the buffer.
  120. \param sz the size of the buffer.
  121. \param ctx a void pointer to the user registered context. The default case
  122. is a WOLFSSL_DTLS_CTX structure.
  123. _Example_
  124. \code
  125. WOLFSSL* ssl;
  126. char* buf;
  127. int sz;
  128. void* ctx;
  129. int sEmbed = EmbedSendto(ssl, buf, sz, ctx);
  130. if(sEmbed <= 0){
  131. // No bytes sent. Failure case.
  132. }
  133. \endcode
  134. \sa LastError
  135. \sa EmbedSend
  136. \sa EmbedReceive
  137. */
  138. WOLFSSL_API int EmbedSendTo(WOLFSSL* ssl, char* buf, int sz, void* ctx);
  139. /*!
  140. \brief This function is the DTLS Generate Cookie callback.
  141. \return Success This function returns the number of bytes copied
  142. into the buffer.
  143. \return GEN_COOKIE_E returned if the getpeername failed in
  144. EmbedGenerateCookie.
  145. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  146. \param buf byte pointer representing the buffer. It is the destination
  147. from XMEMCPY().
  148. \param sz the size of the buffer.
  149. \param ctx a void pointer to user registered context.
  150. _Example_
  151. \code
  152. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  153. WOLFSSL* ssl = wolfSSL_new(ctx);
  154. byte buffer[BUFFER_SIZE];
  155. int sz = sizeof(buffer)/sizeof(byte);
  156. void* ctx;
  157. int ret = EmbedGenerateCookie(ssl, buffer, sz, ctx);
  158. if(ret > 0){
  159. // EmbedGenerateCookie code block for success
  160. }
  161. \endcode
  162. \sa wc_ShaHash
  163. \sa EmbedGenerateCookie
  164. \sa XMEMCPY
  165. \sa XMEMSET
  166. */
  167. WOLFSSL_API int EmbedGenerateCookie(WOLFSSL* ssl, unsigned char* buf,
  168. int sz, void*);
  169. /*!
  170. \brief This function frees the response buffer.
  171. \return none No returns.
  172. \param ctx a void pointer to heap hint.
  173. \param resp a byte pointer representing the response.
  174. _Example_
  175. \code
  176. void* ctx;
  177. byte* resp; // Response buffer.
  178. EmbedOcspRespFree(ctx, resp);
  179. \endcode
  180. \sa XFREE
  181. */
  182. WOLFSSL_API void EmbedOcspRespFree(void*, unsigned char*);
  183. /*!
  184. \brief This function registers a receive callback for wolfSSL to get input
  185. data. By default, wolfSSL uses EmbedReceive() as the callback which uses
  186. the system’s TCP recv() function. The user can register a function to get
  187. input from memory, some other network module, or from anywhere. Please see
  188. the EmbedReceive() function in src/io.c as a guide for how the function
  189. should work and for error codes. In particular, IO_ERR_WANT_READ should
  190. be returned for non blocking receive when no data is ready.
  191. \return none no Returns.
  192. \param ctx pointer to the SSL context, created with wolfSSL_CTX_new().
  193. \param callback function to be registered as the receive callback for the
  194. wolfSSL context, ctx. The signature of this function must follow that as
  195. shown above in the Synopsis section.
  196. _Example_
  197. \code
  198. WOLFSSL_CTX* ctx = 0;
  199. // Receive callback prototype
  200. int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx);
  201. // Register the custom receive callback with wolfSSL
  202. wolfSSL_CTX_SetIORecv(ctx, MyEmbedReceive);
  203. int MyEmbedReceive(WOLFSSL* ssl, char* buf, int sz, void* ctx)
  204. {
  205. // custom EmbedReceive function
  206. }
  207. \endcode
  208. \sa wolfSSL_CTX_SetIOSend
  209. \sa wolfSSL_SetIOReadCtx
  210. \sa wolfSSL_SetIOWriteCtx
  211. */
  212. WOLFSSL_API void wolfSSL_CTX_SetIORecv(WOLFSSL_CTX*, CallbackIORecv);
  213. /*!
  214. \brief This function registers a context for the SSL session’s receive
  215. callback function. By default, wolfSSL sets the file descriptor passed to
  216. wolfSSL_set_fd() as the context when wolfSSL is using the system’s TCP
  217. library. If you’ve registered your own receive callback you may want to set
  218. a specific context for the session. For example, if you’re using memory
  219. buffers the context may be a pointer to a structure describing where and
  220. how to access the memory buffers.
  221. \return none No returns.
  222. \param ssl pointer to the SSL session, created with wolfSSL_new().
  223. \param rctx pointer to the context to be registered with the SSL session’s
  224. (ssl) receive callback function.
  225. _Example_
  226. \code
  227. int sockfd;
  228. WOLFSSL* ssl = 0;
  229. ...
  230. // Manually setting the socket fd as the receive CTX, for example
  231. wolfSSL_SetIOReadCtx(ssl, &sockfd);
  232. ...
  233. \endcode
  234. \sa wolfSSL_CTX_SetIORecv
  235. \sa wolfSSL_CTX_SetIOSend
  236. \sa wolfSSL_SetIOWriteCtx
  237. */
  238. WOLFSSL_API void wolfSSL_SetIOReadCtx( WOLFSSL* ssl, void *ctx);
  239. /*!
  240. \brief This function registers a context for the SSL session’s send
  241. callback function. By default, wolfSSL sets the file descriptor passed to
  242. wolfSSL_set_fd() as the context when wolfSSL is using the system’s TCP
  243. library. If you’ve registered your own send callback you may want to set a
  244. specific context for the session. For example, if you’re using memory
  245. buffers the context may be a pointer to a structure describing where and
  246. how to access the memory buffers.
  247. \return none No returns.
  248. \param ssl pointer to the SSL session, created with wolfSSL_new().
  249. \param wctx pointer to the context to be registered with the SSL session’s
  250. (ssl) send callback function.
  251. _Example_
  252. \code
  253. int sockfd;
  254. WOLFSSL* ssl = 0;
  255. ...
  256. // Manually setting the socket fd as the send CTX, for example
  257. wolfSSL_SetIOWriteCtx(ssl, &sockfd);
  258. ...
  259. \endcode
  260. \sa wolfSSL_CTX_SetIORecv
  261. \sa wolfSSL_CTX_SetIOSend
  262. \sa wolfSSL_SetIOReadCtx
  263. */
  264. WOLFSSL_API void wolfSSL_SetIOWriteCtx(WOLFSSL* ssl, void *ctx);
  265. /*!
  266. \ingroup IO
  267. \brief This function returns the IOCB_ReadCtx member of the WOLFSSL struct.
  268. \return pointer This function returns a void pointer to the IOCB_ReadCtx
  269. member of the WOLFSSL structure.
  270. \return NULL returned if the WOLFSSL struct is NULL.
  271. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  272. _Example_
  273. \code
  274. WOLFSSL* ssl = wolfSSL_new(ctx);
  275. void* ioRead;
  276. ...
  277. ioRead = wolfSSL_GetIOReadCtx(ssl);
  278. if(ioRead == NULL){
  279. // Failure case. The ssl object was NULL.
  280. }
  281. \endcode
  282. \sa wolfSSL_GetIOWriteCtx
  283. \sa wolfSSL_SetIOReadFlags
  284. \sa wolfSSL_SetIOWriteCtx
  285. \sa wolfSSL_SetIOReadCtx
  286. \sa wolfSSL_CTX_SetIOSend
  287. */
  288. WOLFSSL_API void* wolfSSL_GetIOReadCtx( WOLFSSL* ssl);
  289. /*!
  290. \ingroup IO
  291. \brief This function returns the IOCB_WriteCtx member of the WOLFSSL structure.
  292. \return pointer This function returns a void pointer to the IOCB_WriteCtx
  293. member of the WOLFSSL structure.
  294. \return NULL returned if the WOLFSSL struct is NULL.
  295. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  296. _Example_
  297. \code
  298. WOLFSSL* ssl;
  299. void* ioWrite;
  300. ...
  301. ioWrite = wolfSSL_GetIOWriteCtx(ssl);
  302. if(ioWrite == NULL){
  303. // The function returned NULL.
  304. }
  305. \endcode
  306. \sa wolfSSL_GetIOReadCtx
  307. \sa wolfSSL_SetIOWriteCtx
  308. \sa wolfSSL_SetIOReadCtx
  309. \sa wolfSSL_CTX_SetIOSend
  310. */
  311. WOLFSSL_API void* wolfSSL_GetIOWriteCtx(WOLFSSL* ssl);
  312. /*!
  313. \brief This function sets the flags for the receive callback to use for
  314. the given SSL session. The receive callback could be either the default
  315. wolfSSL EmbedReceive callback, or a custom callback specified by the user
  316. (see wolfSSL_CTX_SetIORecv). The default flag value is set internally by
  317. wolfSSL to the value of 0. The default wolfSSL receive callback uses the
  318. recv() function to receive data from the socket. From the recv() man page:
  319. “The flags argument to a recv() function is formed by or'ing one or more
  320. of the values: MSG_OOB process out-of-band data, MSG_PEEK peek at incoming
  321. message, MSG_WAITALL wait for full request or error. The MSG_OOB flag
  322. requests receipt of out-of-band data that would not be received in the
  323. normal data stream. Some protocols place expedited data at the head of
  324. the normal data queue, and thus this flag cannot be used with such
  325. protocols. The MSG_PEEK flag causes the receive operation to return
  326. data from the beginning of the receive queue without removing that data
  327. from the queue. Thus, a subsequent receive call will return the same data.
  328. The MSG_WAITALL flag requests that the operation block until the full
  329. request is satisfied. However, the call may still return less data than
  330. requested if a signal is caught, an error or disconnect occurs, or the next
  331. data to be received is of a different type than that returned.”
  332. \return none No returns.
  333. \param ssl pointer to the SSL session, created with wolfSSL_new().
  334. \param flags value of the I/O read flags for the specified SSL
  335. session (ssl).
  336. _Example_
  337. \code
  338. WOLFSSL* ssl = 0;
  339. ...
  340. // Manually setting recv flags to 0
  341. wolfSSL_SetIOReadFlags(ssl, 0);
  342. ...
  343. \endcode
  344. \sa wolfSSL_CTX_SetIORecv
  345. \sa wolfSSL_CTX_SetIOSend
  346. \sa wolfSSL_SetIOReadCtx
  347. */
  348. WOLFSSL_API void wolfSSL_SetIOReadFlags( WOLFSSL* ssl, int flags);
  349. /*!
  350. \brief This function sets the flags for the send callback to use for the
  351. given SSL session. The send callback could be either the default wolfSSL
  352. EmbedSend callback, or a custom callback specified by the user (see
  353. wolfSSL_CTX_SetIOSend). The default flag value is set internally by wolfSSL
  354. to the value of 0. The default wolfSSL send callback uses the send()
  355. function to send data from the socket. From the send() man page: “The
  356. flags parameter may include one or more of the following:
  357. #define MSG_OOB 0x1 // process out-of-band data,
  358. #define MSG_DONTROUTE 0x4 // bypass routing, use direct interface.
  359. The flag MSG_OOB is used to send ``out-of-band'' data on sockets that
  360. support this notion (e.g. SOCK_STREAM); the underlying protocol must also
  361. support ``out-of-band'' data. MSG_DONTROUTE is usually used only by
  362. diagnostic or routing programs.”
  363. \return none No returns.
  364. \param ssl pointer to the SSL session, created with wolfSSL_new().
  365. \param flags value of the I/O send flags for the specified SSL session (ssl).
  366. _Example_
  367. \code
  368. WOLFSSL* ssl = 0;
  369. ...
  370. // Manually setting send flags to 0
  371. wolfSSL_SetIOWriteFlags(ssl, 0);
  372. ...
  373. \endcode
  374. \sa wolfSSL_CTX_SetIORecv
  375. \sa wolfSSL_CTX_SetIOSend
  376. \sa wolfSSL_SetIOReadCtx
  377. */
  378. WOLFSSL_API void wolfSSL_SetIOWriteFlags(WOLFSSL* ssl, int flags);
  379. /*!
  380. \ingroup IO
  381. \brief This function sets the nxSocket and nxWait members of the nxCtx
  382. struct within the WOLFSSL structure.
  383. \return none No returns.
  384. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  385. \param nxSocket a pointer to type NX_TCP_SOCKET that is set to the
  386. nxSocket member of the nxCTX structure.
  387. \param waitOption a ULONG type that is set to the nxWait member of
  388. the nxCtx structure.
  389. _Example_
  390. \code
  391. WOLFSSL* ssl = wolfSSL_new(ctx);
  392. NX_TCP_SOCKET* nxSocket;
  393. ULONG waitOption;
  394. if(ssl != NULL || nxSocket != NULL || waitOption <= 0){
  395. wolfSSL_SetIO_NetX(ssl, nxSocket, waitOption);
  396. } else {
  397. // You need to pass in good parameters.
  398. }
  399. \endcode
  400. \sa set_fd
  401. \sa NetX_Send
  402. \sa NetX_Receive
  403. */
  404. WOLFSSL_API void wolfSSL_SetIO_NetX(WOLFSSL* ssl, NX_TCP_SOCKET* nxsocket,
  405. ULONG waitoption);
  406. /*!
  407. \brief This function sets the callback for the CBIOCookie member of the
  408. WOLFSSL_CTX structure. The CallbackGenCookie type is a function pointer
  409. and has the signature: int (*CallbackGenCookie)(WOLFSSL* ssl, unsigned
  410. char* buf, int sz, void* ctx);
  411. \return none No returns.
  412. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  413. \param cb a CallbackGenCookie type function pointer with the signature
  414. of CallbackGenCookie.
  415. _Example_
  416. \code
  417. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  418. WOLFSSL* ssl = wolfSSL_new(ctx);
  419. int SetGenCookieCB(WOLFSSL* ssl, unsigned char* buf, int sz, void* ctx){
  420. // Callback function body.
  421. }
  422. wolfSSL_CTX_SetGenCookie(ssl->ctx, SetGenCookieCB);
  423. \endcode
  424. \sa CallbackGenCookie
  425. */
  426. WOLFSSL_API void wolfSSL_CTX_SetGenCookie(WOLFSSL_CTX*, CallbackGenCookie);
  427. /*!
  428. \ingroup Setup
  429. \brief This function returns the IOCB_CookieCtx member of the
  430. WOLFSSL structure.
  431. \return pointer The function returns a void pointer value stored in
  432. the IOCB_CookieCtx.
  433. \return NULL if the WOLFSSL struct is NULL
  434. \param ssl a pointer to a WOLFSSL structure, created using wolfSSL_new().
  435. _Example_
  436. \code
  437. WOLFSSL_CTX* ctx = wolfSSL_CTX_new( method );
  438. WOLFSSL* ssl = wolfSSL_new(ctx);
  439. void* cookie;
  440. ...
  441. cookie = wolfSSL_GetCookieCtx(ssl);
  442. if(cookie != NULL){
  443. // You have the cookie
  444. }
  445. \endcode
  446. \sa wolfSSL_SetCookieCtx
  447. \sa wolfSSL_CTX_SetGenCookie
  448. */
  449. WOLFSSL_API void* wolfSSL_GetCookieCtx(WOLFSSL* ssl);