Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
SRTP (Secure Real-time Transport Protocol)

Data Structures

struct  srtp_policy
 SRTP stream protection policy. More...
struct  srtp_stream
 SRTP per-SSRC cryptographic context. More...
struct  srtp_session_ctx
 SRTP state of an RTP session. More...

Macros

#define SRTP_AES_128_KEY_LEN   16
 Length of an AES-128 key in bytes.
#define SRTP_AES_256_KEY_LEN   32
 Length of an AES-256 key in bytes.
#define SRTP_MASTER_SALT_LEN   14
 Length of the SRTP master and session salt in bytes (RFC 3711).
#define SRTP_AES_GCM_SALT_LEN   12
 Length of the SRTP master and session salt in bytes for AES-GCM (RFC 7714).
#define SRTP_HMAC_SHA1_KEY_LEN   20
 Length of a derived HMAC-SHA1 session authentication key in bytes.
#define SRTP_AES_GCM_TAG_LEN   16
 Length of the AES-GCM authentication tag in bytes (RFC 7714).
#define SRTP_AES_GCM_IV_LEN   12
 Length of the AES-GCM initialization vector in bytes (RFC 7714).
#define SRTP_MKI_MAX_LEN   16
 Maximum length of a master key identifier (MKI) in bytes.
#define SRTP_TRAILER_MAX_LEN   (SRTP_AES_GCM_TAG_LEN + SRTP_MKI_MAX_LEN)
 Maximum number of bytes srtp_stream_protect appends to a packet: the authentication tag plus the MKI, when configured.

Enumerations

enum  srtp_cipher { SRTP_CIPHER_NULL , SRTP_CIPHER_AES_128_CM , SRTP_CIPHER_AES_128_GCM , SRTP_CIPHER_AES_256_GCM }
 SRTP encryption transform. More...
enum  srtp_auth { SRTP_AUTH_NULL , SRTP_AUTH_HMAC_SHA1_80 , SRTP_AUTH_HMAC_SHA1_32 }
 SRTP authentication transform. More...

Functions

int srtp_stream_init (struct srtp_stream *stream, const struct srtp_policy *policy, uint32_t ssrc)
 Initialize an SRTP stream from a policy.
int srtp_stream_deinit (struct srtp_stream *stream)
 Release an SRTP stream.
int srtp_stream_protect (struct srtp_stream *stream, uint8_t *buf, size_t pkt_len, size_t buf_size, size_t *out_len)
 Protect a serialized RTP packet in place (RFC 3711, section-3.3).
int srtp_policy_check (const struct srtp_policy *policy)
 Validate an SRTP policy.
int srtp_stream_unprotect (struct srtp_stream *stream, uint8_t *buf, size_t pkt_len, size_t *out_len)
 Unprotect a serialized SRTP packet in place (RFC 3711, section-3.3).

Detailed Description

Version
0.1.0
Since
4.6

SRTP packet protection as defined in RFC 3711, with AES-GCM crypto suites as defined in RFC 7714. Master keys are provisioned by the application; key exchange (DTLS-SRTP, SDES, MIKEY) and SRTCP are out of scope.

Macro Definition Documentation

◆ SRTP_AES_128_KEY_LEN

#define SRTP_AES_128_KEY_LEN   16

#include <zephyr/net/srtp.h>

Length of an AES-128 key in bytes.

◆ SRTP_AES_256_KEY_LEN

#define SRTP_AES_256_KEY_LEN   32

#include <zephyr/net/srtp.h>

Length of an AES-256 key in bytes.

◆ SRTP_AES_GCM_IV_LEN

#define SRTP_AES_GCM_IV_LEN   12

#include <zephyr/net/srtp.h>

Length of the AES-GCM initialization vector in bytes (RFC 7714).

◆ SRTP_AES_GCM_SALT_LEN

#define SRTP_AES_GCM_SALT_LEN   12

#include <zephyr/net/srtp.h>

Length of the SRTP master and session salt in bytes for AES-GCM (RFC 7714).

◆ SRTP_AES_GCM_TAG_LEN

#define SRTP_AES_GCM_TAG_LEN   16

#include <zephyr/net/srtp.h>

Length of the AES-GCM authentication tag in bytes (RFC 7714).

◆ SRTP_HMAC_SHA1_KEY_LEN

#define SRTP_HMAC_SHA1_KEY_LEN   20

#include <zephyr/net/srtp.h>

Length of a derived HMAC-SHA1 session authentication key in bytes.

◆ SRTP_MASTER_SALT_LEN

#define SRTP_MASTER_SALT_LEN   14

#include <zephyr/net/srtp.h>

Length of the SRTP master and session salt in bytes (RFC 3711).

◆ SRTP_MKI_MAX_LEN

#define SRTP_MKI_MAX_LEN   16

#include <zephyr/net/srtp.h>

Maximum length of a master key identifier (MKI) in bytes.

◆ SRTP_TRAILER_MAX_LEN

#define SRTP_TRAILER_MAX_LEN   (SRTP_AES_GCM_TAG_LEN + SRTP_MKI_MAX_LEN)

#include <zephyr/net/srtp.h>

Maximum number of bytes srtp_stream_protect appends to a packet: the authentication tag plus the MKI, when configured.

Enumeration Type Documentation

◆ srtp_auth

enum srtp_auth

#include <zephyr/net/srtp.h>

SRTP authentication transform.

Enumerator
SRTP_AUTH_NULL 

No authentication tag.

Insecure for AES-CM and NULL ciphers; requires explicit opt-in via srtp_policy.allow_null_auth. Mandatory for the AES-GCM ciphers, where the AEAD provides authentication.

SRTP_AUTH_HMAC_SHA1_80 

HMAC-SHA1 with an 80-bit (10-byte) tag (RFC 3711, section-4.2).

SRTP_AUTH_HMAC_SHA1_32 

HMAC-SHA1 with a 32-bit (4-byte) tag (RFC 3711, section-4.2).

◆ srtp_cipher

#include <zephyr/net/srtp.h>

SRTP encryption transform.

Enumerator
SRTP_CIPHER_NULL 

No encryption (RFC 3711, section-4.1.3); packets are authenticated only.

SRTP_CIPHER_AES_128_CM 

AES-128 in counter mode (AES-CM, RFC 3711, section-4.1.1).

SRTP_CIPHER_AES_128_GCM 

AES-128 in Galois/counter mode (RFC 7714).

Authentication is part of the AEAD transform; the policy auth transform must be SRTP_AUTH_NULL.

SRTP_CIPHER_AES_256_GCM 

AES-256 in Galois/counter mode (RFC 7714); session keys are derived via the AES_256_CM_PRF (RFC 6188).

The policy auth transform must be SRTP_AUTH_NULL.

Function Documentation

◆ srtp_policy_check()

int srtp_policy_check ( const struct srtp_policy * policy)

#include <zephyr/net/srtp.h>

Validate an SRTP policy.

Parameters
policyPolicy to validate.
Return values
0When the policy is consistent and complete.
-EINVALOtherwise.

◆ srtp_stream_deinit()

int srtp_stream_deinit ( struct srtp_stream * stream)

#include <zephyr/net/srtp.h>

Release an SRTP stream.

Destroys all PSA keys held by the stream and zeroizes key material.

Parameters
streamStream to release.
Return values
0On success.
negativeErrno value on failure.

◆ srtp_stream_init()

int srtp_stream_init ( struct srtp_stream * stream,
const struct srtp_policy * policy,
uint32_t ssrc )

#include <zephyr/net/srtp.h>

Initialize an SRTP stream from a policy.

Imports the master key, derives the session keys, and prepares the replay protection state. The policy key material is copied into PSA key storage and the stream; the policy structure itself is not referenced afterwards.

Parameters
streamStream to initialize.
policyProtection policy and master key material.
ssrcSynchronization source identifier of the stream.
Return values
0On success.
negativeErrno value on failure.

◆ srtp_stream_protect()

int srtp_stream_protect ( struct srtp_stream * stream,
uint8_t * buf,
size_t pkt_len,
size_t buf_size,
size_t * out_len )

#include <zephyr/net/srtp.h>

Protect a serialized RTP packet in place (RFC 3711, section-3.3).

Encrypts the payload (including any RTP padding) and appends the MKI, when configured, and the authentication tag. buf_size must allow for up to SRTP_TRAILER_MAX_LEN bytes of growth beyond pkt_len.

Calls for the same stream must be serialized by the caller and made with strictly increasing RTP sequence numbers.

Parameters
streamSRTP stream matching the packet's SSRC.
bufBuffer holding a serialized RTP packet.
pkt_lenLength of the RTP packet in bytes.
buf_sizeSize of buf in bytes.
[out]out_lenLength of the protected packet in bytes.
Return values
0On success.
-EKEYEXPIREDWhen 2^48 packets have been protected with this key.
negativeOther errno value on failure.

◆ srtp_stream_unprotect()

int srtp_stream_unprotect ( struct srtp_stream * stream,
uint8_t * buf,
size_t pkt_len,
size_t * out_len )

#include <zephyr/net/srtp.h>

Unprotect a serialized SRTP packet in place (RFC 3711, section-3.3).

Verifies the authentication tag, checks for replay, and decrypts the payload in place. State is only advanced after successful authentication.

Parameters
streamSRTP stream matching the packet's SSRC.
bufBuffer holding a serialized SRTP packet.
pkt_lenLength of the SRTP packet in bytes.
[out]out_lenLength of the plain RTP packet in bytes.
Return values
0On success.
-EBADMSGWhen authentication fails or the packet is malformed.
-EALREADYWhen the packet is a replay.
-ENOENTWhen the packet's MKI does not match the stream's.
negativeOther errno value on failure.