pkix.h@ 76553

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

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

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

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

Download in other formats: