godot/doc/classes/HMACContext.xml
Rémi Verschelde f5836b40d4
doc: Use self-closing tags for return and argument
For the time being we don't support writing a description for those, preferring
having all details in the method's description.

Using self-closing tags saves half the lines, and prevents contributors from
thinking that they should write the argument or return documentation there.

(cherry picked from commit 7adf4cc9b5)
2021-08-03 10:20:19 +02:00

80 lines
2.6 KiB
XML

<?xml version="1.0" encoding="UTF-8" ?>
<class name="HMACContext" inherits="Reference" version="3.4">
<brief_description>
Used to create an HMAC for a message using a key.
</brief_description>
<description>
The HMACContext class is useful for advanced HMAC use cases, such as streaming the message as it supports creating the message over time rather than providing it all at once.
[codeblock]
extends Node
var ctx = HMACContext.new()
func _ready():
var key = "supersecret".to_utf8()
var err = ctx.start(HashingContext.HASH_SHA256, key)
assert(err == OK)
var msg1 = "this is ".to_utf8()
var msg2 = "vewy vewy secret".to_utf8()
err = ctx.update(msg1)
assert(err == OK)
err = ctx.update(msg2)
assert(err == OK)
var hmac = ctx.finish()
print(hmac.hex_encode())
[/codeblock]
And in C# we can use the following.
[codeblock]
using Godot;
using System;
using System.Diagnostics;
public class CryptoNode : Node
{
private HMACContext ctx = new HMACContext();
public override void _Ready()
{
PoolByteArray key = String("supersecret").to_utf8();
Error err = ctx.Start(HashingContext.HASH_SHA256, key);
GD.Assert(err == OK);
PoolByteArray msg1 = String("this is ").to_utf8();
PoolByteArray msg2 = String("vewy vew secret").to_utf8();
err = ctx.Update(msg1);
GD.Assert(err == OK);
err = ctx.Update(msg2);
GD.Assert(err == OK);
PoolByteArray hmac = ctx.Finish();
GD.Print(hmac.HexEncode());
}
}
[/codeblock]
[b]Note:[/b] Not available in HTML5 exports.
</description>
<tutorials>
</tutorials>
<methods>
<method name="finish">
<return type="PoolByteArray" />
<description>
Returns the resulting HMAC. If the HMAC failed, an empty [PoolByteArray] is returned.
</description>
</method>
<method name="start">
<return type="int" enum="Error" />
<argument index="0" name="hash_type" type="int" enum="HashingContext.HashType" />
<argument index="1" name="key" type="PoolByteArray" />
<description>
Initializes the HMACContext. This method cannot be called again on the same HMACContext until [method finish] has been called.
</description>
</method>
<method name="update">
<return type="int" enum="Error" />
<argument index="0" name="data" type="PoolByteArray" />
<description>
Updates the message to be HMACed. This can be called multiple times before [method finish] is called to append [code]data[/code] to the message, but cannot be called until [method start] has been called.
</description>
</method>
</methods>
<constants>
</constants>
</class>