1/* 2 * Copyright (c) 2006,2011-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// blob - generic extensible binary blob frame 26// 27// To define a new type of binary blob: 28// class MyBlob : public Blob<MyBlob, magic number> { ... } 29// Pick a unique magic number (32-bit). Blobs are understood to be a MyBlob 30// header possibly followed by more data as a contiguous memory area. Length 31// is overall (including the header), so a fixed-size blob would have length 32// sizeof(MyBlob). Both length and magic are stored in NBO. 33// 34// You are highly encouraged to follow these rules: 35// Store all integers in NBO, including offsets. 36// Use internal offsets to "point to" dynamically-sized elements past the 37// header (using the at<Type>(offset) method for access). 38// Don't use pointers in your blob. 39// If you follow those rules, your blobs will be fully relocatable, byte-order 40// independent, and generally spreading happiness around your code. 41// 42#ifndef _H_BLOB 43#define _H_BLOB 44 45#include <security_utilities/endian.h> 46#include <security_utilities/memutils.h> 47#include <security_utilities/errors.h> 48 49namespace Security { 50 51 52// 53// All blobs in memory have this form. 54// You can have polymorphic memory blobs (C style) using different magics numbers. 55// 56class BlobCore { 57public: 58 typedef uint32_t Offset; 59 typedef uint32_t Magic; 60 61 Magic magic() const { return mMagic; } 62 size_t length() const { return mLength; } 63 64 void initialize(Magic magic, size_t length = 0) 65 { mMagic = magic; mLength = (uint32_t)length; } 66 67 bool validateBlob(Magic magic, size_t minSize = 0, size_t maxSize = 0) const; 68 69 template <class T, class Offset> 70 T *at(Offset offset) 71 { return LowLevelMemoryUtilities::increment<T>(this, offset); } 72 73 template <class T, class Offset> 74 const T *at(Offset offset) const 75 { return LowLevelMemoryUtilities::increment<const T>(this, offset); } 76 77 template <class Offset1, class Offset2> 78 bool contains(Offset1 offset, Offset2 size) const 79 { return offset >= 0 && size_t(offset) >= sizeof(BlobCore) && (size_t(offset) + size) <= this->length(); } 80 81 template <class Base, class Offset> 82 bool contains(Base *ptr, Offset size) const 83 { return contains(LowLevelMemoryUtilities::difference(ptr, this), size); } 84 85 char *stringAt(Offset offset); 86 const char *stringAt(Offset offset) const; 87 88 void *data() { return this; } 89 const void *data() const { return this; } 90 void length(size_t size) { mLength = (uint32_t)size; } 91 92 BlobCore *clone() const 93 { 94 if (BlobCore *copy = (BlobCore *)malloc(this->length())) { 95 memcpy(copy, this, this->length()); 96 return copy; 97 } 98 UnixError::throwMe(ENOMEM); 99 } 100 101 template <class BlobType> 102 bool is() const { return magic() == BlobType::typeMagic; } 103 104 static BlobCore *readBlob(std::FILE *file) { return readBlob(file, 0, 0, 0); } 105 static BlobCore *readBlob(int fd) { return readBlob(fd, 0, 0, 0); } 106 107protected: 108 static BlobCore *readBlob(std::FILE *file, uint32_t magic, size_t minSize, size_t maxSize); // streaming 109 static BlobCore *readBlob(int fd, uint32_t magic, size_t minSize, size_t maxSize); // streaming 110 static BlobCore *readBlob(int fd, size_t offset, uint32_t magic, size_t minSize, size_t maxSize); // pread(2)@offset 111 112protected: 113 Endian<uint32_t> mMagic; 114 Endian<uint32_t> mLength; 115}; 116 117 118// basic validation helper 119inline bool BlobCore::validateBlob(Magic magic, size_t minSize /* = 0 */, size_t maxSize /* = 0 */) const 120{ 121 uint32_t length = this->mLength; 122 if (magic && magic != this->mMagic) { 123 errno = EINVAL; 124 return false; 125 } 126 if (minSize ? (length < minSize) : (length < sizeof(BlobCore))) { 127 errno = EINVAL; 128 return false; 129 } 130 if (maxSize && length > maxSize) { 131 errno = ENOMEM; 132 return false; 133 } 134 return true; 135} 136 137 138// 139// Typed Blobs (BlobCores that know their real type and magic) 140// 141template <class BlobType, uint32_t _magic> 142class Blob: public BlobCore { 143public: 144 void initialize(size_t size = 0) { BlobCore::initialize(_magic, size); } 145 146 static const Magic typeMagic = _magic; 147 148 bool validateBlob() const 149 { return BlobCore::validateBlob(_magic, sizeof(BlobType)); } 150 151 bool validateBlob(size_t extLength) const 152 { return extLength >= sizeof(BlobType) && validateBlob() && mLength == extLength; } 153 154 static BlobType *specific(BlobCore *blob, bool unalloc = false) 155 { 156 if (BlobType *p = static_cast<BlobType *>(blob)) { 157 if (p->validateBlob()) 158 return p; 159 if (unalloc) 160 ::free(p); 161 } 162 return NULL; 163 } 164 165 static const BlobType *specific(const BlobCore *blob) 166 { 167 const BlobType *p = static_cast<const BlobType *>(blob); 168 if (p && p->validateBlob()) 169 return p; 170 return NULL; 171 } 172 173 BlobType *clone() const 174 { assert(validateBlob()); return specific(this->BlobCore::clone()); } 175 176 static BlobType *readBlob(int fd) 177 { return specific(BlobCore::readBlob(fd, _magic, sizeof(BlobType), 0), true); } 178 179 static BlobType *readBlob(int fd, size_t offset, size_t maxSize = 0) 180 { return specific(BlobCore::readBlob(fd, offset, _magic, sizeof(BlobType), maxSize), true); } 181 182 static BlobType *readBlob(std::FILE *file) 183 { return specific(BlobCore::readBlob(file, _magic, sizeof(BlobType), 0), true); } 184}; 185 186 187// 188// A generic blob wrapped around arbitrary (flat) binary data. 189// This can be used to "regularize" plain binary data, so it can be handled 190// as a genuine Blob (e.g. for insertion into a SuperBlob). 191// 192class BlobWrapper : public Blob<BlobWrapper, 0xfade0b01> { 193public: 194 static BlobWrapper *alloc(size_t length, Magic magic = BlobWrapper::typeMagic); 195 static BlobWrapper *alloc(const void *data, size_t length, Magic magic = BlobWrapper::typeMagic); 196 197 unsigned char dataArea[0]; 198 199 // override data/length to point to the payload (only) 200 void *data() { return dataArea; } 201 const void *data() const { return dataArea; } 202 size_t length() const { return BlobCore::length() - sizeof(BlobCore); } 203}; 204 205 206} // Security 207 208#endif //_H_BLOB 209