Utility tools for encryption and decryption. More...

Collaboration diagram for Cryptography:

Data Structures
struct	GF_CryptKeyInfo

struct	GF_TrackCryptInfo

struct	GF_CryptInfo

Macros
#define	GF_AES_128_KEYSIZE 16

Typedefs
typedef struct _gf_crypt_context	GF_Crypt

Enumerations
enum	GF_CRYPTO_MODE { GF_CBC = 0 , GF_CTR = 1 , GF_ECB = 2 }

enum	GF_CRYPTO_ALGO { GF_AES_128 = 0 }

enum	{ GF_CRYPT_TYPE_ISMA = GF_4CC( 'i', 'A', 'E', 'C' ) , GF_CRYPT_TYPE_OMA = GF_4CC( 'o', 'd', 'k', 'm' ) , GF_CRYPT_TYPE_CENC = GF_4CC('c','e','n','c') , GF_CRYPT_TYPE_CBC1 = GF_4CC('c','b','c','1') , GF_CRYPT_TYPE_CENS = GF_4CC('c','e','n','s') , GF_CRYPT_TYPE_CBCS = GF_4CC('c','b','c','s') , GF_CRYPT_TYPE_ADOBE = GF_4CC('a','d','k','m') , GF_CRYPT_TYPE_PIFF = GF_4CC('p','i','f','f') , GF_CRYPT_TYPE_SAES = GF_4CC('s','a','e','s') }

enum	{ GF_CRYPT_SELENC_NONE = 0 , GF_CRYPT_SELENC_RAP , GF_CRYPT_SELENC_NON_RAP , GF_CRYPT_SELENC_RAND , GF_CRYPT_SELENC_RAND_RANGE , GF_CRYPT_SELENC_RANGE , GF_CRYPT_SELENC_PREVIEW , GF_CRYPT_SELENC_CLEAR , GF_CRYPT_SELENC_CLEAR_FORCED }

enum	GF_KeyRollType { GF_KEYROLL_NONE = 0 , GF_KEYROLL_SAMPLES , GF_KEYROLL_SAPS , GF_KEYROLL_SEGMENTS , GF_KEYROLL_PERIODS }

Functions
GF_Crypt *	gf_crypt_open (GF_CRYPTO_ALGO algorithm, GF_CRYPTO_MODE mode)

void	gf_crypt_close (GF_Crypt *gfc)

GF_Err	gf_crypt_init (GF_Crypt gfc, void key, const void *iv)

GF_Err	gf_crypt_set_key (GF_Crypt gfc, void key)

GF_Err	gf_crypt_set_IV (GF_Crypt gfc, const void iv, u32 size)

GF_Err	gf_crypt_get_IV (GF_Crypt gfc, void iv, u32 *size)

GF_Err	gf_crypt_encrypt (GF_Crypt gfc, void plaintext, u32 size)

GF_Err	gf_crypt_decrypt (GF_Crypt gfc, void ciphertext, u32 size)

GF_CryptInfo *	gf_crypt_info_load (const char file, GF_Err out_err)

void	gf_crypt_info_del (GF_CryptInfo *info)

GF_Err	gf_decrypt_file (GF_ISOFile infile, const char drm_file, const char *outname, Double interleave_time, u32 fs_dump_flags)

GF_Err	gf_decrypt_fragment (GF_ISOFile infile, const char drm_file, const char dst_file, const char frag_name, u32 fs_dump_flags)

GF_Err	gf_crypt_file (GF_ISOFile infile, const char drm_file, const char *outname, Double interleave_time, u32 fs_dump_flags)

GF_Err	gf_crypt_fragment (GF_ISOFile infile, const char drm_file, const char dst_file, const char frag_name, u32 fs_dump_flags)

Detailed Description

Utility tools for ISMA and Common Encryption.

This section documents the encryption and decryption routines used by GPAC, mostly AES 128 in CBC or CTR modes.

This section documents the helper tools (mostly crypt info file) used in ISMA and CENC encryption.

Data Structure Documentation

◆ GF_CryptKeyInfo

struct GF_CryptKeyInfo

Key info structure, one per defined key in the DRM XML doc

Data Fields
bin128	KID	KEY ID
bin128	key	key value
u8	IV[16]	constant IV or initial IV if not constant
char *	hls_info	hls_info defined
u8	IV_size	IV size
u8	constant_IV_size	constant IV size
char *	repID	DASH representation ID or NULL
char *	periodID	DASH period ID or NULL
u32	ASID	DASH adaptationSet ID or NULL

◆ GF_TrackCryptInfo

struct GF_TrackCryptInfo

Crypto information for one media stream

Collaboration diagram for GF_TrackCryptInfo:

Data Fields
u32	scheme_type	scheme type used for encryptio of the track
u32	trackID	ID of track / PID / ... to be encrypted
char *	KMS_URI	URI of key management system / rightsIssuerURL
char *	Scheme_URI	Scheme URI or contentID for OMA
u32	sel_enc_type	selective encryption type
u32	sel_enc_range	for OMA, sets preview range in samples. Otherwise sets encryption AU frequency (encrypts 1 AU every sel_enc_range ones)
u32	ipmp_type	IPMP signaling: 0: none, 1: IPMP, 2: IPMPX when IPMP signaling is enabled, the OD stream will be updated with IPMP Update commands THIS IS DEPRECATED IN GPAC
u32	ipmp_desc_id	if not set and IPMP enabled, defaults to TrackID THIS IS DEPRECATED IN GPAC
u32	sai_saved_box_type	type of box where sample auxiliary information is saved, either "senc" or "PSEC" (PIFF)
u8	encryption	OMA encryption type: 0: none, 1: AES CBC, 2: AES CTR
char *	TextualHeaders	OMA textual headers
char	TransactionID[17]	OMA transaction ID
u32	IsEncrypted	CENC extensions - TODO, we could extend the support to allow per key patterns and selective encryption modes and also add support for multiple keys in ISMA ? default encryption state for samples
u32	nb_keys	number of defined keys
GF_CryptKeyInfo *	keys	keys defined
u32	defaultKeyIdx	default key index to use
u32	keyRoll	roll period of keys
GF_KeyRollType	roll_type	roll type
u32	clear_bytes	number of bytes to leave in the clear for non NAL-based tracks. Only used in cbcs mode
u32	crypt_byte_block	CENS/CBCS pattern
u32	skip_byte_block
u32	crypt_byte_offset	forces a minimum clear range for subsamples (ignored otherwise) - the final offset is at least the slice header size
Bool	allow_encrypted_slice_header
u32	block_align	force cenc and cbc1: 0: default, 1: no block alignment of encrypted data, 2: always block align even if producing non encrypted samples
u32	force_clear_stsd_idx
char *	metadata	adobe metadata in base64
Bool	force_type	force using type set in XML rather than type indicated in file when decrypting
Bool	rand_keys	generate random keys and key values
u32	subs_rand	randomly encrypts subsample if rand() % subs_rand is 0
char *	subs_crypt	list of VCL NAL/OBU indices to encrypt, 1-based
Bool	multi_key	use multiple keys per sample
u32	mkey_roll_plus_one	roll key over subsamples. If 0, roll by 1 every encrypted sample. If 1 (-1==0) disable key roll
char *	mkey_subs	coma-separated list of indices of keys to use per subsample. Value 0 means keep clear. If less indices than subsamples, keep subsamples in clear

◆ GF_CryptInfo

struct GF_CryptInfo

Crypto information

Data Fields
GF_List *	tcis	list of track infos
u32	def_crypt_type	global for all tracks unless overridden
Bool	has_common_key	indicates a common key is used
Bool	in_text_header	intern to parser
GF_Err	last_parse_error	intern to parser

Macro Definition Documentation

◆ GF_AES_128_KEYSIZE

#define GF_AES_128_KEYSIZE 16

Key size in bytes for AES 128

Typedef Documentation

◆ GF_Crypt

typedef struct _gf_crypt_context GF_Crypt

cryptographic context object

Enumeration Type Documentation

◆ GF_CRYPTO_MODE

enum GF_CRYPTO_MODE

Chaining mode of AES

Enumerator
GF_CBC	CBC chaining mode
GF_CTR	CTR chaining mode
GF_ECB	ECB (no chaining), payload must be a multiple of 16-bytes blocks

◆ GF_CRYPTO_ALGO

enum GF_CRYPTO_ALGO

Algorithm mode to use

Enumerator
GF_AES_128	AES 128 bit encryption

◆ anonymous enum

anonymous enum

Supported encryption scheme types

Enumerator
GF_CRYPT_TYPE_ISMA	ISMA E&A encryption
GF_CRYPT_TYPE_OMA	OMA DRM encryption
GF_CRYPT_TYPE_CENC	CENC CTR-128 encryption
GF_CRYPT_TYPE_CBC1	CENC CBC-128 encryption
GF_CRYPT_TYPE_CENS	CENC CTR-128 pattern encryption
GF_CRYPT_TYPE_CBCS	CENC CBC-128 pattern encryption
GF_CRYPT_TYPE_ADOBE	Adobe CBC-128 encryption
GF_CRYPT_TYPE_PIFF	PIFF CTR-128 encryption
GF_CRYPT_TYPE_SAES	HLS Sample encryption

◆ anonymous enum

anonymous enum

Selective encryption modes

Enumerator
GF_CRYPT_SELENC_NONE	no selective encryption
GF_CRYPT_SELENC_RAP	only encrypts RAP samples
GF_CRYPT_SELENC_NON_RAP	only encrypts non-RAP samples
GF_CRYPT_SELENC_RAND	selective encryption of random samples
GF_CRYPT_SELENC_RAND_RANGE	selective encryption of a random sample in given range
GF_CRYPT_SELENC_RANGE	selective encryption of first sample in given range
GF_CRYPT_SELENC_PREVIEW	encryption of all samples but the preview range
GF_CRYPT_SELENC_CLEAR	no encryption of samples, signaled with sample group
GF_CRYPT_SELENC_CLEAR_FORCED	no encryption of samples, signaled without sample group but bytesOfEncrypted = 0

◆ GF_KeyRollType

enum GF_KeyRollType

key roll modes

Enumerator
GF_KEYROLL_NONE	no key roll
GF_KEYROLL_SAMPLES	change keys every keyRoll AUs
GF_KEYROLL_SAPS	roll keys at each SAP type 1 or 2 for streams with SAPs
GF_KEYROLL_SEGMENTS	change keys every keyRoll DASH segments
GF_KEYROLL_PERIODS	change keys every keyRoll periods

Function Documentation

◆ gf_crypt_open()

GF_Crypt* gf_crypt_open	(	GF_CRYPTO_ALGO	algorithm,
		GF_CRYPTO_MODE	mode
	)

opens crypto context

Parameters

algorithm	the algorithm to use
mode	the chaining mode of the algorithm

Returns: a new crypto context

◆ gf_crypt_close()

void gf_crypt_close ( GF_Crypt * gfc )

destroys a crypto context

Parameters

gfc	the target crytpo context

◆ gf_crypt_init()

GF_Err gf_crypt_init	(	GF_Crypt *	gfc,
		void *	key,
		const void *	iv
	)

initializes all buffers for the specified context After calling this function you can use the crypto context for encryption or decryption (not both).

Parameters

gfc	the target crytpo context
key	the key to use. MUST be 16 bytes long
iv	the seed/initialization vector to use. It needs to be random and unique (but not secret). The same IV must be used for encryption/decryption. MUST be 16 bytes long

Returns: error if any

◆ gf_crypt_set_key()

GF_Err gf_crypt_set_key	(	GF_Crypt *	gfc,
		void *	key
	)

changes key, does not touch IV. This is used for key rolling

Parameters

gfc	the target crytpo context
key	the new key to use. MUST be 16 bytes long

Returns: error if any

◆ gf_crypt_set_IV()

GF_Err gf_crypt_set_IV	(	GF_Crypt *	gfc,
		const void *	iv,
		u32	size
	)

sets the IV for the algorithm. Used for ISMA and CENC CTR.

Parameters

gfc	the target crytpo context
iv	the new eed/initialization vector to use
size	the size of the IV. Must be 16 or 17 for AES. If 17 (AES CTR only), the first byte shall contain the counter position

Returns: error if any

◆ gf_crypt_get_IV()

GF_Err gf_crypt_get_IV	(	GF_Crypt *	gfc,
		void *	iv,
		u32 *	size
	)

gets the IV of the algorithm. The size will hold the size of the state and the state must have enough bytes to hold it (17 is enough for AES 128). In CTR mode, the first byte will be set to the counter value (number of bytes consumed in last block), or 0 if all bytes were consumed

Parameters

gfc	the target crytpo context
iv	filled with the current IV
size	will be set to the IV size (16 for AES CBC? 17 for AES CTR)

Returns: error if any

◆ gf_crypt_encrypt()

GF_Err gf_crypt_encrypt	(	GF_Crypt *	gfc,
		void *	plaintext,
		u32	size
	)

encrypts a payload. The encryption is done inplace (plaintext is replaced by the ciphertext). The buffer size should be k*algorithms_block_size if used in a mode which operated in blocks (CBC) or whatever when used in CTR which operate in streams.

Parameters

gfc	the target crytpo context
plaintext	the clear buffer
size	the size of the clear buffer

Returns: error if any

◆ gf_crypt_decrypt()

GF_Err gf_crypt_decrypt	(	GF_Crypt *	gfc,
		void *	ciphertext,
		u32	size
	)

decrypts a payload. The decryption is done inplace (ciphertext is replaced by the plaintext). The buffer size should be k*algorithms_block_size if used in a mode which operated in blocks (CBC) or whatever when used in CTR which operate in streams.

Parameters

gfc	the target crytpo context
ciphertext	the encrypted buffer
size	the size of the encrypted buffer

Returns: error if any

◆ gf_crypt_info_load()

GF_CryptInfo* gf_crypt_info_load	(	const char *	file,
		GF_Err *	out_err
	)

loads a given crypto configuration file. Full doc is available at https://gpac.io/mp4box/encryption/common-encryption/

Parameters

file	name of the crypt XML file
out_err	set to return error

Returns: the crypt info

◆ gf_crypt_info_del()

void gf_crypt_info_del ( GF_CryptInfo * info )

deletes crypto configuration file.

Parameters

info	the target crypt info

◆ gf_decrypt_file()

GF_Err gf_decrypt_file	(	GF_ISOFile *	infile,
		const char *	drm_file,
		const char *	outname,
		Double	interleave_time,
		u32	fs_dump_flags
	)

decrypts a file

Parameters

infile	source MP4 file to decrypt
drm_file	location of crypto configuration file
outname	location of destination file
interleave_time	interleave time of the destination file - 0 means flat storage
fs_dump_flags	flags for session stats (1) and session graph (1<<1) dumping

Returns: error code if any

◆ gf_decrypt_fragment()

GF_Err gf_decrypt_fragment	(	GF_ISOFile *	infile,
		const char *	drm_file,
		const char *	dst_file,
		const char *	frag_name,
		u32	fs_dump_flags
	)

decrypts a fragment

Parameters

infile	source MP4 file to decrypt
drm_file	location of crypto configuration file
dst_file	location of destination file
frag_name	name of fragment to decrypt
fs_dump_flags	flags for session stats (1) and session graph (1<<1) dumping

Returns: error code if any

◆ gf_crypt_file()

GF_Err gf_crypt_file	(	GF_ISOFile *	infile,
		const char *	drm_file,
		const char *	outname,
		Double	interleave_time,
		u32	fs_dump_flags
	)

encrypts a file

Parameters

infile	source MP4 file to encrypt
drm_file	location of crypto configuration file
outname	location of destination file
interleave_time	interleave time of the destination file - 0 means flat storage
fs_dump_flags	flags for session stats (1) and session graph (1<<1) dumping

Returns: error code if any

◆ gf_crypt_fragment()

GF_Err gf_crypt_fragment	(	GF_ISOFile *	infile,
		const char *	drm_file,
		const char *	dst_file,
		const char *	frag_name,
		u32	fs_dump_flags
	)

encrypts a fragment

Parameters

infile	init segment of the MP4 file to encrypt - this SHALL NOT be encrypted
drm_file	location of crypto configuration file
dst_file	location of destination file
frag_name	name of fragment to encrypt
fs_dump_flags	flags for session stats (1) and session graph (1<<1) dumping

Returns: error code if any

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ GF_CryptKeyInfo

◆ GF_TrackCryptInfo

◆ GF_CryptInfo

Macro Definition Documentation

◆ GF_AES_128_KEYSIZE

Typedef Documentation

◆ GF_Crypt

Enumeration Type Documentation

◆ GF_CRYPTO_MODE

◆ GF_CRYPTO_ALGO

◆ anonymous enum

◆ anonymous enum

◆ GF_KeyRollType

Function Documentation

◆ gf_crypt_open()

◆ gf_crypt_close()

◆ gf_crypt_init()

◆ gf_crypt_set_key()

◆ gf_crypt_set_IV()

◆ gf_crypt_get_IV()

◆ gf_crypt_encrypt()

◆ gf_crypt_decrypt()

◆ gf_crypt_info_load()

◆ gf_crypt_info_del()

◆ gf_decrypt_file()

◆ gf_decrypt_fragment()

◆ gf_crypt_file()

◆ gf_crypt_fragment()