ismacryplib.h

完整的RTP RTSP代码库

ismacryp_rc_t ismacrypGetKey(ismacryp_session_id_t session,
                              uint8_t key_num,
                              uint8_t *key_len,
                              uint8_t *salt_len,
                              uint8_t **key,
                              uint8_t **salt,
                              uint8_t *lifetime_exp);

/*
--------------------------------------------------------------------------------

This API has the same signature as ismacrypGetKey, but instead
of making copies of key and salt in malloc buffers, this API
instead updates key and salt pointers to the live key and salt
buffers.  When using this API, the application must NOT attempt
to free the key and salt pointers!
--------------------------------------------------------------------------------*/

ismacryp_rc_t ismacrypGetKey2(ismacryp_session_id_t session,
                              uint8_t key_num,
                              uint8_t *key_len,
                              uint8_t *salt_len,
                              uint8_t **key,
                              uint8_t **salt,
                              uint8_t *lifetime_exp);

/*
--------------------------------------------------------------------------------

These APIs deallocate and allocate cipher resources for the specified 
session ID.  Used internally and externally, they can be used by application 
to alter cipher on-the-fly.  typical calling sequence is as follows:
1.  retrieve current keying material pointers and attributes
    first established by ismacrypInitSession:
	ismacrypGetKey2() 
2. application updates key and salt using pointers returned
   in step 1.
3. unload current cipher 
	unInitSessionData(...)
4. load new cipher and init crypto context
	initSessionData(...)
--------------------------------------------------------------------------------*/

ismacryp_rc_t unInitSessionData(ismacryp_session_id_t session);
ismacryp_rc_t initSessionData(ismacryp_session_id_t session);



/*
--------------------------------------------------------------------------------
This function is used to encrypt a sample, or buffer of data. The session 
parameter is the value initially obtained with ismaCrypInitSession. The data 
parameter is a pointer to the buffer holding that data that is to be encrypted. 
The length parameter is the length of the data buffer in bytes. The data will be 
encrypted in place. Return code of ismacryp_rc_ok indicates successful completion 
of this function. 

The location in the data stream for this session is updated by this function.
AES ICM requires knowledge of the point in the data stream at which a buffer
of data begins in order to properly operate. This information is kept in the
session state. As such, this function must be called for each buffer of data
in the exact order in which it appears in the data stream

It is critically important that the length parameter be correct. A length value 
shorter than the actual data buffer will result in some of the data not being 
encrypted. A length value longer than the actual data buffer will result in 
unpredictable errors or catastrophic failure.

Any return code other than ismacryp_rc_ok means that the function was called 
with an invalid session identifier or a system error has occurred. In this case 
the application must assume that the data buffer was not properly encrypted.

Data encrypted with this function should be decrypted using 
ismacrypDecryptSample
--------------------------------------------------------------------------------
*/
ismacryp_rc_t ismacrypEncryptSample(ismacryp_session_id_t session,
                                    uint32_t length,
                                    uint8_t *data ); 


/*
--------------------------------------------------------------------------------
This function is used to encrypt a sample, or buffer of data. The session 
parameter is the value initially obtained with ismaCrypInitSession. The data 
parameter is a pointer to the buffer holding that data that is to be encrypted. 
The length parameter is the length of the data buffer in bytes. 

Unlike ismacrypEncryptSample, the data will not be encrypted in place. Rather
a new buffer is allocated and the data is copied to that buffer and encrypted
in the new buffer with Ismacryp protocol headers prepended to the data. 
The new_length parameter is updated with the length of the new_data buffer.
It is the responsibility of the application to free the new_data buffer.

The location in the data stream for this session is updated by this function.
AES ICM requires knowledge of the point in the data stream at which a buffer
of data begins in order to properly operate. This information is kept in the
session state. As such, this function must be called for each buffer of data
in the exact order in which it appears in the data stream

Return code of ismacryp_rc_ok indicates successful completion of this function. 

Any return code other than ismacryp_rc_ok means that the function was called 
with an invalid session identifier or a system error has occurred. In this case 
the application must assume that the data buffer was not properly encrypted.

Data encrypted with this function should be decrypted using 
ismacrypDecryptSampleRemoveHeader
--------------------------------------------------------------------------------
*/
ismacryp_rc_t ismacrypEncryptSampleAddHeader(ismacryp_session_id_t session,
                                    uint32_t length,
                                    uint8_t *data,
                                    uint32_t *new_length,
                                    uint8_t **new_data);

uint32_t ismacrypEncryptSampleAddHeader2 (uint32_t session,
                                          uint32_t length,
                                          uint8_t *data,
                                          uint32_t *new_length,
                                          uint8_t **new_data);

/*
--------------------------------------------------------------------------------
This function is used to decrypt a sample, or buffer of data, that was previously 
encrypted with ismacrypEncryptSample. The session parameter is the value initially 
obtained with ismaCrypInitSession. The data parameter is a pointer to the buffer 
holding that data that is to be encrypted. The length parameter is the length of 
the data buffer in bytes. The data will be decrypted in place. 

Return code of ismacryp_rc_ok indicates successful completion of this function. 

The location in the data stream for this session is updated by this function.
AES ICM requires knowledge of the point in the data stream at which a buffer
of data begins in order to properly operate. This information is kept in the
session state. As such, this function must be called for each buffer of data
in the exact order in which it appears in the data stream.

It is critically important that the length parameter be correct. A length value 
shorter than the actual data buffer will result in some of the data not being 
decrypted. A length value longer than the actual data buffer will result in 
unpredictable errors or catastrophic failure.

Any return code other than ismacryp_rc_ok means that the function was called with 
an invalid session identifier or a system error has occurred. In this case the 
application must assume that the data buffer was not properly decrypted.
--------------------------------------------------------------------------------
*/
ismacryp_rc_t ismacrypDecryptSample(ismacryp_session_id_t session,
                                    uint32_t length,
                                    uint8_t *data);

/*
--------------------------------------------------------------------------------
This function is used to decrypt a sample, or buffer of data, that was previously
encrypted with ismacrypEncryptSampleAddHeader. The session parameter is the value 
initially obtained with ismaCrypInitSession. The data parameter is a pointer to 
the buffer holding that data that is to be decrypted.  The length parameter is 
the length of the data buffer in bytes. 

Unlike ismacrypDecryptSample, the data will not be decrypted in place. Rather
a new buffer is allocated and the data is copied to that buffer and decrypted
in the new buffer with Ismacryp protocol headers removed.  The new_length 
parameter is updated with the length of the new_data buffer.
It is the responsibility of the application to free the new_data buffer.

The location in the data stream for this session is updated by this function.
AES ICM requires knowledge of the point in the data stream at which a buffer
of data begins in order to properly operate. This information is kept in the
session state. As such, this function must be called for each buffer of data
in the exact order in which it appears in the data stream.

Return code of ismacryp_rc_ok indicates successful completion of this function. 

Any return code other than ismacryp_rc_ok means that the function was called 
with an invalid session identifier or a system error has occurred. In this case 
the application must assume that the data buffer was not properly encrypted.

Data encrypted with this function should be decrypted using 
ismacrypDecryptSampleRemoveHeader
--------------------------------------------------------------------------------
*/
ismacryp_rc_t ismacrypDecryptSampleRemoveHeader(ismacryp_session_id_t session,
                                    uint32_t length,
                                    uint8_t *data,
                                    uint32_t *new_length,
                                    uint8_t **new_data);


/*
--------------------------------------------------------------------------------
This function is used to decrypt a sample, or buffer of data, that was previously 
encrypted with ismacrypEncryptSample. The session parameter is the value initially 
obtained with ismaCrypInitSession. The data parameter is a pointer to the buffer 
holding that data that is to be encrypted. The length parameter is the length of 
the data buffer in bytes. The data will be decrypted in place. 

Return code of ismacryp_rc_ok indicates successful completion of this function. 

The location in the data stream for this session is NOT updated by this function.
AES ICM requires knowledge of the point in the data stream at which a buffer
of data begins in order to properly operate. This information is provided to 
the function by the BSO paramater. BSO is Ismacryp speak for Byte Steam Offset.
Counting in a data stream starts at 0 for the first byte and increments by
1 for each subsequent byte.

Unlike the the other encryption and decryption functions where the location in 
the byte stream of data for a session is kept by the session state, this function
allows decryption of data starting from any random point in the data stream.

It is critically important that the length parameter be correct. A length value 
shorter than the actual data buffer will result in some of the data not being 
decrypted. A length value longer than the actual data buffer will result in 
unpredictable errors or catastrophic failure.

Any return code other than ismacryp_rc_ok means that the function was called with 
an invalid session identifier or a system error has occurred. In this case the 
application must assume that the data buffer was not properly decrypted.
--------------------------------------------------------------------------------
*/
ismacryp_rc_t ismacrypDecryptSampleRandomAccess(ismacryp_session_id_t session,
                                    uint32_t BSO,
                                    uint32_t length,
                                    uint8_t *data);

#ifdef __cplusplus
}
#endif
#endif /* ifndef ISMACRYPLIB_H */