SecurityTests/clxutils/clAppUtils/identPicker.h

   1 /*
   2  * Copyright (c) 2003-2007 Apple 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
   7  * obtain a copy of the License at http://www.apple.com/publicsource and
   8  * read it before 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
  12  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  13  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  14  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  15  * Please see the License for the specific language governing rights and
  16  * limitations under the License.
  17  */
  18
  19 /*
  20  * identPicker.h - Given a keychain, select from possible multiple
  21  *                                 SecIdentityRefs via stdio UI, and cook up a
  22  *                                 CFArray containing that identity and all certs needed
  23  *                                 for cert verification by an SSL peer. The resulting
  24  *                                 CFArrayRef is suitable for passing to SSLSetCertificate().
  25  */
  26
  27 #ifndef _IDENT_PICKER_H_
  28 #define _IDENT_PICKER_H_
  29
  30 #include <Security/Security.h>
  31 #include <CoreFoundation/CoreFoundation.h>
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /*
  38  * Get the final term of a keychain's path as a C string. Caller must free()
  39  * the result.
  40  */
  41 char *kcFileName(
  42         SecKeychainRef kcRef);
  43
  44 /*
  45  * Obtain the printable name of a SecKeychainItemRef as a C string.
  46  * Caller must free() the result.
  47  */
  48 char *kcItemPrintableName(
  49         SecKeychainItemRef itemRef);
  50
  51 /*
  52  * Obtain the final term of a keychain item's keychain path as a C string.
  53  * Caller must free() the result.
  54  * May well return NULL indicating the item has no keychain (e.g. az floating cert).
  55  */
  56 char *kcItemKcFileName(SecKeychainItemRef itemRef);
  57
  58 /*
  59  * Safe gets().
  60  * -- guaranteed no buffer overflow
  61  * -- guaranteed NULL-terminated string
  62  * -- handles empty string (i.e., response is just CR) properly
  63  */
  64 void getString(
  65         char *buf,
  66         unsigned bufSize);
  67
  68 /*
  69  * IdentityPicker, returns full cert chain, optionally including root.
  70  */
  71 OSStatus sslIdentPicker(
  72         SecKeychainRef          kc,                             // NULL means use default list
  73         SecCertificateRef       trustedAnchor,  // optional additional trusted anchor
  74         bool                            includeRoot,    // true --> root is appended to outArray
  75                                                                                 // false --> root not included
  76         const CSSM_OID          *vfyPolicy,             // optional - if NULL, use SSL
  77         CFArrayRef                      *outArray);             // created and RETURNED
  78
  79 /*
  80  * Simple version, just returns a SecIdentityRef.
  81  */
  82 OSStatus sslSimpleIdentPicker(
  83         SecKeychainRef          kc,                             // NULL means use default list
  84         SecIdentityRef          *ident);                // RETURNED
  85
  86 #ifdef __cplusplus
  87 }
  88 #endif
  89
  90 #endif  /* _IDENT_PICKER_H_ */
  91