store.h@ 76507

Last change on this file since 76507 was 76507, checked in by vboxsync, 6 years ago
/include: scm --fix-header-guards. bugref:9344
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 15.9 KB

Line
1	/** @file
2	* IPRT - Cryptographic (Certificate) Store.
3	*/
4
5	/*
6	* Copyright (C) 2006-2017 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___iprt_crypto_store_h
27	#define ___iprt_crypto_store_h
28	#ifndef RT_WITHOUT_PRAGMA_ONCE
29	# pragma once
30	#endif
31
32	#include <iprt/crypto/x509.h>
33	#include <iprt/crypto/taf.h>
34	#include <iprt/sha.h>
35
36
37	RT_C_DECLS_BEGIN
38
39	/** @defgroup grp_rt_crstore RTCrStore - Crypotgraphic (Certificate) Store.
40	* @ingroup grp_rt_crypto
41	* @{
42	*/
43
44
45	/**
46	* A certificate store search.
47	*
48	* Used by the store provider to keep track of the current location of a
49	* certificate search.
50	*/
51	typedef struct RTCRSTORECERTSEARCH
52	{
53	/** Opaque provider specific storage.
54	*
55	* Provider restriction: The provider is only allowed to use the two first
56	* entries for the find-all searches, because the front-end API may want the
57	* last two for implementing specific searches on top of it. */
58	uintptr_t auOpaque[4];
59	} RTCRSTORECERTSEARCH;
60	/** Pointer to a certificate store search. */
61	typedef RTCRSTORECERTSEARCH *PRTCRSTORECERTSEARCH;
62
63
64	/**
65	* Info about a wanted certificate.
66	*
67	* All the search criteria are optional, but for a safe and efficient search
68	* it's recommended to specify all possible ones. If none are given, the search
69	* function will fail.
70	*
71	* For use with RTCrStoreCertAddFromFishingExpedition and others.
72	*/
73	typedef struct RTCRCERTWANTED
74	{
75	/** The certificate subject name, optional.
76	* The format is: "C=US, ST=California, L=Redwood Shores, O=Oracle Corporation" */
77	const char *pszSubject;
78	/** The size of the DER (ASN.1) encoded certificate, optional (0). */
79	uint16_t cbEncoded;
80	/** Set if abSha1 contains a valid SHA-1 fingerprint. */
81	bool fSha1Fingerprint;
82	/** Set if abSha512 contains a valid SHA-512 fingerprint. */
83	bool fSha512Fingerprint;
84	/** The SHA-1 fingerprint (of the encoded data). */
85	uint8_t abSha1[RTSHA1_HASH_SIZE];
86	/** The SHA-512 fingerprint (of the encoded data). */
87	uint8_t abSha512[RTSHA512_HASH_SIZE];
88	/** User pointer for directly associating other data with the entry.
89	* Subclassing the structure isn't possible because it's passed as an array. */
90	void const *pvUser;
91	} RTCRCERTWANTED;
92	/** Pointer to a const certificat wanted structure. */
93	typedef RTCRCERTWANTED const *PCRTCRCERTWANTED;
94
95
96	/**
97	* Standard store identifiers.
98	*
99	* This is a least common denominator approach to system specific certificate
100	* stores, could be extended to include things other than certificates later if
101	* we need it.
102	*
103	* Windows has lots of different stores, they'll be combined by the
104	* implementation, possibly leading to duplicates. The user stores on Windows
105	* seems to be unioned with the system (machine) stores.
106	*
107	* Linux may have different stores depending on the distro/version/installation,
108	* in which case we'll combine them, which will most likely lead to
109	* duplicates just like on windows. Haven't found any easily accessible
110	* per-user certificate stores on linux yet, so they'll all be empty.
111	*
112	* Mac OS X seems a lot simpler, at least from the GUI point of view. Each
113	* keychains as a "Certificates" folder (the "My Certificates" folder seems to
114	* only be a matching of "Keys" and "Certificates"). However, there are two
115	* system keychains that we need to combine, "System" and "System Roots". As
116	* with Windows and Linux, there is a possibility for duplicates here.
117	*
118	* On solaris we have currently no idea where to look for a certificate store,
119	* so that doesn't yet work.
120	*
121	* Because of the OS X setup, we do not provide any purpose specific
122	*/
123	typedef enum RTCRSTOREID
124	{
125	/** Mandatory invalid zero value. */
126	RTCRSTOREID_INVALID = 0,
127	/** Open the certificate store of the current user containing trusted
128	* CAs and certificates.
129	* @remarks This may or may not include all the certificates in the system
130	* store, that's host dependent. So, you better look in both. */
131	RTCRSTOREID_USER_TRUSTED_CAS_AND_CERTIFICATES,
132	/** Open the certificate store of the system containg trusted CAs
133	* and certificates. */
134	RTCRSTOREID_SYSTEM_TRUSTED_CAS_AND_CERTIFICATES,
135	/** End of valid values. */
136	RTCRSTOREID_END,
137	/** Traditional enum type compression prevention hack. */
138	RTCRSTOREID_32BIT_HACK = 0x7fffffff
139	} RTCRSTOREID;
140
141	/**
142	* Creates a snapshot of a standard store.
143	*
144	* This will return an in-memory store containing all data from the given store.
145	* There will be no duplicates in this one.
146	*
147	* @returns IPRT status code.
148	* @retval VWRN_ALREADY_EXISTS if the certificate is already present and
149	* RTCRCERTCTX_F_ADD_IF_NOT_FOUND was specified.
150	* @param phStore Where to return the store handle. Use
151	* RTCrStoreRelease to release it.
152	* @param enmStoreId The store to snapshot.
153	* @param pErrInfo Where to return additional error/warning info.
154	* Optional.
155	*/
156	RTDECL(int) RTCrStoreCreateSnapshotById(PRTCRSTORE phStore, RTCRSTOREID enmStoreId, PRTERRINFO pErrInfo);
157
158	RTDECL(int) RTCrStoreCreateSnapshotOfUserAndSystemTrustedCAsAndCerts(PRTCRSTORE phStore, PRTERRINFO pErrInfo);
159
160	RTDECL(int) RTCrStoreCreateInMem(PRTCRSTORE phStore, uint32_t cSizeHint);
161
162	RTDECL(uint32_t) RTCrStoreRetain(RTCRSTORE hStore);
163	RTDECL(uint32_t) RTCrStoreRelease(RTCRSTORE hStore);
164	RTDECL(PCRTCRCERTCTX) RTCrStoreCertByIssuerAndSerialNo(RTCRSTORE hStore, PCRTCRX509NAME pIssuer, PCRTASN1INTEGER pSerialNo);
165
166	/**
167	* Add a certificate to the store.
168	*
169	* @returns IPRT status code.
170	* @retval VWRN_ALREADY_EXISTS if the certificate is already present and
171	* RTCRCERTCTX_F_ADD_IF_NOT_FOUND was specified.
172	* @retval VERR_WRITE_PROTECT if the store doesn't support adding.
173	* @param hStore The store to add the certificate to.
174	* @param fFlags RTCRCERTCTX_F_XXX. Encoding must be specified.
175	* RTCRCERTCTX_F_ADD_IF_NOT_FOUND is supported.
176	* @param pvSrc The encoded certificate bytes.
177	* @param cbSrc The size of the encoded certificate.
178	* @param pErrInfo Where to return additional error/warning info.
179	* Optional.
180	*/
181	RTDECL(int) RTCrStoreCertAddEncoded(RTCRSTORE hStore, uint32_t fFlags, void const *pvSrc, size_t cbSrc, PRTERRINFO pErrInfo);
182
183	/**
184	* Adds certificates from files in the specified directory.
185	*
186	* @returns IPRT status code. Even when RTCRCERTCTX_F_ADD_CONTINUE_ON_ERROR is
187	* used, an error is returned as an error (and not a warning).
188	*
189	* @param hStore The store to add the certificate(s) to.
190	* @param fFlags RTCRCERTCTX_F_ADD_IF_NOT_FOUND and/or
191	* RTCRCERTCTX_F_ADD_CONTINUE_ON_ERROR.
192	* @param pszDir The path to the directory.
193	* @param paSuffixes List of suffixes of files to process.
194	* @param cSuffixes Number of suffixes. If this is 0, all files are
195	* processed.
196	* @param pErrInfo Where to return additional error/warning info.
197	* Optional.
198	*/
199	RTDECL(int) RTCrStoreCertAddFromDir(RTCRSTORE hStore, uint32_t fFlags, const char *pszDir,
200	PCRTSTRTUPLE paSuffixes, size_t cSuffixes, PRTERRINFO pErrInfo);
201
202	RTDECL(int) RTCrStoreCertAddWantedFromDir(RTCRSTORE hStore, uint32_t fFlags,
203	const char *pszDir, PCRTSTRTUPLE paSuffixes, size_t cSuffixes,
204	PCRTCRCERTWANTED paWanted, size_t cWanted, bool *pafFound, PRTERRINFO pErrInfo);
205
206	/**
207	* Adds certificates from the specified file.
208	*
209	* The supported file formats are:
210	* - PEM (base 64 blobs wrapped in -----BEGIN / END----). Support multiple
211	* certificates in one file.
212	* - Binary DER ASN.1 certificate. Only one per file.
213	* - Java key store version 2.
214	*
215	* @returns IPRT status code. Even when RTCRCERTCTX_F_ADD_CONTINUE_ON_ERROR is
216	* used, an error is returned as an error (and not a warning).
217	*
218	* @param hStore The store to add the certificate(s) to.
219	* @param fFlags RTCRCERTCTX_F_ADD_IF_NOT_FOUND and/or
220	* RTCRCERTCTX_F_ADD_CONTINUE_ON_ERROR.
221	* @param pszFilename The filename.
222	* @param pErrInfo Where to return additional error/warning info.
223	* Optional.
224	*/
225	RTDECL(int) RTCrStoreCertAddFromFile(RTCRSTORE hStore, uint32_t fFlags, const char *pszFilename, PRTERRINFO pErrInfo);
226
227	RTDECL(int) RTCrStoreCertAddWantedFromFile(RTCRSTORE hStore, uint32_t fFlags, const char *pszFilename,
228	PCRTCRCERTWANTED paWanted, size_t cWanted, bool *pafFound, PRTERRINFO pErrInfo);
229
230	/**
231	* Adds certificates from the specified java key store file.
232	*
233	* @returns IPRT status code. Even when RTCRCERTCTX_F_ADD_CONTINUE_ON_ERROR is
234	* used, an error is returned as an error (and not a warning).
235	*
236	* @param hStore The store to add the certificate(s) to.
237	* @param fFlags RTCRCERTCTX_F_ADD_IF_NOT_FOUND and/or
238	* RTCRCERTCTX_F_ADD_CONTINUE_ON_ERROR.
239	* @param pszFilename The path to the JKS file.
240	* @param pErrInfo Where to return additional error/warning info.
241	* Optional.
242	*/
243	RTDECL(int) RTCrStoreCertAddFromJavaKeyStore(RTCRSTORE hStore, uint32_t fFlags, const char *pszFilename, PRTERRINFO pErrInfo);
244
245	/**
246	* Adds certificates from an in-memory java key store.
247	*
248	* @returns IPRT status code. Even when RTCRCERTCTX_F_ADD_CONTINUE_ON_ERROR is
249	* used, an error is returned as an error (and not a warning).
250	*
251	* @param hStore The store to add the certificate(s) to.
252	* @param fFlags RTCRCERTCTX_F_ADD_IF_NOT_FOUND and/or
253	* RTCRCERTCTX_F_ADD_CONTINUE_ON_ERROR.
254	* @param pvContent Pointer to the key store bytes.
255	* @param cbContent The size of the key store.
256	* @param pszErrorName The file name or whatever helpful indicator the
257	* caller want in the error messages.
258	* @param pErrInfo Where to return additional error/warning info.
259	* Optional.
260	*/
261	RTDECL(int) RTCrStoreCertAddFromJavaKeyStoreInMem(RTCRSTORE hStore, uint32_t fFlags, void const *pvContent, size_t cbContent,
262	const char *pszErrorName, PRTERRINFO pErrInfo);
263
264	/**
265	* Adds all certificates from @a hStoreSrc into @a hStore.
266	*
267	* @returns IPRT status code. Even when RTCRCERTCTX_F_ADD_CONTINUE_ON_ERROR is
268	* used, an error is returned as an error (and not a warning).
269	*
270	* @param hStore The destination store.
271	* @param fFlags RTCRCERTCTX_F_ADD_IF_NOT_FOUND and/or
272	* RTCRCERTCTX_F_ADD_CONTINUE_ON_ERROR.
273	* @param hStoreSrc The source store.
274	*/
275	RTDECL(int) RTCrStoreCertAddFromStore(RTCRSTORE hStore, uint32_t fFlags, RTCRSTORE hStoreSrc);
276
277	RTDECL(int) RTCrStoreCertAddWantedFromStore(RTCRSTORE hStore, uint32_t fFlags, RTCRSTORE hSrcStore,
278	PCRTCRCERTWANTED paWanted, size_t cWanted, bool *pafFound);
279
280	RTDECL(int) RTCrStoreCertCheckWanted(RTCRSTORE hStore, PCRTCRCERTWANTED paWanted, size_t cWanted, bool *pafFound);
281
282
283	RTDECL(int) RTCrStoreCertAddWantedFromFishingExpedition(RTCRSTORE hStore, uint32_t fFlags,
284	PCRTCRCERTWANTED paWanted, size_t cWanted,
285	bool *pafFound, PRTERRINFO pErrInfo);
286
287	/**
288	* Exports the certificates in the store to a PEM file
289	*
290	* @returns IPRT status code.
291	* @param hStore The store which certificates should be exported.
292	* @param fFlags Reserved for the future, MBZ.
293	* @param pszFilename The name of the destination PEM file. This will
294	* be truncated.
295	*/
296	RTDECL(int) RTCrStoreCertExportAsPem(RTCRSTORE hStore, uint32_t fFlags, const char *pszFilename);
297
298	/**
299	* Counts the number of certificates in the store.
300	*
301	* @returns Certificate count on success, UINT32_MAX on failure.
302	* @param hStore The store which certificates should be counted.
303	*/
304	RTDECL(uint32_t) RTCrStoreCertCount(RTCRSTORE hStore);
305
306	RTDECL(int) RTCrStoreCertFindAll(RTCRSTORE hStore, PRTCRSTORECERTSEARCH pSearch);
307	RTDECL(int) RTCrStoreCertFindBySubjectOrAltSubjectByRfc5280(RTCRSTORE hStore, PCRTCRX509NAME pSubject,
308	PRTCRSTORECERTSEARCH pSearch);
309	RTDECL(PCRTCRCERTCTX) RTCrStoreCertSearchNext(RTCRSTORE hStore, PRTCRSTORECERTSEARCH pSearch);
310	RTDECL(int) RTCrStoreCertSearchDestroy(RTCRSTORE hStore, PRTCRSTORECERTSEARCH pSearch);
311
312	RTDECL(int) RTCrStoreConvertToOpenSslCertStore(RTCRSTORE hStore, uint32_t fFlags, void **ppvOpenSslStore);
313	RTDECL(int) RTCrStoreConvertToOpenSslCertStack(RTCRSTORE hStore, uint32_t fFlags, void **ppvOpenSslStack);
314
315
316	/** @} */
317
318
319	/** @defgroup grp_rt_crcertctx RTCrCertCtx - (Store) Certificate Context.
320	* @{ */
321
322
323	/**
324	* Certificate context.
325	*
326	* This is returned by the certificate store APIs and is part of a larger
327	* reference counted structure. All the data is read only.
328	*/
329	typedef struct RTCRCERTCTX
330	{
331	/** Flags, RTCRCERTCTX_F_XXX. */
332	uint32_t fFlags;
333	/** The size of the (DER) encoded certificate. */
334	uint32_t cbEncoded;
335	/** Pointer to the (DER) encoded certificate. */
336	uint8_t const *pabEncoded;
337	/** Pointer to the decoded X.509 representation of the certificate.
338	* This can be NULL when pTaInfo is present. */
339	PCRTCRX509CERTIFICATE pCert;
340	/** Pointer to the decoded TrustAnchorInfo for the certificate. This can be
341	* NULL, even for trust anchors, as long as pCert isn't. */
342	PCRTCRTAFTRUSTANCHORINFO pTaInfo;
343	/** Reserved for future use. */
344	void *paReserved[2];
345	} RTCRCERTCTX;
346
347	/** @name RTCRCERTCTX_F_XXX.
348	* @{ */
349	/** Encoding mask. */
350	#define RTCRCERTCTX_F_ENC_MASK UINT32_C(0x000000ff)
351	/** X.509 certificate, DER encoded. */
352	#define RTCRCERTCTX_F_ENC_X509_DER UINT32_C(0x00000000)
353	/** RTF-5914 trust anchor info, DER encoded. */
354	#define RTCRCERTCTX_F_ENC_TAF_DER UINT32_C(0x00000001)
355	#if 0
356	/** Extended certificate, DER encoded. */
357	#define RTCRCERTCTX_F_ENC_PKCS6_DER UINT32_C(0x00000002)
358	#endif
359	/** Mask containing the flags that ends up in the certificate context. */
360	#define RTCRCERTCTX_F_MASK UINT32_C(0x000000ff)
361
362	/** Add APIs: Add the certificate if not found. */
363	#define RTCRCERTCTX_F_ADD_IF_NOT_FOUND UINT32_C(0x00010000)
364	/** Add APIs: Continue on error when possible. */
365	#define RTCRCERTCTX_F_ADD_CONTINUE_ON_ERROR UINT32_C(0x00020000)
366	/** @} */
367
368
369	RTDECL(uint32_t) RTCrCertCtxRetain(PCRTCRCERTCTX pCertCtx);
370	RTDECL(uint32_t) RTCrCertCtxRelease(PCRTCRCERTCTX pCertCtx);
371
372	/** @} */
373
374	RT_C_DECLS_END
375
376	#endif
377

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/crypto/store.h@ 76507

Download in other formats: