sec/Security/SecSCEP.h

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