keychain/trust/TrustedPeers/TPVoucher.h

   1 /*
   2  * Copyright (c) 2017 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 #import <Foundation/Foundation.h>
  25
  26 #import "TPSigningKey.h"
  27 #import "TPTypes.h"
  28
  29 NS_ASSUME_NONNULL_BEGIN
  30
  31 /*!
  32  A voucher is a record signed by a "sponsor" peer to say that
  33  a "beneficiary" peer is trusted.
  34
  35  The signature is not checked when an TPVoucher instance is
  36  constructed, because the sponsor's signing key might not be
  37  available at that time.
  38
  39  This class is a value type -- its members are immutable and
  40  instances with identical contents are interchangeable.
  41  It overrides isEqual and hash, so that two instances with
  42  identical contents will compare as equal.
  43  */
  44 @interface TPVoucher : NSObject
  45
  46 /*!
  47  Can return nil with error if [trustSigningKey signatureForData:error:] errors.
  48  */
  49 + (nullable instancetype)voucherWithBeneficiaryID:(NSString *)beneficiaryID
  50                                         sponsorID:(NSString *)sponsorID
  51                                             clock:(TPCounter)clock
  52                                   trustSigningKey:(id<TPSigningKey>)trustSigningKey
  53                                             error:(NSError **)error;
  54
  55 // Returns nil if data cannot be deserialized to a dictionary
  56 // or that dictionary does not contain the expected keys and value types.
  57 // This method performs no signature checking; that should be done later,
  58 // when the sponsor's trustSigningKey is available.
  59 + (nullable instancetype)voucherWithPList:(NSData *)voucherInfoPList
  60                                       sig:(NSData *)voucherInfoSig;
  61
  62 - (BOOL)isEqualToVoucher:(TPVoucher *)other;
  63
  64 @property (nonatomic, readonly) NSString *beneficiaryID;
  65 @property (nonatomic, readonly) NSString *sponsorID;
  66 @property (nonatomic, readonly) TPCounter clock;
  67 @property (nonatomic, readonly) NSData *voucherInfoPList;
  68 @property (nonatomic, readonly) NSData *voucherInfoSig;
  69
  70 @end
  71
  72 NS_ASSUME_NONNULL_END