pem.h@ 84341

Last change on this file since 84341 was 84230, checked in by vboxsync, 5 years ago
IPRT,openssl: Adding RTCrPkcs7SimpleSignSignedData as a feeble start at PKCS#7/CMS signing. bugref:9699
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 11.4 KB

Line
1	/** @file
2	* IPRT - Crypto - PEM-file Reader & Writer.
3	*/
4
5	/*
6	* Copyright (C) 2006-2020 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_INCLUDED_crypto_pem_h
27	#define IPRT_INCLUDED_crypto_pem_h
28	#ifndef RT_WITHOUT_PRAGMA_ONCE
29	# pragma once
30	#endif
31
32	#include <iprt/types.h>
33	#include <iprt/asn1.h> /* PRTASN1CORE */
34	#include <iprt/string.h> /* PFNRTSTROUTPUT */
35
36
37	RT_C_DECLS_BEGIN
38
39	/** @defgroup grp_rt_spc RTCrPem - PEM-file Reader & Writer
40	* @ingroup grp_rt_crypto
41	* @{
42	*/
43
44
45	/**
46	* One PEM marker word (use RT_STR_TUPLE to initialize).
47	*/
48	typedef struct RTCRPEMMARKERWORD
49	{
50	/** The word string. */
51	const char *pszWord;
52	/** The length. */
53	uint32_t cchWord;
54	} RTCRPEMMARKERWORD;
55	/** Pointer to a const marker word. */
56	typedef RTCRPEMMARKERWORD const *PCRTCRPEMMARKERWORD;
57
58
59	/**
60	* A PEM marker.
61	*
62	* This is an array of words with lengths, optimized for avoid unnecessary
63	* strlen() while searching the file content. It is ASSUMED that all PEM
64	* section markers starts with either 'BEGIN' or 'END', followed by the words
65	* in the this structure.
66	*/
67	typedef struct RTCRPEMMARKER
68	{
69	/** Pointer to an array of marker words. */
70	PCRTCRPEMMARKERWORD paWords;
71	/** Number of works in the array papszWords points to. */
72	uint32_t cWords;
73	} RTCRPEMMARKER;
74	/** Pointer to a const PEM marker. */
75	typedef RTCRPEMMARKER const *PCRTCRPEMMARKER;
76
77
78	/**
79	* A PEM field.
80	*/
81	typedef struct RTCRPEMFIELD
82	{
83	/** Pointer to the next field. */
84	struct RTCRPEMFIELD const *pNext;
85	/** The field value. */
86	char const *pszValue;
87	/** The field value length. */
88	size_t cchValue;
89	/** The field name length. */
90	size_t cchName;
91	/** The field name. */
92	char szName[RT_FLEXIBLE_ARRAY];
93	} RTCRPEMFIELD;
94	/** Pointer to a PEM field. */
95	typedef RTCRPEMFIELD *PRTCRPEMFIELD;
96	/** Pointer to a const PEM field. */
97	typedef RTCRPEMFIELD const *PCRTCRPEMFIELD;
98
99
100	/**
101	* A PEM section.
102	*
103	* The API works on linked lists of these.
104	*/
105	typedef struct RTCRPEMSECTION
106	{
107	/** Pointer to the next file section. */
108	struct RTCRPEMSECTION const *pNext;
109	/** The marker for this section. NULL if binary file. */
110	PCRTCRPEMMARKER pMarker;
111	/** Pointer to the binary data. */
112	uint8_t *pbData;
113	/** The size of the binary data. */
114	size_t cbData;
115	/** List of fields, NULL if none. */
116	PCRTCRPEMFIELD pFieldHead;
117	/** Set if RTCRPEMREADFILE_F_SENSITIVE was specified. */
118	bool fSensitive;
119	} RTCRPEMSECTION;
120	/** Pointer to a PEM section. */
121	typedef RTCRPEMSECTION *PRTCRPEMSECTION;
122	/** Pointer to a const PEM section. */
123	typedef RTCRPEMSECTION const *PCRTCRPEMSECTION;
124
125
126	/**
127	* Frees sections returned by RTCrPemReadFile and RTCrPemParseContent.
128	* @returns IPRT status code.
129	* @param pSectionHead The first section.
130	*/
131	RTDECL(int) RTCrPemFreeSections(PCRTCRPEMSECTION pSectionHead);
132
133	/**
134	* Parses the given data and returns a list of binary sections.
135	*
136	* If the file isn't an ASCII file or if no markers were found, the entire file
137	* content is returned as one single section (with pMarker = NULL).
138	*
139	* @returns IPRT status code.
140	* @retval VINF_EOF if the file is empty. The @a ppSectionHead value will be
141	* NULL.
142	* @retval VWRN_NOT_FOUND no section was found and RTCRPEMREADFILE_F_ONLY_PEM
143	* is specified. The @a ppSectionHead value will be NULL.
144	*
145	* @param pvContent The content bytes to parse.
146	* @param cbContent The number of content bytes.
147	* @param fFlags RTCRPEMREADFILE_F_XXX.
148	* @param paMarkers Array of one or more section markers to look for.
149	* @param cMarkers Number of markers in the array.
150	* @param ppSectionHead Where to return the head of the section list. Call
151	* RTCrPemFreeSections to free.
152	* @param pErrInfo Where to return extend error info. Optional.
153	*/
154	RTDECL(int) RTCrPemParseContent(void const *pvContent, size_t cbContent, uint32_t fFlags,
155	PCRTCRPEMMARKER paMarkers, size_t cMarkers, PCRTCRPEMSECTION *ppSectionHead, PRTERRINFO pErrInfo);
156
157	/**
158	* Reads the content of the given file and returns a list of binary sections
159	* found in the file.
160	*
161	* If the file isn't an ASCII file or if no markers were found, the entire file
162	* content is returned as one single section (with pMarker = NULL).
163	*
164	* @returns IPRT status code.
165	* @retval VINF_EOF if the file is empty. The @a ppSectionHead value will be
166	* NULL.
167	* @retval VWRN_NOT_FOUND no section was found and RTCRPEMREADFILE_F_ONLY_PEM
168	* is specified. The @a ppSectionHead value will be NULL.
169	*
170	* @param pszFilename The path to the file to read.
171	* @param fFlags RTCRPEMREADFILE_F_XXX.
172	* @param paMarkers Array of one or more section markers to look for.
173	* @param cMarkers Number of markers in the array.
174	* @param ppSectionHead Where to return the head of the section list. Call
175	* RTCrPemFreeSections to free.
176	* @param pErrInfo Where to return extend error info. Optional.
177	*/
178	RTDECL(int) RTCrPemReadFile(const char *pszFilename, uint32_t fFlags, PCRTCRPEMMARKER paMarkers, size_t cMarkers,
179	PCRTCRPEMSECTION *ppSectionHead, PRTERRINFO pErrInfo);
180	/** @name RTCRPEMREADFILE_F_XXX - Flags for RTCrPemReadFile and
181	* RTCrPemParseContent.
182	* @{ */
183	/** Continue on encoding error. */
184	#define RTCRPEMREADFILE_F_CONTINUE_ON_ENCODING_ERROR RT_BIT(0)
185	/** Only PEM sections, no binary fallback. */
186	#define RTCRPEMREADFILE_F_ONLY_PEM RT_BIT(1)
187	/** Sensitive data, use the safer allocator. */
188	#define RTCRPEMREADFILE_F_SENSITIVE RT_BIT(2)
189	/** Valid flags. */
190	#define RTCRPEMREADFILE_F_VALID_MASK UINT32_C(0x00000007)
191	/** @} */
192
193	/**
194	* Finds the beginning of first PEM section using the specified markers.
195	*
196	* This will not look any further than the first section. Nor will it check for
197	* binaries.
198	*
199	* @returns Pointer to the "-----BEGIN XXXX" sequence on success.
200	* NULL if not found.
201	* @param pvContent The content bytes to parse.
202	* @param cbContent The number of content bytes.
203	* @param paMarkers Array of one or more section markers to look for.
204	* @param cMarkers Number of markers in the array.
205	*/
206	RTDECL(const char ) RTCrPemFindFirstSectionInContent(void const pvContent, size_t cbContent,
207	PCRTCRPEMMARKER paMarkers, size_t cMarkers);
208
209
210	/**
211	* PEM formatter for a binary data blob.
212	*
213	* @returns Number of output bytes (sum of @a pfnOutput return values).
214	* @param pfnOutput The output callback function.
215	* @param pvUser The user argument to the output callback.
216	* @param pvContent The binary blob to output.
217	* @param cbContent Size of the binary blob.
218	* @param pszMarker The PEM marker, .e.g "PRIVATE KEY", "CERTIFICATE" or
219	* similar.
220	* @sa RTCrPemWriteAsn1, RTCrPemWriteAsn1ToVfsFile,
221	* RTCrPemWriteAsn1ToVfsFile
222	*/
223	RTDECL(size_t) RTCrPemWriteBlob(PFNRTSTROUTPUT pfnOutput, void *pvUser,
224	const void pvContent, size_t cbContent, const char pszMarker);
225
226	RTDECL(ssize_t) RTCrPemWriteBlobToVfsIoStrm(RTVFSIOSTREAM hVfsIos, const void pvContent, size_t cbContent, const char pszMarker);
227	RTDECL(ssize_t) RTCrPemWriteBlobToVfsFile(RTVFSFILE hVfsFile, const void pvContent, size_t cbContent, const char pszMarker);
228
229	/**
230	* PEM formatter for a generic ASN.1 structure.
231	*
232	* This will call both RTAsn1EncodePrepare() and RTAsn1EncodeWrite() on
233	* @a pRoot. Uses DER encoding.
234	*
235	* @returns Number of outputted chars (sum of @a pfnOutput return values),
236	* negative values are error status codes from the ASN.1 encoding.
237	* @param pfnOutput The output callback function.
238	* @param pvUser The user argument to the output callback.
239	* @param fFlags Reserved, MBZ.
240	* @param pRoot The root of the ASN.1 to encode and format as PEM.
241	* @param pszMarker The PEM marker, .e.g "PRIVATE KEY", "CERTIFICATE" or
242	* similar.
243	* @param pErrInfo For encoding errors. Optional.
244	* @sa RTCrPemWriteAsn1ToVfsFile, RTCrPemWriteAsn1ToVfsFile,
245	* RTCrPemWriteBlob
246	*/
247	RTDECL(ssize_t) RTCrPemWriteAsn1(PFNRTSTROUTPUT pfnOutput, void *pvUser, PRTASN1CORE pRoot,
248	uint32_t fFlags, const char *pszMarker, PRTERRINFO pErrInfo);
249
250	/**
251	* PEM formatter for a generic ASN.1 structure and output it to @a hVfsIos.
252	*
253	* This will call both RTAsn1EncodePrepare() and RTAsn1EncodeWrite() on
254	* @a pRoot. Uses DER encoding.
255	*
256	* @returns Number of chars written, negative values are error status codes from
257	* the ASN.1 encoding or from RTVfsIoStrmWrite().
258	* @param hVfsIos Handle to the I/O stream to write it to.
259	* @param fFlags Reserved, MBZ.
260	* @param pRoot The root of the ASN.1 to encode and format as PEM.
261	* @param pszMarker The PEM marker, .e.g "PRIVATE KEY", "CERTIFICATE" or
262	* similar.
263	* @param pErrInfo For encoding errors. Optional.
264	* @sa RTCrPemWriteAsn1ToVfsFile, RTCrPemWriteAsn1, RTCrPemWriteBlob
265	*/
266	RTDECL(ssize_t) RTCrPemWriteAsn1ToVfsIoStrm(RTVFSIOSTREAM hVfsIos, PRTASN1CORE pRoot,
267	uint32_t fFlags, const char *pszMarker, PRTERRINFO pErrInfo);
268
269	/**
270	* PEM formatter for a generic ASN.1 structure and output it to @a hVfsFile.
271	*
272	* This will call both RTAsn1EncodePrepare() and RTAsn1EncodeWrite() on
273	* @a pRoot. Uses DER encoding.
274	*
275	* @returns Number of chars written, negative values are error status codes from
276	* the ASN.1 encoding or from RTVfsIoStrmWrite().
277	* @param hVfsFile Handle to the file to write it to.
278	* @param fFlags Reserved, MBZ.
279	* @param pRoot The root of the ASN.1 to encode and format as PEM.
280	* @param pszMarker The PEM marker, .e.g "PRIVATE KEY", "CERTIFICATE" or
281	* similar.
282	* @param pErrInfo For encoding errors. Optional.
283	* @sa RTCrPemWriteAsn1ToVfsIoStrm, RTCrPemWriteAsn1, RTCrPemWriteBlob
284	*/
285	RTDECL(ssize_t) RTCrPemWriteAsn1ToVfsFile(RTVFSFILE hVfsFile, PRTASN1CORE pRoot,
286	uint32_t fFlags, const char *pszMarker, PRTERRINFO pErrInfo);
287
288	/** @} */
289
290	RT_C_DECLS_END
291
292	#endif /* !IPRT_INCLUDED_crypto_pem_h */
293

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

source: vbox/trunk/include/iprt/crypto/pem.h@ 84341

Download in other formats: