pccrc.h File Reference

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

#include <stdint.h>
#include <byteswap.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...

Macros
#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)
	FILE_SECBOOT (PERMITTED)
int	peerdist_info (const void *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
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.

Referenced by peerdist_info(), and peerdist_info_v1().

PEERDIST_INFO_V2

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

PEERDIST_INFO_V1_HASH_SHA256

#define PEERDIST_INFO_V1_HASH_SHA256   0x0000800cUL

SHA-256 hash algorithm.

Definition at line 97 of file pccrc.h.

Referenced by peerdist_info_v1().

PEERDIST_INFO_V1_HASH_SHA384

#define PEERDIST_INFO_V1_HASH_SHA384   0x0000800dUL

SHA-384 hash algorithm.

Definition at line 100 of file pccrc.h.

Referenced by peerdist_info_v1().

PEERDIST_INFO_V1_HASH_SHA512

#define PEERDIST_INFO_V1_HASH_SHA512   0x0000800eUL

SHA-512 hash algorithm.

Definition at line 103 of file pccrc.h.

Referenced by peerdist_info_v1().

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.

#define peerdist_info_v1_segment_t( digestsize )                        \
        struct {                                                        \
                struct peerdist_info_v1_segment segment;                \
                uint8_t hash[digestsize];                               \
                uint8_t secret[digestsize];                             \
        } __attribute__ (( packed ))

Referenced by peerdist_info_v1_block_offset(), and peerdist_info_v1_segment().

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.

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

Referenced by peerdist_info_v1_block(), and peerdist_info_v1_block_offset().

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.

Referenced by peerdist_info_v2().

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.

#define peerdist_info_v2_chunk_t( digestsize )                          \
        struct {                                                        \
                struct peerdist_info_v2_chunk chunk;                    \
                peerdist_info_v2_segment_t ( digestsize ) segment[0];   \
        } __attribute__ (( packed ))

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.

#define peerdist_info_v2_segment_t( digestsize )                        \
        struct {                                                        \
                struct peerdist_info_v2_segment segment;                \
                uint8_t hash[digestsize];                               \
                uint8_t secret[digestsize];                             \
        } __attribute__ (( packed ))

Referenced by peerdist_info_v2_cursor_next(), and peerdist_info_v2_segment().

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.

Referenced by peerdist_info_hash_ntoa().

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.

Referenced by peerdist_info_segment_hash().

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

peerdist_info()

int peerdist_info ( const void * data, size_t len, struct peerdist_info * info )

extern

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 )

extern

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 724 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 )

extern

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 768 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, peerdist_range::start, start, and peerdist_info::trim.

Variable Documentation

sha512_trunc_algorithm

struct digest_algorithm sha512_trunc_algorithm

extern