<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html lang="en" style='--code-editor-font: var(--default-mono-font, "GitLab Mono"), JetBrains Mono, Menlo, DejaVu Sans Mono, Liberation Mono, Consolas, Ubuntu Mono, Courier New, andale mono, lucida console, monospace;'>
<head>
<meta content="text/html; charset=US-ASCII" http-equiv="Content-Type">
<title>
GitLab
</title>
<style data-premailer="ignore" type="text/css">
a { color: #1068bf; }
</style>
<style>img {
max-width: 100%; height: auto;
}
body {
font-size: 0.875rem;
}
body {
-webkit-text-shadow: rgba(255,255,255,0.01) 0 0 1px;
}
body {
font-family: var(--default-regular-font, "GitLab Sans"),-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Noto Sans",Ubuntu,Cantarell,"Helvetica Neue",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji"; font-size: inherit;
}
</style>
</head>
<body style='font-size: inherit; -webkit-text-shadow: rgba(255,255,255,0.01) 0 0 1px; font-family: var(--default-regular-font, "GitLab Sans"),-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Noto Sans",Ubuntu,Cantarell,"Helvetica Neue",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";'>
<div class="content">
<p class="details" style="font-style: italic; color: #737278;">
<a href="https://gitlab.com/dueno">Daiki Ueno</a> created an issue: <a href="https://gitlab.com/gnutls/gnutls/-/issues/1506">#1506</a>
</p>
<div class="md" style="color: #333238; word-wrap: break-word;">
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial"><a href="https://gitlab.com/gnutls/gnutls/-/merge_requests/1749" data-reference-type="merge_request" data-original="!1749" data-link="false" data-link-reference="false" data-project="179611" data-merge-request="228784035" data-project-path="gnutls/gnutls" data-iid="1749" data-container="body" data-placement="top" title="Porting HPKE" class="gfm gfm-merge_request" style="margin-top: 0;">!1749</a> tries to port Nettle's work in progress HPKE implementation for ECH. As HPKE is general purpose mechanism and useful outside of ECH, it would make sense to expose it from the GnuTLS API, possibly in the absract key API.</p>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">The following is the design drafted by <a href="https://gitlab.com/npocs" data-reference-type="user" data-user="5432852" data-container="body" data-placement="top" class="gfm gfm-project_member js-user-link" title="Norbert Pocs" style="background-color: #cbe2f9; border-radius: 4px; color: #0b5cad; margin-top: 0; padding: 0 2px;">@npocs</a> some time ago, with a slight modification:</p>
<h3 dir="auto" style="font-size: 1.3em; margin: 24px 0 16px;" align="initial">
<a id="user-content-new-api-functions" class="anchor" href="#new-api-functions" aria-hidden="true" style="margin-top: 0; float: left; margin-left: -20px; text-decoration: none; outline: none;"></a>New API functions</h3>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-canonical-lang="c" class="code highlight js-syntax-highlight language-c" lang="c" v-pre="true" style='display: block; font-size: 14px; color: #333238; line-height: 1.6em; overflow-x: auto; border-radius: 4px; position: relative; font-family: var(--default-mono-font, "GitLab Mono"),"JetBrains Mono","Menlo","DejaVu Sans Mono","Liberation Mono","Consolas","Ubuntu Mono","Courier New","andale mono","lucida console",monospace; word-break: break-all; word-wrap: break-word; background-color: #fbfafd; margin: 0 0 16px; padding: 12px; border: 1px solid #dcdcde;'><code style='font-size: 0.875rem; color: inherit; word-wrap: normal; word-break: keep-all; background-color: inherit; border-radius: 4px; white-space: pre; margin-top: 0; font-family: var(--default-mono-font, "GitLab Mono"),"JetBrains Mono","Menlo","DejaVu Sans Mono","Liberation Mono","Consolas","Ubuntu Mono","Courier New","andale mono","lucida console",monospace; overflow-wrap: normal; padding: unset;'><span id="LC1" class="line" lang="c" style="margin-top: 0;"><span class="cm" style="margin-top: 0;">/* gnutls_privkey_encap:</span></span>
<span id="LC2" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * @priv: an initialized (and generated) private key</span></span>
<span id="LC3" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * @peer: the public key of the peer side</span></span>
<span id="LC4" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * @mode: the hpke mode to be used, can be: base, auth, psk, auth_psk</span></span>
<span id="LC5" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * @handle: the handle for cipher functions</span></span>
<span id="LC6" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * @key: (out): the calculated shared key</span></span>
<span id="LC7" class="line" lang="c"><span class="cm" style="margin-top: 0;"> *</span></span>
<span id="LC8" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * Performs HPKE encapsulation. Note that gnutls_aead_cipher_init() must be called before this operation.</span></span>
<span id="LC9" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * </span></span>
<span id="LC10" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * Returns: 0 on success, negative error code otherwise</span></span>
<span id="LC11" class="line" lang="c"><span class="cm" style="margin-top: 0;"> */</span></span>
<span id="LC12" class="line" lang="c"><span class="kt" style="margin-top: 0;">int</span> <span class="nf">gnutls_privkey_encap</span> <span class="p">(</span><span class="n">gnutls_privkey_t</span> <span class="n">priv</span><span class="p">,</span> <span class="n">gnutls_pubkey_t</span> <span class="n">peer</span><span class="p">,</span> <span class="n">gnutls_hpke_mode_t</span> <span class="n">mode</span><span class="p">,</span></span>
<span id="LC13" class="line" lang="c"> <span class="n" style="margin-top: 0;">gnutls_aead_cipher_hd_t</span> <span class="o">*</span><span class="n">handle</span><span class="p">,</span> <span class="n">gnutls_datum_t</span> <span class="o">*</span><span class="n">key</span><span class="p">);</span></span>
<span id="LC14" class="line" lang="c"></span>
<span id="LC15" class="line" lang="c"><span class="cm" style="margin-top: 0;">/* gnutls_privkey_decap:</span></span>
<span id="LC16" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * @priv: an initialized (and generated) private key</span></span>
<span id="LC17" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * @peer: the public key of the peer side</span></span>
<span id="LC18" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * @mode: the hpke mode to be used, can be: base, auth, psk, auth_psk</span></span>
<span id="LC19" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * @handle: the handle for cipher functions</span></span>
<span id="LC20" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * @key: (out): the calculated shared key</span></span>
<span id="LC21" class="line" lang="c"><span class="cm" style="margin-top: 0;"> *</span></span>
<span id="LC22" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * Performs HPKE decapsulation. Note that gnutls_aead_cipher_init() must be called before this operation.</span></span>
<span id="LC23" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * </span></span>
<span id="LC24" class="line" lang="c"><span class="cm" style="margin-top: 0;"> * Returns: 0 on success, negative error code otherwise</span></span>
<span id="LC25" class="line" lang="c"><span class="cm" style="margin-top: 0;"> */</span></span>
<span id="LC26" class="line" lang="c"><span class="kt" style="margin-top: 0;">int</span> <span class="nf">gnutls_privkey_decap</span> <span class="p">(</span><span class="n">gnutls_privkey_t</span> <span class="n">priv</span><span class="p">,</span> <span class="n">gnutls_pubkey_t</span> <span class="n">peer</span><span class="p">,</span> <span class="n">gnutls_hpke_mode_t</span> <span class="n">mode</span><span class="p">,</span></span>
<span id="LC27" class="line" lang="c"> <span class="n" style="margin-top: 0;">gnutls_cipher_hd_t</span> <span class="o">*</span><span class="n">handle</span><span class="p">,</span> <span class="n">gnutls_datum_t</span> <span class="o">*</span><span class="n">key</span><span class="p">);</span></span></code></pre>
<copy-code></copy-code>
</div>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">For seal/open <code style='font-size: 0.875rem; color: #1f1e24; word-wrap: break-word; background-color: #ececef; border-radius: 4px; margin-top: 0; font-weight: inherit; font-family: var(--default-mono-font, "GitLab Mono"),"JetBrains Mono","Menlo","DejaVu Sans Mono","Liberation Mono","Consolas","Ubuntu Mono","Courier New","andale mono","lucida console",monospace; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 2px 4px;'>gnutls_aead_cipher_encrypt/decrypt</code> can be freely used instead of creating these new ones.</p>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">Notes:</p>
<ul dir="auto" style="text-align: initial; list-style-type: disc; margin: 0 0 16px; padding: 0;">
<li style="margin-top: 0; line-height: 1.6em; margin-left: 25px; padding-left: 3px;">The KEM context does not need to be saved to a structure, as the user can use it directly with the functions.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">The HPKE mode only affects the public key part of the scheme.</li>
</ul>
<h3 dir="auto" style="font-size: 1.3em; margin: 24px 0 16px;" align="initial">
<a id="user-content-example-usage" class="anchor" href="#example-usage" aria-hidden="true" style="margin-top: 0; float: left; margin-left: -20px; text-decoration: none; outline: none;"></a>Example usage</h3>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">Sender:</p>
<div class="gl-relative markdown-code-block js-markdown-code">
<pre data-canonical-lang="c" class="code highlight js-syntax-highlight language-c" lang="c" v-pre="true" style='display: block; font-size: 14px; color: #333238; line-height: 1.6em; overflow-x: auto; border-radius: 4px; position: relative; font-family: var(--default-mono-font, "GitLab Mono"),"JetBrains Mono","Menlo","DejaVu Sans Mono","Liberation Mono","Consolas","Ubuntu Mono","Courier New","andale mono","lucida console",monospace; word-break: break-all; word-wrap: break-word; background-color: #fbfafd; margin: 0 0 16px; padding: 12px; border: 1px solid #dcdcde;'><code style='font-size: 0.875rem; color: inherit; word-wrap: normal; word-break: keep-all; background-color: inherit; border-radius: 4px; white-space: pre; margin-top: 0; font-family: var(--default-mono-font, "GitLab Mono"),"JetBrains Mono","Menlo","DejaVu Sans Mono","Liberation Mono","Consolas","Ubuntu Mono","Courier New","andale mono","lucida console",monospace; overflow-wrap: normal; padding: unset;'><span id="LC1" class="line" lang="c" style="margin-top: 0;"><span class="n" style="margin-top: 0;">gnutls_aead_cipher_hd_t</span> <span class="n">handle</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span></span>
<span id="LC2" class="line" lang="c"><span class="n" style="margin-top: 0;">gnutls_datum_t</span> <span class="n">key</span><span class="p">;</span></span>
<span id="LC3" class="line" lang="c"><span class="n" style="margin-top: 0;">gnutls_hpke_mode</span> <span class="n">mode</span> <span class="o">=</span> <span class="n">GNUTLS_HPKE_MODE_BASE</span><span class="p">;</span></span>
<span id="LC4" class="line" lang="c"><span class="n" style="margin-top: 0;">gnutls_privkey_t</span> <span class="n">priv</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span></span>
<span id="LC5" class="line" lang="c"><span class="kt" style="margin-top: 0;">int</span> <span class="n">ret</span><span class="p">;</span></span>
<span id="LC6" class="line" lang="c"></span>
<span id="LC7" class="line" lang="c"><span class="n" style="margin-top: 0;">ret</span> <span class="o">=</span> <span class="n">gnutls_privkey_init</span><span class="p">(</span><span class="o">&</span><span class="n">priv</span><span class="p">);</span></span>
<span id="LC8" class="line" lang="c"><span class="n" style="margin-top: 0;">ret</span> <span class="o">=</span> <span class="n">gnutls_privkey_generate2</span><span class="p">(</span><span class="n">priv</span><span class="p">,</span> <span class="n">GNUTLS_PK_ECDH_X25519</span><span class="p">,</span> <span class="p">...);</span></span>
<span id="LC9" class="line" lang="c"></span>
<span id="LC10" class="line" lang="c"><span class="cm" style="margin-top: 0;">/* this creates the shared key and stores it in `key` */</span></span>
<span id="LC11" class="line" lang="c"><span class="n" style="margin-top: 0;">ret</span> <span class="o">=</span> <span class="n">gnutls_privkey_encap</span><span class="p">(</span><span class="n">priv</span><span class="p">,</span> <span class="n">peer</span><span class="p">,</span> <span class="n">mode</span><span class="p">,</span> <span class="n">handle</span><span class="p">,</span> <span class="o">&</span><span class="n">key</span><span class="p">);</span></span>
<span id="LC12" class="line" lang="c"></span>
<span id="LC13" class="line" lang="c"><span class="n" style="margin-top: 0;">ret</span> <span class="o">=</span> <span class="n">gnutls_aead_cipher_init</span><span class="p">(</span><span class="o">&</span><span class="n">handle</span><span class="p">,</span> <span class="n">GNUTLS_CIPHER_AES_128_GCM</span><span class="p">,</span> <span class="o">&</span><span class="n">key</span><span class="p">);</span></span>
<span id="LC14" class="line" lang="c"><span class="n" style="margin-top: 0;">ret</span> <span class="o">=</span> <span class="n">gnutls_aead_cipher_encrypt</span><span class="p">(</span><span class="n">handle</span><span class="p">,</span> <span class="err">…</span><span class="p">);</span></span>
<span id="LC15" class="line" lang="c"></span>
<span id="LC16" class="line" lang="c"><span class="cm" style="margin-top: 0;">/* doing other stuff */</span></span>
<span id="LC17" class="line" lang="c"></span>
<span id="LC18" class="line" lang="c"><span class="cm" style="margin-top: 0;">/* cleanup */</span></span>
<span id="LC19" class="line" lang="c"><span class="p" style="margin-top: 0;">...</span></span></code></pre>
<copy-code></copy-code>
</div>
<p dir="auto" style="color: #333238; margin: 0 0 16px;" align="initial">Receiver:</p>
<div class="gl-relative markdown-code-block js-markdown-code" style="margin-bottom: 0;">
<pre data-canonical-lang="c" class="code highlight js-syntax-highlight language-c" lang="c" v-pre="true" style='display: block; font-size: 14px; color: #333238; line-height: 1.6em; overflow-x: auto; border-radius: 4px; position: relative; font-family: var(--default-mono-font, "GitLab Mono"),"JetBrains Mono","Menlo","DejaVu Sans Mono","Liberation Mono","Consolas","Ubuntu Mono","Courier New","andale mono","lucida console",monospace; word-break: break-all; word-wrap: break-word; background-color: #fbfafd; margin: 0 0 16px; padding: 12px; border: 1px solid #dcdcde;'><code style='font-size: 0.875rem; color: inherit; word-wrap: normal; word-break: keep-all; background-color: inherit; border-radius: 4px; white-space: pre; margin-top: 0; font-family: var(--default-mono-font, "GitLab Mono"),"JetBrains Mono","Menlo","DejaVu Sans Mono","Liberation Mono","Consolas","Ubuntu Mono","Courier New","andale mono","lucida console",monospace; overflow-wrap: normal; padding: unset;'><span id="LC1" class="line" lang="c" style="margin-top: 0;"><span class="n" style="margin-top: 0;">gnutls_aead_cipher_hd_t</span> <span class="n">handle</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span></span>
<span id="LC2" class="line" lang="c"><span class="n" style="margin-top: 0;">gnutls_datum_t</span> <span class="n">key</span><span class="p">;</span></span>
<span id="LC3" class="line" lang="c"><span class="n" style="margin-top: 0;">gnutls_hpke_mode</span> <span class="n">mode</span> <span class="o">=</span> <span class="n">GNUTLS_HPKE_MODE_BASE</span><span class="p">;</span></span>
<span id="LC4" class="line" lang="c"><span class="n" style="margin-top: 0;">gnutls_privkey_t</span> <span class="n">priv</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span></span>
<span id="LC5" class="line" lang="c"><span class="kt" style="margin-top: 0;">int</span> <span class="n">ret</span><span class="p">;</span></span>
<span id="LC6" class="line" lang="c"></span>
<span id="LC7" class="line" lang="c"><span class="n" style="margin-top: 0;">ret</span> <span class="o">=</span> <span class="n">gnutls_privkey_init</span><span class="p">(</span><span class="o">&</span><span class="n">priv</span><span class="p">);</span></span>
<span id="LC8" class="line" lang="c"><span class="n" style="margin-top: 0;">ret</span> <span class="o">=</span> <span class="n">gnutls_privkey_import_x509</span><span class="p">(</span><span class="n">priv</span><span class="p">,</span> <span class="p">...);</span></span>
<span id="LC9" class="line" lang="c"></span>
<span id="LC10" class="line" lang="c"><span class="cm" style="margin-top: 0;">/* this creates the shared key and stores it in `key` */</span></span>
<span id="LC11" class="line" lang="c"><span class="n" style="margin-top: 0;">ret</span> <span class="o">=</span> <span class="n">gnutls_privkey_decap</span><span class="p">(</span><span class="n">priv</span><span class="p">,</span> <span class="n">peer</span><span class="p">,</span> <span class="n">mode</span><span class="p">,</span> <span class="n">handle</span><span class="p">,</span> <span class="o">&</span><span class="n">key</span><span class="p">);</span></span>
<span id="LC12" class="line" lang="c"></span>
<span id="LC13" class="line" lang="c"><span class="n" style="margin-top: 0;">ret</span> <span class="o">=</span> <span class="n">gnutls_aead_cipher_init</span><span class="p">(</span><span class="o">&</span><span class="n">handle</span><span class="p">,</span> <span class="n">GNUTLS_CIPHER_AES_128_GCM</span><span class="p">,</span> <span class="o">&</span><span class="n">key</span><span class="p">);</span></span>
<span id="LC14" class="line" lang="c"><span class="n" style="margin-top: 0;">ret</span> <span class="o">=</span> <span class="n">gnutls_aead_cipher_decrypt</span><span class="p">(</span><span class="n">handle</span><span class="p">,</span> <span class="err">…</span><span class="p">);</span></span>
<span id="LC15" class="line" lang="c"></span>
<span id="LC16" class="line" lang="c"><span class="cm" style="margin-top: 0;">/* doing other stuff */</span></span>
<span id="LC17" class="line" lang="c"></span>
<span id="LC18" class="line" lang="c"><span class="cm" style="margin-top: 0;">/* cleanup */</span></span>
<span id="LC19" class="line" lang="c"><span class="p" style="margin-top: 0;">...</span></span></code></pre>
<copy-code></copy-code>
</div>
</div>
</div>
<div class="footer" style="margin-top: 10px;">
<p style="font-size: small; color: #737278;">
—
<br>
Reply to this email directly or <a href="https://gitlab.com/gnutls/gnutls/-/issues/1506">view it on GitLab</a>.
<br>
You're receiving this email because of your account on <a target="_blank" rel="noopener noreferrer" href="https://gitlab.com">gitlab.com</a>. <a href="https://gitlab.com/-/sent_notifications/acf148aeaf1af6b75975ab56090427c1/unsubscribe" target="_blank" rel="noopener noreferrer">Unsubscribe</a> from this thread · <a href="https://gitlab.com/-/profile/notifications" target="_blank" rel="noopener noreferrer" class="mng-notif-link">Manage all notifications</a> · <a href="https://gitlab.com/help" target="_blank" rel="noopener noreferrer" class="help-link">Help</a>
<script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","action":{"@type":"ViewAction","name":"View Issue","url":"https://gitlab.com/gnutls/gnutls/-/issues/1506"}}</script>
</p>
</div>
</body>
</html>