kmfapi.h revision 12611:d9f75b73c5fd 
1/*
2 * CDDL HEADER START
3 *
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License (the "License").
6 * You may not use this file except in compliance with the License.
7 *
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 *
21 * Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved.
22 *
23 * Constant definitions and function prototypes for the KMF library.
24 * Commonly used data types are defined in "kmftypes.h".
25 */
26
27#ifndef _KMFAPI_H
28#define	_KMFAPI_H
29
30#include <kmftypes.h>
31#include <security/cryptoki.h>
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37/*
38 * Setup operations.
39 */
40extern KMF_RETURN kmf_initialize(KMF_HANDLE_T *, char *, char *);
41extern KMF_RETURN kmf_configure_keystore(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
42extern KMF_RETURN kmf_finalize(KMF_HANDLE_T);
43
44/*
45 * Key operations.
46 */
47extern KMF_RETURN kmf_create_keypair(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
48
49extern KMF_RETURN kmf_delete_key_from_keystore(KMF_HANDLE_T, int,
50	KMF_ATTRIBUTE *);
51
52extern KMF_RETURN kmf_find_key(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
53
54extern KMF_RETURN kmf_find_prikey_by_cert(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
55
56extern KMF_RETURN kmf_store_key(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
57
58extern KMF_RETURN kmf_create_sym_key(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
59
60extern KMF_RETURN kmf_get_sym_key_value(KMF_HANDLE_T, KMF_KEY_HANDLE *,
61	KMF_RAW_SYM_KEY *);
62
63/*
64 * Certificate operations.
65 */
66extern KMF_RETURN kmf_find_cert(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
67
68extern KMF_RETURN kmf_encode_cert_record(KMF_X509_CERTIFICATE *, KMF_DATA *);
69
70extern KMF_RETURN kmf_import_cert(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
71
72extern KMF_RETURN kmf_store_cert(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
73
74extern KMF_RETURN kmf_delete_cert_from_keystore(KMF_HANDLE_T, int,
75	KMF_ATTRIBUTE *);
76
77extern KMF_RETURN kmf_validate_cert(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
78
79extern KMF_RETURN kmf_create_cert_file(const KMF_DATA *, KMF_ENCODE_FORMAT,
80	char *);
81
82extern KMF_RETURN kmf_download_cert(KMF_HANDLE_T, char *, char *, int,
83	unsigned int, char *, KMF_ENCODE_FORMAT *);
84
85extern KMF_RETURN kmf_is_cert_data(KMF_DATA *, KMF_ENCODE_FORMAT *);
86extern KMF_RETURN kmf_is_cert_file(KMF_HANDLE_T, char *, KMF_ENCODE_FORMAT *);
87
88extern KMF_RETURN kmf_check_cert_date(KMF_HANDLE_T, const KMF_DATA *);
89
90/*
91 * Crypto operations with key or cert.
92 */
93extern KMF_RETURN kmf_encrypt(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
94extern KMF_RETURN kmf_decrypt(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
95extern KMF_RETURN kmf_sign_cert(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
96extern KMF_RETURN kmf_sign_data(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
97extern KMF_RETURN kmf_verify_cert(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
98extern KMF_RETURN kmf_verify_data(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
99
100/*
101 * CRL operations.
102 */
103extern KMF_RETURN kmf_import_crl(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
104extern KMF_RETURN kmf_delete_crl(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
105extern KMF_RETURN kmf_list_crl(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
106extern KMF_RETURN kmf_find_crl(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
107extern KMF_RETURN kmf_find_cert_in_crl(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
108extern KMF_RETURN kmf_verify_crl_file(KMF_HANDLE_T, char *, KMF_DATA *);
109extern KMF_RETURN kmf_check_crl_date(KMF_HANDLE_T, char *);
110extern KMF_RETURN kmf_download_crl(KMF_HANDLE_T, char *, char *,
111	int, unsigned int, char *, KMF_ENCODE_FORMAT *);
112extern KMF_RETURN kmf_is_crl_file(KMF_HANDLE_T, char *, KMF_ENCODE_FORMAT *);
113
114/*
115 * CSR operations.
116 */
117extern KMF_RETURN kmf_create_csr_file(KMF_DATA *, KMF_ENCODE_FORMAT, char *);
118extern KMF_RETURN kmf_set_csr_pubkey(KMF_HANDLE_T,
119	KMF_KEY_HANDLE *, KMF_CSR_DATA *);
120extern KMF_RETURN kmf_set_csr_version(KMF_CSR_DATA *, uint32_t);
121extern KMF_RETURN kmf_set_csr_subject(KMF_CSR_DATA *, KMF_X509_NAME *);
122extern KMF_RETURN kmf_set_csr_extn(KMF_CSR_DATA *, KMF_X509_EXTENSION *);
123extern KMF_RETURN kmf_set_csr_sig_alg(KMF_CSR_DATA *, KMF_ALGORITHM_INDEX);
124extern KMF_RETURN kmf_set_csr_subject_altname(KMF_CSR_DATA *, char *,
125	int, KMF_GENERALNAMECHOICES);
126extern KMF_RETURN kmf_set_csr_ku(KMF_CSR_DATA *, int, uint16_t);
127extern KMF_RETURN kmf_decode_csr(KMF_HANDLE_T, KMF_DATA *, KMF_CSR_DATA *);
128extern KMF_RETURN kmf_verify_csr(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
129extern KMF_RETURN kmf_sign_csr(KMF_HANDLE_T, const KMF_CSR_DATA *,
130	KMF_KEY_HANDLE *, KMF_DATA *);
131extern KMF_RETURN kmf_add_csr_eku(KMF_CSR_DATA *, KMF_OID *, int);
132
133/*
134 * GetCert operations.
135 */
136extern KMF_RETURN kmf_get_cert_extn(const KMF_DATA *, KMF_OID *,
137	KMF_X509_EXTENSION *);
138
139extern KMF_RETURN kmf_get_cert_extns(const KMF_DATA *, KMF_FLAG_CERT_EXTN,
140	KMF_X509_EXTENSION **, int *);
141
142extern KMF_RETURN kmf_get_cert_ku(const KMF_DATA *, KMF_X509EXT_KEY_USAGE *);
143
144extern KMF_RETURN kmf_get_cert_eku(const KMF_DATA *, KMF_X509EXT_EKU *);
145
146extern KMF_RETURN kmf_get_cert_basic_constraint(const KMF_DATA *,
147	KMF_BOOL *, KMF_X509EXT_BASICCONSTRAINTS *);
148
149extern KMF_RETURN kmf_get_cert_policies(const KMF_DATA *,
150	KMF_BOOL *, KMF_X509EXT_CERT_POLICIES *);
151
152extern KMF_RETURN kmf_get_cert_auth_info_access(const KMF_DATA *,
153	KMF_X509EXT_AUTHINFOACCESS *);
154
155extern KMF_RETURN kmf_get_cert_crl_dist_pts(const KMF_DATA *,
156	KMF_X509EXT_CRLDISTPOINTS *);
157
158extern KMF_RETURN kmf_get_cert_version_str(KMF_HANDLE_T, const KMF_DATA *,
159	char **);
160
161extern KMF_RETURN kmf_get_cert_subject_str(KMF_HANDLE_T, const KMF_DATA *,
162	char **);
163
164extern KMF_RETURN kmf_get_cert_issuer_str(KMF_HANDLE_T,	const KMF_DATA *,
165	char **);
166
167extern KMF_RETURN kmf_get_cert_serial_str(KMF_HANDLE_T, const KMF_DATA *,
168	char **);
169
170extern KMF_RETURN kmf_get_cert_start_date_str(KMF_HANDLE_T, const KMF_DATA *,
171	char **);
172
173extern KMF_RETURN kmf_get_cert_end_date_str(KMF_HANDLE_T, const KMF_DATA *,
174	char **);
175
176extern KMF_RETURN kmf_get_cert_pubkey_alg_str(KMF_HANDLE_T, const KMF_DATA *,
177	char **);
178
179extern KMF_RETURN kmf_get_cert_sig_alg_str(KMF_HANDLE_T, const KMF_DATA *,
180	char **);
181
182extern KMF_RETURN kmf_get_cert_pubkey_str(KMF_HANDLE_T,	const KMF_DATA *,
183	char **);
184
185extern KMF_RETURN kmf_get_cert_email_str(KMF_HANDLE_T, const KMF_DATA *,
186	char **);
187
188extern KMF_RETURN kmf_get_cert_extn_str(KMF_HANDLE_T, const KMF_DATA *,
189	KMF_PRINTABLE_ITEM, char **);
190
191extern KMF_RETURN kmf_get_cert_id_data(const KMF_DATA *, KMF_DATA *);
192
193extern KMF_RETURN kmf_get_cert_id_str(const KMF_DATA *, char **);
194
195extern KMF_RETURN kmf_get_cert_validity(const KMF_DATA *, time_t *, time_t *);
196
197
198/*
199 * SetCert operations
200 */
201extern KMF_RETURN kmf_set_cert_pubkey(KMF_HANDLE_T, KMF_KEY_HANDLE *,
202	KMF_X509_CERTIFICATE *);
203
204extern KMF_RETURN kmf_set_cert_subject(KMF_X509_CERTIFICATE *,
205	KMF_X509_NAME *);
206
207extern KMF_RETURN kmf_set_cert_ku(KMF_X509_CERTIFICATE *, int, uint16_t);
208
209extern KMF_RETURN kmf_set_cert_issuer(KMF_X509_CERTIFICATE *,
210	KMF_X509_NAME *);
211
212extern KMF_RETURN kmf_set_cert_sig_alg(KMF_X509_CERTIFICATE *,
213	KMF_ALGORITHM_INDEX);
214
215extern KMF_RETURN kmf_set_cert_validity(KMF_X509_CERTIFICATE *,
216	time_t, uint32_t);
217
218extern KMF_RETURN kmf_set_cert_serial(KMF_X509_CERTIFICATE *,
219	KMF_BIGINT *);
220
221extern KMF_RETURN kmf_set_cert_version(KMF_X509_CERTIFICATE *, uint32_t);
222
223extern KMF_RETURN kmf_set_cert_issuer_altname(KMF_X509_CERTIFICATE *,
224	int, KMF_GENERALNAMECHOICES, char *);
225
226extern KMF_RETURN kmf_set_cert_subject_altname(KMF_X509_CERTIFICATE *,
227	int, KMF_GENERALNAMECHOICES, char *);
228
229extern KMF_RETURN kmf_add_cert_eku(KMF_X509_CERTIFICATE *, KMF_OID *, int);
230
231extern KMF_RETURN kmf_set_cert_extn(KMF_X509_CERTIFICATE *,
232	KMF_X509_EXTENSION *);
233
234extern KMF_RETURN kmf_set_cert_basic_constraint(KMF_X509_CERTIFICATE *,
235	KMF_BOOL, KMF_X509EXT_BASICCONSTRAINTS *);
236
237
238/*
239 *  PK12 operations
240 */
241extern KMF_RETURN kmf_export_pk12(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
242
243extern KMF_RETURN kmf_build_pk12(KMF_HANDLE_T, int, KMF_X509_DER_CERT *,
244	int, KMF_KEY_HANDLE *, KMF_CREDENTIAL *, char *);
245
246extern KMF_RETURN kmf_import_objects(KMF_HANDLE_T, char *, KMF_CREDENTIAL *,
247	KMF_X509_DER_CERT **, int *, KMF_RAW_KEY_DATA **, int *);
248
249/*
250 * OCSP operations
251 */
252extern KMF_RETURN kmf_get_ocsp_for_cert(KMF_HANDLE_T, KMF_DATA *, KMF_DATA *,
253	KMF_DATA *);
254
255extern KMF_RETURN kmf_create_ocsp_request(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
256
257extern KMF_RETURN kmf_get_encoded_ocsp_response(KMF_HANDLE_T, char *,
258	char *, int, char *, int, char *, unsigned int);
259
260extern KMF_RETURN kmf_get_ocsp_status_for_cert(KMF_HANDLE_T, int,
261	KMF_ATTRIBUTE *);
262
263/*
264 * Policy Operations
265 */
266extern KMF_RETURN kmf_set_policy(KMF_HANDLE_T, char *, char *);
267
268/*
269 * Error handling.
270 */
271extern KMF_RETURN kmf_get_plugin_error_str(KMF_HANDLE_T, char **);
272extern KMF_RETURN kmf_get_kmf_error_str(KMF_RETURN, char **);
273
274/*
275 * Miscellaneous
276 */
277extern KMF_RETURN kmf_dn_parser(char *, KMF_X509_NAME *);
278extern KMF_RETURN kmf_read_input_file(KMF_HANDLE_T, char *, KMF_DATA *);
279extern KMF_RETURN kmf_der_to_pem(KMF_OBJECT_TYPE, unsigned char *,
280	int, unsigned char **, int *);
281extern KMF_RETURN kmf_pem_to_der(unsigned char *, int, unsigned char **, int *);
282extern char *kmf_oid_to_string(KMF_OID *);
283extern KMF_RETURN kmf_string_to_oid(char *, KMF_OID *);
284extern int kmf_compare_rdns(KMF_X509_NAME *, KMF_X509_NAME *);
285extern KMF_RETURN kmf_get_data_format(KMF_DATA *, KMF_ENCODE_FORMAT *);
286extern KMF_RETURN kmf_get_file_format(char *, KMF_ENCODE_FORMAT *);
287extern uint32_t kmf_string_to_ku(char *);
288extern char *kmf_ku_to_string(uint32_t);
289extern KMF_RETURN kmf_hexstr_to_bytes(unsigned char *, unsigned char **,
290	size_t *);
291
292extern KMF_RETURN kmf_get_plugin_info(KMF_HANDLE_T, char *,
293	KMF_KEYSTORE_TYPE *, char **);
294
295extern KMF_OID *kmf_ekuname_to_oid(char *);
296extern char *kmf_oid_to_ekuname(KMF_OID *);
297
298#define	KMF_CompareRDNs kmf_compare_rdns
299
300/*
301 * Memory cleanup operations
302 */
303extern void kmf_free_dn(KMF_X509_NAME *);
304extern void kmf_free_kmf_cert(KMF_HANDLE_T, KMF_X509_DER_CERT *);
305extern void kmf_free_data(KMF_DATA *);
306extern void kmf_free_algoid(KMF_X509_ALGORITHM_IDENTIFIER *);
307extern void kmf_free_extn(KMF_X509_EXTENSION *);
308extern void kmf_free_tbs_csr(KMF_TBS_CSR *);
309extern void kmf_free_signed_csr(KMF_CSR_DATA *);
310extern void kmf_free_tbs_cert(KMF_X509_TBS_CERT *);
311extern void kmf_free_signed_cert(KMF_X509_CERTIFICATE *);
312extern void kmf_free_str(char *);
313extern void kmf_free_eku(KMF_X509EXT_EKU *);
314extern void kmf_free_spki(KMF_X509_SPKI *);
315extern void kmf_free_kmf_key(KMF_HANDLE_T, KMF_KEY_HANDLE *);
316extern void kmf_free_bigint(KMF_BIGINT *);
317extern void kmf_free_raw_key(KMF_RAW_KEY_DATA *);
318extern void kmf_free_raw_sym_key(KMF_RAW_SYM_KEY *);
319extern void kmf_free_crl_dist_pts(KMF_X509EXT_CRLDISTPOINTS *);
320
321/* APIs for PKCS#11 token */
322extern KMF_RETURN kmf_pk11_token_lookup(KMF_HANDLE_T, char *, CK_SLOT_ID *);
323extern KMF_RETURN kmf_pk11_init_token(KMF_HANDLE_T,
324	char *, char *, CK_UTF8CHAR_PTR, CK_ULONG);
325extern KMF_RETURN kmf_set_token_pin(KMF_HANDLE_T, int, KMF_ATTRIBUTE *);
326extern CK_SESSION_HANDLE kmf_get_pk11_handle(KMF_HANDLE_T);
327
328/*
329 * Attribute management routines.
330 */
331int kmf_find_attr(KMF_ATTR_TYPE, KMF_ATTRIBUTE *, int);
332void *kmf_get_attr_ptr(KMF_ATTR_TYPE, KMF_ATTRIBUTE *, int);
333KMF_RETURN kmf_get_attr(KMF_ATTR_TYPE, KMF_ATTRIBUTE *, int, void *,
334	uint32_t *);
335KMF_RETURN kmf_get_string_attr(KMF_ATTR_TYPE, KMF_ATTRIBUTE *, int, char **);
336KMF_RETURN kmf_set_attr(KMF_ATTRIBUTE *, int, KMF_ATTR_TYPE, void *, uint32_t);
337void kmf_set_attr_at_index(KMF_ATTRIBUTE *, int, KMF_ATTR_TYPE,
338	void *, uint32_t);
339
340/*
341 * Certificate to name mapping functions.
342 */
343KMF_RETURN kmf_cert_to_name_mapping_initialize(KMF_HANDLE_T, int,
344	KMF_ATTRIBUTE *);
345KMF_RETURN kmf_cert_to_name_mapping_finalize(KMF_HANDLE_T);
346KMF_RETURN kmf_map_cert_to_name(KMF_HANDLE_T, KMF_DATA *, KMF_DATA *);
347KMF_RETURN kmf_match_cert_to_name(KMF_HANDLE_T, KMF_DATA *, KMF_DATA *,
348	KMF_DATA *);
349KMF_RETURN kmf_get_mapper_error_str(KMF_HANDLE_T, char **);
350/*
351 * Helper functions for handling the mapper internal state. They are part of the
352 * public interface, too.
353 */
354void kmf_set_mapper_lasterror(KMF_HANDLE_T, uint32_t);
355uint32_t kmf_get_mapper_lasterror(KMF_HANDLE_T);
356void kmf_set_mapper_options(KMF_HANDLE_T, void *);
357void *kmf_get_mapper_options(KMF_HANDLE_T);
358
359#ifdef __cplusplus
360}
361#endif
362#endif /* _KMFAPI_H */
363