OSX/libsecurity_keychain/lib/SecCertificateRequest.h

   1 /*
   2  * Copyright (c) 2002-2004,2011,2013-2014 Apple 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.
  85         @result errSecSuccess 0 No error.
  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.
 107         @result errSecSuccess 0 No error.
 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.
 119     @result errSecSuccess 0 No error.
 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.
 139     @result errSecSuccess 0 No error.
 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.
 180     @result errSecSuccess 0 No error.
 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_ */