Keychain/SecCertificateRequest.h

   1 /*
   2  * Copyright (c) 2002 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18 /*!
  19         @header SecCertificateRequest
  20         SecCertificateRequest implements a way to issue a certificate request to a
  21         certificate authority.
  22 */
  23
  24 #ifndef _SECURITY_SECCERTIFICATEREQUEST_H_
  25 #define _SECURITY_SECCERTIFICATEREQUEST_H_
  26
  27 #include <Security/SecBase.h>
  28 #include <Security/cssmtype.h>
  29
  30
  31 #if defined(__cplusplus)
  32 extern "C" {
  33 #endif
  34
  35 /*!
  36     @typedef SecCertificateRequestRef
  37     @abstract Contains information about a certificate request.
  38 */
  39 typedef struct OpaqueSecCertificateRequestRef *SecCertificateRequestRef;
  40
  41 /*!
  42         @function SecCertificateRequestGetTypeID
  43         Returns the type identifier of all SecCertificateRequest instances.
  44 */
  45 CFTypeID SecCertificateRequestGetTypeID(void);
  46
  47 /*!
  48         @function SecCertificateRequestCreate
  49         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. For this request reference, you can set attributes for it by using SecCertificateRequestSetAttribute(). To submit the request call SecCertificateRequestSubmit().
  50     @param certificateType The certificate type (i.e. X509, PGP, etc). These types are in cssmtype.h
  51     @param requestType The identifier to the type of request to submit (i.e. issue, verify, revoke, etc.). These are defined in cssmtype.h
  52     @param certRequest A returned reference to the certificate request.
  53         @result noErr 0 No error.
  54 */
  55 OSStatus SecCertificateRequestCreate(
  56         SecPolicyRef policy,
  57         CSSM_CERT_TYPE certificateType,
  58         CSSM_TP_AUTHORITY_REQUEST_TYPE requestType,
  59         SecCertificateRequestRef* certRequest);
  60
  61 /*!
  62         @function SecCertificateRequestSetPrivateKey
  63         For a given certificate request, set the private key for which the assocaited public key will be certified.
  64     @param certRequest A reference to the certificate request.
  65         @param privateKeyItemRef The keychain item private key to be used for this certificate request. The private key item must be of class type kSecAppleKeyItemClass.
  66     @result noErr 0 No error.
  67 */
  68 OSStatus SecCertificateRequestSetPrivateKey(
  69         SecCertificateRequestRef certRequest,
  70         SecKeychainItemRef privateKeyItemRef);
  71
  72 /*!
  73         @function SecCertificateRequestSetAttribute
  74         For a given certificate request, set an optional attribute for the request. For example, an attribute can be the caller credentials or any other attribute needed for the certificate request operation.
  75     @param oid An BER-encoded oid that defines the attribute (i.e. CSSMOID_CommonName, CSSMOID_SerialNumber, etc.)
  76         @param value The value for the attribute.
  77     @result noErr 0 No error.
  78 */
  79 OSStatus SecCertificateRequestSetAttribute(
  80         SecCertificateRequestRef certRequest,
  81         const CSSM_OID* oid,
  82         const CSSM_DATA* value);
  83
  84 /*!
  85         @function SecCertificateRequestSubmit
  86         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().
  87     @param certRequest A reference to the certificate request.
  88     @param keychain The keychain in which to store the new certificate (for a new cert request) and the cert request item reference.
  89     @param estimatedTime The number of estimated seconds before the result can be retrieved.
  90     @param certRequestItemRef The returned persistent reference for the submitted request. This item is stored in the keychain specified by the keychain parameter. This item can be viewed as an certificate request operation that is still pending.
  91         @result noErr 0 No error.
  92 */
  93 OSStatus SecCertificateRequestSubmit(
  94         SecCertificateRequestRef certRequest,
  95         SecKeychainRef keychain,
  96         sint32* estimatedTime,
  97         SecKeychainItemRef* certRequestItemRef);
  98
  99 /*!
 100         @function SecCertificateRequestCreateFromItem
 101         Given a keychain item reference (a persistent reference for a certificate request), create a certificate request reference to be used by subsuequent calls that take a SecCertificateRequestRef. The keychain item must be obtained by calling SecKeychainSearchCreateFromAttributes() and SecKeychainCopySearchNextItem() for an item with the class of kSecAppleCertificateRequestItemClass.
 102     @param certRequestItemRef A keychain item reference for the certificate request(%%%kSecGenericPasswordItemClass?)
 103         @param certRequestRef The returned certificate request reference.
 104     @result noErr 0 No error.
 105 */
 106 OSStatus SecCertificateRequestCreateFromItem(
 107         SecKeychainItemRef certRequestItemRef,
 108         SecCertificateRequestRef* certRequestRef);
 109
 110 /*!
 111         @function SecCertificateRequestGetType
 112         Returns the certificate request type (i.e. issue, revoke, etc) for a given certificate request item reference.
 113     @param certRequestRef A reference to a submitted request.
 114         @param requestType The returned request type.
 115     @result noErr 0 No error.
 116 */
 117 OSStatus SecCertificateRequestGetType(
 118         SecCertificateRequestRef certRequestRef,
 119         CSSM_TP_AUTHORITY_REQUEST_TYPE* requestType);
 120
 121 /*!
 122         @function SecCertificateRequestGetResult
 123         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.
 124     @param certRequestRef A reference for the submitted request.
 125     @param estimatedTime The number of estimated seconds before the result can be retrieved.
 126         @param certficateRef The returned certificate reference for a CSSM_TP_AUTHORITY_REQUEST_CERTISSUE only. All other request types return NULL here.
 127     @result noErr 0 No error.
 128 */
 129 OSStatus SecCertificateRequestGetResult(
 130         SecCertificateRequestRef certRequestRef,
 131         sint32* estimatedTime,
 132         SecCertificateRef* certificateRef);
 133
 134 #if defined(__cplusplus)
 135 }
 136 #endif
 137
 138 #endif /* !_SECURITY_SECCERTIFICATEREQUEST_H_ */