1/*
2 * Copyright (c) 2014 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#ifdef __BLOCKS__
43
44/*!
45    @enum Credential Key Constants
46    @discussion Predefined key constants used to get values in a dictionary
47        of credentials returned by SecRequestWebCredential.
48    @constant kSecSharedPassword Specifies a dictionary key whose value is a
49        shared password. You use this key to get a value of type CFStringRef
50        that contains a password.
51*/
52extern CFTypeRef kSecSharedPassword
53    __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_8_0);
54
55/*!
56 @function SecAddSharedWebCredential
57 @abstract Asynchronously store (or update) a shared password for a website.
58 @param fqdn The fully qualified domain name of the website requiring the password.
59 @param account The account name associated with this password.
60 @param password The password to be stored. Pass NULL to remove a shared password if it exists.
61 @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.
62 @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.
63
64 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.
65 */
66void SecAddSharedWebCredential(CFStringRef fqdn, CFStringRef account, CFStringRef password,
67    void (^completionHandler)(CFErrorRef error))
68    __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_8_0);
69
70/*!
71 @function SecRequestSharedWebCredential
72 @abstract Asynchronously obtain one or more shared passwords for a website.
73 @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.
74 @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.
75 @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.
76 @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.
77
78 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):
79        key: kSecAttrServer     value: CFStringRef (the website)
80        key: kSecAttrAccount    value: CFStringRef (the account)
81        key: kSecSharedPassword value: CFStringRef (the password)
82
83 If the found item specifies a non-standard port number (i.e. other than 443 for https), the following key may also be present:
84        key: kSecAttrPort       value: CFNumberRef (the port number)
85
86 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.
87 */
88void SecRequestSharedWebCredential(CFStringRef fqdn, CFStringRef account,
89    void (^completionHandler)(CFArrayRef credentials, CFErrorRef error))
90    __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_8_0);
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
98CFStringRef SecCreateSharedWebCredentialPassword(void)
99__OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_8_0);
100
101
102#endif /* __BLOCKS__ */
103
104__END_DECLS
105
106#endif /* !_SECURITY_SECSHAREDCREDENTIAL_H_ */
107
108