1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="function.sodium-crypto-secretstream-xchacha20poly1305-pull">
<refnamediv>
<refname>sodium_crypto_secretstream_xchacha20poly1305_pull</refname>
<refpurpose>Decrypt a chunk of data from an encrypted stream</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type class="union"><type>array</type><type>false</type></type><methodname>sodium_crypto_secretstream_xchacha20poly1305_pull</methodname>
<methodparam><type>string</type><parameter role="reference">state</parameter></methodparam>
<methodparam><type>string</type><parameter>ciphertext</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>additional_data</parameter><initializer>""</initializer></methodparam>
</methodsynopsis>
<para>
Decrypt a chunk of data from an encrypted stream.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>state</parameter></term>
<listitem>
<para>
See <function>sodium_crypto_secretstream_xchacha20poly1305_init_pull</function>
and <function>sodium_crypto_secretstream_xchacha20poly1305_init_push</function>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ciphertext</parameter></term>
<listitem>
<para>
The ciphertext chunk to decrypt.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>additional_data</parameter></term>
<listitem>
<para>
Optional additional data to include in the authentication tag.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
An array with two values:
<itemizedlist>
<listitem>
<para>
<type>string</type>; The decrypted chunk
</para>
</listitem>
<listitem>
<para>
<type>int</type>; An optional tag (if provided during push). Possible values:
<simplelist>
<member>
<constant>SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE</constant>:
the most common tag, that doesn't add any information about the nature of the message.
</member>
<member>
<constant>SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL</constant>:
indicates that the message marks the end of the stream, and erases the secret key used to encrypt the previous sequence.
</member>
<member>
<constant>SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH</constant>:
indicates that the message marks the end of a set of messages, but not the end of the stream.
For example, a huge JSON string sent as multiple chunks can use this tag to indicate to the application that the
string is complete and that it can be decoded. But the stream itself is not closed, and more data may follow.
</member>
<member>
<constant>SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY</constant>:
"forget" the key used to encrypt this message and the previous ones, and derive a new secret key.
</member>
</simplelist>
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
|
