1 /*
2  * Copyright (c) 2014 Jerry Lundström <lundstrom.jerry@gmail.com>
3  * Copyright (c) 2014 .SE (The Internet Infrastructure Foundation).
4  * Copyright (c) 2014 OpenDNSSEC AB (svb)
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  * 1. Redistributions of source code must retain the above copyright
11  *    notice, this list of conditions and the following disclaimer.
12  * 2. Redistributions in binary form must reproduce the above copyright
13  *    notice, this list of conditions and the following disclaimer in the
14  *    documentation and/or other materials provided with the distribution.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
22  * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
24  * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
25  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
26  * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27  *
28  */
29 
30 #ifndef __hsm_key_h
31 #define __hsm_key_h
32 
33 #include "db_object.h"
34 
35 struct hsm_key;
36 struct hsm_key_list;
37 typedef struct hsm_key hsm_key_t;
38 typedef struct hsm_key_list hsm_key_list_t;
39 
40 typedef enum hsm_key_state {
41     HSM_KEY_STATE_INVALID = -1,
42     HSM_KEY_STATE_UNUSED = 1,
43     HSM_KEY_STATE_PRIVATE = 2,
44     HSM_KEY_STATE_SHARED = 3,
45     HSM_KEY_STATE_DELETE = 4
46 } hsm_key_state_t;
47 extern const db_enum_t hsm_key_enum_set_state[];
48 
49 typedef enum hsm_key_role {
50     HSM_KEY_ROLE_INVALID = -1,
51     HSM_KEY_ROLE_KSK = 1,
52     HSM_KEY_ROLE_ZSK = 2,
53     HSM_KEY_ROLE_CSK = 3
54 } hsm_key_role_t;
55 extern const db_enum_t hsm_key_enum_set_role[];
56 
57 #define HSM_KEY_ROLE_SEP(role) ((role) == HSM_KEY_ROLE_KSK || (role) == HSM_KEY_ROLE_CSK)
58 
59 typedef enum hsm_key_key_type {
60     HSM_KEY_KEY_TYPE_INVALID = -1,
61     HSM_KEY_KEY_TYPE_RSA = 1
62 } hsm_key_key_type_t;
63 
64 typedef enum hsm_key_backup {
65     HSM_KEY_BACKUP_INVALID = -1,
66     HSM_KEY_BACKUP_NO_BACKUP = 0,
67     HSM_KEY_BACKUP_BACKUP_REQUIRED = 1,
68     HSM_KEY_BACKUP_BACKUP_REQUESTED = 2,
69     HSM_KEY_BACKUP_BACKUP_DONE = 3
70 } hsm_key_backup_t;
71 extern const db_enum_t hsm_key_enum_set_backup[];
72 
73 #include "hsm_key_ext.h"
74 #include "policy.h"
75 
76 /**
77  * A hsm key object.
78  */
79 struct hsm_key {
80     db_object_t* dbo;
81     db_value_t id;
82     db_value_t rev;
83     db_value_t policy_id;
84     const policy_t* associated_policy_id;
85     policy_t* private_policy_id;
86     char* locator;
87     hsm_key_state_t state;
88     unsigned int bits;
89     unsigned int algorithm;
90     hsm_key_role_t role;
91     unsigned int inception;
92     unsigned int is_revoked;
93     hsm_key_key_type_t key_type;
94     char* repository;
95     hsm_key_backup_t backup;
96 };
97 
98 /**
99  * Create a new hsm key object.
100  * \param[in] connection a db_connection_t pointer.
101  * \return a hsm_key_t pointer or NULL on error.
102  */
103 extern hsm_key_t* hsm_key_new(const db_connection_t* connection);
104 
105 /**
106  * Create a new hsm key object that is a copy of another hsm key object.
107  * \param[in] hsm_key a hsm_key_t pointer.
108  * \return a hsm_key_t pointer or NULL on error.
109  */
110 extern hsm_key_t* hsm_key_new_copy(const hsm_key_t* hsm_key);
111 
112 /**
113  * Delete a hsm key object, this does not delete it from the database.
114  * \param[in] hsm_key a hsm_key_t pointer.
115  */
116 extern void hsm_key_free(hsm_key_t* hsm_key);
117 
118 /**
119  * Copy the content of a hsm key object.
120  * \param[in] hsm_key a hsm_key_t pointer.
121  * \param[in] hsm_key_copy a hsm_key_t pointer.
122  * \return DB_ERROR_* on failure, otherwise DB_OK.
123  */
124 extern int hsm_key_copy(hsm_key_t* hsm_key, const hsm_key_t* hsm_key_copy);
125 
126 /**
127  * Set the content of a hsm key object based on a database result.
128  * \param[in] hsm_key a hsm_key_t pointer.
129  * \param[in] result a db_result_t pointer.
130  * \return DB_ERROR_* on failure, otherwise DB_OK.
131  */
132 extern int hsm_key_from_result(hsm_key_t* hsm_key, const db_result_t* result);
133 
134 /**
135  * Get the id of a hsm key object.
136  * \param[in] hsm_key a hsm_key_t pointer.
137  * \return a db_value_t pointer or NULL on error.
138  */
139 extern const db_value_t* hsm_key_id(const hsm_key_t* hsm_key);
140 
141 /**
142  * Get the policy_id of a hsm key object.
143  * \param[in] hsm_key a hsm_key_t pointer.
144  * \return a db_value_t pointer or NULL on error.
145  */
146 extern const db_value_t* hsm_key_policy_id(const hsm_key_t* hsm_key);
147 
148 /**
149  * Get the locator of a hsm key object.
150  * \param[in] hsm_key a hsm_key_t pointer.
151  * \return a character pointer or NULL on error or if no locator has been set.
152  */
153 extern const char* hsm_key_locator(const hsm_key_t* hsm_key);
154 
155 /**
156  * Get the state of a hsm key object.
157  * \param[in] hsm_key a hsm_key_t pointer.
158  * \return a hsm_key_state_t which may be HSM_KEY_STATE_INVALID on error or if no state has been set.
159  */
160 extern hsm_key_state_t hsm_key_state(const hsm_key_t* hsm_key);
161 
162 /**
163  * Get the bits of a hsm key object. Undefined behavior if `hsm_key` is NULL.
164  * \param[in] hsm_key a hsm_key_t pointer.
165  * \return an unsigned integer.
166  */
167 extern unsigned int hsm_key_bits(const hsm_key_t* hsm_key);
168 
169 /**
170  * Get the algorithm of a hsm key object. Undefined behavior if `hsm_key` is NULL.
171  * \param[in] hsm_key a hsm_key_t pointer.
172  * \return an unsigned integer.
173  */
174 extern unsigned int hsm_key_algorithm(const hsm_key_t* hsm_key);
175 
176 /**
177  * Get the role of a hsm key object.
178  * \param[in] hsm_key a hsm_key_t pointer.
179  * \return a hsm_key_role_t which may be HSM_KEY_ROLE_INVALID on error or if no role has been set.
180  */
181 extern hsm_key_role_t hsm_key_role(const hsm_key_t* hsm_key);
182 
183 /**
184  * Get the inception of a hsm key object. Undefined behavior if `hsm_key` is NULL.
185  * \param[in] hsm_key a hsm_key_t pointer.
186  * \return an unsigned integer.
187  */
188 extern unsigned int hsm_key_inception(const hsm_key_t* hsm_key);
189 
190 /**
191  * Get the repository of a hsm key object.
192  * \param[in] hsm_key a hsm_key_t pointer.
193  * \return a character pointer or NULL on error or if no repository has been set.
194  */
195 extern const char* hsm_key_repository(const hsm_key_t* hsm_key);
196 
197 /**
198  * Get the backup of a hsm key object.
199  * \param[in] hsm_key a hsm_key_t pointer.
200  * \return a hsm_key_backup_t which may be HSM_KEY_BACKUP_INVALID on error or if no backup has been set.
201  */
202 extern hsm_key_backup_t hsm_key_backup(const hsm_key_t* hsm_key);
203 
204 /**
205  * Set the policy_id of a hsm key object. If this fails the original value may have been lost.
206  * \param[in] hsm_key a hsm_key_t pointer.
207  * \param[in] policy_id a db_value_t pointer.
208  * \return DB_ERROR_* on failure, otherwise DB_OK.
209  */
210 extern int hsm_key_set_policy_id(hsm_key_t* hsm_key, const db_value_t* policy_id);
211 
212 /**
213  * Set the locator of a hsm key object.
214  * \param[in] hsm_key a hsm_key_t pointer.
215  * \param[in] locator_text a character pointer.
216  * \return DB_ERROR_* on failure, otherwise DB_OK.
217  */
218 extern int hsm_key_set_locator(hsm_key_t* hsm_key, const char* locator_text);
219 
220 /**
221  * Set the state of a hsm key object.
222  * \param[in] hsm_key a hsm_key_t pointer.
223  * \param[in] state a hsm_key_state_t.
224  * \return DB_ERROR_* on failure, otherwise DB_OK.
225  */
226 extern int hsm_key_set_state(hsm_key_t* hsm_key, hsm_key_state_t state);
227 
228 /**
229  * Set the bits of a hsm key object.
230  * \param[in] hsm_key a hsm_key_t pointer.
231  * \param[in] bits an unsigned integer.
232  * \return DB_ERROR_* on failure, otherwise DB_OK.
233  */
234 extern int hsm_key_set_bits(hsm_key_t* hsm_key, unsigned int bits);
235 
236 /**
237  * Set the algorithm of a hsm key object.
238  * \param[in] hsm_key a hsm_key_t pointer.
239  * \param[in] algorithm an unsigned integer.
240  * \return DB_ERROR_* on failure, otherwise DB_OK.
241  */
242 extern int hsm_key_set_algorithm(hsm_key_t* hsm_key, unsigned int algorithm);
243 
244 /**
245  * Set the role of a hsm key object.
246  * \param[in] hsm_key a hsm_key_t pointer.
247  * \param[in] role a hsm_key_role_t.
248  * \return DB_ERROR_* on failure, otherwise DB_OK.
249  */
250 extern int hsm_key_set_role(hsm_key_t* hsm_key, hsm_key_role_t role);
251 
252 /**
253  * Set the inception of a hsm key object.
254  * \param[in] hsm_key a hsm_key_t pointer.
255  * \param[in] inception an unsigned integer.
256  * \return DB_ERROR_* on failure, otherwise DB_OK.
257  */
258 extern int hsm_key_set_inception(hsm_key_t* hsm_key, unsigned int inception);
259 
260 /**
261  * Set the key_type of a hsm key object.
262  * \param[in] hsm_key a hsm_key_t pointer.
263  * \param[in] key_type a hsm_key_key_type_t.
264  * \return DB_ERROR_* on failure, otherwise DB_OK.
265  */
266 extern int hsm_key_set_key_type(hsm_key_t* hsm_key, hsm_key_key_type_t key_type);
267 
268 /**
269  * Set the repository of a hsm key object.
270  * \param[in] hsm_key a hsm_key_t pointer.
271  * \param[in] repository_text a character pointer.
272  * \return DB_ERROR_* on failure, otherwise DB_OK.
273  */
274 extern int hsm_key_set_repository(hsm_key_t* hsm_key, const char* repository_text);
275 
276 /**
277  * Set the backup of a hsm key object.
278  * \param[in] hsm_key a hsm_key_t pointer.
279  * \param[in] backup a hsm_key_backup_t.
280  * \return DB_ERROR_* on failure, otherwise DB_OK.
281  */
282 extern int hsm_key_set_backup(hsm_key_t* hsm_key, hsm_key_backup_t backup);
283 
284 /**
285  * Create a clause for policy_id of a hsm key object and add it to a database clause list.
286  * The clause operator is set to DB_CLAUSE_OPERATOR_AND and the clause type is
287  * set to DB_CLAUSE_EQUAL, if you want to change these you can do it with the
288  * returned db_clause_t pointer.
289  * \param[in] clause_list db_clause_list_t pointer.
290  * \param[in] policy_id a db_value_t pointer.
291  * \return a db_clause_t pointer to the added clause or NULL on error.
292  */
293 extern db_clause_t* hsm_key_policy_id_clause(db_clause_list_t* clause_list, const db_value_t* policy_id);
294 
295 /**
296  * Create a clause for state of a hsm key object and add it to a database clause list.
297  * The clause operator is set to DB_CLAUSE_OPERATOR_AND and the clause type is
298  * set to DB_CLAUSE_EQUAL, if you want to change these you can do it with the
299  * returned db_clause_t pointer.
300  * \param[in] clause_list db_clause_list_t pointer.
301  * \param[in] state a hsm_key_state_t.
302  * \return a db_clause_t pointer to the added clause or NULL on error.
303  */
304 extern db_clause_t* hsm_key_state_clause(db_clause_list_t* clause_list, hsm_key_state_t state);
305 
306 /**
307  * Create a clause for bits of a hsm key object and add it to a database clause list.
308  * The clause operator is set to DB_CLAUSE_OPERATOR_AND and the clause type is
309  * set to DB_CLAUSE_EQUAL, if you want to change these you can do it with the
310  * returned db_clause_t pointer.
311  * \param[in] clause_list db_clause_list_t pointer.
312  * \param[in] bits an unsigned integer.
313  * \return a db_clause_t pointer to the added clause or NULL on error.
314  */
315 extern db_clause_t* hsm_key_bits_clause(db_clause_list_t* clause_list, unsigned int bits);
316 
317 /**
318  * Create a clause for algorithm of a hsm key object and add it to a database clause list.
319  * The clause operator is set to DB_CLAUSE_OPERATOR_AND and the clause type is
320  * set to DB_CLAUSE_EQUAL, if you want to change these you can do it with the
321  * returned db_clause_t pointer.
322  * \param[in] clause_list db_clause_list_t pointer.
323  * \param[in] algorithm an unsigned integer.
324  * \return a db_clause_t pointer to the added clause or NULL on error.
325  */
326 extern db_clause_t* hsm_key_algorithm_clause(db_clause_list_t* clause_list, unsigned int algorithm);
327 
328 /**
329  * Create a clause for role of a hsm key object and add it to a database clause list.
330  * The clause operator is set to DB_CLAUSE_OPERATOR_AND and the clause type is
331  * set to DB_CLAUSE_EQUAL, if you want to change these you can do it with the
332  * returned db_clause_t pointer.
333  * \param[in] clause_list db_clause_list_t pointer.
334  * \param[in] role a hsm_key_role_t.
335  * \return a db_clause_t pointer to the added clause or NULL on error.
336  */
337 extern db_clause_t* hsm_key_role_clause(db_clause_list_t* clause_list, hsm_key_role_t role);
338 
339 /**
340  * Create a clause for is_revoked of a hsm key object and add it to a database clause list.
341  * The clause operator is set to DB_CLAUSE_OPERATOR_AND and the clause type is
342  * set to DB_CLAUSE_EQUAL, if you want to change these you can do it with the
343  * returned db_clause_t pointer.
344  * \param[in] clause_list db_clause_list_t pointer.
345  * \param[in] is_revoked an unsigned integer.
346  * \return a db_clause_t pointer to the added clause or NULL on error.
347  */
348 extern db_clause_t* hsm_key_is_revoked_clause(db_clause_list_t* clause_list, unsigned int is_revoked);
349 
350 /**
351  * Create a clause for key_type of a hsm key object and add it to a database clause list.
352  * The clause operator is set to DB_CLAUSE_OPERATOR_AND and the clause type is
353  * set to DB_CLAUSE_EQUAL, if you want to change these you can do it with the
354  * returned db_clause_t pointer.
355  * \param[in] clause_list db_clause_list_t pointer.
356  * \param[in] key_type a hsm_key_key_type_t.
357  * \return a db_clause_t pointer to the added clause or NULL on error.
358  */
359 extern db_clause_t* hsm_key_key_type_clause(db_clause_list_t* clause_list, hsm_key_key_type_t key_type);
360 
361 /**
362  * Create a clause for repository of a hsm key object and add it to a database clause list.
363  * The clause operator is set to DB_CLAUSE_OPERATOR_AND and the clause type is
364  * set to DB_CLAUSE_EQUAL, if you want to change these you can do it with the
365  * returned db_clause_t pointer.
366  * \param[in] clause_list db_clause_list_t pointer.
367  * \param[in] repository_text a character pointer.
368  * \return a db_clause_t pointer to the added clause or NULL on error.
369  */
370 extern db_clause_t* hsm_key_repository_clause(db_clause_list_t* clause_list, const char* repository_text);
371 
372 /**
373  * Create a clause for backup of a hsm key object and add it to a database clause list.
374  * The clause operator is set to DB_CLAUSE_OPERATOR_AND and the clause type is
375  * set to DB_CLAUSE_EQUAL, if you want to change these you can do it with the
376  * returned db_clause_t pointer.
377  * \param[in] clause_list db_clause_list_t pointer.
378  * \param[in] backup a hsm_key_backup_t.
379  * \return a db_clause_t pointer to the added clause or NULL on error.
380  */
381 extern db_clause_t* hsm_key_backup_clause(db_clause_list_t* clause_list, hsm_key_backup_t backup);
382 
383 /**
384  * Create a hsm key object in the database.
385  * \param[in] hsm_key a hsm_key_t pointer.
386  * \return DB_ERROR_* on failure, otherwise DB_OK.
387  */
388 extern int hsm_key_create(hsm_key_t* hsm_key);
389 
390 /**
391  * Get a hsm key object from the database by a id specified in `id`.
392  * \param[in] hsm_key a hsm_key_t pointer.
393  * \param[in] id a db_value_t pointer.
394  * \return DB_ERROR_* on failure, otherwise DB_OK.
395  */
396 extern int hsm_key_get_by_id(hsm_key_t* hsm_key, const db_value_t* id);
397 
398 /**
399  * Get a hsm key object from the database by a locator specified in `locator`.
400  * \param[in] hsm_key a hsm_key_t pointer.
401  * \param[in] locator a character pointer.
402  * \return DB_ERROR_* on failure, otherwise DB_OK.
403  */
404 extern int hsm_key_get_by_locator(hsm_key_t* hsm_key, const char* locator);
405 
406 /**
407  * Get a new hsm key object from the database by a locator specified in `locator`.
408  * \param[in] connection a db_connection_t pointer.
409  * \param[in] locator a character pointer.
410  * \return a hsm_key_t pointer or NULL on error or if it does not exist.
411  */
412 extern hsm_key_t* hsm_key_new_get_by_locator(const db_connection_t* connection, const char* locator);
413 
414 /**
415  * Update a hsm key object in the database.
416  * \param[in] hsm_key a hsm_key_t pointer.
417  * \return DB_ERROR_* on failure, otherwise DB_OK.
418  */
419 extern int hsm_key_update(hsm_key_t* hsm_key);
420 
421 /**
422  * Count the number of hsm key objects in the database, if a selection of
423  * objects should be counted then it can be limited by a database clause list
424  * otherwise all objects are counted.
425  * \param[in] hsm_key a hsm_key_t pointer.
426  * \param[in] clause_list a db_clause_list_t pointer or NULL if all objects.
427  * \param[out] count a size_t pointer to where the count should be stored.
428  * should be counted.
429  * \return DB_ERROR_* on failure, otherwise DB_OK.
430  */
431 extern int hsm_key_count(hsm_key_t* hsm_key, db_clause_list_t* clause_list, size_t* count);
432 
433 /**
434  * A list of hsm key objects.
435  */
436 struct hsm_key_list {
437     db_object_t* dbo;
438     db_result_list_t* result_list;
439     const db_result_t* result;
440     hsm_key_t* hsm_key;
441     int object_store;
442     hsm_key_t** object_list;
443     size_t object_list_size;
444     size_t object_list_position;
445     int object_list_first;
446     int associated_fetch;
447     policy_list_t* policy_id_list;
448 };
449 
450 /**
451  * Create a new hsm key object list.
452  * \param[in] connection a db_connection_t pointer.
453  * \return a hsm_key_list_t pointer or NULL on error.
454  */
455 extern hsm_key_list_t* hsm_key_list_new(const db_connection_t* connection);
456 
457 /**
458  * Create a new hsm key object list that is a copy of another.
459  * \param[in] hsm_key_list a hsm_key_list_t pointer.
460  * \return a hsm_key_list_t pointer or NULL on error.
461  */
462 extern hsm_key_list_t* hsm_key_list_new_copy(const hsm_key_list_t* hsm_key_copy);
463 
464 /**
465  * Specify that objects should be stored within the list as they are fetch,
466  * this is optimal if the list is to be iterated over more then once.
467  * \param[in] hsm_key_list a hsm_key_list_t pointer.
468  * \return DB_ERROR_* on failure, otherwise DB_OK.
469  */
470 extern int hsm_key_list_object_store(hsm_key_list_t* hsm_key_list);
471 
472 /**
473  * Delete a hsm key object list.
474  * \param[in] hsm_key_list a hsm_key_list_t pointer.
475  */
476 extern void hsm_key_list_free(hsm_key_list_t* hsm_key_list);
477 
478 /**
479  * free global allocator.
480  * hsm_key_list_free MUST be called for all its contents.
481  */
482 /**
483  * Copy the content of another hsm key object list.
484  * \param[in] hsm_key_list a hsm_key_list_t pointer.
485  * \param[in] from_hsm_key_list a hsm_key_list_t pointer.
486  * \return DB_ERROR_* on failure, otherwise DB_OK.
487  */
488 extern int hsm_key_list_copy(hsm_key_list_t* hsm_key_list, const hsm_key_list_t* from_hsm_key_list);
489 
490 /**
491  * Get hsm key objects from the database by a clause list.
492  * \param[in] hsm_key_list a hsm_key_list_t pointer.
493  * \param[in] clause_list a db_clause_list_t pointer.
494  * \return DB_ERROR_* on failure, otherwise DB_OK.
495  */
496 extern int hsm_key_list_get_by_clauses(hsm_key_list_t* hsm_key_list, const db_clause_list_t* clause_list);
497 
498 /**
499  * Get a new list of hsm key objects from the database by a clause list.
500  * \param[in] connection a db_connection_t pointer.
501  * \param[in] clause_list a db_clause_list_t pointer.
502  * \return a hsm_key_list_t pointer or NULL on error.
503  */
504 extern hsm_key_list_t* hsm_key_list_new_get_by_clauses(const db_connection_t* connection, const db_clause_list_t* clause_list);
505 
506 /**
507  * Get hsm key objects from the database by a policy_id specified in `policy_id`.
508  * \param[in] hsm_key_list a hsm_key_list_t pointer.
509  * \param[in] policy_id a db_value_t pointer.
510  * \return DB_ERROR_* on failure, otherwise DB_OK.
511  */
512 extern int hsm_key_list_get_by_policy_id(hsm_key_list_t* hsm_key_list, const db_value_t* policy_id);
513 
514 /**
515  * Get a new list of hsm key objects from the database by a policy_id specified in `policy_id`.
516  * \param[in] connection a db_connection_t pointer.
517  * \param[in] policy_id a db_value_t pointer.
518  * \return a hsm_key_list_t pointer or NULL on error.
519  */
520 extern hsm_key_list_t* hsm_key_list_new_get_by_policy_id(const db_connection_t* connection, const db_value_t* policy_id);
521 
522 /**
523  * Get the first hsm key object in a hsm key object list and reset the
524  * position of the list.
525  * \param[in] hsm_key_list a hsm_key_list_t pointer.
526  * \return a hsm_key_t pointer or NULL on error or if there are no
527  * hsm key objects in the hsm key object list.
528  */
529 extern const hsm_key_t* hsm_key_list_begin(hsm_key_list_t* hsm_key_list);
530 
531 /**
532  * Get the first hsm key object in a hsm key object list and reset the
533  * position of the list. The caller will be given ownership of this object and
534  * is responsible for freeing it.
535  * \param[in] hsm_key_list a hsm_key_list_t pointer.
536  * \return a hsm_key_t pointer or NULL on error or if there are no
537  * hsm key objects in the hsm key object list.
538  */
539 extern hsm_key_t* hsm_key_list_get_begin(hsm_key_list_t* hsm_key_list);
540 
541 /**
542  * Get the next hsm key object in a hsm key object list.
543  * Ownership of this object is retained within the list and the object is only
544  * valid until the next call to this function.
545  * \param[in] hsm_key_list a hsm_key_list_t pointer.
546  * \return a hsm_key_t pointer or NULL on error or if there are no more
547  * hsm key objects in the hsm key object list.
548  */
549 extern const hsm_key_t* hsm_key_list_next(hsm_key_list_t* hsm_key_list);
550 
551 /**
552  * Get the next hsm key object in a hsm key object list.
553  * The caller will be given ownership of this object and is responsible for
554  * freeing it.
555  * \param[in] hsm_key_list a hsm_key_list_t pointer.
556  * \return a hsm_key_t pointer or NULL on error or if there are no more
557  * hsm key objects in the hsm key object list.
558  */
559 extern hsm_key_t* hsm_key_list_get_next(hsm_key_list_t* hsm_key_list);
560 
561 #endif
562