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
  48     @param publicKey public key to be certified
  49     @param privateKey accompanying private key signing the request (proof of possession)
  50     @param signer identity to sign scep request with, if NULL the keypair to be
  51         certified will be turned into a self-signed cert.  The expired identity
  52         should be passed in case automatic re-enrollment is desired.
  53     @param recipient SecCertificateRef or CFArray thereof for CA (and optionally RA if used).
  54 */
  55 CFDataRef
  56 SecSCEPGenerateCertificateRequest(CFArrayRef subject, CFDictionaryRef parameters,
  57     SecKeyRef publicKey, SecKeyRef privateKey,
  58     SecIdentityRef signer, CFTypeRef recipient) CF_RETURNS_RETAINED;
  59
  60 /*!
  61     @function SecSCEPCertifyRequest
  62     @abstract take a SCEP request and issue a cert
  63     @param request the request; the ra/ca identity needed to decrypt it needs to be
  64         in the keychain.
  65     @param ca_identity to sign the csr
  66     @param serialno encoded serial number for cert to be issued
  67         @param pend_request don't issue cert now
  68 */
  69 CFDataRef
  70 SecSCEPCertifyRequest(CFDataRef request, SecIdentityRef ca_identity, CFDataRef serialno, bool pend_request) CF_RETURNS_RETAINED;
  71
  72 /*!
  73     @function SecSCEPVerifyReply
  74     @abstract validate a reply for a sent request and retrieve the issued
  75         request
  76     @param request the request sent to the server
  77     @param reply reply received from server
  78     @param signer SecCertificateRef or CFArray thereof for CA (and optionally RA if used).
  79     @param server_error @@@ unused
  80     @result issued_cert certificate returned in a success reply
  81 */
  82 CFArrayRef
  83 SecSCEPVerifyReply(CFDataRef request, CFDataRef reply, CFTypeRef signer,
  84     CFErrorRef *server_error) CF_RETURNS_RETAINED;
  85
  86
  87 /*!
  88  @function SecSCEPGetCertInitial
  89  @abstract generate a scep cert initial request, to be presented to
  90  a scep server, in case the first request timed out
  91  */
  92 CF_RETURNS_RETAINED
  93 CFDataRef
  94 SecSCEPGetCertInitial(SecCertificateRef ca_certificate, CFArrayRef subject, CFDictionaryRef parameters,
  95                                           CFDictionaryRef signed_attrs, SecIdentityRef signer, CFTypeRef recipient);
  96
  97 /*!
  98     @function SecSCEPValidateCACertMessage
  99     @abstract validate GetCACert data against CA fingerprint and find
 100         appropriate RA certificates if applicable.
 101     @param certs a PKCS#7 GetCACert response
 102     @param ca_fingerprint CFDataRef with CA fingerprint.  Size indicates hash type.  Recognises SHA-1 and MD5.
 103     @param ca_certificate SecCertificateRef CA certificate
 104     @param ra_certificate SecCertificateRef RA certificate.  Use both for signing and encryption unless ra_encryption_certificate is also returned.
 105     @param ra_encryption_certificate SecCertificateRef RA encryption certificate.  Returned if there isn't an RA certificate that can both sign and encrypt.
 106     @result status errSecSuccess on success.
 107 */
 108 OSStatus
 109 SecSCEPValidateCACertMessage(CFArrayRef certs,
 110     CFDataRef ca_fingerprint, SecCertificateRef *ca_certificate,
 111     SecCertificateRef *ra_signing_certificate,
 112     SecCertificateRef *ra_encryption_certificate);
 113
 114
 115 __END_DECLS
 116
 117 #endif /* _SECURITY_SECSCEP_H_ */