pkix.h@ 104070

Last change on this file since 104070 was 100442, checked in by vboxsync, 17 months ago
IPRT,OpenSSL: Support ECDSA for verficiation purposes when IPRT links with OpenSSL. This required quite a bit of cleanups, so not entirely no-risk. bugref:10479 ticketref:21621
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 30.9 KB

Line
1	/** @file
2	* IPRT - Public Key Infrastructure APIs.
3	*/
4
5	/*
6	* Copyright (C) 2006-2023 Oracle and/or its affiliates.
7	*
8	* This file is part of VirtualBox base platform packages, as
9	* available from https://www.virtualbox.org.
10	*
11	* This program is free software; you can redistribute it and/or
12	* modify it under the terms of the GNU General Public License
13	* as published by the Free Software Foundation, in version 3 of the
14	* License.
15	*
16	* This program is distributed in the hope that it will be useful, but
17	* WITHOUT ANY WARRANTY; without even the implied warranty of
18	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19	* General Public License for more details.
20	*
21	* You should have received a copy of the GNU General Public License
22	* along with this program; if not, see <https://www.gnu.org/licenses>.
23	*
24	* The contents of this file may alternatively be used under the terms
25	* of the Common Development and Distribution License Version 1.0
26	* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27	* in the VirtualBox distribution, in which case the provisions of the
28	* CDDL are applicable instead of those of the GPL.
29	*
30	* You may elect to license modified versions of this file under the
31	* terms and conditions of either the GPL or the CDDL or both.
32	*
33	* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34	*/
35
36	#ifndef IPRT_INCLUDED_crypto_pkix_h
37	#define IPRT_INCLUDED_crypto_pkix_h
38	#ifndef RT_WITHOUT_PRAGMA_ONCE
39	# pragma once
40	#endif
41
42	#include <iprt/asn1.h>
43
44
45	RT_C_DECLS_BEGIN
46
47	struct RTCRX509CERTIFICATE;
48	struct RTCRX509SUBJECTPUBLICKEYINFO;
49
50	/** @defgroup grp_rt_crpkix RTCrPkix - Public Key Infrastructure APIs
51	* @ingroup grp_rt_crypto
52	* @{
53	*/
54
55	/**
56	* Verifies the signature (@a pSignatureValue) of the give data (@a pvData)
57	* using the specfied public key (@a pPublicKey) and algorithm.
58	*
59	* @returns IPRT status code.
60	* @param pAlgorithm The signature algorithm (digest w/ cipher).
61	* @param hPublicKey The public key.
62	* @param pParameters The signature parameters (not key, those are already
63	* kept by hPublicKey).
64	* @param pSignatureValue The signature value.
65	* @param pvData The signed data.
66	* @param cbData The amount of signed data.
67	* @param pErrInfo Where to return extended error info. Optional.
68	*
69	* @remarks Depending on the IPRT build configuration, the verficiation may be
70	* performed more than once using all available crypto implementations.
71	*/
72	RTDECL(int) RTCrPkixPubKeyVerifySignature(PCRTASN1OBJID pAlgorithm, RTCRKEY hPublicKey, PCRTASN1DYNTYPE pParameters,
73	PCRTASN1BITSTRING pSignatureValue, const void *pvData, size_t cbData,
74	PRTERRINFO pErrInfo);
75
76
77	/**
78	* Verifies the signed digest (@a pvSignedDigest) against our digest (@a
79	* hDigest) using the specfied public key (@a pPublicKey) and algorithm.
80	*
81	* @returns IPRT status code.
82	* @param pAlgorithm The signature algorithm (digest w/ cipher).
83	* @param hPublicKey The public key.
84	* @param pParameters The signature parameters (not key, those are already
85	* kept by hPublicKey).
86	* @param pvSignedDigest The signed digest.
87	* @param cbSignedDigest The signed digest size.
88	* @param hDigest The digest of the data to compare @a pvSignedDigest
89	* with.
90	* @param pErrInfo Where to return extended error info. Optional.
91	*
92	* @remarks Depending on the IPRT build configuration, the verficiation may be
93	* performed more than once using all available crypto implementations.
94	*/
95	RTDECL(int) RTCrPkixPubKeyVerifySignedDigest(PCRTASN1OBJID pAlgorithm, RTCRKEY hPublicKey, PCRTASN1DYNTYPE pParameters,
96	void const *pvSignedDigest, size_t cbSignedDigest,
97	RTCRDIGEST hDigest, PRTERRINFO pErrInfo);
98
99	/**
100	* Wrapper around RTCrPkixPubKeyVerifySignedDigest & RTCrKeyCreateFromAlgorithmAndBits.
101	*
102	* @note The public key info must include digest type for this to work.
103	*/
104	RTDECL(int) RTCrPkixPubKeyVerifySignedDigestByCertPubKeyInfo(struct RTCRX509SUBJECTPUBLICKEYINFO const *pCertPubKeyInfo,
105	void const *pvSignedDigest, size_t cbSignedDigest,
106	RTCRDIGEST hDigest, PRTERRINFO pErrInfo);
107
108	/**
109	* Checks if the hash size can be handled by the given public key.
110	*/
111	RTDECL(bool) RTCrPkixPubKeyCanHandleDigestType(struct RTCRX509SUBJECTPUBLICKEYINFO const *pPublicKeyInfo,
112	RTDIGESTTYPE enmDigestType, PRTERRINFO pErrInfo);
113
114	/**
115	* Checks if the hash size can be handled by the given certificate's public key.
116	*/
117	RTDECL(bool) RTCrPkixCanCertHandleDigestType(struct RTCRX509CERTIFICATE const *pCertificate,
118	RTDIGESTTYPE enmDigestType, PRTERRINFO pErrInfo);
119
120	/**
121	* Signs a digest (@a hDigest) using the specified private key (@a pPrivateKey) and algorithm.
122	*
123	* @returns IPRT status code.
124	* @param pAlgorithm The signature algorithm (digest w/ cipher).
125	* @param hPrivateKey Handle to the private key to use.
126	* @param pParameters Parameter to the public key algorithm. Optional.
127	* @param hDigest The digest of the data being signed.
128	* @param fFlags Flags for future extensions, MBZ.
129	* @param pvSignature The output signature buffer. Pass NULL to query
130	* the signature size.
131	* @param pcbSignature On input the variable pointed to holds the size of
132	* the buffer @a pvSignature points to.
133	* On return the variable pointed to is set to the size
134	* of the returned signature, or the required size in
135	* case of VERR_BUFFER_OVERFLOW.
136	* @param pErrInfo Where to return extended error info. Optional.
137	*
138	* @remarks Depending on the IPRT build configuration and the algorithm used, the
139	* signing may be performed more than once using all available crypto
140	* implementations.
141	*/
142	RTDECL(int) RTCrPkixPubKeySignDigest(PCRTASN1OBJID pAlgorithm, RTCRKEY hPrivateKey, PCRTASN1DYNTYPE pParameters,
143	RTCRDIGEST hDigest, uint32_t fFlags,
144	void pvSignature, size_t pcbSignature, PRTERRINFO pErrInfo);
145
146	/**
147	* Gets the cipher OID matching the given signature algorithm.
148	*
149	* @returns Cipher OID string on success, NULL on failure.
150	* @param pAlgorithm The signature algorithm (hash function w/ cipher).
151	* @sa RTCrX509AlgorithmIdentifier_GetEncryptionOid,
152	* RTCrX509AlgorithmIdentifier_GetEncryptionOidFromOid
153	*/
154	RTDECL(const char *) RTCrPkixGetCiperOidFromSignatureAlgorithm(PCRTASN1OBJID pAlgorithm);
155
156	/**
157	* Gets the cipher OID matching the given signature algorithm OID.
158	*
159	* @returns Cipher OID string on success, NULL on failure.
160	* @param pszSignatureOid The signature algorithm ID (hash function w/ cipher).
161	* @sa RTCrX509AlgorithmIdentifier_GetEncryptionOid,
162	* RTCrX509AlgorithmIdentifier_GetEncryptionOidFromOid
163	*/
164	RTDECL(const char ) RTCrPkixGetCiperOidFromSignatureAlgorithmOid(const char pszSignatureOid);
165
166
167	/** @name PKCS-1 Object Identifiers (OIDs)
168	* @{ */
169	#define RTCR_PKCS1_OID "1.2.840.113549.1.1"
170	#define RTCR_PKCS1_RSA_OID "1.2.840.113549.1.1.1"
171	#define RTCR_PKCS1_MD2_WITH_RSA_OID "1.2.840.113549.1.1.2"
172	#define RTCR_PKCS1_MD4_WITH_RSA_OID "1.2.840.113549.1.1.3"
173	#define RTCR_PKCS1_MD5_WITH_RSA_OID "1.2.840.113549.1.1.4"
174	#define RTCR_PKCS1_SHA1_WITH_RSA_OID "1.2.840.113549.1.1.5"
175	#define RTCR_PKCS1_RSA_OAEP_ENCRYPTION_SET_OID "1.2.840.113549.1.1.6"
176	#define RTCR_PKCS1_RSA_AES_OAEP_OID "1.2.840.113549.1.1.7"
177	#define RTCR_PKCS1_MSGF1_OID "1.2.840.113549.1.1.8"
178	#define RTCR_PKCS1_P_SPECIFIED_OID "1.2.840.113549.1.1.9"
179	#define RTCR_PKCS1_RSASSA_PSS_OID "1.2.840.113549.1.1.10"
180	#define RTCR_PKCS1_SHA256_WITH_RSA_OID "1.2.840.113549.1.1.11"
181	#define RTCR_PKCS1_SHA384_WITH_RSA_OID "1.2.840.113549.1.1.12"
182	#define RTCR_PKCS1_SHA512_WITH_RSA_OID "1.2.840.113549.1.1.13"
183	#define RTCR_PKCS1_SHA224_WITH_RSA_OID "1.2.840.113549.1.1.14"
184	#define RTCR_PKCS1_SHA512T224_WITH_RSA_OID "1.2.840.113549.1.1.15"
185	#define RTCR_PKCS1_SHA512T256_WITH_RSA_OID "1.2.840.113549.1.1.16"
186	/** @} */
187
188	/** @name ANSI X9.62 Object Identifiers (OIDs)
189	* @{ */
190	#define RTCR_X962_ECDSA_OID "1.2.840.10045.2.1"
191	#define RTCR_X962_ECDSA_WITH_SHA1_OID "1.2.840.10045.4.1"
192	#define RTCR_X962_ECDSA_WITH_SHA2_OID "1.2.840.10045.4.3"
193	#define RTCR_X962_ECDSA_WITH_SHA224_OID "1.2.840.10045.4.3.1"
194	#define RTCR_X962_ECDSA_WITH_SHA256_OID "1.2.840.10045.4.3.2"
195	#define RTCR_X962_ECDSA_WITH_SHA384_OID "1.2.840.10045.4.3.3"
196	#define RTCR_X962_ECDSA_WITH_SHA512_OID "1.2.840.10045.4.3.4"
197	/** @} */
198
199	/** @name NIST Object Identifiers (OIDs)
200	* @{ */
201	#define RTCR_NIST_ALGORITHM_OID "2.16.840.1.101.3.4"
202	#define RTCR_NIST_HASH_ALGS_OID "2.16.840.1.101.3.4.2"
203	#define RTCR_NIST_SIG_ALGS_OID "2.16.840.1.101.3.4.3"
204	#define RTCR_NIST_SHA3_224_WITH_ECDSA_OID "2.16.840.1.101.3.4.3.9"
205	#define RTCR_NIST_SHA3_256_WITH_ECDSA_OID "2.16.840.1.101.3.4.3.10"
206	#define RTCR_NIST_SHA3_384_WITH_ECDSA_OID "2.16.840.1.101.3.4.3.11"
207	#define RTCR_NIST_SHA3_512_WITH_ECDSA_OID "2.16.840.1.101.3.4.3.12"
208	#define RTCR_NIST_SHA3_224_WITH_RSA_OID "2.16.840.1.101.3.4.3.13"
209	#define RTCR_NIST_SHA3_256_WITH_RSA_OID "2.16.840.1.101.3.4.3.14"
210	#define RTCR_NIST_SHA3_384_WITH_RSA_OID "2.16.840.1.101.3.4.3.15"
211	#define RTCR_NIST_SHA3_512_WITH_RSA_OID "2.16.840.1.101.3.4.3.16"
212	/** @} */
213
214
215	/**
216	* Public key signature scheme provider descriptor.
217	*/
218	typedef struct RTCRPKIXSIGNATUREDESC
219	{
220	/** The signature scheme provider name. */
221	const char *pszName;
222	/** The object ID string. */
223	const char *pszObjId;
224	/** Pointer to a NULL terminated table of alias object IDs (optional). */
225	const char * const *papszObjIdAliases;
226	/** The size of the state. */
227	uint32_t cbState;
228	/** Reserved for future / explicit padding. */
229	uint32_t uReserved;
230	/** Provider specific field. This generally indicates the kind of padding
231	* scheme to employ with the given OID. */
232	uintptr_t uProviderSpecific;
233
234	/**
235	* Initializes the state of the signature scheme provider.
236	*
237	* Optional, RT_BZERO will be used if NULL.
238	*
239	* @returns IPRT status code.
240	* @param pDesc Pointer to this structure (for uProviderSpecific).
241	* @param pvState The opaque provider state.
242	* @param pvOpaque Opaque provider specific parameter.
243	* @param fSigning Set if a signing operation is going to be performed,
244	* clear if it is a verification. This is a fixed
245	* setting for the lifetime of the instance due to the
246	* algorithm requiring different keys.
247	* @param hKey The key handle. Caller has retained it for the
248	* lifetime of the state being initialize.
249	* @param pParams Algorithm/key parameters, optional. Will be NULL if
250	* none.
251	*/
252	DECLCALLBACKMEMBER(int, pfnInit,(struct RTCRPKIXSIGNATUREDESC const pDesc, void pvState, void *pvOpaque, bool fSigning,
253	RTCRKEY hKey, PCRTASN1DYNTYPE pParams));
254
255	/**
256	* Resets the state before performing another signing or verification.
257	*
258	* Optional. It is assumed that the provider does not have any state needing to
259	* be re-initialized if this method is not implemented.
260	*
261	* @returns IPRT status code.
262	* @param pDesc Pointer to this structure (for uProviderSpecific).
263	* @param pvState The opaque provider state.
264	* @param fSigning Exactly the same value as the init call.
265	*/
266	DECLCALLBACKMEMBER(int, pfnReset,(struct RTCRPKIXSIGNATUREDESC const pDesc, void pvState, bool fSigning));
267
268	/**
269	* Deletes the provider state. Optional.
270	*
271	* The state will be securely wiped clean after the call, regardless of whether
272	* the method is implemented or not.
273	*
274	* @param pDesc Pointer to this structure (for uProviderSpecific).
275	* @param pvState The opaque provider state.
276	* @param fSigning Exactly the same value as the init call.
277	*/
278	DECLCALLBACKMEMBER(void, pfnDelete,(struct RTCRPKIXSIGNATUREDESC const pDesc, void pvState, bool fSigning));
279
280	/**
281	* Verifies a signed message digest (fSigning = false).
282	*
283	* @returns IPRT status code.
284	* @retval VINF_SUCCESS if the signature checked out correctly.
285	* @retval VINF_CR_DIGEST_DEPRECATED if the signature checked out correctly
286	* but the hash algorithm is deprecated.
287	* @retval VINF_CR_DIGEST_COMPROMISED if the signature checked out correctly
288	* but the hash algorithm is compromised.
289	* @retval VINF_CR_DIGEST_SEVERELY_COMPROMISED if the signature checked out
290	* correctly but the hash algorithm is severely compromised.
291	* @retval VERR_PKIX_KEY wrong key or some other key issue.
292	*
293	* @param pDesc Pointer to this structure (for uProviderSpecific).
294	* @param pvState The opaque provider state.
295	* @param hKey The key handle associated with the state at init.
296	* @param hDigest The handle to the digest. Calls RTCrDigestFinal to
297	* complete and retreive the final hash value.
298	* @param pvSignature The signature to validate.
299	* @param cbSignature The size of the signature (in bytes).
300	*/
301	DECLCALLBACKMEMBER(int, pfnVerify,(struct RTCRPKIXSIGNATUREDESC const pDesc, void pvState, RTCRKEY hKey,
302	RTCRDIGEST hDigest, void const *pvSignature, size_t cbSignature));
303
304	/**
305	* Sign a message digest (fSigning = true).
306	*
307	* @returns IPRT status code.
308	* @retval VINF_SUCCESS on success.
309	* @retval VINF_CR_DIGEST_DEPRECATED on success but the hash algorithm is deprecated.
310	* @retval VINF_CR_DIGEST_COMPROMISED on success but the hash algorithm is compromised.
311	* @retval VINF_CR_DIGEST_SEVERELY_COMPROMISED on success but the hash algorithm
312	* is severely compromised.
313	* @retval VERR_PKIX_KEY wrong key or some other key issue.
314	* @retval VERR_BUFFER_OVERFLOW if the signature buffer is too small, the
315	* require buffer size will be available in @a *pcbSignature.
316	*
317	* @param pDesc Pointer to this structure (for uProviderSpecific).
318	* @param pvState The opaque provider state.
319	* @param hKey The key handle associated with the state at init.
320	* @param hDigest The handle to the digest. Calls RTCrDigestFinal to
321	* complete and retreive the final hash value.
322	* @param pvSignature The output signature buffer.
323	* @param pcbSignature On input the variable pointed to holds the size of
324	* the buffer @a pvSignature points to.
325	* On return the variable pointed to is set to the size
326	* of the returned signature, or the required size in
327	* case of VERR_BUFFER_OVERFLOW.
328	*/
329	DECLCALLBACKMEMBER(int, pfnSign,(struct RTCRPKIXSIGNATUREDESC const pDesc, void pvState, RTCRKEY hKey,
330	RTCRDIGEST hDigest, void pvSignature, size_t pcbSignature));
331
332	} RTCRPKIXSIGNATUREDESC;
333	/** Pointer to a public key signature scheme provider descriptor. */
334	typedef RTCRPKIXSIGNATUREDESC const *PCRTCRPKIXSIGNATUREDESC;
335
336	/**
337	* Locates a signature schema provider descriptor by object ID string.
338	* @returns Pointer to descriptor on success, NULL on if not found.
339	* @param pszObjId The ID of the signature to search for.
340	* @param ppvOpaque Where to store an opaque schema parameter. Optional.
341	*/
342	PCRTCRPKIXSIGNATUREDESC RTCrPkixSignatureFindByObjIdString(const char pszObjId, void *ppvOpaque);
343
344	/**
345	* Locates a signature schema provider descriptor by ASN.1 object ID.
346	* @returns Pointer to descriptor on success, NULL on if not found.
347	* @param pObjId The ID of the signature to search for.
348	* @param ppvOpaque Where to store an opaque schema parameter. Optional.
349	*/
350	PCRTCRPKIXSIGNATUREDESC RTCrPkixSignatureFindByObjId(PCRTASN1OBJID pObjId, void **ppvOpaque);
351
352	/**
353	* Create a signature schema provier instance.
354	*
355	* @returns IPRT status code.
356	* @param phSignature Where to return the handle to the created instance.
357	* @param pDesc The signature schema provider descriptor. Use
358	* RTCrPkixSignatureFindByObjIdString() or RTCrPkixSignatureFindByObjId()
359	* to get this.
360	* @param pvOpaque The opaque schema parameter returned by the find functions.
361	* @param fSigning Set if the intention is to sign stuff, clear if verification only.
362	* @param hKey The key handle. A referenced will be retained.
363	* @param pParams Algorithm/key parameters, optional.
364	*/
365	RTDECL(int) RTCrPkixSignatureCreate(PRTCRPKIXSIGNATURE phSignature, PCRTCRPKIXSIGNATUREDESC pDesc, void *pvOpaque,
366	bool fSigning, RTCRKEY hKey, PCRTASN1DYNTYPE pParams);
367	/** Convenience wrapper function for RTCrPkixSignatureCreate(). */
368	RTDECL(int) RTCrPkixSignatureCreateByObjIdString(PRTCRPKIXSIGNATURE phSignature, const char *pszObjId,
369	RTCRKEY hKey, PCRTASN1DYNTYPE pParams, bool fSigning);
370	/** Convenience wrapper function for RTCrPkixSignatureCreate(). */
371	RTDECL(int) RTCrPkixSignatureCreateByObjId(PRTCRPKIXSIGNATURE phSignature, PCRTASN1OBJID pObjId, RTCRKEY hKey,
372	PCRTASN1DYNTYPE pParams, bool fSigning);
373
374	/**
375	* Retains a reference to the signature schema provider instance.
376	*
377	* @returns New reference count on success, UINT32_MAX if invalid handle.
378	* @param hSignature The signature schema provider handle.
379	*/
380	RTDECL(uint32_t) RTCrPkixSignatureRetain(RTCRPKIXSIGNATURE hSignature);
381
382	/**
383	* Releases a reference to the signature schema provider instance.
384	*
385	* @returns New reference count on success, UINT32_MAX if invalid handle.
386	* @param hSignature The signature schema provider handle. NIL is ignored.
387	*/
388	RTDECL(uint32_t) RTCrPkixSignatureRelease(RTCRPKIXSIGNATURE hSignature);
389
390	/**
391	* Verifies a signed message digest.
392	*
393	* @returns IPRT status code.
394	* @retval VINF_SUCCESS if the signature checked out correctly.
395	* @retval VINF_CR_DIGEST_DEPRECATED if the signature checked out correctly
396	* but the hash algorithm is deprecated.
397	* @retval VINF_CR_DIGEST_COMPROMISED if the signature checked out correctly
398	* but the hash algorithm is compromised.
399	* @retval VINF_CR_DIGEST_SEVERELY_COMPROMISED if the signature checked out
400	* correctly but the hash algorithm is severely compromised.
401	* @retval VERR_PKIX_KEY wrong key or some other key issue.
402	*
403	* @param hSignature The signature schema provider handle.
404	* @param hDigest The handle to the digest. All that must have been
405	* feed to it via RTCrDigestUpdate() and friends prior
406	* to calling this function. The function will itself
407	* call RTCrDigestFinal() to complete and retreive the
408	* final hash value.
409	* @param pvSignature The signature to validate.
410	* @param cbSignature The size of the signature (in bytes).
411	*/
412	RTDECL(int) RTCrPkixSignatureVerify(RTCRPKIXSIGNATURE hSignature, RTCRDIGEST hDigest, void const *pvSignature, size_t cbSignature);
413	/** Convenience wrapper function for RTCrPkixSignatureVerify(). */
414	RTDECL(int) RTCrPkixSignatureVerifyBitString(RTCRPKIXSIGNATURE hSignature, RTCRDIGEST hDigest, PCRTASN1BITSTRING pSignature);
415	/** Convenience wrapper function for RTCrPkixSignatureVerify(). */
416	RTDECL(int) RTCrPkixSignatureVerifyOctetString(RTCRPKIXSIGNATURE hSignature, RTCRDIGEST hDigest, PCRTASN1OCTETSTRING pSignature);
417
418	/**
419	* Sign a message digest.
420	*
421	* @returns IPRT status code.
422	* @retval VINF_SUCCESS on success.
423	* @retval VINF_CR_DIGEST_DEPRECATED on success but the hash algorithm is deprecated.
424	* @retval VINF_CR_DIGEST_COMPROMISED on success but the hash algorithm is compromised.
425	* @retval VINF_CR_DIGEST_SEVERELY_COMPROMISED on success but the hash algorithm
426	* is severely compromised.
427	* @retval VERR_PKIX_KEY wrong key or some other key issue.
428	* @retval VERR_BUFFER_OVERFLOW if the signature buffer is too small, the
429	* require buffer size will be available in @a *pcbSignature.
430	*
431	* @param hSignature The signature schema provider handle.
432	* @param hDigest The handle to the digest. All that must have been
433	* feed to it via RTCrDigestUpdate() and friends prior
434	* to calling this function. The function will itself
435	* call RTCrDigestFinal() to complete and retreive the
436	* final hash value.
437	* @param pvSignature The output signature buffer.
438	* @param pcbSignature On input the variable pointed to holds the size of
439	* the buffer @a pvSignature points to.
440	* On return the variable pointed to is set to the size
441	* of the returned signature, or the required size in
442	* case of VERR_BUFFER_OVERFLOW.
443	*/
444	RTDECL(int) RTCrPkixSignatureSign(RTCRPKIXSIGNATURE hSignature, RTCRDIGEST hDigest, void pvSignature, size_t pcbSignature);
445
446
447	/**
448	* Public key encryption scheme provider descriptor.
449	*
450	* @todo This is just a sketch left over from when the signature code was
451	* chiseled out.
452	*/
453	typedef struct RTCRPKIXENCRYPTIONDESC
454	{
455	/** The encryption scheme provider name. */
456	const char *pszName;
457	/** The object ID string. */
458	const char *pszObjId;
459	/** Pointer to a NULL terminated table of alias object IDs (optional). */
460	const char * const *papszObjIdAliases;
461	/** The size of the state. */
462	uint32_t cbState;
463	/** Reserved for future use / padding. */
464	uint32_t uReserved;
465	/** Provider specific field. */
466	uintptr_t uProviderSpecific;
467
468	/**
469	* Initializes the state for this encryption scheme.
470	*
471	* Optional, RT_BZERO will be used if NULL.
472	*
473	* @returns IPRT status code.
474	* @param pDesc Pointer to this structure (so uProviderSpecific can
475	* be read).
476	* @param pvState The opaque provider state.
477	* @param pvOpaque Opaque provider specific parameter.
478	* @param fEncrypt Set if the instance will be encrypting, clear if it
479	* will be decrypting. This aspect of the instance is
480	* immutable due to the algorithm requiring different
481	* keys for each of the operations.
482	* @param pKey The key to use (whether private or public depends on
483	* the operation type).
484	* @param pParams Algorithm/key parameters, optional. Will be NULL if
485	* none.
486	*/
487	DECLCALLBACKMEMBER(int, pfnInit,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState, void *pvOpaque, bool fEncrypt,
488	PCRTASN1BITSTRING pKey, PCRTASN1DYNTYPE pParams));
489
490	/**
491	* Re-initializes the provider state.
492	*
493	* Optional. It is assumed that the provider does not have any state needing
494	* to be re-initialized if this method is not implemented. (Do not assume that
495	* a final encrypt/decrypt call has been made prior to this call.)
496	*
497	* @returns IPRT status code.
498	* @param pDesc Pointer to this structure (so uProviderSpecific can
499	* be read).
500	* @param pvState The opaque provider state.
501	* @param enmOperation Same as for the earlier pfnInit call.
502	*/
503	DECLCALLBACKMEMBER(int, pfnReset,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState, bool fEncrypt));
504
505	/**
506	* Deletes the provider state. Optional.
507	*
508	* The state will be securely wiped clean after the call, regardless of whether
509	* the method is implemented or not.
510	*
511	* @param pDesc Pointer to this structure (so uProviderSpecific can
512	* be read).
513	* @param pvState The opaque provider state.
514	* @param enmOperation Same as for the earlier pfnInit call.
515	*/
516	DECLCALLBACKMEMBER(void, pfnDelete,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState, bool fEncrypt));
517
518	/**
519	* Encrypt using the public key (fEncrypt = true).
520	*
521	* @returns IPRT status code.
522	* @retval VINF_SUCCESS on success.
523	* @retval VERR_PKIX_KEY wrong key or some other key issue.
524	* @retval VERR_BUFFER_OVERFLOW if the output buffer is too small, the require
525	* buffer size will be available in @a *pcbCiphertext. The caller can
526	* should retry the call with a larger buffer.
527	*
528	* @param pDesc Pointer to this structure (so uProviderSpecific can
529	* be read).
530	* @param pvState The opaque provider state.
531	* @param pvPlaintext The plaintext to encrypt.
532	* @param cbPlaintext The number of bytes of plaintext.
533	* @param pvCiphertext Where to return the ciphertext (if any).
534	* @param cbMaxCiphertext The size of the buffer @a pvCiphertext points to.
535	* @param pcbCiphertext Where to return the actual number of bytes of
536	* ciphertext returned.
537	* @param fFinal Whether this is the final call.
538	*/
539	DECLCALLBACKMEMBER(int, pfnEncrypt,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState,
540	void const *pvPlaintext, size_t cbPlaintext,
541	void pvCiphertext, size_t cbMaxCiphertext, size_t pcbCiphertext, bool fFinal));
542
543	/**
544	* Calculate the output buffer size for the next pfnEncrypt call.
545	*
546	* @returns IPRT status code.
547	* @param pDesc Pointer to this structure (so uProviderSpecific can
548	* be read).
549	* @param pvState The opaque provider state.
550	* @param cbPlaintext The number of bytes of plaintext.
551	* @param pcbCiphertext Where to return the minimum buffer size. This may
552	* be larger than the actual number of bytes return.
553	* @param fFinal Whether this is the final call.
554	*/
555	DECLCALLBACKMEMBER(int, pfnEncryptLength,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState,
556	size_t cbPlaintext, size_t *pcbCiphertext, bool fFinal));
557
558	/**
559	* Decrypt using the private key (fEncrypt = false).
560	*
561	* @returns IPRT status code.
562	* @retval VINF_SUCCESS on success.
563	* @retval VERR_PKIX_KEY wrong key or some other key issue.
564	* @retval VERR_BUFFER_OVERFLOW if the output buffer is too small, the require
565	* buffer size will be available in @a *pcbCiphertext. The caller can
566	* should retry the call with a larger buffer.
567	*
568	* @param pDesc Pointer to this structure (so uProviderSpecific can
569	* be read).
570	* @param pvState The opaque provider state.
571	* @param pvCiphertext The ciphertext to decrypt.
572	* @param cbCiphertext The number of bytes of ciphertext.
573	* @param pvPlaintext Where to return the plaintext (if any).
574	* @param cbMaxPlaintext The size of the buffer @a pvPlaintext points to.
575	* @param pcbPlaintext Where to return the actual number of bytes of
576	* plaintext returned.
577	* @param fFinal Whether this is the final call.
578	*/
579	DECLCALLBACKMEMBER(int, pfnDecrypt,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState,
580	void const *pvCiphertext, size_t cbCiphertext,
581	void pvPlaintext, size_t cbMaxPlaintext, size_t pcbPlaintext, bool fFinal));
582
583	/**
584	* Calculate the output buffer size for the next pfnDecrypt call.
585	*
586	* @returns IPRT status code.
587	* @param pDesc Pointer to this structure (so uProviderSpecific can
588	* be read).
589	* @param pvState The opaque provider state.
590	* @param cbCiphertext The number of bytes of ciphertext.
591	* @param pcbPlaintext Where to return the minimum buffer size. This may
592	* be larger than the actual number of bytes return.
593	* @param fFinal Whether this is the final call.
594	*/
595	DECLCALLBACKMEMBER(int, pfnDecryptLength,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState,
596	size_t cbCiphertext, size_t *pcbPlaintext, bool fFinal));
597	} RTCRPKIXENCRYPTIONDESC;
598	/** Pointer to a public key encryption schema provider descriptor. */
599	typedef RTCRPKIXENCRYPTIONDESC const *PCRTCRPKIXENCRYPTIONDESC;
600
601
602	PCRTCRPKIXENCRYPTIONDESC RTCrPkixEncryptionFindByObjIdString(const char pszObjId, void ppvOpaque);
603	PCRTCRPKIXENCRYPTIONDESC RTCrPkixEncryptionFindByObjId(PCRTASN1OBJID pObjId, void *ppvOpaque);
604	RTDECL(int) RTCrPkixEncryptionCreateByObjIdString(PRTCRPKIXENCRYPTION phEncryption, const char *pszObjId,
605	bool fEncrypt, RTCRKEY hKey, PCRTASN1DYNTYPE pParams);
606	RTDECL(int) RTCrPkixEncryptionCreateByObjId(PRTCRPKIXENCRYPTION phEncryption, PCRTASN1OBJID pObjId, bool fEncrypt,
607	RTCRKEY hKey, PCRTASN1DYNTYPE pParams);
608
609
610	RTDECL(int) RTCrPkixEncryptionCreate(PRTCRPKIXENCRYPTION phEncryption, PCRTCRPKIXENCRYPTIONDESC pDesc, void *pvOpaque,
611	bool fEncrypt, PCRTASN1BITSTRING pKey, PCRTASN1DYNTYPE pParams);
612	RTDECL(int) RTCrPkixEncryptionReset(RTCRPKIXENCRYPTION hEncryption);
613	RTDECL(uint32_t) RTCrPkixEncryptionRetain(RTCRPKIXENCRYPTION hEncryption);
614	RTDECL(uint32_t) RTCrPkixEncryptionRelease(RTCRPKIXENCRYPTION hEncryption);
615
616
617	/** @} */
618
619	RT_C_DECLS_END
620
621	#endif /* !IPRT_INCLUDED_crypto_pkix_h */
622

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

source: vbox/trunk/include/iprt/crypto/pkix.h@ 104070

Download in other formats: