ismacryplib.h

完整的RTP RTSP代码库

/*
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Initial Developer of the Original Code is Cisco Systems Inc.
 * Portions created by Cisco Systems Inc. are
 * Copyright (C) Cisco Systems Inc. 2003, 2004.  All Rights Reserved.
 * 
 * Contributor(s): 
 *              Alex Vanzella           [e-mail]
 */

#ifndef ISMACRYPLIB_H
#define ISMACRYPLIB_H
#include "mpeg4ip.h"

#ifndef TRUE
#define TRUE 1
#define FALSE 0
#endif

#define ISMACRYP_SESSION_G_INIT	10
//#define ISMACRYP_DEBUG_TRACE	1



#ifdef __cplusplus
extern "C" {
#endif

/*
--------------------------------------------------------------------------------
General operation of ismacryplib.

The ismacryp library is a new addition to mpeg4ip which implements the ISMA 
encryption and authentication protocol defined in "ISMA 1.0 Encryption and 
Authentication, Version 1.0" specification which is published on the ISMA 
web site, www.isma.tv This specification is referred to as Ismacryp.

This library provides an interface to Ismacryp encryption for use by the various 
other libraries and tools while hiding encryption-specific details from the 
applications which use the library. The intent of this architecture is to 
accomodate future changes to Ismacryp (e.g. new  encryption scheme)  with 
little or no changes required to the applications.
	
Use of the library requires one call to initialize internal data structures 
which are private to the library. Once the library has been initialized, 
Ismacryp sessions can be initiated. A session defines an Ismacryp context 
which mainly consists of an encryption key and a salt for encryption various 
other protocol and state items.

The information that comprises a context is generally not required by the 
application but in cases where context information is required by the application, 
it is obtained by functions provided in this interface.

Applications access their Ismacryp context by means of a session identifier which 
is returned when a session is initiated and which is kept by the application for 
all future calls to the Ismacryp library.

After a session is initiated, applications encrypt or decrypt buffers of data by 
calling the appropriate Ismacryp library routines. When no more encryption or 
decryption services are needed, the application closes the Ismacryp session.  

Multi-threaded applications may use the library with each thread using one or more 
sessions as required.

Call sequence for encryption:
1. ismacrypInitLib                    (once per application)
2. ismacrypInitSession                (once per session, no limit on sessions)
3. ismacrypEncryptSample 
   or ismacrypEncryptSampleAddHeader  (once per each data buffer comprising a track)
4. ismacrypEndSession

Call sequence for decryption:
1. ismacrypInitLib                    (once per application)
2. ismacrypInitSession                (once per session, no limit on sessions)
3. ismacrypDecryptSample 
   or ismacrypDecryptSampleRemoveHeader 
   or ismacrypDecryptSampleRandomAccess (once per each data buffer comprising a track)
4. ismacrypEndSession


Note on Advanced Encryption Standard Integer Counter Mode (AES ICM) which is
used by Ismacryp for encryption. 

AES ICM alters its encryption key after 16 bytes of data have been encrypted. 
As such, the position in a data stream of a buffer of data is necessary 
information for decryption of that data.

The encryption functions provided in this interface require that data for a
track or a stream be encrypted in the exact same order in which it occurs
in the data stream. The postion in the data stream for data in a given session
is kept in the session context. When a buffer of data has been encrypted,
the library assumes that the next buffer of data begins at the point in the
data stream immediately following the previous buffer.

Decryption of tracks and streams may be performed in order if desired. In this
case, the application is responsible for delivering data buffers to the decryption
functions in the exact same order as those buffers were previously encrypted.
Failure to do so will result in improper decryption.

Alternatively an application may decrypt a data buffer from any random location
in the data stream but in this case the start location in the data stream of
the particular buffer must be provided to the appropriate decryption function.

The count of data in a data stream starts at 0 for the first byte of data
and increments by 1 for each byte.
--------------------------------------------------------------------------------
*/



/*
--------------------------------------------------------------------------------
All function calls in the Ismacryp library, save for the library initialization 
function, ismacrypInitLib,  and the session initialization function, 
ismacrypInitSession, require a session identifier of this type. Applications 
acquire a session identifier with the session initialization function, 
ismaCrypInitSession, and supply this identifier in all subsequent library 
function calls.
--------------------------------------------------------------------------------
*/
typedef uint32_t ismacryp_session_id_t; 


/*
--------------------------------------------------------------------------------
All Ismacryp library functions return a code indicating either successful 
completion of the function or failure.
--------------------------------------------------------------------------------
*/
typedef enum  ismacryp_rc_t { ismacryp_rc_ok = 0, 
                            ismacryp_rc_sessid_error, 
                            ismacryp_rc_keytype_error, 
                            ismacryp_rc_keyfile_error, 
                            ismacryp_rc_keyfilename_error, 
                            ismacryp_rc_key_error, 
                            ismacryp_rc_memory_error, 
                            ismacryp_rc_cipheralloc_error, 
                            ismacryp_rc_cipherinit_error, 
                            ismacryp_rc_unsupported_error, 
                            ismacryp_rc_encrypt_error, 
                            ismacryp_rc_protocol_error } ismacryp_rc_t;


/*
--------------------------------------------------------------------------------
There are two key types defined so that audio and video streams/tracks can be
encoded with a different key.
--------------------------------------------------------------------------------
*/
typedef enum  ismacryp_keytype_t { KeyTypeOther=0, 
                            KeyTypeVideo, 
                            KeyTypeAudio } ismacryp_keytype_t;


typedef uint32_t ismacryp_scheme_t;
typedef uint16_t ismacryp_schemeversion_t;

/*
--------------------------------------------------------------------------------
This function is called once by applications prior to using any other functions 
in the library.  It is used to initialize internal data structures in the 
library.  Return code of ismacryp_rc_ok indicates successful completion of this 
function.

Any return code other than ismacryp_rc_ok means that the library cannot 
initialize properly and, as a result, no other library functions will operate 
correctly and they should not be used. Erratic operation or catastrophic failure 
will result if library functions are used after a failure of this library 
initialization routine. It is important in multi-threaded applications that 
this function not be called by more than one thread.
--------------------------------------------------------------------------------
*/
ismacryp_rc_t ismacrypInitLib(void);


/*
--------------------------------------------------------------------------------
This function is used to initialize an Ismacryp session. The session parameter 
is updated with a value for the session and this is to be retained by the 
application for all further calls to the library. Return code of ismacryp_rc_ok 
indicates successful completion of this function. 

Any return code other than ismacryp_rc_ok means that the session was not properly 
initiated and the session identifier will contain a null or invalid value. Use 
of a null session identifier in any other library function will result in an error 
code being returned.
--------------------------------------------------------------------------------
*/
ismacryp_rc_t ismacrypInitSession(ismacryp_session_id_t *session, ismacryp_keytype_t  keytype);


/*
--------------------------------------------------------------------------------
This function is used to deallocate resources associated with a sesssion when 
an application no longer has need for Ismacryp lib services. The session 
parameter is the value initially obtained with ismaCrypInitSession. Return code 
of ismacryp_rc_ok indicates successful completion of this function.

Any return code other than ok means that this function was called with an invalid 
session identifier or a system error of some kind has occurred.
--------------------------------------------------------------------------------
*/
ismacryp_rc_t ismacrypEndSession(ismacryp_session_id_t session);


/*
--------------------------------------------------------------------------------
These functions are used to set and get the Ismacryp scheme (see specification)
for a given session.

The get function updates the scheme parameter with the only currently-defined 
encryption scheme of iAEC. The set function allows for setting of any defined 
Ismacryp schemes. The session parameter in both functions is the value initially 
obtained with ismaCrypInitSession. 

A return code of ismacryp_rc_ok indicates successful completion of these functions.

Any return code other than ismacryp_rc_ok means that these functions were called 
with invalid session identifiers or a system error has occurred. In this case the 
application must assume that scheme was not properly returned or not properly set.
--------------------------------------------------------------------------------
*/