updated some inline docs
[strongswan.git] / src / charon / sa / transactions / transaction.h
1 /**
2 * @file transaction.h
3 *
4 * @brief Interface transaction_t.
5 *
6 */
7
8 /*
9 * Copyright (C) 2006 Martin Willi
10 * Hochschule fuer Technik Rapperswil
11 *
12 * This program is free software; you can redistribute it and/or modify it
13 * under the terms of the GNU General Public License as published by the
14 * Free Software Foundation; either version 2 of the License, or (at your
15 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
19 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20 * for more details.
21 */
22
23 #ifndef TRANSACTION_H_
24 #define TRANSACTION_H_
25
26
27 typedef struct transaction_t transaction_t;
28
29 #include <types.h>
30 #include <encoding/message.h>
31 #include <sa/ike_sa.h>
32
33
34
35 /**
36 * @brief This interface represents a transaction an established IKE_SA can do.
37 *
38 * To every transaction, a message ID is associated. IKEv2 uses strict message
39 * IDs, which are equal for a request/response pair in a transaction.
40 * An initiator of a transaction does the following:
41 * - create the transaction using a specific constructor
42 * - call request() to get the message for initiaton
43 * - call conclude() to process received reply
44 * The other peer does the following:
45 * - create a transanction using the generic transaction constructor
46 * - call respond() to get a reply to send
47 *
48 * The responder must not destroy the transaction, until the
49 * initiator initiates another transaction (or a number of transactions
50 * > window size). This allows us to redo a transaction in case of a
51 * message loss. The initiator can destroy the the transaction once
52 * the conclude() function is called.
53 *
54 * @b Constructors:
55 * - transaction_create()
56 * - ike_sa_init_create()
57 * - ike_auth_create()
58 *
59 * @ingroup transactions
60 */
61 struct transaction_t {
62
63 /**
64 * @brief Get the request to use for initiating the transaction.
65 *
66 * A transaction creates a request only once. The request is stored
67 * internally and may be queried multiple times for retransmission.
68 * The transaction is not responsible for generating/encrypting the
69 * message, this is the job of the caller. But it MAY be already
70 * generated when calling get_request() the second time.
71 *
72 * @param this calling object
73 * @param[out] request resultin request
74 * @return
75 * - FAILED if transaction failed
76 * - DESTROY_ME if transaction failed and IKE SA
77 * must be deleted
78 * - SUCCESS
79 */
80 status_t (*get_request) (transaction_t *this, message_t **request);
81
82 /**
83 * @brief Build the response for a received request.
84 *
85 * A transaction creates a response only once for a unique request.
86 * This allows the use of get_response multiple times for retransmission
87 * purposes.
88 * The transaction is not responsible for generating/encrypting the
89 * response, nor is it responsible for decrypting/parsing the request.
90 * This is the job of the caller. But the response MAY be already
91 * generated when calling get_request() the second time.
92 * The initiator waits for a response, so we send one in every case. This
93 * means response points always to a valid message. This message
94 * may not be modified or destroyed, it gets destroyed along with the
95 * transaction.
96 * The get_response() function may return a next transaction. This allows
97 * passing of informations from one transaction to a next one.
98 *
99 * @param this calling object
100 * @param request received request
101 * @param[out] response resulting response
102 * @param[out] next transaction expected as next, or NULL
103 * @return
104 * - FAILED if transaction failed
105 * - DESTROY_ME if transaction failed and IKE SA
106 * must be deleted
107 * - SUCCESS
108 */
109 status_t (*get_response) (transaction_t *this, message_t *request,
110 message_t **response, transaction_t **next);
111
112 /**
113 * @brief Conclude an initiated transaction with a received response.
114 *
115 * The response must be decrypted and parsed. The conclude function
116 * may return a new transaction. This transaction has to be executed
117 * next to complete a multi-exchange scenario. It allows a clean
118 * transaction mechanism, as the transaction knows best whats to do
119 * after it completes. It must only be executed if conclude returns
120 * SUCCESS.
121 *
122 * @param this calling object
123 * @param response received response
124 * @param[out] next transaction to execute as next, or NULL
125 * @return
126 * - FAILED if transaction failed
127 * - DESTROY_ME if transaction failed and IKE SA
128 * must be deleted
129 * - SUCCESS
130 */
131 status_t (*conclude) (transaction_t *this, message_t *response,
132 transaction_t **next);
133
134 /**
135 * @brief Get the message ID associated with this transaction.
136 *
137 * Every transaction consists of a message pair with the same
138 * message ID. This ID can be queried with get_message_id().
139 *
140 * @param this calling object
141 * @return message id
142 */
143 u_int32_t (*get_message_id) (transaction_t *this);
144
145 /**
146 * @brief Times we already sent the request (retransmitted).
147 *
148 * The transaction stores an internal counter to see how
149 * many times we sent the request. This counter is incremented
150 * each time after a call to requested().
151 *
152 * @param this calling object
153 * @return message id
154 */
155 u_int32_t (*requested) (transaction_t *this);
156
157 /**
158 * @brief Destroys a transaction_t object.
159 *
160 * @param this calling object
161 */
162 void (*destroy) (transaction_t *this);
163 };
164
165 /**
166 * @brief Create a transaction instance based on a received request.
167 *
168 * Incoming requests are handled by a transaction. But as we don't
169 * know what kind of transaction we use for a specific request, we use
170 * a generic constructor. This constructor decides which instance will
171 * handle the transaction, and creates it.
172 *
173 * @param ike_sa ike_sa associated with this transaction
174 * @param request received request
175 * @return
176 * - created transaction, or
177 * - NULL no transaction needed
178 *
179 * @ingroup transactions
180 */
181 transaction_t *transaction_create(ike_sa_t *ike_sa, message_t* request);
182
183 #endif /* TRANSACTION_H_ */