pkix.h@ 98279

Last change on this file since 98279 was 98103, checked in by vboxsync, 21 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 28.8 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 Parameter to the public key algorithm. Optional.
63	* @param pSignatureValue The signature value.
64	* @param pvData The signed data.
65	* @param cbData The amount of signed data.
66	* @param pErrInfo Where to return extended error info. Optional.
67	*
68	* @remarks Depending on the IPRT build configuration, the verficiation may be
69	* performed more than once using all available crypto implementations.
70	*/
71	RTDECL(int) RTCrPkixPubKeyVerifySignature(PCRTASN1OBJID pAlgorithm, RTCRKEY hPublicKey, PCRTASN1DYNTYPE pParameters,
72	PCRTASN1BITSTRING pSignatureValue, const void *pvData, size_t cbData,
73	PRTERRINFO pErrInfo);
74
75
76	/**
77	* Verifies the signed digest (@a pvSignedDigest) against our digest (@a
78	* hDigest) using the specfied public key (@a pPublicKey) and algorithm.
79	*
80	* @returns IPRT status code.
81	* @param pAlgorithm The signature algorithm (digest w/ cipher).
82	* @param hPublicKey The public key.
83	* @param pParameters Parameter to the public key algorithm. Optional.
84	* @param pvSignedDigest The signed digest.
85	* @param cbSignedDigest The signed digest size.
86	* @param hDigest The digest of the data to compare @a pvSignedDigest
87	* with.
88	* @param pErrInfo Where to return extended error info. Optional.
89	*
90	* @remarks Depending on the IPRT build configuration, the verficiation may be
91	* performed more than once using all available crypto implementations.
92	*/
93	RTDECL(int) RTCrPkixPubKeyVerifySignedDigest(PCRTASN1OBJID pAlgorithm, RTCRKEY hPublicKey, PCRTASN1DYNTYPE pParameters,
94	void const *pvSignedDigest, size_t cbSignedDigest,
95	RTCRDIGEST hDigest, PRTERRINFO pErrInfo);
96
97	/**
98	* Wrapper around RTCrPkixPubKeyVerifySignedDigest & RTCrKeyCreateFromAlgorithmAndBits.
99	*
100	* @note The public key info must include digest type for this to work.
101	*/
102	RTDECL(int) RTCrPkixPubKeyVerifySignedDigestByCertPubKeyInfo(struct RTCRX509SUBJECTPUBLICKEYINFO const *pCertPubKeyInfo,
103	void const *pvSignedDigest, size_t cbSignedDigest,
104	RTCRDIGEST hDigest, PRTERRINFO pErrInfo);
105
106	/**
107	* Checks if the hash size can be handled by the given public key.
108	*/
109	RTDECL(bool) RTCrPkixPubKeyCanHandleDigestType(struct RTCRX509SUBJECTPUBLICKEYINFO const *pPublicKeyInfo,
110	RTDIGESTTYPE enmDigestType, PRTERRINFO pErrInfo);
111
112	/**
113	* Checks if the hash size can be handled by the given certificate's public key.
114	*/
115	RTDECL(bool) RTCrPkixCanCertHandleDigestType(struct RTCRX509CERTIFICATE const *pCertificate,
116	RTDIGESTTYPE enmDigestType, PRTERRINFO pErrInfo);
117
118	/**
119	* Signs a digest (@a hDigest) using the specified private key (@a pPrivateKey) and algorithm.
120	*
121	* @returns IPRT status code.
122	* @param pAlgorithm The signature algorithm (digest w/ cipher).
123	* @param hPrivateKey Handle to the private key to use.
124	* @param pParameters Parameter to the public key algorithm. Optional.
125	* @param hDigest The digest of the data being signed.
126	* @param fFlags Flags for future extensions, MBZ.
127	* @param pvSignature The output signature buffer. Pass NULL to query
128	* the signature size.
129	* @param pcbSignature On input the variable pointed to holds the size of
130	* the buffer @a pvSignature points to.
131	* On return the variable pointed to is set to the size
132	* of the returned signature, or the required size in
133	* case of VERR_BUFFER_OVERFLOW.
134	* @param pErrInfo Where to return extended error info. Optional.
135	*
136	* @remarks Depending on the IPRT build configuration and the algorithm used, the
137	* signing may be performed more than once using all available crypto
138	* implementations.
139	*/
140	RTDECL(int) RTCrPkixPubKeySignDigest(PCRTASN1OBJID pAlgorithm, RTCRKEY hPrivateKey, PCRTASN1DYNTYPE pParameters,
141	RTCRDIGEST hDigest, uint32_t fFlags,
142	void pvSignature, size_t pcbSignature, PRTERRINFO pErrInfo);
143
144	/**
145	* Gets the cipher OID matching the given signature algorithm.
146	*
147	* @returns Cipher OID string on success, NULL on failure.
148	* @param pAlgorithm The signature algorithm (digest w/ cipher).
149	*/
150	RTDECL(const char *) RTCrPkixGetCiperOidFromSignatureAlgorithm(PCRTASN1OBJID pAlgorithm);
151
152
153	/** @name PKCS-1 Object Identifiers (OIDs)
154	* @{ */
155	#define RTCR_PKCS1_OID "1.2.840.113549.1.1"
156	#define RTCR_PKCS1_RSA_OID "1.2.840.113549.1.1.1"
157	#define RTCR_PKCS1_MD2_WITH_RSA_OID "1.2.840.113549.1.1.2"
158	#define RTCR_PKCS1_MD4_WITH_RSA_OID "1.2.840.113549.1.1.3"
159	#define RTCR_PKCS1_MD5_WITH_RSA_OID "1.2.840.113549.1.1.4"
160	#define RTCR_PKCS1_SHA1_WITH_RSA_OID "1.2.840.113549.1.1.5"
161	#define RTCR_PKCS1_RSA_OAEP_ENCRYPTION_SET_OID "1.2.840.113549.1.1.6"
162	#define RTCR_PKCS1_RSA_AES_OAEP_OID "1.2.840.113549.1.1.7"
163	#define RTCR_PKCS1_MSGF1_OID "1.2.840.113549.1.1.8"
164	#define RTCR_PKCS1_P_SPECIFIED_OID "1.2.840.113549.1.1.9"
165	#define RTCR_PKCS1_RSASSA_PSS_OID "1.2.840.113549.1.1.10"
166	#define RTCR_PKCS1_SHA256_WITH_RSA_OID "1.2.840.113549.1.1.11"
167	#define RTCR_PKCS1_SHA384_WITH_RSA_OID "1.2.840.113549.1.1.12"
168	#define RTCR_PKCS1_SHA512_WITH_RSA_OID "1.2.840.113549.1.1.13"
169	#define RTCR_PKCS1_SHA224_WITH_RSA_OID "1.2.840.113549.1.1.14"
170	#define RTCR_PKCS1_SHA512T224_WITH_RSA_OID "1.2.840.113549.1.1.15"
171	#define RTCR_PKCS1_SHA512T256_WITH_RSA_OID "1.2.840.113549.1.1.16"
172	/** @} */
173
174
175	/**
176	* Public key signature scheme provider descriptor.
177	*/
178	typedef struct RTCRPKIXSIGNATUREDESC
179	{
180	/** The signature scheme provider name. */
181	const char *pszName;
182	/** The object ID string. */
183	const char *pszObjId;
184	/** Pointer to a NULL terminated table of alias object IDs (optional). */
185	const char * const *papszObjIdAliases;
186	/** The size of the state. */
187	uint32_t cbState;
188	/** Reserved for future / explicit padding. */
189	uint32_t uReserved;
190	/** Provider specific field. This generally indicates the kind of padding
191	* scheme to employ with the given OID. */
192	uintptr_t uProviderSpecific;
193
194	/**
195	* Initializes the state of the signature scheme provider.
196	*
197	* Optional, RT_BZERO will be used if NULL.
198	*
199	* @returns IPRT status code.
200	* @param pDesc Pointer to this structure (for uProviderSpecific).
201	* @param pvState The opaque provider state.
202	* @param pvOpaque Opaque provider specific parameter.
203	* @param fSigning Set if a signing operation is going to be performed,
204	* clear if it is a verification. This is a fixed
205	* setting for the lifetime of the instance due to the
206	* algorithm requiring different keys.
207	* @param hKey The key handle. Caller has retained it for the
208	* lifetime of the state being initialize.
209	* @param pParams Algorithm/key parameters, optional. Will be NULL if
210	* none.
211	*/
212	DECLCALLBACKMEMBER(int, pfnInit,(struct RTCRPKIXSIGNATUREDESC const pDesc, void pvState, void *pvOpaque, bool fSigning,
213	RTCRKEY hKey, PCRTASN1DYNTYPE pParams));
214
215	/**
216	* Resets the state before performing another signing or verification.
217	*
218	* Optional. It is assumed that the provider does not have any state needing to
219	* be re-initialized if this method is not implemented.
220	*
221	* @returns IPRT status code.
222	* @param pDesc Pointer to this structure (for uProviderSpecific).
223	* @param pvState The opaque provider state.
224	* @param fSigning Exactly the same value as the init call.
225	*/
226	DECLCALLBACKMEMBER(int, pfnReset,(struct RTCRPKIXSIGNATUREDESC const pDesc, void pvState, bool fSigning));
227
228	/**
229	* Deletes the provider state. Optional.
230	*
231	* The state will be securely wiped clean after the call, regardless of whether
232	* the method is implemented or not.
233	*
234	* @param pDesc Pointer to this structure (for uProviderSpecific).
235	* @param pvState The opaque provider state.
236	* @param fSigning Exactly the same value as the init call.
237	*/
238	DECLCALLBACKMEMBER(void, pfnDelete,(struct RTCRPKIXSIGNATUREDESC const pDesc, void pvState, bool fSigning));
239
240	/**
241	* Verifies a signed message digest (fSigning = false).
242	*
243	* @returns IPRT status code.
244	* @retval VINF_SUCCESS if the signature checked out correctly.
245	* @retval VINF_CR_DIGEST_DEPRECATED if the signature checked out correctly
246	* but the hash algorithm is deprecated.
247	* @retval VINF_CR_DIGEST_COMPROMISED if the signature checked out correctly
248	* but the hash algorithm is compromised.
249	* @retval VINF_CR_DIGEST_SEVERELY_COMPROMISED if the signature checked out
250	* correctly but the hash algorithm is severely compromised.
251	* @retval VERR_PKIX_KEY wrong key or some other key issue.
252	*
253	* @param pDesc Pointer to this structure (for uProviderSpecific).
254	* @param pvState The opaque provider state.
255	* @param hKey The key handle associated with the state at init.
256	* @param hDigest The handle to the digest. Calls RTCrDigestFinal to
257	* complete and retreive the final hash value.
258	* @param pvSignature The signature to validate.
259	* @param cbSignature The size of the signature (in bytes).
260	*/
261	DECLCALLBACKMEMBER(int, pfnVerify,(struct RTCRPKIXSIGNATUREDESC const pDesc, void pvState, RTCRKEY hKey,
262	RTCRDIGEST hDigest, void const *pvSignature, size_t cbSignature));
263
264	/**
265	* Sign a message digest (fSigning = true).
266	*
267	* @returns IPRT status code.
268	* @retval VINF_SUCCESS on success.
269	* @retval VINF_CR_DIGEST_DEPRECATED on success but the hash algorithm is deprecated.
270	* @retval VINF_CR_DIGEST_COMPROMISED on success but the hash algorithm is compromised.
271	* @retval VINF_CR_DIGEST_SEVERELY_COMPROMISED on success but the hash algorithm
272	* is severely compromised.
273	* @retval VERR_PKIX_KEY wrong key or some other key issue.
274	* @retval VERR_BUFFER_OVERFLOW if the signature buffer is too small, the
275	* require buffer size will be available in @a *pcbSignature.
276	*
277	* @param pDesc Pointer to this structure (for uProviderSpecific).
278	* @param pvState The opaque provider state.
279	* @param hKey The key handle associated with the state at init.
280	* @param hDigest The handle to the digest. Calls RTCrDigestFinal to
281	* complete and retreive the final hash value.
282	* @param pvSignature The output signature buffer.
283	* @param pcbSignature On input the variable pointed to holds the size of
284	* the buffer @a pvSignature points to.
285	* On return the variable pointed to is set to the size
286	* of the returned signature, or the required size in
287	* case of VERR_BUFFER_OVERFLOW.
288	*/
289	DECLCALLBACKMEMBER(int, pfnSign,(struct RTCRPKIXSIGNATUREDESC const pDesc, void pvState, RTCRKEY hKey,
290	RTCRDIGEST hDigest, void pvSignature, size_t pcbSignature));
291
292	} RTCRPKIXSIGNATUREDESC;
293	/** Pointer to a public key signature scheme provider descriptor. */
294	typedef RTCRPKIXSIGNATUREDESC const *PCRTCRPKIXSIGNATUREDESC;
295
296	/**
297	* Locates a signature schema provider descriptor by object ID string.
298	* @returns Pointer to descriptor on success, NULL on if not found.
299	* @param pszObjId The ID of the signature to search for.
300	* @param ppvOpaque Where to store an opaque schema parameter. Optional.
301	*/
302	PCRTCRPKIXSIGNATUREDESC RTCrPkixSignatureFindByObjIdString(const char pszObjId, void ppvOpaque);
303
304	/**
305	* Locates a signature schema provider descriptor by ASN.1 object ID.
306	* @returns Pointer to descriptor on success, NULL on if not found.
307	* @param pObjId The ID of the signature to search for.
308	* @param ppvOpaque Where to store an opaque schema parameter. Optional.
309	*/
310	PCRTCRPKIXSIGNATUREDESC RTCrPkixSignatureFindByObjId(PCRTASN1OBJID pObjId, void **ppvOpaque);
311
312	/**
313	* Create a signature schema provier instance.
314	*
315	* @returns IPRT status code.
316	* @param phSignature Where to return the handle to the created instance.
317	* @param pDesc The signature schema provider descriptor. Use
318	* RTCrPkixSignatureFindByObjIdString() or RTCrPkixSignatureFindByObjId()
319	* to get this.
320	* @param pvOpaque The opaque schema parameter returned by the find functions.
321	* @param fSigning Set if the intention is to sign stuff, clear if verification only.
322	* @param hKey The key handle. A referenced will be retained.
323	* @param pParams Algorithm/key parameters, optional.
324	*/
325	RTDECL(int) RTCrPkixSignatureCreate(PRTCRPKIXSIGNATURE phSignature, PCRTCRPKIXSIGNATUREDESC pDesc, void *pvOpaque,
326	bool fSigning, RTCRKEY hKey, PCRTASN1DYNTYPE pParams);
327	/** Convenience wrapper function for RTCrPkixSignatureCreate(). */
328	RTDECL(int) RTCrPkixSignatureCreateByObjIdString(PRTCRPKIXSIGNATURE phSignature, const char *pszObjId,
329	RTCRKEY hKey, PCRTASN1DYNTYPE pParams, bool fSigning);
330	/** Convenience wrapper function for RTCrPkixSignatureCreate(). */
331	RTDECL(int) RTCrPkixSignatureCreateByObjId(PRTCRPKIXSIGNATURE phSignature, PCRTASN1OBJID pObjId, RTCRKEY hKey,
332	PCRTASN1DYNTYPE pParams, bool fSigning);
333
334	/**
335	* Retains a reference to the signature schema provider instance.
336	*
337	* @returns New reference count on success, UINT32_MAX if invalid handle.
338	* @param hSignature The signature schema provider handle.
339	*/
340	RTDECL(uint32_t) RTCrPkixSignatureRetain(RTCRPKIXSIGNATURE hSignature);
341
342	/**
343	* Releases a reference to the signature schema provider instance.
344	*
345	* @returns New reference count on success, UINT32_MAX if invalid handle.
346	* @param hSignature The signature schema provider handle. NIL is ignored.
347	*/
348	RTDECL(uint32_t) RTCrPkixSignatureRelease(RTCRPKIXSIGNATURE hSignature);
349
350	/**
351	* Verifies a signed message digest.
352	*
353	* @returns IPRT status code.
354	* @retval VINF_SUCCESS if the signature checked out correctly.
355	* @retval VINF_CR_DIGEST_DEPRECATED if the signature checked out correctly
356	* but the hash algorithm is deprecated.
357	* @retval VINF_CR_DIGEST_COMPROMISED if the signature checked out correctly
358	* but the hash algorithm is compromised.
359	* @retval VINF_CR_DIGEST_SEVERELY_COMPROMISED if the signature checked out
360	* correctly but the hash algorithm is severely compromised.
361	* @retval VERR_PKIX_KEY wrong key or some other key issue.
362	*
363	* @param hSignature The signature schema provider handle.
364	* @param hDigest The handle to the digest. All that must have been
365	* feed to it via RTCrDigestUpdate() and friends prior
366	* to calling this function. The function will itself
367	* call RTCrDigestFinal() to complete and retreive the
368	* final hash value.
369	* @param pvSignature The signature to validate.
370	* @param cbSignature The size of the signature (in bytes).
371	*/
372	RTDECL(int) RTCrPkixSignatureVerify(RTCRPKIXSIGNATURE hSignature, RTCRDIGEST hDigest, void const *pvSignature, size_t cbSignature);
373	/** Convenience wrapper function for RTCrPkixSignatureVerify(). */
374	RTDECL(int) RTCrPkixSignatureVerifyBitString(RTCRPKIXSIGNATURE hSignature, RTCRDIGEST hDigest, PCRTASN1BITSTRING pSignature);
375	/** Convenience wrapper function for RTCrPkixSignatureVerify(). */
376	RTDECL(int) RTCrPkixSignatureVerifyOctetString(RTCRPKIXSIGNATURE hSignature, RTCRDIGEST hDigest, PCRTASN1OCTETSTRING pSignature);
377
378	/**
379	* Sign a message digest.
380	*
381	* @returns IPRT status code.
382	* @retval VINF_SUCCESS on success.
383	* @retval VINF_CR_DIGEST_DEPRECATED on success but the hash algorithm is deprecated.
384	* @retval VINF_CR_DIGEST_COMPROMISED on success but the hash algorithm is compromised.
385	* @retval VINF_CR_DIGEST_SEVERELY_COMPROMISED on success but the hash algorithm
386	* is severely compromised.
387	* @retval VERR_PKIX_KEY wrong key or some other key issue.
388	* @retval VERR_BUFFER_OVERFLOW if the signature buffer is too small, the
389	* require buffer size will be available in @a *pcbSignature.
390	*
391	* @param hSignature The signature schema provider handle.
392	* @param hDigest The handle to the digest. All that must have been
393	* feed to it via RTCrDigestUpdate() and friends prior
394	* to calling this function. The function will itself
395	* call RTCrDigestFinal() to complete and retreive the
396	* final hash value.
397	* @param pvSignature The output signature buffer.
398	* @param pcbSignature On input the variable pointed to holds the size of
399	* the buffer @a pvSignature points to.
400	* On return the variable pointed to is set to the size
401	* of the returned signature, or the required size in
402	* case of VERR_BUFFER_OVERFLOW.
403	*/
404	RTDECL(int) RTCrPkixSignatureSign(RTCRPKIXSIGNATURE hSignature, RTCRDIGEST hDigest, void pvSignature, size_t pcbSignature);
405
406
407	/**
408	* Public key encryption scheme provider descriptor.
409	*
410	* @todo This is just a sketch left over from when the signature code was
411	* chiseled out.
412	*/
413	typedef struct RTCRPKIXENCRYPTIONDESC
414	{
415	/** The encryption scheme provider name. */
416	const char *pszName;
417	/** The object ID string. */
418	const char *pszObjId;
419	/** Pointer to a NULL terminated table of alias object IDs (optional). */
420	const char * const *papszObjIdAliases;
421	/** The size of the state. */
422	uint32_t cbState;
423	/** Reserved for future use / padding. */
424	uint32_t uReserved;
425	/** Provider specific field. */
426	uintptr_t uProviderSpecific;
427
428	/**
429	* Initializes the state for this encryption scheme.
430	*
431	* Optional, RT_BZERO will be used if NULL.
432	*
433	* @returns IPRT status code.
434	* @param pDesc Pointer to this structure (so uProviderSpecific can
435	* be read).
436	* @param pvState The opaque provider state.
437	* @param pvOpaque Opaque provider specific parameter.
438	* @param fEncrypt Set if the instance will be encrypting, clear if it
439	* will be decrypting. This aspect of the instance is
440	* immutable due to the algorithm requiring different
441	* keys for each of the operations.
442	* @param pKey The key to use (whether private or public depends on
443	* the operation type).
444	* @param pParams Algorithm/key parameters, optional. Will be NULL if
445	* none.
446	*/
447	DECLCALLBACKMEMBER(int, pfnInit,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState, void *pvOpaque, bool fEncrypt,
448	PCRTASN1BITSTRING pKey, PCRTASN1DYNTYPE pParams));
449
450	/**
451	* Re-initializes the provider state.
452	*
453	* Optional. It is assumed that the provider does not have any state needing
454	* to be re-initialized if this method is not implemented. (Do not assume that
455	* a final encrypt/decrypt call has been made prior to this call.)
456	*
457	* @returns IPRT status code.
458	* @param pDesc Pointer to this structure (so uProviderSpecific can
459	* be read).
460	* @param pvState The opaque provider state.
461	* @param enmOperation Same as for the earlier pfnInit call.
462	*/
463	DECLCALLBACKMEMBER(int, pfnReset,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState, bool fEncrypt));
464
465	/**
466	* Deletes the provider state. Optional.
467	*
468	* The state will be securely wiped clean after the call, regardless of whether
469	* the method is implemented or not.
470	*
471	* @param pDesc Pointer to this structure (so uProviderSpecific can
472	* be read).
473	* @param pvState The opaque provider state.
474	* @param enmOperation Same as for the earlier pfnInit call.
475	*/
476	DECLCALLBACKMEMBER(void, pfnDelete,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState, bool fEncrypt));
477
478	/**
479	* Encrypt using the public key (fEncrypt = true).
480	*
481	* @returns IPRT status code.
482	* @retval VINF_SUCCESS on success.
483	* @retval VERR_PKIX_KEY wrong key or some other key issue.
484	* @retval VERR_BUFFER_OVERFLOW if the output buffer is too small, the require
485	* buffer size will be available in @a *pcbCiphertext. The caller can
486	* should retry the call with a larger buffer.
487	*
488	* @param pDesc Pointer to this structure (so uProviderSpecific can
489	* be read).
490	* @param pvState The opaque provider state.
491	* @param pvPlaintext The plaintext to encrypt.
492	* @param cbPlaintext The number of bytes of plaintext.
493	* @param pvCiphertext Where to return the ciphertext (if any).
494	* @param cbMaxCiphertext The size of the buffer @a pvCiphertext points to.
495	* @param pcbCiphertext Where to return the actual number of bytes of
496	* ciphertext returned.
497	* @param fFinal Whether this is the final call.
498	*/
499	DECLCALLBACKMEMBER(int, pfnEncrypt,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState,
500	void const *pvPlaintext, size_t cbPlaintext,
501	void pvCiphertext, size_t cbMaxCiphertext, size_t pcbCiphertext, bool fFinal));
502
503	/**
504	* Calculate the output buffer size for the next pfnEncrypt call.
505	*
506	* @returns IPRT status code.
507	* @param pDesc Pointer to this structure (so uProviderSpecific can
508	* be read).
509	* @param pvState The opaque provider state.
510	* @param cbPlaintext The number of bytes of plaintext.
511	* @param pcbCiphertext Where to return the minimum buffer size. This may
512	* be larger than the actual number of bytes return.
513	* @param fFinal Whether this is the final call.
514	*/
515	DECLCALLBACKMEMBER(int, pfnEncryptLength,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState,
516	size_t cbPlaintext, size_t *pcbCiphertext, bool fFinal));
517
518	/**
519	* Decrypt using the private key (fEncrypt = false).
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 pvCiphertext The ciphertext to decrypt.
532	* @param cbCiphertext The number of bytes of ciphertext.
533	* @param pvPlaintext Where to return the plaintext (if any).
534	* @param cbMaxPlaintext The size of the buffer @a pvPlaintext points to.
535	* @param pcbPlaintext Where to return the actual number of bytes of
536	* plaintext returned.
537	* @param fFinal Whether this is the final call.
538	*/
539	DECLCALLBACKMEMBER(int, pfnDecrypt,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState,
540	void const *pvCiphertext, size_t cbCiphertext,
541	void pvPlaintext, size_t cbMaxPlaintext, size_t pcbPlaintext, bool fFinal));
542
543	/**
544	* Calculate the output buffer size for the next pfnDecrypt 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 cbCiphertext The number of bytes of ciphertext.
551	* @param pcbPlaintext 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, pfnDecryptLength,(struct RTCRPKIXENCRYPTIONDESC const pDesc, void pvState,
556	size_t cbCiphertext, size_t *pcbPlaintext, bool fFinal));
557	} RTCRPKIXENCRYPTIONDESC;
558	/** Pointer to a public key encryption schema provider descriptor. */
559	typedef RTCRPKIXENCRYPTIONDESC const *PCRTCRPKIXENCRYPTIONDESC;
560
561
562	PCRTCRPKIXENCRYPTIONDESC RTCrPkixEncryptionFindByObjIdString(const char pszObjId, void ppvOpaque);
563	PCRTCRPKIXENCRYPTIONDESC RTCrPkixEncryptionFindByObjId(PCRTASN1OBJID pObjId, void *ppvOpaque);
564	RTDECL(int) RTCrPkixEncryptionCreateByObjIdString(PRTCRPKIXENCRYPTION phEncryption, const char *pszObjId,
565	bool fEncrypt, RTCRKEY hKey, PCRTASN1DYNTYPE pParams);
566	RTDECL(int) RTCrPkixEncryptionCreateByObjId(PRTCRPKIXENCRYPTION phEncryption, PCRTASN1OBJID pObjId, bool fEncrypt,
567	RTCRKEY hKey, PCRTASN1DYNTYPE pParams);
568
569
570	RTDECL(int) RTCrPkixEncryptionCreate(PRTCRPKIXENCRYPTION phEncryption, PCRTCRPKIXENCRYPTIONDESC pDesc, void *pvOpaque,
571	bool fEncrypt, PCRTASN1BITSTRING pKey, PCRTASN1DYNTYPE pParams);
572	RTDECL(int) RTCrPkixEncryptionReset(RTCRPKIXENCRYPTION hEncryption);
573	RTDECL(uint32_t) RTCrPkixEncryptionRetain(RTCRPKIXENCRYPTION hEncryption);
574	RTDECL(uint32_t) RTCrPkixEncryptionRelease(RTCRPKIXENCRYPTION hEncryption);
575
576
577	/** @} */
578
579	RT_C_DECLS_END
580
581	#endif /* !IPRT_INCLUDED_crypto_pkix_h */
582

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

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

Download in other formats: