mirror of
https://codeberg.org/scip/pcp.git
synced 2025-12-17 20:00:58 +01:00
131 lines
11 KiB
HTML
131 lines
11 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||
|
|
<title>libpcp: Main Page</title>
|
||
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="jquery.js"></script>
|
||
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
||
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
|
|
<div id="titlearea">
|
||
|
|
<table cellspacing="0" cellpadding="0">
|
||
|
|
<tbody>
|
||
|
|
<tr style="height: 56px;">
|
||
|
|
<td style="padding-left: 0.5em;">
|
||
|
|
<div id="projectname">libpcp
|
||
|
|
 <span id="projectnumber">0.2.1</span>
|
||
|
|
</div>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<!-- end header part -->
|
||
|
|
<!-- Generated by Doxygen 1.8.2 -->
|
||
|
|
<div id="navrow1" class="tabs">
|
||
|
|
<ul class="tablist">
|
||
|
|
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
|
||
|
|
<li><a href="modules.html"><span>Modules</span></a></li>
|
||
|
|
<li><a href="annotated.html"><span>Classes</span></a></li>
|
||
|
|
<li><a href="files.html"><span>Files</span></a></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div><!-- top -->
|
||
|
|
<div class="header">
|
||
|
|
<div class="headertitle">
|
||
|
|
<div class="title">libpcp Documentation</div> </div>
|
||
|
|
</div><!--header-->
|
||
|
|
<div class="contents">
|
||
|
|
<div class="textblock"><h1><a class="anchor" id="intro_sec"></a>
|
||
|
|
Introduction</h1>
|
||
|
|
<p>This is the API documentation of libpcp, the library behind <a href="/PrettyCurvedPrivacy">Pretty Curved Privacy (pcp)</a>. The library can be used independently of pcp to manage keys and to encrypt or sign files or buffers.</p>
|
||
|
|
<p>For most actual crypto related things, libpcp uses <a href="https://github.com/jedisct1/libsodium">libsodium, the portable NaCL library</a>.</p>
|
||
|
|
<h1><a class="anchor" id="sample_sec"></a>
|
||
|
|
Sample usage</h1>
|
||
|
|
<p>Example use of the libpcp library:</p>
|
||
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <pcp.h></span></div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"><span class="keywordtype">int</span> main() {</div>
|
||
|
|
<div class="line"> <a class="code" href="struct__pcp__buffer.html" title="A flexible buffer object wich automatically resizes, if neccessary.">Buffer</a> *inbuf;</div>
|
||
|
|
<div class="line"> <a class="code" href="struct__pcp__key__t.html" title="PCP private key structure.">pcp_key_t</a> *alice, *bob;</div>
|
||
|
|
<div class="line"> <a class="code" href="struct__pcp__pubkey__t.html" title="PCP public key structure.">pcp_pubkey_t</a> *alicepub, *bobpub, *pubhash;</div>
|
||
|
|
<div class="line"> <a class="code" href="struct__pcp__stream__t.html" title="An I/O wrapper object backed by a file or a buffer.">Pcpstream</a> *clear_in, *crypt_out, *clear_out;</div>
|
||
|
|
<div class="line"> <span class="keywordtype">char</span> message[] = <span class="stringliteral">"hello world"</span>; </div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="comment">/* generate the keypairs for both */</span></div>
|
||
|
|
<div class="line"> alice = <a class="code" href="group__KEYS.html#gaecf6a1829b4133350a7cb694c3eca8ad" title="Generate a new key structure.">pcpkey_new</a>();</div>
|
||
|
|
<div class="line"> bob = <a class="code" href="group__KEYS.html#gaecf6a1829b4133350a7cb694c3eca8ad" title="Generate a new key structure.">pcpkey_new</a>();</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="comment">/* get the public parts of them */</span></div>
|
||
|
|
<div class="line"> alicepub = <a class="code" href="group__KEYS.html#ga22c965c007208e860deaa4c145046283" title="Generate a public key structure from a given secret key structure.">pcpkey_pub_from_secret</a>(alice);</div>
|
||
|
|
<div class="line"> bobpub = <a class="code" href="group__KEYS.html#ga22c965c007208e860deaa4c145046283" title="Generate a public key structure from a given secret key structure.">pcpkey_pub_from_secret</a>(bob);</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="comment">/* put the clear text message into the stream */</span></div>
|
||
|
|
<div class="line"> inbuf = <a class="code" href="group__Buffer.html#ga55e468b36750f28308b7fa5dfea5b564" title="Create a new buffer.">buffer_new</a>(32, <span class="stringliteral">"a"</span>);</div>
|
||
|
|
<div class="line"> <a class="code" href="group__Buffer.html#ga5b99c0ae55b2e279339c745b6fd7bb21" title="Add a formated string to the buffer.">buffer_add_str</a>(inbuf, message);</div>
|
||
|
|
<div class="line"> clear_in = <a class="code" href="group__Pcpstream.html#ga1b50c92fdad290e59317af2404460662" title="Create a new input stream, backed with filled a buffer.">ps_new_inbuffer</a>(inbuf);</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="comment">/* create the output stream as buffer */</span></div>
|
||
|
|
<div class="line"> crypt_out = <a class="code" href="group__Pcpstream.html#ga13ec0245b579949e6d586e1817615d2e" title="Create a new output stream, backed with a buffer.">ps_new_outbuffer</a>();</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="comment">/* prepare the pubkey recipient list (only 1 recipient: Bob) */</span></div>
|
||
|
|
<div class="line"> pubhash = NULL;</div>
|
||
|
|
<div class="line"> strncpy(bobpub-><a class="code" href="struct__pcp__pubkey__t.html#ad10eadcb9325538e71c9fd8b140dbdd2" title="key-id, used internally only, jenhash of public keys">id</a>, <a class="code" href="group__KEYS.html#gab16e85cdb769465c8ce8808b581c7a3d" title="Calculate a key-id from public key fields.">pcp_getpubkeyid</a>(bobpub), 17);</div>
|
||
|
|
<div class="line"> HASH_ADD_STR( pubhash, <span class="keywordtype">id</span>, bobpub);</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="comment">/* actually encrypt the message, don't sign it</span></div>
|
||
|
|
<div class="line"><span class="comment"> Alice is the sender, Bob is the recipient */</span></div>
|
||
|
|
<div class="line"> <a class="code" href="group__CRYPTO.html#gadbdb839246cac65ff20ef63902041597" title="Asymmetrically encrypt a file or a buffer stream.">pcp_encrypt_stream</a>(clear_in, crypt_out, alice, pubhash, 0);</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="comment">/* now, print the encrypted result */</span></div>
|
||
|
|
<div class="line"> fprintf(stderr, <span class="stringliteral">"Alice encrypted %ld bytes for Bob:\n"</span>, strlen(message));</div>
|
||
|
|
<div class="line"> <a class="code" href="group__Buffer.html#ga0e0f433cbd077d3048ebdda35aa9ccb6" title="Dump the Buffer contents to stderr in hex form.">buffer_dump</a>(<a class="code" href="group__Pcpstream.html#ga64bc34dfbc1b3951c3d62e82a1ae8c34" title="Access the Buffer backend pointer.">ps_buffer</a>(crypt_out));</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="comment">/* ---- encryption don, now decrypt ---- */</span></div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="comment">/* prepare the output buffer stream */</span></div>
|
||
|
|
<div class="line"> clear_out = <a class="code" href="group__Pcpstream.html#ga13ec0245b579949e6d586e1817615d2e" title="Create a new output stream, backed with a buffer.">ps_new_outbuffer</a>();</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="comment">/* in order for the decryptor find the senders public key,</span></div>
|
||
|
|
<div class="line"><span class="comment"> we need to put it into the global hash. this step can be</span></div>
|
||
|
|
<div class="line"><span class="comment"> omitted when using a Vault. */</span></div>
|
||
|
|
<div class="line"> <a class="code" href="group__KEYHASH.html#ga2953fd446079220a948693dfab5d6055" title="Global hash for public keys.">pcppubkey_hash</a> = NULL;</div>
|
||
|
|
<div class="line"> HASH_ADD_STR( <a class="code" href="group__KEYHASH.html#ga2953fd446079220a948693dfab5d6055" title="Global hash for public keys.">pcppubkey_hash</a> , <span class="keywordtype">id</span>, alicepub);</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="comment">/* try to decrypt the message */</span></div>
|
||
|
|
<div class="line"> <span class="keywordflow">if</span>(<a class="code" href="group__CRYPTO.html#gaeb1196ed4a3edc911e77d1d15612c539" title="Asymmetrically decrypt a file or a buffer stream.">pcp_decrypt_stream</a>(crypt_out, clear_out, bob, NULL, 0) == 0)</div>
|
||
|
|
<div class="line"> <a class="code" href="group__FATALS.html#ga0ea01da59af8a06c55258d78da6cb0cb" title="Prints error messages to STDERR, if there are some.">fatals_ifany</a>();</div>
|
||
|
|
<div class="line"> <span class="keywordflow">else</span> {</div>
|
||
|
|
<div class="line"> <span class="comment">/* and finally print out the decrypted message */</span></div>
|
||
|
|
<div class="line"> fprintf(stderr, <span class="stringliteral">"Bob decrypted %ld bytes from Alice:\n"</span>, <a class="code" href="group__Buffer.html#ga714b0a831d0f31a33e66e8ef76a26e46" title="Tell how much data there is in the buffer available.">buffer_size</a>(<a class="code" href="group__Pcpstream.html#ga64bc34dfbc1b3951c3d62e82a1ae8c34" title="Access the Buffer backend pointer.">ps_buffer</a>(crypt_out)));</div>
|
||
|
|
<div class="line"> printf(<span class="stringliteral">"Decrypted message: %s\n"</span>, <a class="code" href="group__Buffer.html#ga8c89e4ab5d03dff079b7b861a1e04a7f" title="Read the whole Buffer content as string.">buffer_get_str</a>(<a class="code" href="group__Pcpstream.html#ga64bc34dfbc1b3951c3d62e82a1ae8c34" title="Access the Buffer backend pointer.">ps_buffer</a>(clear_out)));</div>
|
||
|
|
<div class="line"> }</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <a class="code" href="group__Pcpstream.html#ga4a68da22eca6e9bd854d54467a071d0a" title="Close the stream and frees allocated memory.">ps_close</a>(clear_in);</div>
|
||
|
|
<div class="line"> <a class="code" href="group__Pcpstream.html#ga4a68da22eca6e9bd854d54467a071d0a" title="Close the stream and frees allocated memory.">ps_close</a>(crypt_out);</div>
|
||
|
|
<div class="line"> <a class="code" href="group__Pcpstream.html#ga4a68da22eca6e9bd854d54467a071d0a" title="Close the stream and frees allocated memory.">ps_close</a>(clear_out);</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> free(alice);</div>
|
||
|
|
<div class="line"> free(alicepub);</div>
|
||
|
|
<div class="line"> free(bob);</div>
|
||
|
|
<div class="line"> free(bobpub);</div>
|
||
|
|
<div class="line"></div>
|
||
|
|
<div class="line"> <span class="keywordflow">return</span> 0;</div>
|
||
|
|
<div class="line">}</div>
|
||
|
|
</div><!-- fragment --><p>To compile the example, use the following commands:</p>
|
||
|
|
<div class="fragment"><div class="line">g++ -c sample.o `pkg-config --cflags libpcp1`</div>
|
||
|
|
<div class="line">g++ sample.o `pkg-config --libs libpcp1` -o sample</div>
|
||
|
|
</div><!-- fragment --> </div></div><!-- contents -->
|
||
|
|
<!-- start footer part -->
|
||
|
|
<hr class="footer"/><address class="footer"><small>
|
||
|
|
Generated on Thu Feb 20 2014 19:59:14 for libpcp by  <a href="http://www.doxygen.org/index.html">
|
||
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/>
|
||
|
|
</a> 1.8.2
|
||
|
|
</small></address>
|
||
|
|
</body>
|
||
|
|
</html>
|