pkix.h@ 93115

Last change on this file since 93115 was 93115, checked in by vboxsync, 3 years ago
scm --update-copyright-year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 28.4 KB

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

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

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

Download in other formats: