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

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

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...

Macros
#define	PEERDIST_INFO_V1 0x0100
	Content Information version 1. More...

#define	PEERDIST_INFO_V2 0x0200
	Content Information version 2. More...

#define	PEERDIST_INFO_V1_HASH_SHA256 0x0000800cUL
	SHA-256 hash algorithm. More...

#define	PEERDIST_INFO_V1_HASH_SHA384 0x0000800dUL
	SHA-384 hash algorithm. More...

#define	PEERDIST_INFO_V1_HASH_SHA512 0x0000800eUL
	SHA-512 hash algorithm. More...

#define	peerdist_info_v1_segment_t(digestsize)
	Content Information version 1 segment description. More...

#define	peerdist_info_v1_block_t(digestsize, blocks)
	Content Information version 1 block description. More...

#define	PEERDIST_INFO_V2_HASH_SHA512_TRUNC 0x04
	SHA-512 hash algorithm with output truncated to first 256 bits. More...

#define	peerdist_info_v2_chunk_t(digestsize)
	Content Information version 2 chunk description. More...

#define	PEERDIST_INFO_V2_CHUNK_TYPE 0x00
	Chunk type. More...

#define	peerdist_info_v2_segment_t(digestsize)
	Content Information version 2 segment description. More...

#define	PEERDIST_DIGEST_MAX_SIZE 64
	Maximum digest size for any supported algorithm. More...

#define	PEERDIST_SEGMENT_ID_MAGIC L"MS_P2P_CACHING"
	Magic string constant used to calculate segment identifier. More...

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)

union peerdist_info_version	__attribute__ ((packed))
	Major:minor version number. More...

int	peerdist_info (userptr_t data, size_t len, struct peerdist_info *info)
	Populate content information. More...

int	peerdist_info_segment (const struct peerdist_info info, struct peerdist_info_segment segment, unsigned int index)
	Populate content information segment. More...

int	peerdist_info_block (const struct peerdist_info_segment segment, struct peerdist_info_block block, unsigned int index)
	Populate content information block. More...

Variables
uint8_t	minor
	Minor version number. More...

uint8_t	major
	Major version number. More...

uint16_t	raw
	Raw version number. More...

union peerdist_info_version	version
	Version number. More...

uint32_t	hash
	Hash algorithm. More...

uint32_t	first
	Length to skip in first segment. More...

uint32_t	last
	Length to read in last segment, or zero. More...

uint32_t	segments
	Number of segments within the content information. More...

uint64_t	offset
	Offset of this segment within the content. More...

uint32_t	len
	Length of this segment. More...

uint32_t	blksize
	Block size for this segment. More...

uint32_t	blocks
	Number of blocks within the block description. More...

uint64_t	index = ( bit / ( 8 * sizeof ( value->element[0] ) ) )
	Index of the first segment within the content. More...

uint8_t	type
	Chunk type. More...

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.

Macro Definition Documentation

◆ PEERDIST_INFO_V1

#define PEERDIST_INFO_V1 0x0100

Content Information version 1.

Definition at line 46 of file pccrc.h.

◆ PEERDIST_INFO_V2

#define PEERDIST_INFO_V2 0x0200

Content Information version 2.

Definition at line 49 of file pccrc.h.

◆ PEERDIST_INFO_V1_HASH_SHA256

#define PEERDIST_INFO_V1_HASH_SHA256 0x0000800cUL

SHA-256 hash algorithm.

Definition at line 97 of file pccrc.h.

◆ PEERDIST_INFO_V1_HASH_SHA384

#define PEERDIST_INFO_V1_HASH_SHA384 0x0000800dUL

SHA-384 hash algorithm.

Definition at line 100 of file pccrc.h.

◆ PEERDIST_INFO_V1_HASH_SHA512

#define PEERDIST_INFO_V1_HASH_SHA512 0x0000800eUL

SHA-512 hash algorithm.

Definition at line 103 of file pccrc.h.

◆ peerdist_info_v1_segment_t

#define peerdist_info_v1_segment_t ( digestsize )

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

digestsize Digest size

Definition at line 146 of file pccrc.h.

◆ peerdist_info_v1_block_t

#define peerdist_info_v1_block_t	(	digestsize,
		blocks
	)

Value:

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

Content Information version 1 block description.

Parameters

digestsize	Digest size
blocks	Number of blocks

Definition at line 179 of file pccrc.h.

◆ PEERDIST_INFO_V2_HASH_SHA512_TRUNC

#define PEERDIST_INFO_V2_HASH_SHA512_TRUNC 0x04

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

Definition at line 225 of file pccrc.h.

◆ peerdist_info_v2_chunk_t

#define peerdist_info_v2_chunk_t ( digestsize )

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

digestsize Digest size

Definition at line 250 of file pccrc.h.

◆ PEERDIST_INFO_V2_CHUNK_TYPE

#define PEERDIST_INFO_V2_CHUNK_TYPE 0x00

Chunk type.

Definition at line 257 of file pccrc.h.

◆ peerdist_info_v2_segment_t

#define peerdist_info_v2_segment_t ( digestsize )

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

digestsize Digest size

Definition at line 280 of file pccrc.h.

◆ PEERDIST_DIGEST_MAX_SIZE

#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.

◆ PEERDIST_SEGMENT_ID_MAGIC

#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.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL )

◆ attribute()

union peerdist_info_version __attribute__ ( (packed) )

Major:minor version number.

◆ peerdist_info()

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

Populate content information.

Parameters

data	Raw data
len	Length of raw data
info	Content information to fill in

Return values

rc	Return status code

Definition at line 670 of file pccrc.c.

                                                                              {
         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;
 }

References assert(), cpu_to_le16, data, DBGC, DBGC2, ENOTSUP, info, len, memset(), NULL, peerdist_info_get(), PEERDIST_INFO_V1, peerdist_info_v1_operations, PEERDIST_INFO_V2, peerdist_info_v2_operations, rc, strerror(), and version.

◆ peerdist_info_segment()

int peerdist_info_segment	(	const struct peerdist_info *	info,
		struct peerdist_info_segment *	segment,
		unsigned int	index
	)

Populate content information segment.

Parameters

info	Content information
segment	Content information segment to fill in
index	Segment index

Return values

rc	Return status code

Definition at line 723 of file pccrc.c.

                                                  {
         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;
 }

References assert(), DBGC, DBGC2, ERANGE, index, info, memset(), NULL, peerdist_info_hash_ntoa(), rc, and segment.

◆ peerdist_info_block()

int peerdist_info_block	(	const struct peerdist_info_segment *	segment,
		struct peerdist_info_block *	block,
		unsigned int	index
	)

Populate content information block.

Parameters

segment	Content information segment
block	Content information block to fill in
index	Block index

Return values

rc	Return status code

Definition at line 767 of file pccrc.c.

                                                {
         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;
 }

References assert(), block, DBGC, DBGC2, end, ERANGE, index, info, memset(), NULL, peerdist_info_hash_ntoa(), rc, segment, start, peerdist_range::start, and peerdist_info::trim.

Variable Documentation

◆ minor

uint8_t minor

Minor version number.

Definition at line 37 of file pccrc.h.

◆ major

uint8_t major

Major version number.

Definition at line 39 of file pccrc.h.

◆ raw

uint16_t raw

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 17 of file pccrc.h.

◆ version

union peerdist_info_version version

Version number.

Definition at line 12 of file pccrc.h.

◆ hash

uint8_t hash

Hash algorithm.

This is a PEERDIST_INFO_V1_HASH_XXX constant.

This is a PEERDIST_INFO_V2_HASH_XXX constant.

Definition at line 17 of file pccrc.h.

◆ first

uint32_t first

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 23 of file pccrc.h.

Referenced by dns_compare(), draw_editbox(), efi_paths(), inline_list_cut_position(), inline_list_splice(), inline_list_splice_tail(), ioremap_pages(), iounmap_pages(), memcmp(), memswap(), peerdist_info_v1(), strcasecmp(), strcmp(), strncasecmp(), strncmp(), tls_new_ciphertext(), trivial_memcmp_user(), uhci_restart(), uristrcmp(), usb_describe(), usb_interface_association_descriptor(), usb_probe_all(), usb_score(), usbio_interfaces(), vmbus_consume(), vmbus_dump_channel(), vmbus_produce(), and x509_chain_okx().

◆ last

uint32_t last

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 30 of file pccrc.h.

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

◆ segments

uint32_t segments

Number of segments within the content information.

Definition at line 32 of file pccrc.h.

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

◆ offset

uint64_t offset

Offset of this segment within the content.

Offset of the first segment within the content.

Definition at line 12 of file pccrc.h.

◆ len

uint32_t len

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 18 of file pccrc.h.

◆ blksize

uint32_t blksize

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 24 of file pccrc.h.

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

◆ blocks

uint32_t blocks

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 17 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

unsigned int index = ( bit / ( 8 * sizeof ( value->element[0] ) ) )

Index of the first segment within the content.

Definition at line 21 of file pccrc.h.

Referenced by _tg3_flag(), _tg3_flag_clear(), _tg3_flag_set(), a3c90x_prepare_rx_desc(), acpi_find(), acpi_find_via_rsdt(), acpi_table(), acpi_test_find(), amd8111e_poll(), amd8111e_transmit(), amd8111e_wait_tx_ring(), arbel_cmd_hw2sw_eq(), arbel_cmd_read_mgm(), arbel_cmd_sw2hw_eq(), arbel_cmd_sw2hw_mpt(), arbel_cmd_write_mgm(), arbel_mcast_attach(), arbel_mcast_detach(), ath5k_hw_rfb_op(), atl1e_clean_tx_ring(), b44_cam_write(), bigint_multiply_raw(), bitmap_set(), bitmap_test(), deflate_inflate(), deflate_length(), deflate_set_length(), dns_send_packet(), draw_menu_item(), ecam_find(), ecam_read(), ecam_write(), efi_entropy_tick(), efi_file_read_dir(), efi_usb_async_start(), efi_usb_async_stop(), efi_usb_close(), efi_usb_control_transfer(), efi_usb_get_endpoint_descriptor(), efi_usb_get_string_descriptor(), efi_usb_is_open(), efi_usb_open(), efi_usb_sync_transfer(), efi_wait_for_event_wrapper(), efifb_draw(), efifb_draw_unknown(), efifb_dynamic(), efifb_glyph(), 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(), falcon_read_sram(), falcon_write_sram(), hermon_cmd_hw2sw_eq(), hermon_cmd_hw2sw_mpt(), hermon_cmd_query_eq(), hermon_cmd_read_mcg(), hermon_cmd_sw2hw_eq(), hermon_cmd_sw2hw_mpt(), hermon_cmd_write_mcg(), hermon_mcast_attach(), hermon_mcast_detach(), intelxl_admin_command(), intelxl_admin_event_init(), intelxl_context(), intelxl_context_dump(), intelxl_context_line(), intelxlvf_admin_event(), isapnp_read_iobase(), isapnp_read_irqno(), jump_scroll(), menu_item(), nodnic_port_add_mac_filter(), nodnic_port_recv_db_dma(), nodnic_port_remove_mac_filter(), nodnic_port_send_db_dma(), nodnic_port_update_ring_doorbell(), nvconfig_get_tlv_type_and_class(), nvconfig_nvdata_access(), nvconfig_nvdata_default_access(), nvconfig_read_rom_ini_values(), nvconfig_set_fw_reset_level(), pcnet32_dwio_read_bcr(), pcnet32_dwio_read_csr(), pcnet32_dwio_write_bcr(), pcnet32_dwio_write_csr(), pcnet32_wio_read_bcr(), pcnet32_wio_read_csr(), pcnet32_wio_write_bcr(), pcnet32_wio_write_csr(), peerdist_info_block(), peerdist_info_segment(), peerdist_info_v1_block_offset(), peerdist_info_v1_segment(), peerdist_info_v2_segment(), phantom_clp_cmd(), phantom_refill_rx_ring(), phantom_transmit(), phantom_update_macaddr(), pnm_bitmap(), pxe_menu_draw_item(), qib7322_send_buffer_offset(), read_smbios_string(), ring_next(), select_setting_row(), sign_extend32(), smbios_fetch(), smscusb_get_statistics(), uhci_dequeue(), uhci_endpoint_poll(), uhci_enqueue(), usb_autoconfigure(), usb_clear_feature(), usb_config_descriptor(), usb_control(), usb_endpoint_described(), usb_endpoint_descriptor(), usb_get_config_descriptor(), usb_get_descriptor(), usb_get_status(), usb_get_string_descriptor(), usb_hub_clear_port_feature(), usb_hub_set_port_feature(), usb_message(), usb_set_configuration(), usb_set_feature(), usbio_bulk_in_poll(), usbio_bulk_out_poll(), usbio_control_poll(), usbio_endpoint_close(), usbio_endpoint_enqueue(), usbio_interrupt_callback(), usbio_interrupt_poll(), vesafb_glyph(), xen_hvm_get_param(), xhci_dequeue(), xhci_enqueue(), xhci_ring_consumed(), and xhci_set_tr_dequeue_pointer().

◆ type

uint8_t type

Chunk type.

Definition at line 12 of file pccrc.h.

◆ attribute

struct peerdist_raw __attribute__

◆ sha512_trunc_algorithm

struct digest_algorithm sha512_trunc_algorithm

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ PEERDIST_INFO_V1

◆ PEERDIST_INFO_V2

◆ PEERDIST_INFO_V1_HASH_SHA256

◆ PEERDIST_INFO_V1_HASH_SHA384

◆ PEERDIST_INFO_V1_HASH_SHA512

◆ peerdist_info_v1_segment_t

◆ peerdist_info_v1_block_t

◆ PEERDIST_INFO_V2_HASH_SHA512_TRUNC

◆ peerdist_info_v2_chunk_t

◆ PEERDIST_INFO_V2_CHUNK_TYPE

◆ peerdist_info_v2_segment_t

◆ PEERDIST_DIGEST_MAX_SIZE

◆ PEERDIST_SEGMENT_ID_MAGIC

Function Documentation

◆ FILE_LICENCE()

◆ __attribute__()

◆ peerdist_info()

◆ peerdist_info_segment()

◆ peerdist_info_block()

Variable Documentation

◆ minor

◆ major

◆ raw

◆ version

◆ hash

◆ first

◆ last

◆ segments

◆ offset

◆ len

◆ blksize

◆ blocks

◆ index

◆ type

◆ __attribute__

◆ sha512_trunc_algorithm

◆ attribute()

◆ attribute