iPXE
Data Structures | Defines | Functions | Variables
pccrc.h File Reference

Peer Content Caching and Retrieval: Content Identification [MS-PCCRC]. More...

#include <stdint.h>
#include <byteswap.h>
#include <ipxe/uaccess.h>
#include <ipxe/crypto.h>

Go to the source code of this file.

Data Structures

union  peerdist_info_version
 Content Information version number. More...
struct  peerdist_info_v1
 Content Information version 1 data structure header. More...
struct  peerdist_info_v1_segment
 Content Information version 1 segment description header. More...
struct  peerdist_info_v1_block
 Content Information version 1 block description header. More...
struct  peerdist_info_v2
 Content Information version 2 data structure header. More...
struct  peerdist_info_v2_chunk
 Content Information version 2 chunk description header. More...
struct  peerdist_info_v2_segment
 Content Information version 2 segment description header. More...
struct  peerdist_raw
 Raw content information. More...
struct  peerdist_range
 A content range. More...
struct  peerdist_info
 Content information. More...
struct  peerdist_info_segment
 A content information segment. More...
struct  peerdist_info_block
 A content information block. More...
struct  peerdist_info_operations
 Content information operations. More...

Defines

#define PEERDIST_INFO_V1   0x0100
 Content Information version 1.
#define PEERDIST_INFO_V2   0x0200
 Content Information version 2.
#define PEERDIST_INFO_V1_HASH_SHA256   0x0000800cUL
 SHA-256 hash algorithm.
#define PEERDIST_INFO_V1_HASH_SHA384   0x0000800dUL
 SHA-384 hash algorithm.
#define PEERDIST_INFO_V1_HASH_SHA512   0x0000800eUL
 SHA-512 hash algorithm.
#define peerdist_info_v1_segment_t(digestsize)
 Content Information version 1 segment description.
#define peerdist_info_v1_block_t(digestsize, blocks)
 Content Information version 1 block description.
#define PEERDIST_INFO_V2_HASH_SHA512_TRUNC   0x04
 SHA-512 hash algorithm with output truncated to first 256 bits.
#define peerdist_info_v2_chunk_t(digestsize)
 Content Information version 2 chunk description.
#define PEERDIST_INFO_V2_CHUNK_TYPE   0x00
 Chunk type.
#define peerdist_info_v2_segment_t(digestsize)
 Content Information version 2 segment description.
#define PEERDIST_DIGEST_MAX_SIZE   64
 Maximum digest size for any supported algorithm.
#define PEERDIST_SEGMENT_ID_MAGIC   L"MS_P2P_CACHING"
 Magic string constant used to calculate segment identifier.

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
union peerdist_info_version __attribute__ ((packed))
 Major:minor version number.
int peerdist_info (userptr_t data, size_t len, struct peerdist_info *info)
 Populate content information.
int peerdist_info_segment (const struct peerdist_info *info, struct peerdist_info_segment *segment, unsigned int index)
 Populate content information segment.
int peerdist_info_block (const struct peerdist_info_segment *segment, struct peerdist_info_block *block, unsigned int index)
 Populate content information block.

Variables

uint8_t minor
 Minor version number.
uint8_t major
 Major version number.
uint16_t raw
 Raw version number.
union peerdist_info_version version
 Version number.
uint32_t hash
 Hash algorithm.
uint32_t first
 Length to skip in first segment.
uint32_t last
 Length to read in last segment, or zero.
uint32_t segments
 Number of segments within the content information.
uint64_t offset
 Offset of this segment within the content.
uint32_t len
 Length of this segment.
uint32_t blksize
 Block size for this segment.
uint32_t blocks
 Number of blocks within the block description.
uint64_t index
 Index of the first segment within the content.
uint8_t type
 Chunk type.
struct peerdist_raw __attribute__
struct digest_algorithm sha512_trunc_algorithm

Detailed Description

Peer Content Caching and Retrieval: Content Identification [MS-PCCRC].

Definition in file pccrc.h.


Define Documentation

#define PEERDIST_INFO_V1   0x0100

Content Information version 1.

Definition at line 46 of file pccrc.h.

Referenced by peerdist_info(), and peerdist_info_v1().

#define PEERDIST_INFO_V2   0x0200

Content Information version 2.

Definition at line 49 of file pccrc.h.

Referenced by peerdist_info(), and peerdist_info_v2().

#define PEERDIST_INFO_V1_HASH_SHA256   0x0000800cUL

SHA-256 hash algorithm.

Definition at line 97 of file pccrc.h.

Referenced by peerdist_info_v1().

#define PEERDIST_INFO_V1_HASH_SHA384   0x0000800dUL

SHA-384 hash algorithm.

Definition at line 100 of file pccrc.h.

Referenced by peerdist_info_v1().

#define PEERDIST_INFO_V1_HASH_SHA512   0x0000800eUL

SHA-512 hash algorithm.

Definition at line 103 of file pccrc.h.

Referenced by peerdist_info_v1().

Value:
struct {                                                        \
                struct peerdist_info_v1_segment segment;                \
                uint8_t hash[digestsize];                               \
                uint8_t secret[digestsize];                             \
        } __attribute__ (( packed ))

Content Information version 1 segment description.

Parameters:
digestsizeDigest size

Definition at line 146 of file pccrc.h.

Referenced by peerdist_info_v1_block_offset(), and peerdist_info_v1_segment().

Value:
struct {                                                        \
                struct peerdist_info_v1_block block;                    \
                uint8_t hash[blocks][digestsize];                       \
        } __attribute__ (( packed ))

Content Information version 1 block description.

Parameters:
digestsizeDigest size
blocksNumber of blocks

Definition at line 179 of file pccrc.h.

Referenced by peerdist_info_v1_block(), and peerdist_info_v1_block_offset().

SHA-512 hash algorithm with output truncated to first 256 bits.

Definition at line 225 of file pccrc.h.

Referenced by peerdist_info_v2().

Value:
struct {                                                        \
                struct peerdist_info_v2_chunk chunk;                    \
                peerdist_info_v2_segment_t ( digestsize ) segment[0];   \
        } __attribute__ (( packed ))

Content Information version 2 chunk description.

Parameters:
digestsizeDigest size

Definition at line 250 of file pccrc.h.

#define PEERDIST_INFO_V2_CHUNK_TYPE   0x00

Chunk type.

Definition at line 257 of file pccrc.h.

Value:
struct {                                                        \
                struct peerdist_info_v2_segment segment;                \
                uint8_t hash[digestsize];                               \
                uint8_t secret[digestsize];                             \
        } __attribute__ (( packed ))

Content Information version 2 segment description.

Parameters:
digestsizeDigest size

Definition at line 280 of file pccrc.h.

Referenced by peerdist_info_v2_cursor_next(), and peerdist_info_v2_segment().

#define PEERDIST_DIGEST_MAX_SIZE   64

Maximum digest size for any supported algorithm.

The largest digest size that we support is for SHA-512 at 64 bytes

Definition at line 298 of file pccrc.h.

Referenced by peerdist_info_hash_ntoa().

#define PEERDIST_SEGMENT_ID_MAGIC   L"MS_P2P_CACHING"

Magic string constant used to calculate segment identifier.

Note that the MS-PCCRC specification states that this constant is

"the null-terminated ASCII string constant "MS_P2P_CACHING"; string literals are all ASCII strings with NULL terminators unless otherwise noted."

The specification lies. This constant is a UTF-16LE string, not an ASCII string. The terminating wNUL *is* included within the constant.

Definition at line 391 of file pccrc.h.

Referenced by peerdist_info_segment_hash().


Function Documentation

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )
union peerdist_info_version __attribute__ ( (packed)  )

Major:minor version number.

int peerdist_info ( userptr_t  data,
size_t  len,
struct peerdist_info info 
)

Populate content information.

Parameters:
dataRaw data
lenLength of raw data
infoContent information to fill in
Return values:
rcReturn status code

Definition at line 673 of file pccrc.c.

References assert, cpu_to_le16, data, peerdist_raw::data, DBGC, DBGC2, peerdist_range::end, ENOTSUP, peerdist_info_operations::info, len, peerdist_raw::len, peerdist_info_version::major, memset(), peerdist_info_version::minor, NULL, peerdist_info::op, peerdist_info_get(), PEERDIST_INFO_V1, peerdist_info_v1_operations, PEERDIST_INFO_V2, peerdist_info_v2_operations, peerdist_info::range, peerdist_info_version::raw, peerdist_info::raw, rc, peerdist_info::segments, peerdist_range::start, strerror(), and peerdist_info::trim.

                                                                             {
        union peerdist_info_version version;
        int rc;

        /* Initialise structure */
        memset ( info, 0, sizeof ( *info ) );
        info->raw.data = data;
        info->raw.len = len;

        /* Get version */
        if ( ( rc = peerdist_info_get ( info, &version, 0,
                                        sizeof ( version ) ) ) != 0 ) {
                DBGC ( info, "PCCRC %p could not get version: %s\n",
                       info, strerror ( rc ) );
                return rc;
        }
        DBGC2 ( info, "PCCRC %p version %d.%d\n",
                info, version.major, version.minor );

        /* Determine version */
        switch ( version.raw ) {
        case cpu_to_le16 ( PEERDIST_INFO_V1 ) :
                info->op = &peerdist_info_v1_operations;
                break;
        case cpu_to_le16 ( PEERDIST_INFO_V2 ) :
                info->op = &peerdist_info_v2_operations;
                break;
        default:
                DBGC ( info, "PCCRC %p unsupported version %d.%d\n",
                       info, version.major, version.minor );
                return -ENOTSUP;
        }
        assert ( info->op != NULL );
        assert ( info->op->info != NULL );

        /* Populate content information */
        if ( ( rc = info->op->info ( info ) ) != 0 )
                return rc;

        DBGC2 ( info, "PCCRC %p range [%08zx,%08zx) covers [%08zx,%08zx) with "
                "%d segments\n", info, info->range.start, info->range.end,
                info->trim.start, info->trim.end, info->segments );
        return 0;
}
int peerdist_info_segment ( const struct peerdist_info info,
struct peerdist_info_segment segment,
unsigned int  index 
)

Populate content information segment.

Parameters:
infoContent information
segmentContent information segment to fill in
indexSegment index
Return values:
rcReturn status code

Definition at line 726 of file pccrc.c.

References assert, peerdist_info_segment::blocks, DBGC, DBGC2, peerdist_range::end, ERANGE, peerdist_info_segment::hash, peerdist_info_segment::id, index, peerdist_info_segment::index, info, peerdist_info_segment::info, memset(), NULL, peerdist_info::op, peerdist_info_hash_ntoa(), peerdist_info_segment::range, rc, peerdist_info_segment::secret, peerdist_info_operations::segment, peerdist_info::segments, and peerdist_range::start.

                                                 {
        int rc;

        /* Sanity checks */
        assert ( info != NULL );
        assert ( info->op != NULL );
        assert ( info->op->segment != NULL );
        if ( index >= info->segments ) {
                DBGC ( info, "PCCRC %p segment %d of [0,%d) out of range\n",
                       info, index, info->segments );
                return -ERANGE;
        }

        /* Initialise structure */
        memset ( segment, 0, sizeof ( *segment ) );
        segment->info = info;
        segment->index = index;

        /* Populate content information segment */
        if ( ( rc = info->op->segment ( segment ) ) != 0 )
                return rc;

        DBGC2 ( info, "PCCRC %p segment %d range [%08zx,%08zx) with %d "
                "blocks\n", info, segment->index, segment->range.start,
                segment->range.end, segment->blocks );
        DBGC2 ( info, "PCCRC %p segment %d digest %s\n", info, segment->index,
                peerdist_info_hash_ntoa ( info, segment->hash ) );
        DBGC2 ( info, "PCCRC %p segment %d secret %s\n", info, segment->index,
                peerdist_info_hash_ntoa ( info, segment->secret ) );
        DBGC2 ( info, "PCCRC %p segment %d identf %s\n", info, segment->index,
                peerdist_info_hash_ntoa ( info, segment->id ) );
        return 0;
}
int peerdist_info_block ( const struct peerdist_info_segment segment,
struct peerdist_info_block block,
unsigned int  index 
)

Populate content information block.

Parameters:
segmentContent information segment
blockContent information block to fill in
indexBlock index
Return values:
rcReturn status code

Definition at line 770 of file pccrc.c.

References assert, peerdist_info_operations::block, peerdist_info_segment::blocks, DBGC, DBGC2, end, peerdist_range::end, ERANGE, peerdist_info_block::hash, index, peerdist_info_segment::index, peerdist_info_block::index, info, peerdist_info_segment::info, memset(), NULL, peerdist_info::op, peerdist_info_hash_ntoa(), peerdist_info_block::range, rc, segment, peerdist_info_block::segment, start, peerdist_range::start, peerdist_info::trim, and peerdist_info_block::trim.

                                               {
        const struct peerdist_info *info = segment->info;
        size_t start;
        size_t end;
        int rc;

        /* Sanity checks */
        assert ( segment != NULL );
        assert ( info != NULL );
        assert ( info->op != NULL );
        assert ( info->op->block != NULL );
        if ( index >= segment->blocks ) {
                DBGC ( info, "PCCRC %p segment %d block %d of [0,%d) out of "
                       "range\n", info, segment->index, index, segment->blocks);
                return -ERANGE;
        }

        /* Initialise structure */
        memset ( block, 0, sizeof ( *block ) );
        block->segment = segment;
        block->index = index;

        /* Populate content information block */
        if ( ( rc = info->op->block ( block ) ) != 0 )
                return rc;

        /* Calculate trimmed range */
        start = block->range.start;
        if ( start < info->trim.start )
                start = info->trim.start;
        end = block->range.end;
        if ( end > info->trim.end )
                end = info->trim.end;
        if ( end < start )
                end = start;
        block->trim.start = start;
        block->trim.end = end;

        DBGC2 ( info, "PCCRC %p segment %d block %d hash %s\n",
                info, segment->index, block->index,
                peerdist_info_hash_ntoa ( info, block->hash ) );
        DBGC2 ( info, "PCCRC %p segment %d block %d range [%08zx,%08zx) covers "
                "[%08zx,%08zx)\n", info, segment->index, block->index,
                block->range.start, block->range.end, block->trim.start,
                block->trim.end );
        return 0;
}

Variable Documentation

Minor version number.

Definition at line 44 of file pccrc.h.

Major version number.

Definition at line 46 of file pccrc.h.

Raw version number.

Always little-endian, regardless of whether the encompassing structure is version 1 (little-endian) or version 2 (big-endian).

Definition at line 50 of file pccrc.h.

Version number.

Definition at line 96 of file pccrc.h.

Hash algorithm.

This is a PEERDIST_INFO_V1_HASH_XXX constant.

This is a PEERDIST_INFO_V2_HASH_XXX constant.

Definition at line 101 of file pccrc.h.

Length to skip in first segment.

Length at the start of the first segment which is not included within the content range.

Definition at line 107 of file pccrc.h.

Referenced by draw_editbox(), inline_list_cut_position(), inline_list_splice(), inline_list_splice_tail(), ioremap_pages(), iounmap_pages(), memcmp(), memswap(), uhci_restart(), usb_describe(), usb_probe_all(), usb_score(), usbio_interfaces(), vmbus_consume(), vmbus_dump_channel(), vmbus_produce(), and x509_chain_okx().

Length to read in last segment, or zero.

Length within the last segment which is included within the content range. A zero value indicates that the whole of the last segment is included within the content range.

Definition at line 114 of file pccrc.h.

Referenced by asn1_bit_string(), eepro_transmit(), inline_list_splice(), inline_list_splice_tail(), jump_scroll_move(), pbkdf2_sha1_f(), phantom_clp_cmd(), validator_append(), and validator_step().

Number of segments within the content information.

Definition at line 116 of file pccrc.h.

Referenced by peerdist_info_v1_block_offset(), peerdist_info_v2(), and peerdist_info_v2_segments().

Offset of this segment within the content.

Offset of the first segment within the content.

Definition at line 142 of file pccrc.h.

Length of this segment.

Segment length.

Chunk data length.

Length of content range, or zero.

Should always be 32MB, except for the last segment within the content.

Length of the content range. A zero indicates that everything up to the end of the last segment is included in the content range.

Definition at line 148 of file pccrc.h.

Block size for this segment.

Block length in bytes.

Should always be 64kB. Note that the last block within the last segment may actually be less than 64kB.

Definition at line 154 of file pccrc.h.

Referenced by efi_pxe_mtftp(), peerblk_parse_iv(), pxe_tftp_open(), sandev_parse_iso9660(), and tftp_send_rrq().

Number of blocks within the block description.

This is the number of blocks within the segment which overlap the content range. It may therefore be less than the number of blocks within the segment.

Definition at line 179 of file pccrc.h.

Referenced by int13_get_disk_type(), int13_guess_geometry(), int13_guess_geometry_fdd(), pbkdf2_sha1(), peerdist_info_v1_block_offset(), peerdist_info_v1_blocks(), and peerdist_info_v1_segment().

Index of the first segment within the content.

Definition at line 233 of file pccrc.h.

Referenced by _tg3_flag(), _tg3_flag_clear(), _tg3_flag_set(), a3c90x_prepare_rx_desc(), amd8111e_poll(), amd8111e_transmit(), arbel_mcast_attach(), arbel_mcast_detach(), ath5k_hw_rfb_op(), atl1e_clean_tx_ring(), bigint_multiply_raw(), bitmap_set(), bitmap_test(), deflate_inflate(), efi_entropy_tick(), efi_file_read_dir(), efi_usb_async_start(), efi_usb_async_stop(), efi_usb_close(), efi_usb_control_transfer(), efi_usb_open(), efi_usb_sync_transfer(), ehci_dequeue(), ehci_endpoint_poll(), ehci_enqueue(), ena_admin(), ena_admin_req(), ena_poll_rx(), ena_poll_tx(), ena_refill_rx(), ena_transmit(), exanic_expired(), exanic_probe_port(), exanic_remove_port(), hermon_mcast_attach(), hermon_mcast_detach(), intelxl_admin_command(), intelxl_context(), intelxl_context_dump(), jump_scroll(), nodnic_port_add_mac_filter(), nodnic_port_recv_db_dma(), nodnic_port_remove_mac_filter(), nodnic_port_send_db_dma(), nvconfig_get_tlv_type_and_class(), nvconfig_nvdata_access(), nvconfig_nvdata_default_access(), nvconfig_read_rom_ini_values(), nvconfig_set_fw_reset_level(), peerdist_info_block(), peerdist_info_segment(), peerdist_info_v1_block_offset(), peerdist_info_v2_segment(), phantom_clp_cmd(), phantom_refill_rx_ring(), phantom_transmit(), phantom_update_macaddr(), pxe_menu_draw_item(), qib7322_send_buffer_offset(), sign_extend32(), smbios_fetch(), uhci_dequeue(), uhci_endpoint_poll(), uhci_enqueue(), usb_autoconfigure(), usbio_bulk_in_poll(), usbio_bulk_out_poll(), usbio_control_poll(), usbio_endpoint_close(), usbio_endpoint_enqueue(), usbio_interrupt_callback(), usbio_interrupt_poll(), xen_hvm_get_param(), xhci_dequeue(), xhci_enqueue(), xhci_ring_consumed(), and xhci_set_tr_dequeue_pointer().

Chunk type.

Definition at line 246 of file pccrc.h.