libgpac
Documentation of the core library of GPAC
Cryptography

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_Cryptgf_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_CryptInfogf_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

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

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

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
algorithmthe algorithm to use
modethe 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
gfcthe 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
gfcthe target crytpo context
keythe key to use. MUST be 16 bytes long
ivthe 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
gfcthe target crytpo context
keythe 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
gfcthe target crytpo context
ivthe new eed/initialization vector to use
sizethe 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
gfcthe target crytpo context
ivfilled with the current IV
sizewill 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
gfcthe target crytpo context
plaintextthe clear buffer
sizethe 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
gfcthe target crytpo context
ciphertextthe encrypted buffer
sizethe 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
filename of the crypt XML file
out_errset to return error
Returns
the crypt info

◆ gf_crypt_info_del()

void gf_crypt_info_del ( GF_CryptInfo info)

deletes crypto configuration file.

Parameters
infothe 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
infilesource MP4 file to decrypt
drm_filelocation of crypto configuration file
outnamelocation of destination file
interleave_timeinterleave time of the destination file - 0 means flat storage
fs_dump_flagsflags 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
infilesource MP4 file to decrypt
drm_filelocation of crypto configuration file
dst_filelocation of destination file
frag_namename of fragment to decrypt
fs_dump_flagsflags 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
infilesource MP4 file to encrypt
drm_filelocation of crypto configuration file
outnamelocation of destination file
interleave_timeinterleave time of the destination file - 0 means flat storage
fs_dump_flagsflags 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
infileinit segment of the MP4 file to encrypt - this SHALL NOT be encrypted
drm_filelocation of crypto configuration file
dst_filelocation of destination file
frag_namename of fragment to encrypt
fs_dump_flagsflags for session stats (1) and session graph (1<<1) dumping
Returns
error code if any