keychain/SecSharedCredential.h

   1 /*
   2  * Copyright (c) 2014-2016 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 SecSharedCredential
  26  SecSharedCredential defines CoreFoundation-based functions for
  27  storing and requesting shared password-based credentials.
  28  These credentials are currently able to be shared with Safari and
  29  applications which have a 'com.apple.developer.associated-domains'
  30  entitlement that includes the domain being requested.
  31  */
  32
  33 #ifndef _SECURITY_SECSHAREDCREDENTIAL_H_
  34 #define _SECURITY_SECSHAREDCREDENTIAL_H_
  35
  36 #include <Security/SecItem.h>
  37 #include <CoreFoundation/CoreFoundation.h>
  38 #include <AvailabilityMacros.h>
  39
  40 __BEGIN_DECLS
  41
  42 CF_ASSUME_NONNULL_BEGIN
  43 CF_IMPLICIT_BRIDGING_ENABLED
  44
  45 #ifdef __BLOCKS__
  46
  47 /*!
  48     @enum Credential Key Constants
  49     @discussion Predefined key constants used to get values in a dictionary
  50         of credentials returned by SecRequestWebCredential.
  51     @constant kSecSharedPassword Specifies a dictionary key whose value is a
  52         shared password. You use this key to get a value of type CFStringRef
  53         that contains a password.
  54 */
  55 extern const CFStringRef kSecSharedPassword API_AVAILABLE(ios(8.0)) API_UNAVAILABLE(macos, iosmac, tvos, watchos);
  56
  57 /*!
  58  @function SecAddSharedWebCredential
  59  @abstract Asynchronously store (or update) a shared password for a website.
  60  @param fqdn The fully qualified domain name of the website requiring the password.
  61  @param account The account name associated with this password.
  62  @param password The password to be stored. Pass NULL to remove a shared password if it exists.
  63  @param completionHandler A block which will be invoked when the function has completed. If the shared password was successfully added (or removed), the CFErrorRef parameter passed to the block will be NULL. If the error parameter is non-NULL, an error occurred and the error reference will hold the result. Note: the error reference will be automatically released after this handler is called, though you may optionally retain it for as long as needed.
  64  @discussion This function adds a shared password item which will be accessible by Safari and applications that have the specified fully-qualified domain name in their 'com.apple.developer.associated-domains' entitlement. If a shared password item already exists for the specified website and account, it will be updated with the provided password. To remove a password, pass NULL for the password parameter.
  65
  66  Note: since a request involving shared web credentials may potentially require user interaction or other verification to be approved, this function is dispatched asynchronously; your code provides a completion handler that will be called once the results (if any) are available.
  67  */
  68 void SecAddSharedWebCredential(CFStringRef fqdn, CFStringRef account, CFStringRef __nullable password,
  69     void (^completionHandler)(CFErrorRef __nullable error)) API_AVAILABLE(ios(8.0)) API_UNAVAILABLE(macos, iosmac, tvos, watchos);
  70
  71 /*!
  72  @function SecRequestSharedWebCredential
  73  @abstract Asynchronously obtain one or more shared passwords for a website.
  74  @param fqdn (Optional) Fully qualified domain name of the website for which passwords are being requested. If NULL is passed in this argument, the domain name(s) listed in the calling application's 'com.apple.developer.associated-domains' entitlement are searched implicitly.
  75  @param account (Optional) Account name for which passwords are being requested. The account may be NULL to request all shared credentials which are available for the site, allowing the caller to discover an existing account.
  76  @param completionHandler A block which will be called to deliver the requested credentials. If no matching items were found, the credentials array will be empty, and the CFErrorRef parameter will provide the error result. Note: the credentials and error references will be automatically released after this handler is called, though you may optionally retain either for as long as needed.
  77  @discussion This function requests one or more shared passwords for a given website, depending on whether the optional account parameter is supplied. To obtain results, the website specified in the fqdn parameter must be one which matches an entry in the calling application's 'com.apple.developer.associated-domains' entitlement.
  78
  79  If matching shared password items are found, the credentials provided to the completionHandler will be a CFArrayRef containing CFDictionaryRef entries. Each dictionary entry will contain the following pairs (see Security/SecItem.h):
  80         key: kSecAttrServer     value: CFStringRef (the website)
  81         key: kSecAttrAccount    value: CFStringRef (the account)
  82         key: kSecSharedPassword value: CFStringRef (the password)
  83
  84  If the found item specifies a non-standard port number (i.e. other than 443 for https), the following key may also be present:
  85         key: kSecAttrPort       value: CFNumberRef (the port number)
  86
  87  Note: since a request involving shared web credentials may potentially require user interaction or other verification to be approved, this function is dispatched asynchronously; your code provides a completion handler that will be called once the results (if any) are available.
  88  */
  89 void SecRequestSharedWebCredential(CFStringRef __nullable fqdn, CFStringRef __nullable account,
  90     void (^completionHandler)(CFArrayRef __nullable credentials, CFErrorRef __nullable error)) API_AVAILABLE(ios(8.0)) API_UNAVAILABLE(macos, iosmac, tvos, watchos);
  91
  92 /*!
  93  @function SecCreateSharedWebCredentialPassword
  94  @abstract Returns a randomly generated password.
  95  @return CFStringRef password in the form xxx-xxx-xxx-xxx where x is taken from the sets "abcdefghkmnopqrstuvwxy", "ABCDEFGHJKLMNPQRSTUVWXYZ", "3456789" with at least one character from each set being present.
  96 */
  97 __nullable
  98 CFStringRef SecCreateSharedWebCredentialPassword(void) API_AVAILABLE(ios(8.0)) API_UNAVAILABLE(macos, iosmac, tvos, watchos);
  99
 100
 101 #endif /* __BLOCKS__ */
 102
 103 CF_IMPLICIT_BRIDGING_DISABLED
 104 CF_ASSUME_NONNULL_END
 105
 106 __END_DECLS
 107
 108 #endif /* !_SECURITY_SECSHAREDCREDENTIAL_H_ */
 109