1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE task

    11   PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

    12 <task id="GUID-7B6073BF-6D8C-5F00-98EC-966573777677" xml:lang="en"><title>Managing

    13 Master Key</title><abstract><p>The Secure Real-Time Transport Protocol (SRTP) stream requires

    14 the sender and receiver to maintain the cryptographic context of the packets.

    15 SRTP uses two types of keys: master keys and session keys for packet encryption

    16 and decryption. Master key is a random bit string. The session keys are derived

    17 from the master key. The Session key is used directly in cryptographic transform

    18 for encryption or message authentication.  </p><p> A single master key provides

    19 keying material for confidentiality and integrity protection of both SRTP

    20 and the corresponding SRTCP stream. For each master key, a count of processed

    21 packets is maintained. There is a limit on the number of packets processed

    22 by a single master key. SRTCP maintains a separate counter for master key

    23 even if the master key is the same as that for SRTP. The counter counts the

    24 number of SRTCP packets processed with the key.   </p><p>The SRTP stack checks

    25 for the count of packet processed when the RTP/RTCP packets are encrypted

    26 or decrypted. If the number of packets processed is maximum, the master key

    27 status is identified as stale. The SRTP notifies the SRTP client of the master

    28 key status. This is Notifying the Master Key Expiry.  </p><p> The SRTP stack

    29 can request for a new master key(ReKey) even before the master key status

    30 is identified as stale.This is ReKey request.</p></abstract><prolog><metadata><keywords/></metadata></prolog><taskbody>

    31 <prereq id="GUID-E3BEB74D-79C7-59A9-9366-CCD8B52DB7F8-GENID-1-7-1-19-1-1-6-1-5-1-10-1-3-1"><p>An SRTP session

    32 must be created and initialized before an application requests for a RTP/RTCP

    33 packet decryption and encryption. </p> <p>The two variants of the API <xref href="GUID-4301A1D8-5A9B-39F6-B4F0-84A7A1698617.dita"><apiname>SRTPMasterKeyStaleEvent()</apiname></xref> must be

    34 implemented by the application. </p> </prereq>

    35 <steps id="GUID-FB88B32D-6FD6-504B-A39F-D2882FF355FB">

    36 <step id="GUID-B7B460C7-C6C2-5AB0-957B-2ABA30877680"><cmd>An RTP/RTCP packet

    37 is encrypted or decrypted . </cmd>

    38 </step>

    39 <step id="GUID-67F4846F-16C8-5DB1-ABB2-3886993AF5A4"><cmd>The SRTP uses the

    40 current master key to check the count of packet processed. If the number of

    41 packets processed is not the maximum permissible value, the count is increased.

    42 If the number of packets processed has reached maximum permissible value,

    43 the SRTP DLL notifies the expiry(stale) state of the current master key. </cmd>

    44 </step>

    45 <step id="GUID-BB007F89-6FC5-58D0-9C89-5A04643C508F"><cmd>The SRTP DLL notifies

    46 the master key status using the API's <xref href="GUID-4301A1D8-5A9B-39F6-B4F0-84A7A1698617.dita"><apiname>SRTPMasterKeyStaleEvent()</apiname></xref> of

    47 the class <xref href="GUID-4301A1D8-5A9B-39F6-B4F0-84A7A1698617.dita"><apiname>MSRTPReKeyingObserver</apiname></xref> .The

    48 notification can be initiated by MSRTPReKeyingObserver or CSRTPSession. </cmd>

    49 <substeps id="GUID-7DD25E11-8593-53E4-AFFB-1DEFBA4EB9EC">

    50 <substep id="GUID-69A703E5-6CA8-5BC1-A910-533981F9374C"><cmd/>

    51 <info>The prototypes for both the variants of <xref href="GUID-4301A1D8-5A9B-39F6-B4F0-84A7A1698617.dita"><apiname>SRTPMasterKeyStaleEvent()</apiname></xref> are

    52 described below: </info>

    53 <info><ul>

    54 <li id="GUID-B9D9F267-48AD-55A6-AD8A-54B3C85C8764"><codeblock id="GUID-4373AEA4-66E2-5968-B6C9-13E300C1617B" xml:space="preserve"> virtual void SRTPMasterKeyStaleEvent(const CSRTPStream&amp; aStream)=0;

    55                      

    56                   </codeblock> <p>This API is called

    57 by the SRTP Stream initiated with MSRTPReKeyingObserver, if a master key is

    58 identified as stale and needs to be refreshed. </p> <p>aStream is the input

    59 parameter. It contains the stream of the master key that needs to be refreshed. </p> </li>

    60 </ul> </info>

    61 <info><ul>

    62 <li id="GUID-A652F1E7-E2F9-59CB-B050-8FB3221FD7FA"><codeblock id="GUID-12C8EF78-DA37-5BA4-A62E-162B32EC301A" xml:space="preserve"> virtual void SRTPMasterKeyStaleEvent(const CSRTPSession&amp; aSession)=0;

    63                      

    64                   </codeblock> <p>This API is called

    65 by SRTP Stream initiated with CSRTPSession if a master key is identified as

    66 stale and needs to be refreshed. </p> <p>aSession is the input parameter.

    67 It contains the session of the master key that needs to be refreshed. </p> </li>

    68 </ul> </info>

    69 </substep>

    70 </substeps>

    71 </step>

    72 <step id="GUID-4A10324C-9356-5083-B109-C1CE1EEDEBED"><cmd>The SRTP DLL requests

    73 for a new master key using the API <xref href="GUID-4301A1D8-5A9B-39F6-B4F0-84A7A1698617.dita"><apiname> 

    74                ReKeyNeeded()</apiname></xref> of the class<xref href="GUID-4301A1D8-5A9B-39F6-B4F0-84A7A1698617.dita"><apiname>CSRTPSession</apiname></xref>. </cmd>

    75 <substeps id="GUID-56DEF32A-0762-5D93-9F5D-D025DBB03533">

    76 <substep id="GUID-876D52C4-F774-569F-9A09-BEAD80557D07"><cmd/>

    77 <info>The prototype of the API is as described below: </info>

    78 <info><ul>

    79 <li id="GUID-06E4B681-D1C0-52C3-AE2B-A5BA4F5A037D"><codeblock id="GUID-B005930E-F049-5144-AF9F-2AD38DCF1F50" xml:space="preserve">void ReKeyNeeded(const CSRTPStream&amp; aStream, TBool aIsStrmCrypto);

    80                      

    81                   </codeblock> <p>This API requests

    82 for ReKey. </p> <p>aStream is the input parameter that needs the Rekey. </p> <p>aIsStrmCrypto

    83 is the boolean input parameter. It contains true if stream has its own cryptographic

    84 context. Else the value is false. </p> </li>

    85 </ul> </info>

    86 </substep>

    87 </substeps>

    88 </step>

    89 </steps>

    90 <result><p>SRTP stack notifies the SRTP client of the master key expiry state. </p> <p>SRTP

    91 stack requests for ReKey. </p> </result>

    92 </taskbody><related-links>

    93 <link href="GUID-06370120-7738-5694-9A8C-3B5B1E3A4352.dita"><linktext>Creating

    94 an SRTP                 Session</linktext></link>

    95 <link href="GUID-425A208C-5D2D-55FD-8623-9E00006E2781.dita"><linktext>Creating

    96 a                 Cryptographic Context</linktext></link>

    97 <link href="GUID-372B7A9F-261E-5F3F-B114-4BE2FE2EF7C7.dita"><linktext>Creating

    98 an SRTP                 Stream</linktext></link>

    99 <link href="GUID-79846EA2-33CD-5D01-8E96-6092C15BD839.dita"><linktext>Encrypting

   100                 RTCP Packet Data</linktext></link>

   101 <link href="GUID-922F292E-9420-593B-B226-2764C5F29DF9.dita"><linktext>Encrypting

   102 RTP                 Packet Data</linktext></link>

   103 <link href="GUID-6E1AC4C9-7CA3-503A-AFC0-BAF29CCA8290.dita"><linktext>Decrypting

   104 RTP                 Packet Data</linktext></link>

   105 <link href="GUID-F9A24A47-7A0B-5F6E-8B0A-B7A7BCC4EAFC.dita"><linktext>Decrypting

   106                 RTCP Packet Data</linktext></link>

   107 <link href="GUID-B9BD2E0A-F214-5344-91A6-E4E99F0D74C8.dita"><linktext>Updating

   108 Master                 Key</linktext></link>

   109 </related-links></task>