trust/SecCertificateRequest.h

   1 /*
   2  * Copyright (c) 2002-2004,2008-2009,2011-2014,2016 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/SecKey.h>
  35 #include <Security/SecCertificatePriv.h>
  36
  37 #if SEC_OS_OSX
  38 #include <Security/cssmtype.h>
  39 #endif
  40
  41 __BEGIN_DECLS
  42
  43 #if SEC_OS_OSX
  44
  45 struct SecCertificateRequestAttribute /* for optional oids */
  46 {
  47     CSSM_OID    oid;
  48     CSSM_DATA   value;
  49 };
  50 typedef struct SecCertificateRequestAttribute SecCertificateRequestAttribute;
  51
  52 struct SecCertificateRequestAttributeList
  53 {
  54     UInt32 count;
  55     SecCertificateRequestAttribute *attr;
  56 };
  57 typedef struct SecCertificateRequestAttributeList  SecCertificateRequestAttributeList;
  58
  59 /*!
  60     @typedef SecCertificateRequestRef
  61     @abstract Contains information about a certificate request.
  62 */
  63 typedef struct OpaqueSecCertificateRequestRef *SecCertificateRequestRef;
  64
  65 /*!
  66     @function SecCertificateRequestGetTypeID
  67     Returns the type identifier of all SecCertificateRequest instances.
  68 */
  69 CFTypeID SecCertificateRequestGetTypeID(void);
  70
  71 /*!
  72     @function SecCertificateRequestCreate
  73
  74     Create a certificate request operation based on a policy and certificate
  75     type.  If a policy is not specified, one will be chosen for the caller.
  76     Once the requeste is created, a request reference is returned.
  77     To submit the request call SecCertificateRequestSubmit().
  78
  79     @param policy A policy.
  80     @param certificateType The certificate type (i.e. X509, PGP, etc).
  81        These types are in cssmtype.h
  82     @param requestType The identifier to the type of request to submit (i.e.
  83        issue, verify, revoke, etc.). These are defined in cssmtype.h
  84     @param privateKeyItemRef The keychain item private key to be used for this
  85        certificate request. The private key item must be of class type
  86        kSecAppleKeyItemClass.
  87     @param attributeList An optional list of OIDs for the certificate request.
  88     @param certRequest A returned reference to the certificate request. Call CFRelease when done with this certificate request.
  89     @result errSecSuccess 0 No error.
  90 */
  91 OSStatus SecCertificateRequestCreate(
  92         const CSSM_OID *policy,
  93         CSSM_CERT_TYPE certificateType,
  94         CSSM_TP_AUTHORITY_REQUEST_TYPE requestType,
  95         SecKeyRef privateKeyItemRef,
  96         SecKeyRef publicKeyItemRef,
  97         const SecCertificateRequestAttributeList* attributeList,
  98         SecCertificateRequestRef* certRequest);
  99
 100 /*!
 101     @function SecCertificateRequestSubmit
 102
 103     Submit a certificate request to be processed by the Security framework.
 104     Once the request is submitted, an estimated time is returned indicating
 105     when the request results can be retrieved. Once the estimated time has
 106     elapsed, obtain the result by calling SecCertificateRequestGetResult().
 107
 108     @param certRequest A reference to the certificate request.
 109     @param estimatedTime The number of estimated seconds before the result
 110        can be retrieved.
 111     @result errSecSuccess 0 No error.
 112 */
 113 OSStatus SecCertificateRequestSubmit(
 114         SecCertificateRequestRef certRequest,
 115         sint32* estimatedTime);
 116
 117 /*!
 118     @function SecCertificateRequestGetType
 119     Returns the certificate request type (i.e. issue, revoke, etc) for a given
 120     certificate request item reference.
 121     @param certRequestRef A reference to a submitted request.
 122     @param requestType The returned request type.
 123     @result errSecSuccess 0 No error.
 124 */
 125 OSStatus SecCertificateRequestGetType(
 126         SecCertificateRequestRef certRequestRef,
 127         CSSM_TP_AUTHORITY_REQUEST_TYPE* requestType);
 128
 129 /*!
 130     @function SecCertificateRequestGetResult
 131     Get the results of a certificate request. If the request is still
 132     pending, the estimated time will be returned which indicates when to
 133     call this function again.
 134     @param certRequestRef A reference for the submitted request.
 135     @param keychain The keychain in which to store the new certificate (for
 136        a new cert request) and the cert request item reference. Pass NULL
 137        to specify the default keychain.
 138     @param estimatedTime The number of estimated seconds before the result can
 139        be retrieved.
 140     @param certificateRef The returned certificate reference for a
 141        CSSM_TP_AUTHORITY_REQUEST_CERTISSUE only. All other request types return
 142        NULL here. Call CFRelease when done with this certificate reference.
 143     @result errSecSuccess 0 No error.
 144 */
 145 OSStatus SecCertificateRequestGetResult(
 146         SecCertificateRequestRef certRequestRef,
 147         SecKeychainRef keychain,
 148         sint32* estimatedTime,
 149         SecCertificateRef* certificateRef);
 150
 151 /*!
 152     @function SecCertificateFindRequest
 153     Find a pending certificate request and return a reference object
 154        for it. The search criteria is based on the input parameters.
 155     @param policy A policy.
 156     @param certificateType The certificate type (i.e. X509, PGP, etc).
 157        These types are in cssmtype.h
 158     @param requestType The identifier to the type of request to find (i.e.
 159        issue, verify, revoke, etc.). These are defined in cssmtype.h
 160     @param privateKeyItemRef Optional private key to be used
 161        for the certificate request. Matches the same argument as passed to
 162        SecCertificateRequestCreate().
 163     @param publicKeyItemRef Optional public key to be used
 164        for the certificate request. Matches the same argument as passed to
 165        SecCertificateRequestCreate().
 166     @param attributeList An optional list of OID/value pairs for finding the
 167        certificate request.
 168     @param certRequest A returned reference to the certificate request. Call CFRelease when done with this reference.
 169 */
 170 OSStatus SecCertificateFindRequest(
 171         const CSSM_OID *policy,
 172         CSSM_CERT_TYPE certificateType,
 173         CSSM_TP_AUTHORITY_REQUEST_TYPE requestType,
 174         SecKeyRef privateKeyItemRef,
 175         SecKeyRef publicKeyItemRef,
 176         const SecCertificateRequestAttributeList* attributeList,
 177         SecCertificateRequestRef* certRequest);
 178
 179 /*!
 180     @function SecCertificateRequestGetData
 181     Get policy-specific data following a SecCertificateRequestSubmit.
 182     @param certRequestRef A reference for the submitted request.
 183     @param data Policy-specific data.
 184     @result errSecSuccess 0 No error.
 185 */
 186
 187 OSStatus SecCertificateRequestGetData(
 188     SecCertificateRequestRef    certRequestRef,
 189     CSSM_DATA                    *data);
 190
 191
 192 #endif
 193
 194 extern const void * kSecOidCommonName;
 195 extern const void * kSecOidCountryName;
 196 extern const void * kSecOidStateProvinceName;
 197 extern const void * kSecOidLocalityName;
 198 extern const void * kSecOidOrganization;
 199 extern const void * kSecOidOrganizationalUnit;
 200
 201 extern const unsigned char SecASN1PrintableString;
 202 extern const unsigned char SecASN1UTF8String;
 203
 204 /*
 205         Parameter keys for certificate request generation:
 206         @param kSecCSRChallengePassword CFStringRef
 207             conversion to PrintableString or UTF8String needs to be possible.
 208         @param kSecCertificateKeyUsage  CFNumberRef
 209             with key usage mask using kSecKeyUsage constants.
 210         @param kSecSubjectAltName       CFArrayRef of CFStringRef or CFDataRef
 211             either dnsName or emailAddress (if contains @) or
 212             ipAddress, ipv4 (4) or ipv6 (16) bytes
 213         @param kSecCSRBasicContraintsPathLen    CFNumberRef
 214             if set will include basic constraints and mark it as
 215             a CA cert.  If 0 <= number < 256, specifies path length, otherwise
 216             path length will be omitted.  Basic contraints will always be
 217             marked critical.
 218         @param kSecCertificateExtensions     CFDictionaryRef
 219             if set all keys (strings with oids in dotted notation) will be added
 220             as extensions with accompanying value in binary (CFDataRef) or
 221             appropriate string (CFStringRef) type (based on used character set).
 222         @param kSecCertificateExtensionsEncoded     CFDictionaryRef
 223             if set all keys (strings with oids in dotted notation) will be added
 224             as extensions with accompanying value.  It is assumed that the value
 225             is a CFDataRef and is already properly encoded.  This value will be
 226             placed straight into the extension value OCTET STRING.
 227 */
 228 extern const void * kSecCSRChallengePassword;
 229 extern const void * kSecSubjectAltName;
 230 extern const void * kSecCertificateKeyUsage;
 231 extern const void * kSecCSRBasicContraintsPathLen;
 232 extern const void * kSecCertificateExtensions;
 233 extern const void * kSecCertificateExtensionsEncoded;
 234
 235 typedef struct {
 236     const void *oid;    /* kSecOid constant or CFDataRef with oid */
 237     unsigned char type; /* currently only SecASN1PrintableString */
 238     CFTypeRef value;    /* CFStringRef -> ASCII, UTF8, CFDataRef -> binary */
 239 } SecATV;
 240
 241 typedef SecATV *SecRDN;
 242
 243 /*
 244     @function SecGenerateCertificateRequest
 245     @abstract Return a newly generated CSR for subject and keypair.
 246     @param subject  RDNs in the subject
 247     @param num      Number of RDNs
 248     @param publicKey    Public key
 249     @param privateKey   Private key
 250     @discussion only handles RSA keypairs and uses a SHA-1 PKCS1 signature
 251     @result On success, a newly allocated CSR, otherwise NULL
 252
 253 Example for subject:
 254     SecATV cn[]   = { { kSecOidCommonName, SecASN1PrintableString, CFSTR("test") }, {} };
 255     SecATV c[]    = { { kSecOidCountryName, SecASN1PrintableString, CFSTR("US") }, {} };
 256     SecATV o[]    = { { kSecOidOrganization, SecASN1PrintableString, CFSTR("Apple Inc.") }, {} };
 257     SecRDN atvs[] = { cn, c, o, NULL };
 258 */
 259 CFDataRef SecGenerateCertificateRequestWithParameters(SecRDN *subject,
 260     CFDictionaryRef parameters, SecKeyRef publicKey, SecKeyRef privateKey) CF_RETURNS_RETAINED;
 261
 262 CFDataRef SecGenerateCertificateRequest(CFArrayRef subject,
 263     CFDictionaryRef parameters, SecKeyRef publicKey, SecKeyRef privateKey) CF_RETURNS_RETAINED;
 264
 265 /*
 266     @function SecVerifyCertificateRequest
 267     @abstract validate a CSR and return contained information to certify
 268     @param publicKey (optional/out) SecKeyRef public key to certify
 269     @param challenge (optional/out) CFStringRef enclosed challenge
 270     @param subject (optional/out) encoded subject RDNs
 271     @param extensions (optional/out) encoded extensions
 272 */
 273 bool SecVerifyCertificateRequest(CFDataRef csr, SecKeyRef *publicKey,
 274     CFStringRef *challenge, CFDataRef *subject, CFDataRef *extensions);
 275
 276 SecCertificateRef
 277 SecGenerateSelfSignedCertificate(CFArrayRef subject, CFDictionaryRef parameters,
 278     SecKeyRef publicKey, SecKeyRef privateKey);
 279
 280 SecCertificateRef
 281 SecIdentitySignCertificate(SecIdentityRef issuer, CFDataRef serialno,
 282     SecKeyRef publicKey, CFTypeRef subject, CFTypeRef extensions);
 283
 284 /* PRIVATE */
 285
 286 CF_RETURNS_RETAINED
 287 CFDataRef
 288 SecGenerateCertificateRequestSubject(SecCertificateRef ca_certificate, CFArrayRef subject);
 289
 290 __END_DECLS
 291
 292 #endif /* _SECURITY_SECCERTIFICATEREQUEST_H_ */