Keychain/SecCertificate.h

   1 /*
   2  * Copyright (c) 2002 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18 /*!
  19         @header SecCertificate
  20         The functions provided in SecCertificate implement and manage a particular type of keychain item that represents a certificate.  You can store a certificate in a keychain, but a certificate can also be a transient object.
  21
  22         You can use a certificate as a keychain item in most functions.
  23 */
  24
  25 #ifndef _SECURITY_SECCERTIFICATE_H_
  26 #define _SECURITY_SECCERTIFICATE_H_
  27
  28 #include <Security/SecBase.h>
  29 #include <Security/cssmtype.h>
  30
  31 // @@@ Here for X509 specific defines
  32 #include <Security/x509defs.h>
  33
  34
  35 #if defined(__cplusplus)
  36 extern "C" {
  37 #endif
  38
  39
  40 /*!
  41         @enum CertificateItemAttributes
  42         @abstract Indicates the type of a certificate item attribute.
  43         @constant kSecSubjectItemAttr Indicates a DER-encoded subject distinguished name.
  44         @constant kSecIssuerItemAttr Indicates a DER-encoded issuer distinguished name.
  45         @constant kSecSerialNumberItemAttr Indicates a DER-encoded certificate serial number.
  46         @constant kSecPublicKeyHashItemAttr Indicates a public key hash.
  47         @constant kSecSubjectKeyIdentifierItemAttr Indicates a subject key identifier.
  48         @constant kSecCertTypeItemAttr Indicates a certificate type.
  49         @constant kSecCertEncodingItemAttr Indicates a certificate encoding.
  50 */
  51 enum
  52 {
  53     kSecSubjectItemAttr                          = 'subj',
  54     kSecIssuerItemAttr                           = 'issu',
  55     kSecSerialNumberItemAttr             = 'snbr',
  56     kSecPublicKeyHashItemAttr            = 'hpky',
  57     kSecSubjectKeyIdentifierItemAttr = 'skid',
  58         kSecCertTypeItemAttr                     = 'ctyp',
  59         kSecCertEncodingItemAttr                 = 'cenc'
  60 };
  61
  62 /*!
  63         @function SecCertificateGetTypeID
  64         @abstract Returns the type identifier of SecCertificate instances.
  65         @result The CFTypeID of SecCertificate instances.
  66 */
  67 CFTypeID SecCertificateGetTypeID(void);
  68
  69 #pragma mark ÑÑÑÑ Certificate Operations ÑÑÑÑ
  70
  71 /*!
  72         @function SecCertificateCreateFromData
  73         @abstract Creates a certificate based on the input data, type, and encoding.
  74     @param data A pointer to the certificate data.
  75     @param type The certificate type as defined in cssmtype.h.
  76     @param encoding The certificate encoding as defined in cssmtype.h.
  77         @param certificate On return, a pointer to the newly created certificate reference.
  78     @result A result code.  See "Security Error Codes" (SecBase.h).
  79 */
  80 OSStatus SecCertificateCreateFromData(const CSSM_DATA *data, CSSM_CERT_TYPE type, CSSM_CERT_ENCODING encoding, SecCertificateRef *certificate);
  81
  82 /*!
  83         @function SecCertificateAddToKeychain
  84         @abstract Adds a certificate to the keychain specified.
  85     @param certificate A reference to the certificate to add to the keychain.
  86     @param keychain A reference to the keychain to which to add the certificate. Pass NULL to add the certificate to the default keychain.
  87     @result A result code.  See "Security Error Codes" (SecBase.h).
  88         @discussion This function call only works if the certificate was created using the SecCertificateCreateFromData function and the certificate has not yet been added to a keychain.
  89 */
  90 OSStatus SecCertificateAddToKeychain(SecCertificateRef certificate, SecKeychainRef keychain);
  91
  92 /*!
  93         @function SecCertificateGetData
  94         @abstract Retrieves the data for a given certificate.
  95     @param certificate A reference to the certificate from which to retrieve the data.
  96     @param data On return, a pointer to the data for the certificate specified.  The caller must allocate the space for a CSSM_DATA structure before calling this function.  This data pointer is only guaranteed to remain valid as long as the certificate remains unchanged and valid.
  97         @result A result code.  See "Security Error Codes" (SecBase.h).
  98 */
  99 OSStatus SecCertificateGetData(SecCertificateRef certificate, CSSM_DATA_PTR data);
 100
 101 /*!
 102         @function SecCertificateGetItem
 103         @abstract Retrieves the keychain item reference for a given certificate.
 104     @param certificate A reference to the certificate from which to obtain the keychain item reference.
 105     @param item On return, a pointer to the keychain item reference of the certificate specified. If the certificate is not based on a keychain item, the value of item is NULL.
 106         @result A result code.  See "Security Error Codes" (SecBase.h).
 107 */
 108 OSStatus SecCertificateGetItem(SecCertificateRef certificate, SecKeychainItemRef *item);
 109
 110 /*!
 111         @function SecCertificateGetType
 112         @abstract Retrieves the type for a given certificate.
 113     @param certificate A reference to the certificate from which to obtain the type.
 114     @param certificateType On return, a pointer to the certificate type of the certificate specified. Certificate types are defined in cssmtype.h
 115         @result A result code.  See "Security Error Codes" (SecBase.h).
 116 */
 117 OSStatus SecCertificateGetType(SecCertificateRef certificate, CSSM_CERT_TYPE *certificateType);
 118
 119 /*!
 120         @function SecCertificateGetSubject
 121         @abstract Retrieves the subject for a given certificate.
 122     @param certificate A reference to the certificate from which to obtain the subject.
 123     @param subject On return, a pointer to the subject of the given certificate.
 124         @result A result code.  See "Security Error Codes" (SecBase.h).
 125 */
 126 OSStatus SecCertificateGetSubject(SecCertificateRef certificate, CSSM_X509_NAME *subject);
 127
 128 /*!
 129         @function SecCertificateGetIssuer
 130         @abstract Retrieves the issuer of a given certificate.
 131     @param certificate A reference to the certificate from which to obtain the issuer.
 132     @param issuer On return, a pointer to the issuer of the given certificate.
 133         @result A result code.  See "Security Error Codes" (SecBase.h).
 134 */
 135 OSStatus SecCertificateGetIssuer(SecCertificateRef certificate, CSSM_X509_NAME *issuer);
 136
 137 /*!
 138         @function SecCertificateGetCLHandle
 139         @abstract Retrieves the certificate library handle for a given certificate.
 140     @param certificate A reference to the certificate from which to obtain the certificate library handle.
 141     @param clHandle On return, a pointer to the certificate library handle of the given certificate.  This handle remains valid at least as long as the certificate does.
 142         @result A result code.  See "Security Error Codes" (SecBase.h).
 143 */
 144 OSStatus SecCertificateGetCLHandle(SecCertificateRef certificate, CSSM_CL_HANDLE *clHandle);
 145
 146 #if defined(__cplusplus)
 147 }
 148 #endif
 149
 150 #endif /* !_SECURITY_SECCERTIFICATE_H_ */