[apple/security.git] / libsecurity_keychain / lib / SecCertificateRequest.h

/*
 * Copyright (c) 2002-2004 Apple Computer, Inc. All Rights Reserved.
 * 
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */

/*!
	@header SecCertificateRequest
	SecCertificateRequest implements a way to issue a certificate request to a
	certificate authority.
*/

#ifndef _SECURITY_SECCERTIFICATEREQUEST_H_
#define _SECURITY_SECCERTIFICATEREQUEST_H_

#include <Security/SecBase.h>
#include <Security/cssmtype.h>


#if defined(__cplusplus)
extern "C" {
#endif

struct SecCertificateRequestAttribute /* for optional oids */
{
	CSSM_OID	oid;
	CSSM_DATA	value;
};
typedef struct SecCertificateRequestAttribute SecCertificateRequestAttribute;

struct SecCertificateRequestAttributeList 
{
    UInt32 count;
    SecCertificateRequestAttribute *attr;
};
typedef struct SecCertificateRequestAttributeList  SecCertificateRequestAttributeList;

/*!
    @typedef SecCertificateRequestRef
    @abstract Contains information about a certificate request.
*/
typedef struct OpaqueSecCertificateRequestRef *SecCertificateRequestRef;

/*!
	@function SecCertificateRequestGetTypeID
	Returns the type identifier of all SecCertificateRequest instances.
*/
CFTypeID SecCertificateRequestGetTypeID(void);

/*!
	@function SecCertificateRequestCreate
	
	Create a certificate request operation based on a policy and certificate 
	type.  If a policy is not specified, one will be chosen for the caller. 
	Once the requeste is created, a request reference is returned.
	To submit the request call SecCertificateRequestSubmit(). 
    
	@param policy A policy.
	@param certificateType The certificate type (i.e. X509, PGP, etc). 
	   These types are in cssmtype.h
	@param requestType The identifier to the type of request to submit (i.e. 
	   issue, verify, revoke, etc.). These are defined in cssmtype.h
	@param privateKeyItemRef The keychain item private key to be used for this
	   certificate request. The private key item must be of class type 
	   kSecAppleKeyItemClass.
	@param attributeList An optional list of OIDs for the certificate request.
	@param certRequest A returned reference to the certificate request. Call CFRelease when done with this certificate request.
	@result errSecSuccess 0 No error.
*/
OSStatus SecCertificateRequestCreate(
        const CSSM_OID *policy,
        CSSM_CERT_TYPE certificateType,
        CSSM_TP_AUTHORITY_REQUEST_TYPE requestType,
	    SecKeyRef privateKeyItemRef,
	    SecKeyRef publicKeyItemRef,
	    const SecCertificateRequestAttributeList* attributeList,
        SecCertificateRequestRef* certRequest);

/*!
	@function SecCertificateRequestSubmit
	
	Submit a certificate request to be processed by the Security framework. 
	Once the request is submitted, an estimated time is returned indicating 
	when the request results can be retrieved. Once the estimated time has 
	elapsed, obtain the result by calling SecCertificateRequestGetResult(). 
    
	@param certRequest A reference to the certificate request.
	@param estimatedTime The number of estimated seconds before the result 
	   can be retrieved.
	@result errSecSuccess 0 No error.
*/
OSStatus SecCertificateRequestSubmit(
        SecCertificateRequestRef certRequest,
        sint32* estimatedTime);

/*!
	@function SecCertificateRequestGetType
	Returns the certificate request type (i.e. issue, revoke, etc) for a given 
	certificate request item reference.
    @param certRequestRef A reference to a submitted request.
	@param requestType The returned request type.
    @result errSecSuccess 0 No error.
*/
OSStatus SecCertificateRequestGetType(
        SecCertificateRequestRef certRequestRef,
        CSSM_TP_AUTHORITY_REQUEST_TYPE* requestType);

/*!
	@function SecCertificateRequestGetResult
	Get the results of a certificate request. If the request is still 
	pending, the estimated time will be returned which indicates when to 
	call this function again.
    @param certRequestRef A reference for the submitted request.
    @param keychain The keychain in which to store the new certificate (for 
	   a new cert request) and the cert request item reference. Pass NULL 
	   to specify the default keychain.
    @param estimatedTime The number of estimated seconds before the result can 
	   be retrieved.
	@param certficateRef The returned certificate reference for a 
	   CSSM_TP_AUTHORITY_REQUEST_CERTISSUE only. All other request types return 
	   NULL here. Call CFRelease when done with this certificate reference.
    @result errSecSuccess 0 No error.
*/
OSStatus SecCertificateRequestGetResult(
        SecCertificateRequestRef certRequestRef,
        SecKeychainRef keychain,
        sint32* estimatedTime,
        SecCertificateRef* certificateRef);

/*!
	@function SecCertificateFindRequest
	Find a pending certificate request and return a reference object 
	   for it. The search criteria is based on the input parameters.
    @param policy A policy.
    @param certificateType The certificate type (i.e. X509, PGP, etc). 
	   These types are in cssmtype.h
    @param requestType The identifier to the type of request to find (i.e. 
	   issue, verify, revoke, etc.). These are defined in cssmtype.h
	@param privateKeyItemRef Optional private key to be used 
	   for the certificate request. Matches the same argument as passed to
	   SecCertificateRequestCreate().
	@param publicKeyItemRef Optional public key to be used 
	   for the certificate request. Matches the same argument as passed to
	   SecCertificateRequestCreate().
    @param attributeList An optional list of OID/value pairs for finding the 
	   certificate request.
    @param certRequest A returned reference to the certificate request. Call CFRelease when done with this reference.
*/
OSStatus SecCertificateFindRequest(
        const CSSM_OID *policy,
        CSSM_CERT_TYPE certificateType,
        CSSM_TP_AUTHORITY_REQUEST_TYPE requestType,
		SecKeyRef privateKeyItemRef,				
		SecKeyRef publicKeyItemRef,				
		const SecCertificateRequestAttributeList* attributeList,
        SecCertificateRequestRef* certRequest);

/*!
	@function SecCertificateRequestGetData
	Get policy-specific data following a SecCertificateRequestSubmit.
    @param certRequestRef A reference for the submitted request.
    @param data Policy-specific data.
    @result errSecSuccess 0 No error.
*/

OSStatus SecCertificateRequestGetData(
	SecCertificateRequestRef	certRequestRef,
	CSSM_DATA					*data);

#if defined(__cplusplus)
}
#endif

#endif /* !_SECURITY_SECCERTIFICATEREQUEST_H_ */
Commit	Line	Data
b1ab9ed8 A	1	/*
	2	* Copyright (c) 2002-2004 Apple Computer, Inc. All Rights Reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. Please obtain a copy of the License at
	10	* http://www.opensource.apple.com/apsl/ and read it before using this
	11	* file.
	12	*
	13	* The Original Code and all software distributed under the License are
	14	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	15	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	16	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	17	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	18	* Please see the License for the specific language governing rights and
	19	* limitations under the License.
	20	*
	21	* @APPLE_LICENSE_HEADER_END@
	22	*/
	23
	24	/*!
	25	@header SecCertificateRequest
	26	SecCertificateRequest implements a way to issue a certificate request to a
	27	certificate authority.
	28	*/
	29
	30	#ifndef _SECURITY_SECCERTIFICATEREQUEST_H_
	31	#define _SECURITY_SECCERTIFICATEREQUEST_H_
	32
	33	#include <Security/SecBase.h>
	34	#include <Security/cssmtype.h>
	35
	36
	37	#if defined(__cplusplus)
	38	extern "C" {
	39	#endif
	40
	41	struct SecCertificateRequestAttribute /* for optional oids */
	42	{
	43	CSSM_OID oid;
	44	CSSM_DATA value;
	45	};
	46	typedef struct SecCertificateRequestAttribute SecCertificateRequestAttribute;
	47
	48	struct SecCertificateRequestAttributeList
	49	{
	50	UInt32 count;
	51	SecCertificateRequestAttribute *attr;
	52	};
	53	typedef struct SecCertificateRequestAttributeList SecCertificateRequestAttributeList;
	54
	55	/*!
	56	@typedef SecCertificateRequestRef
	57	@abstract Contains information about a certificate request.
	58	*/
	59	typedef struct OpaqueSecCertificateRequestRef *SecCertificateRequestRef;
	60
	61	/*!
	62	@function SecCertificateRequestGetTypeID
	63	Returns the type identifier of all SecCertificateRequest instances.
	64	*/
65	CFTypeID SecCertificateRequestGetTypeID(void);
66
67	/*!
68	@function SecCertificateRequestCreate
69
70	Create a certificate request operation based on a policy and certificate
71	type. If a policy is not specified, one will be chosen for the caller.
72	Once the requeste is created, a request reference is returned.
73	To submit the request call SecCertificateRequestSubmit().
74
75	@param policy A policy.
76	@param certificateType The certificate type (i.e. X509, PGP, etc).
77	These types are in cssmtype.h
78	@param requestType The identifier to the type of request to submit (i.e.
79	issue, verify, revoke, etc.). These are defined in cssmtype.h
80	@param privateKeyItemRef The keychain item private key to be used for this
81	certificate request. The private key item must be of class type
82	kSecAppleKeyItemClass.
83	@param attributeList An optional list of OIDs for the certificate request.
84	@param certRequest A returned reference to the certificate request. Call CFRelease when done with this certificate request.
427c49bc	85	@result errSecSuccess 0 No error.
b1ab9ed8 A	86	*/
	87	OSStatus SecCertificateRequestCreate(
	88	const CSSM_OID *policy,
	89	CSSM_CERT_TYPE certificateType,
	90	CSSM_TP_AUTHORITY_REQUEST_TYPE requestType,
	91	SecKeyRef privateKeyItemRef,
	92	SecKeyRef publicKeyItemRef,
	93	const SecCertificateRequestAttributeList* attributeList,
	94	SecCertificateRequestRef* certRequest);
	95
	96	/*!
	97	@function SecCertificateRequestSubmit
	98
	99	Submit a certificate request to be processed by the Security framework.
	100	Once the request is submitted, an estimated time is returned indicating
	101	when the request results can be retrieved. Once the estimated time has
	102	elapsed, obtain the result by calling SecCertificateRequestGetResult().
	103
	104	@param certRequest A reference to the certificate request.
	105	@param estimatedTime The number of estimated seconds before the result
	106	can be retrieved.
427c49bc	107	@result errSecSuccess 0 No error.
b1ab9ed8 A	108	*/
	109	OSStatus SecCertificateRequestSubmit(
	110	SecCertificateRequestRef certRequest,
	111	sint32* estimatedTime);
	112
	113	/*!
	114	@function SecCertificateRequestGetType
	115	Returns the certificate request type (i.e. issue, revoke, etc) for a given
	116	certificate request item reference.
	117	@param certRequestRef A reference to a submitted request.
	118	@param requestType The returned request type.
427c49bc	119	@result errSecSuccess 0 No error.
b1ab9ed8 A	120	*/
	121	OSStatus SecCertificateRequestGetType(
	122	SecCertificateRequestRef certRequestRef,
	123	CSSM_TP_AUTHORITY_REQUEST_TYPE* requestType);
	124
	125	/*!
	126	@function SecCertificateRequestGetResult
	127	Get the results of a certificate request. If the request is still
	128	pending, the estimated time will be returned which indicates when to
	129	call this function again.
	130	@param certRequestRef A reference for the submitted request.
	131	@param keychain The keychain in which to store the new certificate (for
	132	a new cert request) and the cert request item reference. Pass NULL
	133	to specify the default keychain.
	134	@param estimatedTime The number of estimated seconds before the result can
	135	be retrieved.
	136	@param certficateRef The returned certificate reference for a
	137	CSSM_TP_AUTHORITY_REQUEST_CERTISSUE only. All other request types return
	138	NULL here. Call CFRelease when done with this certificate reference.
427c49bc	139	@result errSecSuccess 0 No error.
b1ab9ed8 A	140	*/
	141	OSStatus SecCertificateRequestGetResult(
	142	SecCertificateRequestRef certRequestRef,
	143	SecKeychainRef keychain,
	144	sint32* estimatedTime,
	145	SecCertificateRef* certificateRef);
	146
	147	/*!
	148	@function SecCertificateFindRequest
	149	Find a pending certificate request and return a reference object
	150	for it. The search criteria is based on the input parameters.
	151	@param policy A policy.
	152	@param certificateType The certificate type (i.e. X509, PGP, etc).
	153	These types are in cssmtype.h
	154	@param requestType The identifier to the type of request to find (i.e.
	155	issue, verify, revoke, etc.). These are defined in cssmtype.h
	156	@param privateKeyItemRef Optional private key to be used
	157	for the certificate request. Matches the same argument as passed to
	158	SecCertificateRequestCreate().
	159	@param publicKeyItemRef Optional public key to be used
	160	for the certificate request. Matches the same argument as passed to
	161	SecCertificateRequestCreate().
	162	@param attributeList An optional list of OID/value pairs for finding the
	163	certificate request.
	164	@param certRequest A returned reference to the certificate request. Call CFRelease when done with this reference.
	165	*/
	166	OSStatus SecCertificateFindRequest(
	167	const CSSM_OID *policy,
	168	CSSM_CERT_TYPE certificateType,
	169	CSSM_TP_AUTHORITY_REQUEST_TYPE requestType,
	170	SecKeyRef privateKeyItemRef,
	171	SecKeyRef publicKeyItemRef,
	172	const SecCertificateRequestAttributeList* attributeList,
	173	SecCertificateRequestRef* certRequest);
	174
	175	/*!
	176	@function SecCertificateRequestGetData
	177	Get policy-specific data following a SecCertificateRequestSubmit.
	178	@param certRequestRef A reference for the submitted request.
	179	@param data Policy-specific data.
427c49bc	180	@result errSecSuccess 0 No error.
b1ab9ed8 A	181	*/
	182
	183	OSStatus SecCertificateRequestGetData(
	184	SecCertificateRequestRef certRequestRef,
	185	CSSM_DATA *data);
	186
	187	#if defined(__cplusplus)
	188	}
	189	#endif
	190
	191	#endif /* !_SECURITY_SECCERTIFICATEREQUEST_H_ */