677b6d0ad0c19548bae4ab8c02b9cf04a675dbf2
[strongswan.git] / src / libstrongswan / plugins / ntru / ntru_crypto / ntru_crypto.h
1 /******************************************************************************
2 * NTRU Cryptography Reference Source Code
3 * Copyright (c) 2009-2013, by Security Innovation, Inc. All rights reserved.
4 *
5 * ntru_crypto.h is a component of ntru-crypto.
6 *
7 * Copyright (C) 2009-2013 Security Innovation
8 *
9 * This program is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU General Public License
11 * as published by the Free Software Foundation; either version 2
12 * of the License, or (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 *
23 *****************************************************************************/
24
25
26 /******************************************************************************
27 *
28 * File: ntru_crypto.h
29 *
30 * Contents: Public header file for NTRUEncrypt.
31 *
32 *****************************************************************************/
33
34 #ifndef NTRU_CRYPTO_H
35 #define NTRU_CRYPTO_H
36
37 #include <library.h>
38
39 #include "ntru_param_set.h"
40 #include "ntru_drbg.h"
41
42 #if !defined( NTRUCALL )
43 #if !defined(WIN32) || defined (NTRUCRYPTO_STATIC)
44 // Linux, or a Win32 static library
45 #define NTRUCALL extern uint32_t
46 #elif defined (NTRUCRYPTO_EXPORTS)
47 // Win32 DLL build
48 #define NTRUCALL extern __declspec(dllexport) uint32_t
49 #else
50 // Win32 DLL import
51 #define NTRUCALL extern __declspec(dllimport) uint32_t
52 #endif
53 #endif /* NTRUCALL */
54
55 /* error codes */
56
57 #define NTRU_OK 0
58 #define NTRU_FAIL 1
59 #define NTRU_BAD_PARAMETER 2
60 #define NTRU_BAD_LENGTH 3
61 #define NTRU_BUFFER_TOO_SMALL 4
62 #define NTRU_INVALID_PARAMETER_SET 5
63 #define NTRU_BAD_PUBLIC_KEY 6
64 #define NTRU_BAD_PRIVATE_KEY 7
65 #define NTRU_OUT_OF_MEMORY 8
66 #define NTRU_BAD_ENCODING 9
67 #define NTRU_OID_NOT_RECOGNIZED 10
68 #define NTRU_DRBG_FAIL 11
69 #define NTRU_MGF1_FAIL 12
70
71 /* function declarations */
72
73 /* ntru_crypto_ntru_encrypt
74 *
75 * Implements NTRU encryption (SVES) for the parameter set specified in
76 * the public key blob.
77 *
78 * Before invoking this function, a DRBG must be instantiated using
79 * ntru_crypto_drbg_instantiate() to obtain a DRBG handle, and in that
80 * instantiation the requested security strength must be at least as large
81 * as the security strength of the NTRU parameter set being used.
82 * Failure to instantiate the DRBG with the proper security strength will
83 * result in this function returning DRBG_ERROR_BASE + DRBG_BAD_LENGTH.
84 *
85 * The required minimum size of the output ciphertext buffer (ct) may be
86 * queried by invoking this function with ct = NULL. In this case, no
87 * encryption is performed, NTRU_OK is returned, and the required minimum
88 * size for ct is returned in ct_len.
89 *
90 * When ct != NULL, at invocation *ct_len must be the size of the ct buffer.
91 * Upon return it is the actual size of the ciphertext.
92 *
93 * Returns NTRU_OK if successful.
94 * Returns NTRU_DRBG_FAIL if the DRBG handle is invalid.
95 * Returns NTRU_BAD_PARAMETER if an argument pointer (other than ct) is NULL.
96 * Returns NTRU_BAD_LENGTH if a length argument (pubkey_blob_len or pt_len) is
97 * zero, or if pt_len exceeds the maximum plaintext length for the parameter set.
98 * Returns NTRU_BAD_PUBLIC_KEY if the public-key blob is invalid
99 * (unknown format, corrupt, bad length).
100 * Returns NTRU_BUFFER_TOO_SMALL if the ciphertext buffer is too small.
101 * Returns NTRU_NO_MEMORY if memory needed cannot be allocated from the heap.
102 */
103
104 NTRUCALL
105 ntru_crypto_ntru_encrypt(
106 ntru_drbg_t *drbg , /* in - handle for DRBG */
107 uint16_t pubkey_blob_len, /* in - no. of octets in public key
108 blob */
109 uint8_t const *pubkey_blob, /* in - pointer to public key */
110 uint16_t pt_len, /* in - no. of octets in plaintext */
111 uint8_t const *pt, /* in - pointer to plaintext */
112 uint16_t *ct_len, /* in/out - no. of octets in ct, addr for
113 no. of octets in ciphertext */
114 uint8_t *ct); /* out - address for ciphertext */
115
116
117 /* ntru_crypto_ntru_decrypt
118 *
119 * Implements NTRU decryption (SVES) for the parameter set specified in
120 * the private key blob.
121 *
122 * The maximum size of the output plaintext may be queried by invoking
123 * this function with pt = NULL. In this case, no decryption is performed,
124 * NTRU_OK is returned, and the maximum size the plaintext could be is
125 * returned in pt_len.
126 * Note that until the decryption is performed successfully, the actual size
127 * of the resulting plaintext cannot be known.
128 *
129 * When pt != NULL, at invocation *pt_len must be the size of the pt buffer.
130 * Upon return it is the actual size of the plaintext.
131 *
132 * Returns NTRU_OK if successful.
133 * Returns NTRU_BAD_PARAMETER if an argument pointer (other than pt) is NULL.
134 * Returns NTRU_BAD_LENGTH if a length argument (privkey_blob) is zero, or if
135 * ct_len is invalid for the parameter set.
136 * Returns NTRU_BAD_PRIVATE_KEY if the private-key blob is invalid
137 * (unknown format, corrupt, bad length).
138 * Returns NTRU_BUFFER_TOO_SMALL if the plaintext buffer is too small.
139 * Returns NTRU_NO_MEMORY if memory needed cannot be allocated from the heap.
140 * Returns NTRU_FAIL if a decryption error occurs.
141 */
142
143 NTRUCALL
144 ntru_crypto_ntru_decrypt(
145 uint16_t privkey_blob_len, /* in - no. of octets in private key
146 blob */
147 uint8_t const *privkey_blob, /* in - pointer to private key */
148 uint16_t ct_len, /* in - no. of octets in ciphertext */
149 uint8_t const *ct, /* in - pointer to ciphertext */
150 uint16_t *pt_len, /* in/out - no. of octets in pt, addr for
151 no. of octets in plaintext */
152 uint8_t *pt); /* out - address for plaintext */
153
154
155 /* ntru_crypto_ntru_encrypt_keygen
156 *
157 * Implements key generation for NTRUEncrypt for the parameter set specified.
158 *
159 * Before invoking this function, a DRBG must be instantiated using
160 * ntru_crypto_drbg_instantiate() to obtain a DRBG handle, and in that
161 * instantiation the requested security strength must be at least as large
162 * as the security strength of the NTRU parameter set being used.
163 * Failure to instantiate the DRBG with the proper security strength will
164 * result in this function returning NTRU_DRBG_FAIL.
165 *
166 * The required minimum size of the output public-key buffer (pubkey_blob)
167 * may be queried by invoking this function with pubkey_blob = NULL.
168 * In this case, no key generation is performed, NTRU_OK is returned, and
169 * the required minimum size for pubkey_blob is returned in pubkey_blob_len.
170 *
171 * The required minimum size of the output private-key buffer (privkey_blob)
172 * may be queried by invoking this function with privkey_blob = NULL.
173 * In this case, no key generation is performed, NTRU_OK is returned, and
174 * the required minimum size for privkey_blob is returned in privkey_blob_len.
175 *
176 * The required minimum sizes of both pubkey_blob and privkey_blob may be
177 * queried as described above, in a single invocation of this function.
178 *
179 * When pubkey_blob != NULL and privkey_blob != NULL, at invocation
180 * *pubkey_blob_len must be the size of the pubkey_blob buffer and
181 * *privkey_blob_len must be the size of the privkey_blob buffer.
182 * Upon return, *pubkey_blob_len is the actual size of the public-key blob
183 * and *privkey_blob_len is the actual size of the private-key blob.
184 *
185 * Returns NTRU_OK if successful.
186 * Returns NTRU_BAD_PARAMETER if an argument pointer (other than pubkey_blob
187 * or privkey_blob) is NULL.
188 * Returns NTRU_INVALID_PARAMETER_SET if the parameter-set ID is invalid.
189 * Returns NTRU_BAD_LENGTH if a length argument is invalid.
190 * Returns NTRU_BUFFER_TOO_SMALL if either the pubkey_blob buffer or the
191 * privkey_blob buffer is too small.
192 * Returns NTRU_NO_MEMORY if memory needed cannot be allocated from the heap.
193 * Returns NTRU_FAIL if the polynomial generated for f is not invertible in
194 * (Z/qZ)[X]/(X^N - 1), which is extremely unlikely.
195 * Should this occur, this function should simply be invoked again.
196 */
197
198 NTRUCALL
199 ntru_crypto_ntru_encrypt_keygen(
200 ntru_drbg_t *drbg, /* in - handle of DRBG */
201 ntru_param_set_id_t param_set_id, /* in - parameter set ID */
202 uint16_t *pubkey_blob_len, /* in/out - no. of octets in
203 pubkey_blob, addr
204 for no. of octets
205 in pubkey_blob */
206 uint8_t *pubkey_blob, /* out - address for
207 public key blob */
208 uint16_t *privkey_blob_len, /* in/out - no. of octets in
209 privkey_blob, addr
210 for no. of octets
211 in privkey_blob */
212 uint8_t *privkey_blob); /* out - address for
213 private key blob */
214 #endif /* NTRU_CRYPTO_H */