scip/pcp
1
0
Fork 0
mirror of https://codeberg.org/scip/pcp.git synced 2025-12-17 12:00:56 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
30481fed9a1200078c37a7c5158c42d1e719ec8f
pcp/man/html/group__VAULT.html
TLINDEN 30481fed9a added Pcpstream example
2014-02-20 21:02:52 +01:00

369 lines
22 KiB
HTML
Raw Blame History

<!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: VAULT</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
&#160;<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><a href="index.html"><span>Main&#160;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="summary">
<a href="#nested-classes">Classes</a> &#124;
<a href="#typedef-members">Typedefs</a> &#124;
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">VAULT</div> </div>
</div><!--header-->
<div class="contents">
<p>The vault file is used to store keys and key-signatures on disk.
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Classes</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct__vault__t.html">_vault_t</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">This structure represents a vault. <a href="struct__vault__t.html#details">More...</a><br/></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct__vault__header__t.html">_vault_header_t</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Defines the vault header. <a href="struct__vault__header__t.html#details">More...</a><br/></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="struct__vault__item__header__t.html">_vault_item_header_t</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">An item header. <a href="struct__vault__item__header__t.html#details">More...</a><br/></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="typedef-members"></a>
Typedefs</h2></td></tr>
<tr class="memitem:ga98977ca195f87fe0c70521c07e01ef64"><td class="memItemLeft" align="right" valign="top">typedef struct <a class="el" href="struct__vault__t.html">_vault_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a></td></tr>
<tr class="memdesc:ga98977ca195f87fe0c70521c07e01ef64"><td class="mdescLeft">&#160;</td><td class="mdescRight">Name of the struct. <a href="#ga98977ca195f87fe0c70521c07e01ef64"></a><br/></td></tr>
<tr class="separator:ga98977ca195f87fe0c70521c07e01ef64"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaeeeef6ec087f97f2d73ddd6863db7eba"><td class="memItemLeft" align="right" valign="top">typedef struct <a class="el" href="struct__vault__header__t.html">_vault_header_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__VAULT.html#gaeeeef6ec087f97f2d73ddd6863db7eba">vault_header_t</a></td></tr>
<tr class="memdesc:gaeeeef6ec087f97f2d73ddd6863db7eba"><td class="mdescLeft">&#160;</td><td class="mdescRight">Name of the struct. <a href="#gaeeeef6ec087f97f2d73ddd6863db7eba"></a><br/></td></tr>
<tr class="separator:gaeeeef6ec087f97f2d73ddd6863db7eba"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga3b5f740c6dd319d7876f61c93b7ab72c"><td class="memItemLeft" align="right" valign="top">typedef struct <a class="el" href="struct__vault__item__header__t.html">_vault_item_header_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__VAULT.html#ga3b5f740c6dd319d7876f61c93b7ab72c">vault_item_header_t</a></td></tr>
<tr class="memdesc:ga3b5f740c6dd319d7876f61c93b7ab72c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Name of the struct. <a href="#ga3b5f740c6dd319d7876f61c93b7ab72c"></a><br/></td></tr>
<tr class="separator:ga3b5f740c6dd319d7876f61c93b7ab72c"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga6c4f1297f284440089536a038fdf3376"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__VAULT.html#ga6c4f1297f284440089536a038fdf3376">pcpvault_init</a> (char *filename)</td></tr>
<tr class="memdesc:ga6c4f1297f284440089536a038fdf3376"><td class="mdescLeft">&#160;</td><td class="mdescRight">Open a vault file. <a href="#ga6c4f1297f284440089536a038fdf3376"></a><br/></td></tr>
<tr class="separator:ga6c4f1297f284440089536a038fdf3376"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gad4cf9423cb397da3cd379127f7291faa"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__VAULT.html#gad4cf9423cb397da3cd379127f7291faa">pcpvault_additem</a> (<a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a> *vault, void *item, size_t itemsize, uint8_t type)</td></tr>
<tr class="memdesc:gad4cf9423cb397da3cd379127f7291faa"><td class="mdescLeft">&#160;</td><td class="mdescRight">Add an item to the vault. <a href="#gad4cf9423cb397da3cd379127f7291faa"></a><br/></td></tr>
<tr class="separator:gad4cf9423cb397da3cd379127f7291faa"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaa4ff722fbe407da88fdb893a5c40f7ed"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__VAULT.html#gaa4ff722fbe407da88fdb893a5c40f7ed">pcpvault_addkey</a> (<a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a> *vault, void *item, uint8_t type)</td></tr>
<tr class="memdesc:gaa4ff722fbe407da88fdb893a5c40f7ed"><td class="mdescLeft">&#160;</td><td class="mdescRight">Add a key to the vault. <a href="#gaa4ff722fbe407da88fdb893a5c40f7ed"></a><br/></td></tr>
<tr class="separator:gaa4ff722fbe407da88fdb893a5c40f7ed"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaf0696f85075e0e7c8056e42e2e6a31e6"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__VAULT.html#gaf0696f85075e0e7c8056e42e2e6a31e6">pcpvault_close</a> (<a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a> *vault)</td></tr>
<tr class="memdesc:gaf0696f85075e0e7c8056e42e2e6a31e6"><td class="mdescLeft">&#160;</td><td class="mdescRight">Close a vault file. <a href="#gaf0696f85075e0e7c8056e42e2e6a31e6"></a><br/></td></tr>
<tr class="separator:gaf0696f85075e0e7c8056e42e2e6a31e6"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga303629777a5b784b71ca718c8cda8dbf"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__VAULT.html#ga303629777a5b784b71ca718c8cda8dbf">pcpvault_fetchall</a> (<a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a> *vault)</td></tr>
<tr class="memdesc:ga303629777a5b784b71ca718c8cda8dbf"><td class="mdescLeft">&#160;</td><td class="mdescRight">Reads in the vault contents. <a href="#ga303629777a5b784b71ca718c8cda8dbf"></a><br/></td></tr>
<tr class="separator:ga303629777a5b784b71ca718c8cda8dbf"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>The vault file is used to store keys and key-signatures on disk. </p>
<p>It works like a keyring.</p>
<h1><a class="anchor" id="vformat"></a>
Vault File Format</h1>
<p>The vault file contains all public and secret keys. It's a portable binary file.</p>
<p>The file starts with a header:</p>
<div class="fragment"><div class="line">+-------------------------------------------+</div>
<div class="line">| Field Size Description |</div>
<div class="line">+-------------------------------------------+</div>
<div class="line">| File ID | 1 | Vault Identifier 0xC4 |</div>
<div class="line">+-------------------------------------------+</div>
<div class="line">| Version | 4 | Big endian, <a class="code" href="struct__vault__item__header__t.html#a5d3634c7c9d5050f60444326e0a9eea7" title="Version of the item.">version</a> |</div>
<div class="line">+-------------------------------------------+</div>
<div class="line">| Checksum | 32 | SHA256 Checksum |</div>
<div class="line">+-------------------------------------------+</div>
</div><!-- fragment --><p>The checksum is a checksum of all keys.</p>
<p>The header is followed by the keys. Each key is preceded by an item header which looks like this:</p>
<div class="fragment"><div class="line">+--------------------------------------------+</div>
<div class="line">| Field Size Description |</div>
<div class="line">+--------------------------------------------+</div>
<div class="line">| Type | 1 | Key <a class="code" href="struct__vault__item__header__t.html#a300141ad03ff5f6cb79aafd9984e5e0e" title="Item type (secret key, public, key, keysig,.">type</a> (S,P,M) |</div>
<div class="line">+--------------------------------------------+</div>
<div class="line">| Size | 4 | Big endian, keysize |</div>
<div class="line">+--------------------------------------------+</div>
<div class="line">| Version | 4 | Big endian, keyversion |</div>
<div class="line">+--------------------------------------------+</div>
<div class="line">| Checksum | 32 | SHA256 Key Checksum |</div>
<div class="line">+--------------------------------------------+</div>
</div><!-- fragment --><p>Type can be one of:</p>
<ul>
<li>PCP_KEY_TYPE_MAINSECRET 0x01</li>
<li>PCP_KEY_TYPE_SECRET 0x02</li>
<li>PCP_KEY_TYPE_PUBLIC 0x03</li>
</ul>
<p>The item header is followed by the actual key contents. </p>
<h2 class="groupheader">Typedef Documentation</h2>
<a class="anchor" id="gaeeeef6ec087f97f2d73ddd6863db7eba"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef struct <a class="el" href="struct__vault__header__t.html">_vault_header_t</a> <a class="el" href="group__VAULT.html#gaeeeef6ec087f97f2d73ddd6863db7eba">vault_header_t</a></td>
</tr>
</table>
</div><div class="memdoc">
<p>Name of the struct. </p>
<p>Definition at line <a class="el" href="vault_8h_source.html#l00119">119</a> of file <a class="el" href="vault_8h_source.html">vault.h</a>.</p>
</div>
</div>
<a class="anchor" id="ga3b5f740c6dd319d7876f61c93b7ab72c"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef struct <a class="el" href="struct__vault__item__header__t.html">_vault_item_header_t</a> <a class="el" href="group__VAULT.html#ga3b5f740c6dd319d7876f61c93b7ab72c">vault_item_header_t</a></td>
</tr>
</table>
</div><div class="memdoc">
<p>Name of the struct. </p>
<p>Definition at line <a class="el" href="vault_8h_source.html#l00131">131</a> of file <a class="el" href="vault_8h_source.html">vault.h</a>.</p>
</div>
</div>
<a class="anchor" id="ga98977ca195f87fe0c70521c07e01ef64"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef struct <a class="el" href="struct__vault__t.html">_vault_t</a> <a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a></td>
</tr>
</table>
</div><div class="memdoc">
<p>Name of the struct. </p>
<p>Definition at line <a class="el" href="vault_8h_source.html#l00108">108</a> of file <a class="el" href="vault_8h_source.html">vault.h</a>.</p>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="gad4cf9423cb397da3cd379127f7291faa"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int pcpvault_additem </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a> *&#160;</td>
<td class="paramname"><em>vault</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>item</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t&#160;</td>
<td class="paramname"><em>itemsize</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t&#160;</td>
<td class="paramname"><em>type</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Add an item to the vault. </p>
<p>Adds <em>item</em> with the size <em>itemsize</em> and type <em>type</em> to the vault. Generates the item header and the checksum of the item.</p>
<p>This function writes directly into the vault file. Use with care. To be safe, use <a class="el" href="group__VAULT.html#gaa4ff722fbe407da88fdb893a5c40f7ed" title="Add a key to the vault.">pcpvault_addkey()</a> instead.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[out]</td><td class="paramname">vault</td><td>The vault object. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">item</td><td>The item to write. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">itemsize</td><td>Size of the item. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">type</td><td>Type of the item. </td></tr>
</table>
</dd>
</dl>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="group__KEYS.html#ga19da9fe7a497dcd854feff4d29e4472d" title="Internal key types.">_PCP_KEY_TYPES</a>.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd>Returns the number of bytes written or 0 in case of an error. Check fatals_if_any(). </dd></dl>
</div>
</div>
<a class="anchor" id="gaa4ff722fbe407da88fdb893a5c40f7ed"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int pcpvault_addkey </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a> *&#160;</td>
<td class="paramname"><em>vault</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>item</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t&#160;</td>
<td class="paramname"><em>type</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Add a key to the vault. </p>
<p>This function determines the size of the item to write based on the given type. It converts the internal structure to a binary blob and converty multibyte values to big endian.</p>
<p>It copies the given vault file to a temporary vault file, adds the item and if this went ok, copies the temporary file back to the original location. It then re-calculates the vault checksum and puts it into the vault header.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[out]</td><td class="paramname">vault</td><td>The vault object. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">item</td><td>The item to write (a key or keysig) </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">type</td><td>Type of the item. </td></tr>
</table>
</dd>
</dl>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="group__KEYS.html#ga19da9fe7a497dcd854feff4d29e4472d" title="Internal key types.">_PCP_KEY_TYPES</a>.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd>Returns 0 on success or 1 in case of errors. Check fatals_if_any(). </dd></dl>
</div>
</div>
<a class="anchor" id="gaf0696f85075e0e7c8056e42e2e6a31e6"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int pcpvault_close </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a> *&#160;</td>
<td class="paramname"><em>vault</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Close a vault file. </p>
<p>If the vault is in unsafed state, write everything to disk and close the vault. Before overwriting the current vault file a backup will be made. If anything fails during writing the backup file will be retained and the error message will contain the filename of the backup file, so that the user doesn't loose data.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[out]</td><td class="paramname">vault</td><td>The vault object.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns 0. Check fatals_if_any() anyway. </dd></dl>
</div>
</div>
<a class="anchor" id="ga303629777a5b784b71ca718c8cda8dbf"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int pcpvault_fetchall </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a> *&#160;</td>
<td class="paramname"><em>vault</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Reads in the vault contents. </p>
<p>This function reads the open vault contents and puts them into the apropriate hashes. </p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="group__KEYHASH.html" title="Uthashes of secret and public key structures.">KEYHASH</a>.</dd></dl>
<p>Currently only known types can be read. If your're saving unknown types to the vault, an error will occur. </p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="group__KEYS.html#ga19da9fe7a497dcd854feff4d29e4472d" title="Internal key types.">_PCP_KEY_TYPES</a>.</dd></dl>
<p>Each item will be converted put into the aproprieate structure, multibyte values will be converted to host endianess. It also calculates the checksum of the vault contents and compares it with the one stored in the vault header. If it doesn't match an error will be thrown.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[out]</td><td class="paramname">vault</td><td>The vault object.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns 0 on success or -1 in case of errors. Check fatals_if_any(). </dd></dl>
</div>
</div>
<a class="anchor" id="ga6c4f1297f284440089536a038fdf3376"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__VAULT.html#ga98977ca195f87fe0c70521c07e01ef64">vault_t</a>* pcpvault_init </td>
<td>(</td>
<td class="paramtype">char *&#160;</td>
<td class="paramname"><em>filename</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Open a vault file. </p>
<p>If the file doesn't exist, it will be created.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">filename</td><td>The filename of the vault file.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns a vault object. </dd></dl>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Thu Feb 20 2014 20:58:12 for libpcp by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.2
</small></address>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink