Asterisk - The Open Source Telephony Project  21.4.1
res_stir_shaken.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2020, Sangoma Technologies Corporation
5  *
6  * Kevin Harwell <kharwell@sangoma.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 #ifndef _RES_STIR_SHAKEN_H
19 #define _RES_STIR_SHAKEN_H
20 
21 #include "asterisk/sorcery.h"
22 
23 enum ast_stir_shaken_vs_response_code {
24  AST_STIR_SHAKEN_VS_SUCCESS = 0,
25  AST_STIR_SHAKEN_VS_DISABLED,
26  AST_STIR_SHAKEN_VS_INVALID_ARGUMENTS,
27  AST_STIR_SHAKEN_VS_INTERNAL_ERROR,
28  AST_STIR_SHAKEN_VS_NO_IDENTITY_HDR,
29  AST_STIR_SHAKEN_VS_NO_DATE_HDR,
30  AST_STIR_SHAKEN_VS_DATE_HDR_PARSE_FAILURE,
31  AST_STIR_SHAKEN_VS_DATE_HDR_EXPIRED,
32  AST_STIR_SHAKEN_VS_NO_JWT_HDR,
33  AST_STIR_SHAKEN_VS_INVALID_OR_NO_X5U,
34  AST_STIR_SHAKEN_VS_CERT_CACHE_MISS,
35  AST_STIR_SHAKEN_VS_CERT_CACHE_INVALID,
36  AST_STIR_SHAKEN_VS_CERT_CACHE_EXPIRED,
37  AST_STIR_SHAKEN_VS_CERT_RETRIEVAL_FAILURE,
38  AST_STIR_SHAKEN_VS_CERT_CONTENTS_INVALID,
39  AST_STIR_SHAKEN_VS_CERT_NOT_TRUSTED,
40  AST_STIR_SHAKEN_VS_CERT_DATE_INVALID,
41  AST_STIR_SHAKEN_VS_CERT_NO_TN_AUTH_EXT,
42  AST_STIR_SHAKEN_VS_CERT_NO_SPC_IN_TN_AUTH_EXT,
43  AST_STIR_SHAKEN_VS_NO_RAW_KEY,
44  AST_STIR_SHAKEN_VS_SIGNATURE_VALIDATION,
45  AST_STIR_SHAKEN_VS_NO_IAT,
46  AST_STIR_SHAKEN_VS_IAT_EXPIRED,
47  AST_STIR_SHAKEN_VS_INVALID_OR_NO_PPT,
48  AST_STIR_SHAKEN_VS_INVALID_OR_NO_ALG,
49  AST_STIR_SHAKEN_VS_INVALID_OR_NO_TYP,
50  AST_STIR_SHAKEN_VS_INVALID_OR_NO_GRANTS,
51  AST_STIR_SHAKEN_VS_INVALID_OR_NO_ATTEST,
52  AST_STIR_SHAKEN_VS_NO_ORIGID,
53  AST_STIR_SHAKEN_VS_NO_ORIG_TN,
54  AST_STIR_SHAKEN_VS_CID_ORIG_TN_MISMATCH,
55  AST_STIR_SHAKEN_VS_NO_DEST_TN,
56  AST_STIR_SHAKEN_VS_INVALID_HEADER,
57  AST_STIR_SHAKEN_VS_INVALID_GRANT,
58  AST_STIR_SHAKEN_VS_RESPONSE_CODE_MAX
59 };
60 
61 enum ast_stir_shaken_as_response_code {
62  AST_STIR_SHAKEN_AS_SUCCESS = 0,
63  AST_STIR_SHAKEN_AS_DISABLED,
64  AST_STIR_SHAKEN_AS_INVALID_ARGUMENTS,
65  AST_STIR_SHAKEN_AS_MISSING_PARAMETERS,
66  AST_STIR_SHAKEN_AS_INTERNAL_ERROR,
67  AST_STIR_SHAKEN_AS_NO_TN_FOR_CALLERID,
68  AST_STIR_SHAKEN_AS_NO_PRIVATE_KEY_AVAIL,
69  AST_STIR_SHAKEN_AS_NO_PUBLIC_CERT_URL_AVAIL,
70  AST_STIR_SHAKEN_AS_NO_ATTEST_LEVEL,
71  AST_STIR_SHAKEN_AS_IDENTITY_HDR_EXISTS,
72  AST_STIR_SHAKEN_AS_NO_TO_HDR,
73  AST_STIR_SHAKEN_AS_TO_HDR_BAD_URI,
74  AST_STIR_SHAKEN_AS_SIGN_ENCODE_FAILURE,
75  AST_STIR_SHAKEN_AS_RESPONSE_CODE_MAX
76 };
77 
78 enum stir_shaken_failure_action_enum {
79  /*! Unknown value */
80  stir_shaken_failure_action_UNKNOWN = -1,
81  /*! Continue and let dialplan decide action */
82  stir_shaken_failure_action_CONTINUE = 0,
83  /*! Reject request with respone codes defined in RFC8224 */
84  stir_shaken_failure_action_REJECT_REQUEST,
85  /*! Continue but return a Reason header in next provisional response */
86  stir_shaken_failure_action_CONTINUE_RETURN_REASON,
87  /*! Not set in config */
88  stir_shaken_failure_action_NOT_SET,
89 };
90 
92 
93 /*!
94  * \brief Create Attestation Service Context
95  *
96  * \param caller_id The caller_id for the outgoing call
97  * \param dest_tn Canonicalized destination tn
98  * \param chan The outgoing channel
99  * \param profile_name The profile name on the endpoint
100  * May be NULL.
101  * \param tag Identifying string to output in log and trace messages.
102  * \param ctxout Receives a pointer to the newly created context
103  * The caller must release with ao2_ref or ao2_cleanup.
104 
105  * \retval AST_STIR_SHAKEN_AS_SUCCESS if successful.
106  * \retval AST_STIR_SHAKEN_AS_DISABLED if attestation is disabled
107  * by the endpoint itself, the profile or globally.
108  * \retval Other AST_STIR_SHAKEN_AS errors.
109  */
110 enum ast_stir_shaken_as_response_code
111  ast_stir_shaken_as_ctx_create(const char *caller_id,
112  const char *dest_tn, struct ast_channel *chan,
113  const char *profile_name,
114  const char *tag, struct ast_stir_shaken_as_ctx **ctxout);
115 
116 /*!
117  * \brief Indicates if the AS context needs DTLS fingerprints
118  *
119  * \param ctx AS Context
120  *
121  * \retval 0 Not needed
122  * \retval 1 Needed
123  */
124 int ast_stir_shaken_as_ctx_wants_fingerprints(struct ast_stir_shaken_as_ctx *ctx);
125 
126 /*!
127  * \brief Add DTLS fingerprints to AS context
128  *
129  * \param ctx AS context
130  * \param alg Fingerprint algorithm ("sha-1" or "sha-256")
131  * \param fingerprint Fingerprint
132  *
133  * \retval AST_STIR_SHAKEN_AS_SUCCESS if successful
134  * \retval Other AST_STIR_SHAKEN_AS errors.
135  */
136 enum ast_stir_shaken_as_response_code ast_stir_shaken_as_ctx_add_fingerprint(
137  struct ast_stir_shaken_as_ctx *ctx, const char *alg, const char *fingerprint);
138 
139 /*!
140  * \brief Attest and return Identity header value
141  *
142  * \param ctx AS Context
143  * \param header Pointer to buffer to receive the header value
144  * Must be freed with ast_free when done
145  *
146  * \retval AST_STIR_SHAKEN_AS_SUCCESS if successful
147  * \retval Other AST_STIR_SHAKEN_AS errors.
148  */
149 enum ast_stir_shaken_as_response_code ast_stir_shaken_attest(
150  struct ast_stir_shaken_as_ctx *ctx, char **header);
151 
152 
154 
155 /*!
156  * \brief Create Verification Service context
157  *
158  * \param caller_id Incoming caller id
159  * \param chan Incoming channel
160  * \param profile_name The profile name on the endpoint
161  * May be NULL.
162  * \param endpoint_behavior Behavior associated to the specific
163  * endpoint
164  * \param tag Identifying string to output in log and trace messages.
165  * \param ctxout Receives a pointer to the newly created context
166  * The caller must release with ao2_ref or ao2_cleanup.
167  *
168  * \retval AST_STIR_SHAKEN_VS_SUCCESS if successful.
169  * \retval AST_STIR_SHAKEN_VS_DISABLED if verification is disabled
170  * by the endpoint itself, the profile or globally.
171  * \retval Other AST_STIR_SHAKEN_VS errors.
172  */
173 enum ast_stir_shaken_vs_response_code
174  ast_stir_shaken_vs_ctx_create(const char *caller_id,
175  struct ast_channel *chan, const char *profile_name,
176  const char *tag, struct ast_stir_shaken_vs_ctx **ctxout);
177 
178 /*!
179  * \brief Sets response code on VS context
180  *
181  * \param ctx VS context
182  * \param vs_rc ast_stir_shaken_vs_response_code to set
183  */
184 void ast_stir_shaken_vs_ctx_set_response_code(
185  struct ast_stir_shaken_vs_ctx *ctx,
186  enum ast_stir_shaken_vs_response_code vs_rc);
187 
188 /*!
189  * \brief Add the received Identity header value to the VS context
190  *
191  * \param ctx VS context
192  * \param identity_hdr Identity header value
193  *
194  * \retval AST_STIR_SHAKEN_VS_SUCCESS if successful
195  * \retval Other AST_STIR_SHAKEN_VS errors.
196  */
197 enum ast_stir_shaken_vs_response_code
198  ast_stir_shaken_vs_ctx_add_identity_hdr(struct ast_stir_shaken_vs_ctx * ctx,
199  const char *identity_hdr);
200 
201 /*!
202  * \brief Add the received Date header value to the VS context
203  *
204  * \param ctx VS context
205  * \param date_hdr Date header value
206  *
207  * \retval AST_STIR_SHAKEN_VS_SUCCESS if successful
208  * \retval Other AST_STIR_SHAKEN_VS errors.
209  */
210 enum ast_stir_shaken_vs_response_code
211  ast_stir_shaken_vs_ctx_add_date_hdr(struct ast_stir_shaken_vs_ctx * ctx,
212  const char *date_hdr);
213 
214 /*!
215  * \brief Get failure_action from context
216  *
217  * \param ctx VS context
218  *
219  * \retval ast_stir_shaken_failure_action
220  */
221 enum stir_shaken_failure_action_enum
222  ast_stir_shaken_vs_get_failure_action(
223  struct ast_stir_shaken_vs_ctx *ctx);
224 
225 /*!
226  * \brief Get use_rfc9410_responses from context
227  *
228  * \param ctx VS context
229  *
230  * \retval 1 if true
231  * \retval 0 if false
232  */
233 int ast_stir_shaken_vs_get_use_rfc9410_responses(
234  struct ast_stir_shaken_vs_ctx *ctx);
235 
236 /*!
237  * \brief Add a STIR/SHAKEN verification result to a channel
238  *
239  * \param ctx VS context
240  *
241  * \retval -1 on failure
242  * \retval 0 on success
243  */
244 int ast_stir_shaken_add_result_to_channel(
245  struct ast_stir_shaken_vs_ctx *ctx);
246 
247 /*!
248  * \brief Perform incoming call verification
249  *
250  * \param ctx VS context
251  *
252  * \retval AST_STIR_SHAKEN_AS_SUCCESS if successful
253  * \retval Other AST_STIR_SHAKEN_AS errors.
254  */
255 enum ast_stir_shaken_vs_response_code
256  ast_stir_shaken_vs_verify(struct ast_stir_shaken_vs_ctx * ctx);
257 
258 #endif /* _RES_STIR_SHAKEN_H */
Main Channel structure associated with a channel.
Sorcery Data Access Layer API.