OSX/sec/Security/SecSCEP.h

   1 /*
   2  * Copyright (c) 2008-2010,2012-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 SecSCEP
  26 */
  27 #include <stdbool.h>
  28
  29 #include <Security/SecKey.h>
  30 #include <Security/SecCertificateRequest.h>
  31 #include <CoreFoundation/CFError.h>
  32
  33 #ifndef _SECURITY_SECSCEP_H_
  34 #define _SECURITY_SECSCEP_H_
  35
  36 __BEGIN_DECLS
  37
  38
  39 SecIdentityRef
  40 SecSCEPCreateTemporaryIdentity(SecKeyRef publicKey, SecKeyRef privateKey);
  41
  42 /*!
  43     @function SecSCEPGenerateCertificateRequest
  44     @abstract generate a scep certificate request blob, to be presented to
  45                 a scep server
  46     @param subject distinguished name to be put in the request
  47     @param parameters additional information such as challenge and extensions (see SecCMS.h and
  48          SecCertificateRequest.h for supported keys)
  49     @param publicKey public key to be certified
  50     @param privateKey accompanying private key signing the request (proof of possession)
  51     @param signer identity to sign scep request with, if NULL the keypair to be
  52         certified will be turned into a self-signed cert.  The expired identity
  53         should be passed in case automatic re-enrollment is desired.
  54     @param recipient SecCertificateRef or CFArray thereof for CA (and optionally RA if used).
  55 */
  56 CFDataRef
  57 SecSCEPGenerateCertificateRequest(CFArrayRef subject, CFDictionaryRef parameters,
  58     SecKeyRef publicKey, SecKeyRef privateKey,
  59     SecIdentityRef signer, CFTypeRef recipient) CF_RETURNS_RETAINED;
  60
  61 /*!
  62     @function SecSCEPCertifyRequest
  63     @abstract take a SCEP request and issue a cert
  64     @param request the request; the ra/ca identity needed to decrypt it needs to be
  65         in the keychain.
  66     @param ca_identity to sign the csr
  67     @param serialno encoded serial number for cert to be issued
  68         @param pend_request don't issue cert now
  69 */
  70 CFDataRef
  71 SecSCEPCertifyRequest(CFDataRef request, SecIdentityRef ca_identity, CFDataRef serialno, bool pend_request) CF_RETURNS_RETAINED;
  72
  73 /*!
  74  @function SecSCEPCertifyRequestWithAlgorithms
  75  @abstract take a SCEP request and issue a cert
  76  @param request the request; the ra/ca identity needed to decrypt it needs to be
  77  in the keychain.
  78  @param ca_identity to sign the csr
  79  @param serialno encoded serial number for cert to be issued
  80  @param pend_request don't issue cert now
  81  @param hashingAlgorithm hashing algorithm to use, see SecCMS.h
  82  @param encryptionAlgorithm encryption algorithm to use, see SecCMS.h
  83  */
  84 CFDataRef
  85 SecSCEPCertifyRequestWithAlgorithms(CFDataRef request, SecIdentityRef ca_identity, CFDataRef serialno, bool pend_request,
  86                                    CFStringRef hashingAlgorithm, CFStringRef encryptionAlgorithm) CF_RETURNS_RETAINED;
  87
  88 /*!
  89     @function SecSCEPVerifyReply
  90     @abstract validate a reply for a sent request and retrieve the issued
  91         request
  92     @param request the request sent to the server
  93     @param reply reply received from server
  94     @param signer SecCertificateRef or CFArray thereof for CA (and optionally RA if used).
  95     @param server_error @@@ unused
  96     @result issued_cert certificate returned in a success reply
  97 */
  98 CFArrayRef
  99 SecSCEPVerifyReply(CFDataRef request, CFDataRef reply, CFTypeRef signer,
 100     CFErrorRef *server_error) CF_RETURNS_RETAINED;
 101
 102
 103 /*!
 104  @function SecSCEPGetCertInitial
 105  @abstract generate a scep cert initial request, to be presented to
 106  a scep server, in case the first request timed out
 107  */
 108 CF_RETURNS_RETAINED
 109 CFDataRef
 110 SecSCEPGetCertInitial(SecCertificateRef ca_certificate, CFArrayRef subject, CFDictionaryRef parameters,
 111                                           CFDictionaryRef signed_attrs, SecIdentityRef signer, CFTypeRef recipient);
 112
 113 /*!
 114     @function SecSCEPValidateCACertMessage
 115     @abstract validate GetCACert data against CA fingerprint and find
 116         appropriate RA certificates if applicable.
 117     @param certs a PKCS#7 GetCACert response
 118     @param ca_fingerprint CFDataRef with CA fingerprint.  Size indicates hash type.  Recognises SHA-1 and MD5.
 119     @param ca_certificate SecCertificateRef CA certificate
 120     @param ra_signing_certificate SecCertificateRef RA certificate.  Use both for signing and encryption unless ra_encryption_certificate is also returned.
 121     @param ra_encryption_certificate SecCertificateRef RA encryption certificate.  Returned if there isn't an RA certificate that can both sign and encrypt.
 122     @result status errSecSuccess on success.
 123 */
 124 OSStatus
 125 SecSCEPValidateCACertMessage(CFArrayRef certs,
 126     CFDataRef ca_fingerprint, SecCertificateRef *ca_certificate,
 127     SecCertificateRef *ra_signing_certificate,
 128     SecCertificateRef *ra_encryption_certificate);
 129
 130
 131 __END_DECLS
 132
 133 #endif /* _SECURITY_SECSCEP_H_ */