Avoid problems with Doxygen by adding warn_unused_result attribute at the end of...
[strongswan.git] / src / libstrongswan / crypto / prfs / prf.h
1 /*
2 * Copyright (C) 2005-2006 Martin Willi
3 * Copyright (C) 2005 Jan Hutter
4 * Hochschule fuer Technik Rapperswil
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * for more details.
15 */
16
17 /**
18 * @defgroup prf prf
19 * @{ @ingroup crypto
20 */
21
22 #ifndef PRF_H_
23 #define PRF_H_
24
25 typedef enum pseudo_random_function_t pseudo_random_function_t;
26 typedef struct prf_t prf_t;
27
28 #include <library.h>
29
30 /**
31 * Pseudo random function, as in IKEv2 RFC 3.3.2.
32 *
33 * PRF algorithms not defined in IKEv2 are allocated in "private use" space.
34 */
35 enum pseudo_random_function_t {
36 PRF_UNDEFINED = 1024,
37 /** RFC2104 */
38 PRF_HMAC_MD5 = 1,
39 /** RFC2104 */
40 PRF_HMAC_SHA1 = 2,
41 /** RFC2104 */
42 PRF_HMAC_TIGER = 3,
43 /** RFC4434 */
44 PRF_AES128_XCBC = 4,
45 /** RFC4868 */
46 PRF_HMAC_SHA2_256 = 5,
47 /** RFC4868. */
48 PRF_HMAC_SHA2_384 = 6,
49 /** RFC4868 */
50 PRF_HMAC_SHA2_512 = 7,
51 /** RFC4615 */
52 PRF_AES128_CMAC = 8,
53 /** FIPS 186-2-change1 */
54 PRF_FIPS_SHA1_160 = 1025,
55 /** FIPS 186-2-change1, uses fixed output size of 160bit */
56 PRF_FIPS_DES = 1026,
57 /** Keyed hash algorithm using SHA1, used in EAP-AKA:
58 * This PRF uses SHA1, but XORs the key into the IV. No "Final()" operation
59 * is applied to the SHA1 state. */
60 PRF_KEYED_SHA1 = 1027,
61 /** draft-kanno-ipsecme-camellia-xcbc, not yet assigned by IANA */
62 PRF_CAMELLIA128_XCBC = 1028,
63 };
64
65 /**
66 * enum name for encryption_algorithm_t.
67 */
68 extern enum_name_t *pseudo_random_function_names;
69
70 /**
71 * Generic interface for pseudo-random-functions.
72 */
73 struct prf_t {
74
75 /**
76 * Generates pseudo random bytes and writes them in the buffer.
77 *
78 * @param seed a chunk containing the seed for the next bytes
79 * @param buffer pointer where the generated bytes will be written
80 * @return TRUE if bytes generated successfully
81 */
82 bool (*get_bytes)(prf_t *this, chunk_t seed,
83 u_int8_t *buffer) __attribute__((warn_unused_result));
84
85 /**
86 * Generates pseudo random bytes and allocate space for them.
87 *
88 * @param seed a chunk containing the seed for the next bytes
89 * @param chunk chunk which will hold generated bytes
90 * @return TRUE if bytes allocated and generated successfully
91 */
92 bool (*allocate_bytes)(prf_t *this, chunk_t seed,
93 chunk_t *chunk) __attribute__((warn_unused_result));
94
95 /**
96 * Get the block size of this prf_t object.
97 *
98 * @return block size in bytes
99 */
100 size_t (*get_block_size)(prf_t *this);
101
102 /**
103 * Get the key size of this prf_t object.
104 *
105 * This is a suggestion only, all implemented PRFs accept variable key
106 * length.
107 *
108 * @return key size in bytes
109 */
110 size_t (*get_key_size)(prf_t *this);
111
112 /**
113 * Set the key for this prf_t object.
114 *
115 * @param key key to set
116 * @return TRUE if key set successfully
117 */
118 bool (*set_key)(prf_t *this,
119 chunk_t key) __attribute__((warn_unused_result));
120
121 /**
122 * Destroys a prf object.
123 */
124 void (*destroy)(prf_t *this);
125 };
126
127 #endif /** PRF_H_ @}*/