[apple/security.git] / OSX / sec / securityd / SecRevocationDb.h

/*
 * Copyright (c) 2016-2018 Apple Inc. All Rights Reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_LICENSE_HEADER_END@
 *
 */

/*!
 @header SecRevocationDb
 The functions in SecRevocationDb.h provide an interface to look up
 revocation information, and refresh that information periodically.
 */

#ifndef _SECURITY_SECREVOCATIONDB_H_
#define _SECURITY_SECREVOCATIONDB_H_

#include <CoreFoundation/CFData.h>
#include <CoreFoundation/CFDate.h>
#include <CoreFoundation/CFDictionary.h>
#include <CoreFoundation/CFString.h>
#include <dispatch/dispatch.h>
#include <Security/SecBase.h>

__BEGIN_DECLS

/* issuer group data format */
typedef CF_ENUM(uint32_t, SecValidInfoFormat) {
    kSecValidInfoFormatUnknown      = 0,
    kSecValidInfoFormatSerial       = 1,
    kSecValidInfoFormatSHA256       = 2,
    kSecValidInfoFormatNto1         = 3
};

/*!
    @typedef SecValidInfoRef
    @abstract Object used to return valid info lookup results.
 */
typedef struct __SecValidInfo *SecValidInfoRef;

struct __SecValidInfo {
    SecValidInfoFormat  format;               // format of per-issuer validity data
    CFDataRef           certHash;             // SHA-256 hash of cert to which the following info applies
    CFDataRef           issuerHash;           // SHA-256 hash of issuing CA certificate
    CFDataRef           anchorHash;           // SHA-256 hash of anchor certificate (optional)
    bool                isOnList;             // true if this cert was found on allow list or block list
    bool                valid;                // true if this is an allow list, false if a block list
    bool                complete;             // true if list is complete (i.e. status is definitive)
    bool                checkOCSP;            // true if complete is false and OCSP check is required
    bool                knownOnly;            // true if all intermediates under issuer must be found in database
    bool                requireCT;            // true if this cert must have CT proof
    bool                noCACheck;            // true if an entry does not require an OCSP check to accept
    bool                overridable;          // true if the trust status is recoverable and can be overridden
    bool                hasDateConstraints;   // true if this issuer has supplemental date constraints
    bool                hasNameConstraints;   // true if this issuer has supplemental name constraints
    bool                hasPolicyConstraints; // true if this issuer has policy constraints
    CFDateRef           notBeforeDate;        // minimum notBefore for this certificate (if hasDateConstraints is true)
    CFDateRef           notAfterDate;         // maximum notAfter for this certificate (if hasDateConstraints is true)
    CFDataRef           nameConstraints;      // name constraints blob (if hasNameConstraints is true)
    CFDataRef           policyConstraints;    // policy constraints blob (if policyConstraints is true)
};

/*!
	@function SecValidInfoRelease
	@abstract Releases a SecValidInfo reference previously obtained from a call to SecRevocationDbCopyMatching.
	@param validInfo The SecValidInfo reference to be released.
 */
void SecValidInfoRelease(SecValidInfoRef validInfo);

/*!
	@function SecValidInfoSetAnchor
	@abstract Updates a SecValidInfo reference with info about the anchor certificate in a chain.
	@param validInfo The SecValidInfo reference to be updated.
	@param anchor The certificate which anchors the chain for the certificate in this SecValidInfo reference.
	@discussion A SecValidInfo reference contains information about a single certificate and its issuer. In some cases, it may be necessary to additionally examine the anchor of the certificate chain to determine validity.
 */
void SecValidInfoSetAnchor(SecValidInfoRef validInfo, SecCertificateRef anchor);

/*!
	@function SecRevocationDbCheckNextUpdate
	@abstract Periodic hook to poll for updates.
 */
void SecRevocationDbCheckNextUpdate(void);

/*!
	@function SecRevocationDbCopyMatching
	@abstract Returns a SecValidInfo reference if matching revocation (or allow list) info was found.
	@param certificate The certificate whose validity status is being requested.
	@param issuer The issuing CA certificate. If the cert is self-signed, the same reference should be passed in both certificate and issuer parameters. Omitting either cert parameter is an error and NULL will be returned.
	@result A SecValidInfoRef if there was matching revocation info. Caller must release this reference when finished by calling SecValidInfoRelease. NULL is returned if no matching info was found in the database.
 */
SecValidInfoRef SecRevocationDbCopyMatching(SecCertificateRef certificate,
                                            SecCertificateRef issuer);

/*!
	@function SecRevocationDbGetVersion
	@abstract Returns a CFIndex containing the version number of the database.
	@result On success, the returned version will be a value greater than or equal to zero. A version of 0 indicates an empty database which has yet to be populated. If the version cannot be obtained, -1 is returned.
 */
CFIndex SecRevocationDbGetVersion(void);

/*!
	@function SecRevocationDbGetSchemaVersion
	@abstract Returns a CFIndex containing the schema version number of the database.
	@result On success, the returned version will be a value greater than or equal to zero. A version of 0 indicates an empty database which has yet to be populated. If the version cannot be obtained, -1 is returned.
 */
CFIndex SecRevocationDbGetSchemaVersion(void);

/*!
 @function SecValidUpdateVerifyAndIngest
 @abstract Callback for receiving update data.
 @param updateData The decompressed update data.
 @param updateServer The source server for this data.
 @param fullUpdate If true, a full update was requested.
 */
void SecValidUpdateVerifyAndIngest(CFDataRef updateData, CFStringRef updateServer, bool fullUpdate);

/*!
 @function readValidFile
 @abstract Reads data into a CFDataRef using mmap.
 @param fileName The file to read.
 @param bytes The data read from the file.
 @result An integer indicating failure (non-zero) or success.
 @discussion This function mmaps the file and then makes a no-copy CFData for use of that mmapped file.  This data MUST be munmapped when the caller has finished with the data.
 */
int readValidFile(const char *fileName, CFDataRef  *bytes);

/*!
 @function SecRevocationDbComputeAndSetNextUpdateTime
 @abstract Callback to push forward next update.
 */
void SecRevocationDbComputeAndSetNextUpdateTime(void);

/*!
 @function SecRevocationDbInitialize
 @abstract Initializes revocation database if it doesn't exist or needs to be replaced. This should only be called once at process startup, before any database connections are established.
 */
void SecRevocationDbInitialize(void);


__END_DECLS

#endif /* _SECURITY_SECREVOCATIONDB_H_ */
Commit	Line	Data
6b200bc3	1	/*
ecaf5866	2	* Copyright (c) 2016-2018 Apple Inc. All Rights Reserved.
6b200bc3 A	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	/*!
	26	@header SecRevocationDb
	27	The functions in SecRevocationDb.h provide an interface to look up
	28	revocation information, and refresh that information periodically.
	29	*/
	30
	31	#ifndef _SECURITY_SECREVOCATIONDB_H_
	32	#define _SECURITY_SECREVOCATIONDB_H_
	33
	34	#include <CoreFoundation/CFData.h>
	35	#include <CoreFoundation/CFDate.h>
	36	#include <CoreFoundation/CFDictionary.h>
	37	#include <CoreFoundation/CFString.h>
	38	#include <dispatch/dispatch.h>
	39	#include <Security/SecBase.h>
	40
	41	__BEGIN_DECLS
	42
	43	/* issuer group data format */
	44	typedef CF_ENUM(uint32_t, SecValidInfoFormat) {
	45	kSecValidInfoFormatUnknown = 0,
	46	kSecValidInfoFormatSerial = 1,
	47	kSecValidInfoFormatSHA256 = 2,
	48	kSecValidInfoFormatNto1 = 3
	49	};
	50
	51	/*!
	52	@typedef SecValidInfoRef
	53	@abstract Object used to return valid info lookup results.
	54	*/
	55	typedef struct __SecValidInfo *SecValidInfoRef;
	56
	57	struct __SecValidInfo {
ecaf5866 A	58	SecValidInfoFormat format; // format of per-issuer validity data
	59	CFDataRef certHash; // SHA-256 hash of cert to which the following info applies
	60	CFDataRef issuerHash; // SHA-256 hash of issuing CA certificate
	61	CFDataRef anchorHash; // SHA-256 hash of anchor certificate (optional)
	62	bool isOnList; // true if this cert was found on allow list or block list
	63	bool valid; // true if this is an allow list, false if a block list
	64	bool complete; // true if list is complete (i.e. status is definitive)
	65	bool checkOCSP; // true if complete is false and OCSP check is required
	66	bool knownOnly; // true if all intermediates under issuer must be found in database
	67	bool requireCT; // true if this cert must have CT proof
	68	bool noCACheck; // true if an entry does not require an OCSP check to accept
	69	bool overridable; // true if the trust status is recoverable and can be overridden
	70	bool hasDateConstraints; // true if this issuer has supplemental date constraints
	71	bool hasNameConstraints; // true if this issuer has supplemental name constraints
	72	bool hasPolicyConstraints; // true if this issuer has policy constraints
	73	CFDateRef notBeforeDate; // minimum notBefore for this certificate (if hasDateConstraints is true)
	74	CFDateRef notAfterDate; // maximum notAfter for this certificate (if hasDateConstraints is true)
	75	CFDataRef nameConstraints; // name constraints blob (if hasNameConstraints is true)
	76	CFDataRef policyConstraints; // policy constraints blob (if policyConstraints is true)
6b200bc3 A	77	};
	78
	79	/*!
	80	@function SecValidInfoRelease
	81	@abstract Releases a SecValidInfo reference previously obtained from a call to SecRevocationDbCopyMatching.
	82	@param validInfo The SecValidInfo reference to be released.
	83	*/
	84	void SecValidInfoRelease(SecValidInfoRef validInfo);
	85
866f8763 A	86	/*!
	87	@function SecValidInfoSetAnchor
	88	@abstract Updates a SecValidInfo reference with info about the anchor certificate in a chain.
	89	@param validInfo The SecValidInfo reference to be updated.
	90	@param anchor The certificate which anchors the chain for the certificate in this SecValidInfo reference.
	91	@discussion A SecValidInfo reference contains information about a single certificate and its issuer. In some cases, it may be necessary to additionally examine the anchor of the certificate chain to determine validity.
	92	*/
	93	void SecValidInfoSetAnchor(SecValidInfoRef validInfo, SecCertificateRef anchor);
	94
6b200bc3 A	95	/*!
	96	@function SecRevocationDbCheckNextUpdate
	97	@abstract Periodic hook to poll for updates.
6b200bc3	98	*/
866f8763	99	void SecRevocationDbCheckNextUpdate(void);
6b200bc3 A	100
	101	/*!
	102	@function SecRevocationDbCopyMatching
	103	@abstract Returns a SecValidInfo reference if matching revocation (or allow list) info was found.
	104	@param certificate The certificate whose validity status is being requested.
	105	@param issuer The issuing CA certificate. If the cert is self-signed, the same reference should be passed in both certificate and issuer parameters. Omitting either cert parameter is an error and NULL will be returned.
	106	@result A SecValidInfoRef if there was matching revocation info. Caller must release this reference when finished by calling SecValidInfoRelease. NULL is returned if no matching info was found in the database.
	107	*/
	108	SecValidInfoRef SecRevocationDbCopyMatching(SecCertificateRef certificate,
	109	SecCertificateRef issuer);
	110
	111	/*!
	112	@function SecRevocationDbGetVersion
	113	@abstract Returns a CFIndex containing the version number of the database.
	114	@result On success, the returned version will be a value greater than or equal to zero. A version of 0 indicates an empty database which has yet to be populated. If the version cannot be obtained, -1 is returned.
	115	*/
	116	CFIndex SecRevocationDbGetVersion(void);
	117
	118	/*!
	119	@function SecRevocationDbGetSchemaVersion
	120	@abstract Returns a CFIndex containing the schema version number of the database.
	121	@result On success, the returned version will be a value greater than or equal to zero. A version of 0 indicates an empty database which has yet to be populated. If the version cannot be obtained, -1 is returned.
	122	*/
	123	CFIndex SecRevocationDbGetSchemaVersion(void);
	124
866f8763 A	125	/*!
	126	@function SecValidUpdateVerifyAndIngest
	127	@abstract Callback for receiving update data.
	128	@param updateData The decompressed update data.
29734401 A	129	@param updateServer The source server for this data.
29734401 A	130	@param fullUpdate If true, a full update was requested.
866f8763	131	*/
29734401	132	void SecValidUpdateVerifyAndIngest(CFDataRef updateData, CFStringRef updateServer, bool fullUpdate);
866f8763 A	133
	134	/*!
	135	@function readValidFile
	136	@abstract Reads data into a CFDataRef using mmap.
	137	@param fileName The file to read.
	138	@param bytes The data read from the file.
	139	@result An integer indicating failure (non-zero) or success.
	140	@discussion This function mmaps the file and then makes a no-copy CFData for use of that mmapped file. This data MUST be munmapped when the caller has finished with the data.
	141	*/
	142	int readValidFile(const char fileName, CFDataRef bytes);
	143
	144	/*!
	145	@function SecRevocationDbComputeAndSetNextUpdateTime
	146	@abstract Callback to push forward next update.
	147	*/
	148	void SecRevocationDbComputeAndSetNextUpdateTime(void);
	149
	150	/*!
	151	@function SecRevocationDbInitialize
	152	@abstract Initializes revocation database if it doesn't exist or needs to be replaced. This should only be called once at process startup, before any database connections are established.
	153	*/
	154	void SecRevocationDbInitialize(void);
	155
6b200bc3 A	156
	157	__END_DECLS
	158
	159	#endif /* _SECURITY_SECREVOCATIONDB_H_ */