1/* 2 * KerberosHelper.h 3 * KerberosHelper 4*/ 5 6/* 7 * Copyright (c) 2006-2007 Apple Inc. All rights reserved. 8 * 9 * @APPLE_LICENSE_HEADER_START@ 10 * 11 * This file contains Original Code and/or Modifications of Original Code 12 * as defined in and that are subject to the Apple Public Source License 13 * Version 2.0 (the 'License'). You may not use this file except in 14 * compliance with the License. Please obtain a copy of the License at 15 * http://www.opensource.apple.com/apsl/ and read it before using this 16 * file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_LICENSE_HEADER_END@ 27 */ 28#ifndef _KERBEROSHELPER_H_ 29#define _KERBEROSHELPER_H_ 30 31#include <CoreFoundation/CoreFoundation.h> 32#include <Security/Security.h> 33 34#ifdef __cplusplus 35extern "C" { 36#endif 37 38typedef struct KRBhelperContext *KRBHelperContextRef; 39 40/* 41 KRBCreateSession will start a kerberos session and return a pointer to a kerberosSession that is passed to the other SPIs. 42 inHostName is the name of the host to get the service principal and/or user principal for. If inHostName is NULL, it is 43 assumed that the local machine is the target. 44 inAdvertisedPrincipal is a service principal guess (can be NULL), perhaps provided by the service. This is not secure 45 and is given the least priorty when other information is available 46 outKerberosSession is a pointer that should be passed to the other KRB functions. 47*/ 48OSStatus KRBCreateSession (CFStringRef inHostName, CFStringRef inAdvertisedPrincipal, void **outKerberosSession) 49 /* __attribute__((deprecated)) use KRBCreateSessionInfo */; 50 51 52/* 53 KRBCreateSession will start a kerberos session and return a pointer to a kerberosSession that is passed to the other SPIs. 54 inDict is a dictionary that should contain the following keys: 55 56 kKRBHostnameKey the name of the host to get the service principal and/or user principal for. If inHostName is NULL, it is 57 assumed that the local machine is the target. 58 Optional keys: 59 kKRBAdvertisedPrincipalKey 60 is a service principal guess (can be NULL), perhaps provided by the service. This is not secure 61 and is given the least priorty when other information is available 62 kKRBNoLKDCKey Don't try Local KDC if it will mean time penalties 63 64 outKerberosSession is a pointer that should be passed to the other KRB functions. 65*/ 66 67 68OSStatus KRBCreateSessionInfo (CFDictionaryRef inDict, KRBHelperContextRef *outKerberosSession); 69 70#define kKRBHostnameKey CFSTR("Hostname") 71#define kKRBAdvertisedPrincipalKey CFSTR("AdvertisedPrincipal") 72#define kKRBNoLKDCKey CFSTR("NoLKDC") 73 74/* 75 KRBCopyREALM will return the best-guess REALM for the host that was passed to KRBCreateSession 76 inKerberosSession is the pointer returned by KRBCreateSession 77 outREALM is the REALM of the host 78*/ 79OSStatus KRBCopyRealm (KRBHelperContextRef inKerberosSession, CFStringRef *outRealm); 80 81/* 82 KRBCopyKeychainLookupInfo will return a dictionary containing information related to Kerberos and keychain items. 83 inKerberosSession is the pointer returned by KRBCreateSession 84 inUsername is an available and usable Username or NULL 85 outKeychainLookupInfo is a dictionary containing keychain lookup info and if it is acceptable to store a 86 password in the keychain. 87 88 This call for use by KerberosAgent and NetAuthAgent only. 89 90 outKeychainLookupInfo 91 kKRBUsernameKey : CFStringRef 92 kKRBKeychainAccountNameKey : CFStringRef 93 kKRBDisableSaveToKeychainKey : CFBooleanRef 94 95*/ 96#define kKRBDisableSaveToKeychainKey CFSTR("DisableSaveToKeychain") 97#define kKRBKeychainAccountNameKey CFSTR("KeychainAccountName") 98#define kKRBAgentBundleIdentifier CFSTR("edu.mit.Kerberos.KerberosAgent") 99 100OSStatus KRBCopyKeychainLookupInfo (KRBHelperContextRef inKerberosSession, CFStringRef inUsername, CFDictionaryRef *outKeychainLookupInfo); 101 102/* 103 KRBCopyServicePrincipal will return the service principal for the inServiceName on the host associated with inKerberosSession 104 inKerberosSession is the pointer returned by KRBCreateSession 105 inServiceName is the name of the service on the host, it can be NULL if inAdvertisedPrincipal was non-NULL. 106 However it is highly recommended that this be set as it is insecure to rely on remotely provided information 107 outServicePrincipal the service principal 108 */ 109 110OSStatus KRBCopyServicePrincipal (KRBHelperContextRef inKerberosSession, CFStringRef inServiceName, CFStringRef *outServicePrincipal); 111 112 113/* 114 KRBCopyServicePrincipalInfo will return the service principal and optional a key that canolization shouldn't be done for the inServiceName on the host associated with inKerberosSession 115 inKerberosSession is the pointer returned by KRBCreateSession 116 inServiceName is the name of the service on the host, it can be NULL if inAdvertisedPrincipal was non-NULL. 117 However it is highly recommended that this be set as it is insecure to rely on remotely provided information 118 outServiceInfo a dictionary contain the key kKRBServicePrincipal and optionally kKRBNoCanon, both are strings. 119 */ 120 121#define kKRBServicePrincipalKey CFSTR("KRBServicePrincipal") 122#define kKRBNoCanonKey CFSTR("KRBNoCanon") 123 124OSStatus KRBCopyServicePrincipalInfo (KRBHelperContextRef inKerberosSession, CFStringRef inServiceName, CFDictionaryRef *outServiceInfo); 125 126 127/* 128 KRBCopyClientPrincipalInfo will return a dictionary with the user principal and other information. 129 inKerberosSession is the pointer returned by KRBCreateSession. 130 inOptions a dictionary with options regarding the acquisition of the user principal. 131 inIdentityRef is a reference to list of usable identities 132 outClientPrincipalInfo a dictionary containing the user principal and other information necessary to get a ticket. 133 134 inOptions Dictionary Keys 135 kKRBAllowKerberosUIKey : CFStringRef [See AllowKeberosUI values] 136 kKRBServerDisplayNameKey : CFStringRef 137 kKRBUsernameKey : CFStringRef 138 kKRBClientPasswordKey : CFStringRef 139 kKRBCertificateKey : SecCertificateRef 140 outClientPrincipalInfo 141 kKRBClientPrincipalKey : CFStringRef 142 kKRBUsernameKey : CFStringRef 143 kKRBCertificateHashKey : CFStringRef 144 kKRBCertificateInferredLabelKey : CFStringRef 145 and private information 146*/ 147#define kKRBUsernameKey CFSTR("Username") 148#define kKRBClientPasswordKey CFSTR("Password") 149#define kKRBCertificateKey CFSTR("Certificate") 150#define kKRBCertificateHashKey CFSTR("CetificateHash") 151#define kKRBUsingCertificateKey CFSTR("UsingCertificate") 152#define kKRBCertificateInferredLabelKey CFSTR("CertificateInferredLabel") 153#define kKRBAllowKerberosUI CFSTR("AllowKerberosUI") 154#define kKRBServerDisplayNameKey CFSTR("ServerDisplayName") 155#define kKRBClientPrincipalKey CFSTR("ClientPrincipal") 156#define kKRBAllowKerberosUIKey CFSTR("AllowKerberosUI"); 157 158/* AllowKeberosUI values */ 159#define kKRBOptionNoUI CFSTR("NoUI") 160#define kKRBOptionAllowUI CFSTR("AllowUI") 161#define kKRBOptionForceUI CFSTR("ForceUI") 162 163OSStatus KRBCopyClientPrincipalInfo (KRBHelperContextRef inKerberosSession, CFDictionaryRef inOptions, CFDictionaryRef *outClientPrincipalInfo); 164 165 166/* 167 KRBTestForExistingTicket will look for an existing ticket in the 168 ccache. This call looks for a principal that matches the principal 169 stored in the outClientPrincipalInfo dictionary fom the 170 KRBCopyClientPrincipalInfo call. 171 This call should be performed before prompting the user to enter credential 172 information. 173 inKerberosSession is the pointer returned by KRBCreateSession 174 inClientPrincipalInfo the dictionary containing the 175 kKRBClientPrincipalKey. 176*/ 177OSStatus KRBTestForExistingTicket (KRBHelperContextRef inKerberosSession, CFDictionaryRef inClientPrincipalInfo); 178 179 180/* 181 KRBAcquireTicket will acquire a ticket for the user. 182 inKerberosSession is the pointer returned by KRBCreateSession. 183 inClientPrincipalInfo is the outClientPrincipalInfo dictionary from KRBCopyClientPrincipalInfo. 184*/ 185OSStatus KRBAcquireTicket(KRBHelperContextRef inKerberosSession, CFDictionaryRef inClientPrincipalInfo); 186 187 188/* 189 KRBCloseSession will release the kerberos session 190 inKerberosSession is the pointer returned by KRBCreateSession. 191*/ 192OSStatus KRBCloseSession (KRBHelperContextRef inKerberosSession); 193 194 /* compat backward */ 195 196#define kKRBServicePrincipal CFSTR("KRBServicePrincipal") 197#define kKRBNoCanon CFSTR("KRBNoCanon") 198#define kKRBHostname CFSTR("Hostname") 199#define kKRBAdvertisedPrincipal CFSTR("AdvertisedPrincipal") 200#define kKRBNoLKDC CFSTR("NoLKDC") 201#define kKRBKeychainAccountName CFSTR("KeychainAccountName") 202 203 204/* 205 Mark up the credential for user `clientprincipal' as used by 206 `identitier'. If the caller acquired ticket, pass in ticketAcquired 207 set to non-zero. 208 209 For every identitier added to the clientprincipal, it should be 210 removed once by KRBCredAddReferenceAndLabel(). 211 212 The identitier is something that the caller can construct on 213 KRBCredFindByLabelAndRelease time, and probably the identitier looks like 214 this: 215 216 vnc:hostname 217 fs:/Volume/mountpoint 218 (not not afp: since the unmounter probably doesn't know its afp) 219 220 */ 221 222OSStatus KRBCredAddReferenceAndLabel(CFStringRef clientPrincipal, 223 CFStringRef identifier); 224 225/* 226 * Remove mark on the credential for 'identifier', and if its not a 227 * sso credential, remove the related kerberos credential cache when 228 * this was the last reference count.q 229 */ 230 231OSStatus KRBCredFindByLabelAndRelease(CFStringRef identifier); 232 233OSStatus KRBCredAddReference(CFStringRef clientPrincipal); 234OSStatus KRBCredRemoveReference(CFStringRef clientPrincipal); 235 236 237#define kSPNEGONegTokenInitMechs CFSTR("SPNEGONegTokenInitMechs") 238#define kSPNEGONegTokenInitHintsHostname CFSTR("SPNEGONegTokenInitHintsHostname") 239#define KSPNEGOSupportsLKDC CFSTR("SPNEGOServerSupportsLKDC") 240 241/* 242 * These are the maching the Name version kGSSAPIMech<name> 243 */ 244 245#define kGSSAPIMechNTLMOID CFSTR("1.3.6.1.4.1.311.2.2.10") 246#define kGSSAPIMechKerberosOID CFSTR("1.2.840.113554.1.2.2") 247#define kGSSAPIMechKerberosU2UOID CFSTR("1.2.840.113554.1.2.2.3") 248#define kGSSAPIMechKerberosMicrosoftOID CFSTR("1.2.840.48018.1.2.2") 249#define kGSSAPIMechIAKERB CFSTR("1.3.6.1.5.2.5") 250#define kGSSAPIMechPKU2UOID CFSTR("1.3.6.1.5.2.7") 251 252CFDictionaryRef 253KRBDecodeNegTokenInit(CFAllocatorRef, CFDataRef) 254 CF_RETURNS_RETAINED; 255 256CFDictionaryRef 257KRBCreateNegTokenLegacyKerberos(CFAllocatorRef); 258 259CFDictionaryRef 260KRBCreateNegTokenLegacyNTLM(CFAllocatorRef); 261 262#ifdef __cplusplus 263} 264#endif 265 266#endif /* _KERBEROSHELPER_H_ */ 267