trust/SecCertificateRequest.h

   1 /*
   2  * Copyright (c) 2002-2017 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 #include <Security/SecCMS.h>
  37
  38 __BEGIN_DECLS
  39
  40 CF_ASSUME_NONNULL_BEGIN
  41
  42 extern const CFStringRef kSecOidCommonName;
  43 extern const CFStringRef kSecOidCountryName;
  44 extern const CFStringRef kSecOidStateProvinceName;
  45 extern const CFStringRef kSecOidLocalityName;
  46 extern const CFStringRef kSecOidOrganization;
  47 extern const CFStringRef kSecOidOrganizationalUnit;
  48
  49 extern const unsigned char SecASN1PrintableString;
  50 extern const unsigned char SecASN1UTF8String;
  51
  52 /*
  53         Parameter keys for certificate request generation:
  54         @param kSecCSRChallengePassword CFStringRef
  55             conversion to PrintableString or UTF8String needs to be possible.
  56         @param kSecCertificateKeyUsage  CFNumberRef
  57             with key usage mask using kSecKeyUsage constants.
  58         @param kSecSubjectAltName       CFDictionaryRef
  59             with keys defined below.
  60         @param kSecCSRBasicContraintsPathLen    CFNumberRef
  61             if set will include basic constraints and mark it as
  62             a CA cert.  If 0 <= number < 256, specifies path length, otherwise
  63             path length will be omitted.  Basic contraints will always be
  64             marked critical.
  65         @param kSecCertificateExtensions     CFDictionaryRef
  66             if set all keys (strings with oids in dotted notation) will be added
  67             as extensions with accompanying value in binary (CFDataRef) or
  68             appropriate string (CFStringRef) type (based on used character set).
  69         @param kSecCertificateExtensionsEncoded     CFDictionaryRef
  70             if set all keys (strings with oids in dotted notation) will be added
  71             as extensions with accompanying value.  It is assumed that the value
  72             is a CFDataRef and is already properly encoded.  This value will be
  73             placed straight into the extension value OCTET STRING.
  74          @param kSecCMSSignHashAlgorithm    CFStringRef
  75              (Declared in SecCMS.h)
  76              if set, determines the hash algorithm used to create the signing
  77              request or certificate. If this parameter is omitted, the default
  78              hash algorithm will be used (SHA1 for RSA and SHA256 for ECDSA).
  79              Supported digest algorithm strings are defined in
  80              SecCMS.h, e.g. kSecCMSHashingAlgorithmSHA256;.
  81 */
  82 extern const CFStringRef kSecCSRChallengePassword;
  83 extern const CFStringRef kSecSubjectAltName;
  84 extern const CFStringRef kSecCertificateKeyUsage;
  85 extern const CFStringRef kSecCSRBasicContraintsPathLen;
  86 extern const CFStringRef kSecCertificateExtensions;
  87 extern const CFStringRef kSecCertificateExtensionsEncoded;
  88
  89 /*
  90  Keys for kSecSubjectAltName dictionaries:
  91  @param kSecSubjectAltNameDNSName CFArrayRef or CFStringRef
  92      The value for this key is either a CFStringRef containing a single DNS name,
  93      or a CFArrayRef of CFStringRefs, each containing a single DNS Name.
  94  @param kkSecSubjectAltNameEmailAddress CFArrayRef or CFStringRef
  95      The value for this key is either a CFStringRef containing a single email
  96      address (RFC 822 Name), or a CFArrayRef of CFStringRefs, each containing a
  97      single email address.
  98  @param kSecSubjectAltNameURI CFArrayRef or CFStringRef
  99      The value for this key is either a CFStringRef containing a single URI,
 100      or a CFArrayRef of CFStringRefs, each containing a single URI.
 101  @param kSecSubjectAltNameNTPrincipalName CFStringRef
 102      The value for this key is a CFStringRef containing the NTPrincipalName.
 103 */
 104 extern const CFStringRef kSecSubjectAltNameDNSName;
 105 extern const CFStringRef kSecSubjectAltNameEmailAddress;
 106 extern const CFStringRef kSecSubjectAltNameURI;
 107 extern const CFStringRef kSecSubjectAltNameNTPrincipalName;
 108
 109 typedef struct {
 110     CFTypeRef oid;    /* kSecOid constant or CFDataRef with oid */
 111     unsigned char type; /* currently only SecASN1PrintableString or SecASN1UTF8String */
 112     CFTypeRef value;    /* CFStringRef -> ASCII, UTF8, CFDataRef -> binary */
 113 } SecATV;
 114
 115 typedef SecATV *SecRDN;
 116
 117 /*
 118     @function SecGenerateCertificateRequestWithParameters
 119     @abstract Return a newly generated CSR for subject and keypair.
 120     @param subject  RDNs in the subject
 121     @param paramters    Parameters for the CSR generation. See above.
 122     @param publicKey    Public key
 123     @param privateKey   Private key
 124     @result On success, a newly allocated CSR, otherwise NULL
 125
 126 Example for subject:
 127     SecATV cn[]   = { { kSecOidCommonName, SecASN1PrintableString, CFSTR("test") }, {} };
 128     SecATV c[]    = { { kSecOidCountryName, SecASN1PrintableString, CFSTR("US") }, {} };
 129     SecATV o[]    = { { kSecOidOrganization, SecASN1PrintableString, CFSTR("Apple Inc.") }, {} };
 130     SecRDN atvs[] = { cn, c, o, NULL };
 131 */
 132 CF_RETURNS_RETAINED _Nullable
 133 CFDataRef SecGenerateCertificateRequestWithParameters(SecRDN _Nonnull * _Nonnull subject,
 134     CFDictionaryRef _Nullable parameters, SecKeyRef _Nullable publicKey, SecKeyRef privateKey) CF_RETURNS_RETAINED;
 135
 136 /*
 137  @function SecGenerateCertificateRequest
 138  @abstract Return a newly generated CSR for subject and keypair.
 139  @param subject  RDNs in the subject in array format
 140  @param paramters    Parameters for the CSR generation. See above.
 141  @param publicKey    Public key
 142  @param privateKey   Private key
 143  @result On success, a newly allocated CSR, otherwise NULL
 144  @discussion The subject array contains an array of the RDNS. Each RDN is
 145  itself an array of ATVs. Each ATV is an array of length two containing
 146  first the OID and then the value.
 147
 148 Example for subject (in Objective-C for ease of reading):
 149  NSArray *subject = @[
 150      @[@[(__bridge NSString*)kSecOidCommonName, @"test"]]
 151      @[@[(__bridge NSString*)kSecOidCountryName, @"US"]],
 152      @[@[(__bridge NSString*)kSecOidOrganization, @"Apple Inc"]],
 153  ];
 154  */
 155 CF_RETURNS_RETAINED _Nullable
 156 CFDataRef SecGenerateCertificateRequest(CFArrayRef subject,
 157     CFDictionaryRef _Nullable parameters, SecKeyRef _Nullable publicKey, SecKeyRef privateKey) CF_RETURNS_RETAINED;
 158
 159 /*
 160     @function SecVerifyCertificateRequest
 161     @abstract validate a CSR and return contained information to certify
 162     @param publicKey (optional/out) SecKeyRef public key to certify
 163     @param challenge (optional/out) CFStringRef enclosed challenge
 164     @param subject (optional/out) encoded subject RDNs
 165     @param extensions (optional/out) encoded extensions
 166 */
 167 bool SecVerifyCertificateRequest(CFDataRef csr, SecKeyRef CF_RETURNS_RETAINED * _Nullable publicKey,
 168                                  CFStringRef CF_RETURNS_RETAINED _Nullable * _Nullable challenge,
 169                                  CFDataRef CF_RETURNS_RETAINED _Nullable * _Nullable subject,
 170                                  CFDataRef CF_RETURNS_RETAINED _Nullable * _Nullable extensions);
 171
 172
 173 /*
 174  @function SecGenerateSelfSignedCertificate
 175  @abstract Return a newly generated certificate for subject and keypair.
 176  @param subject  RDNs in the subject in array format
 177  @param paramters    Parameters for the CSR generation. See above.
 178  @param publicKey    Public key (NOTE: This is unused)
 179  @param privateKey   Private key
 180  @result On success, a newly allocated certificate, otherwise NULL
 181  @discussion The subject array contains an array of the RDNS. Each RDN is
 182  itself an array of ATVs. Each ATV is an array of length two containing
 183  first the OID and then the value.
 184
 185  Example for subject (in Objective-C for ease of reading):
 186  NSArray *subject = @[
 187      @[@[(__bridge NSString*)kSecOidCommonName, @"test"]]
 188      @[@[(__bridge NSString*)kSecOidCountryName, @"US"]],
 189      @[@[(__bridge NSString*)kSecOidOrganization, @"Apple Inc"]],
 190  ];
 191  */
 192 CF_RETURNS_RETAINED _Nullable
 193 SecCertificateRef SecGenerateSelfSignedCertificate(CFArrayRef subject, CFDictionaryRef parameters,
 194     SecKeyRef _Nullable publicKey, SecKeyRef privateKey);
 195
 196 /*
 197  @function SecIdentitySignCertificate
 198  @param issuer      issuer's identity (certificate/private key pair)
 199  @param serialno    serial number for the issued certificate
 200  @param publicKey   public key for the issued certificate
 201  @param subject     subject name for the issued certificate
 202  @param extensions  extensions for the issued certificate
 203  @param hashingAlgorithm hash algorithm to use for signature
 204  @result On success, a newly allocated certificate, otherwise NULL
 205  @discussion This call can be used in combination with SecVerifyCertificateRequest
 206  to generate a signed certifcate from a CSR after verifying it. The outputs
 207  of SecVerifyCertificateRequest may be passed as inputs to this function.
 208
 209  The subject may be an array, as specified in SecCertificateGenerateRequest,
 210  or a data containing an encoded subject sequence, as specified by RFC 5280.
 211
 212  Supported digest algorithm strings are defined in SecCMS.h, e.g.
 213  kSecCMSHashingAlgorithmSHA256.
 214  */
 215 CF_RETURNS_RETAINED _Nullable
 216 SecCertificateRef SecIdentitySignCertificate(SecIdentityRef issuer, CFDataRef serialno,
 217     SecKeyRef publicKey, CFTypeRef subject, CFTypeRef _Nullable extensions);
 218
 219 CF_RETURNS_RETAINED _Nullable
 220 SecCertificateRef SecIdentitySignCertificateWithAlgorithm(SecIdentityRef issuer, CFDataRef serialno,
 221    SecKeyRef publicKey, CFTypeRef subject, CFTypeRef _Nullable extensions, CFStringRef _Nullable hashingAlgorithm);
 222
 223 /* PRIVATE */
 224
 225 CF_RETURNS_RETAINED _Nullable
 226 CFDataRef SecGenerateCertificateRequestSubject(SecCertificateRef ca_certificate, CFArrayRef subject);
 227
 228 CF_ASSUME_NONNULL_END
 229
 230 __END_DECLS
 231
 232 #endif /* _SECURITY_SECCERTIFICATEREQUEST_H_ */