← Back to branch summary

~ubuntu-branches/debian/sid/botan/sid

« back to all changes in this revision

Viewing changes to doc/manual/tpm.rst

  • Committer: Package Import Robot
  • Author(s): Laszlo Boszormenyi (GCS)
  • Date: 2018-03-01 22:23:25 UTC
  • mfrom: (1.2.2)
  • Revision ID: package-import@ubuntu.com-20180301222325-7p7vc45gu3hta34d
Tags: 2.4.0-2
* Don't remove .doctrees from the manual if it doesn't exist.
* Don't specify parallel to debhelper.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/manual/tpm.rst
 
1
Trusted Platform Module (TPM)
 
2
==========================================
 
3
 
 
4
.. versionadded:: 1.11.26
 
5
 
 
6
Some computers come with a TPM, which is a small side processor which can
 
7
perform certain operations which include RSA key generation and signing, a
 
8
random number generator, accessing a small amount of NVRAM, and a set of PCRs
 
9
which can be used to measure software state (this is TPMs most famous use, for
 
10
authenticating a boot sequence).
 
11
 
 
12
The TPM NVRAM and PCR APIs are not supported by Botan at this time, patches welcome.
 
13
 
 
14
Currently only v1.2 TPMs are supported, and the only TPM library supported is
 
15
TrouSerS (http://trousers.sourceforge.net/). Hopefully both of these limitations
 
16
will be removed in a future release, in order to support newer TPM v2.0 systems.
 
17
The current code has been tested with an ST TPM running in a Lenovo laptop.
 
18
 
 
19
Test for TPM support with the macro ``BOTAN_HAS_TPM``, include ``<botan/tpm.h>``.
 
20
 
 
21
First, create a connection to the TPM with a ``TPM_Context``. The context is
 
22
passed to all other TPM operations, and should remain alive as long as any other
 
23
TPM object which the context was passed to is still alive, otherwise errors or
 
24
even an application crash are possible. In the future, the API may change to
 
25
using ``shared_ptr`` to remove this problem.
 
26
 
 
27
.. cpp:class:: TPM_Context
 
28
 
 
29
    .. cpp:function:: TPM_Context(pin_cb cb, const char* srk_password)
 
30
 
 
31
     The (somewhat improperly named) pin_cb callback type takes a std::string as
 
32
     an argument, which is an informative message for the user. It should return
 
33
     a string containing the password entered by the user.
 
34
 
 
35
     Normally the SRK password is null. Use nullptr to signal this.
 
36
 
 
37
The TPM contains a RNG of unknown design or quality. If that doesn't scare you
 
38
off, you can use it with ``TPM_RNG`` which implements the standard
 
39
``RandomNumberGenerator`` interface.
 
40
 
 
41
.. cpp:class:: TPM_RNG
 
42
 
 
43
   .. cpp:function:: TPM_RNG(TPM_Context& ctx)
 
44
 
 
45
      Initialize a TPM RNG object. After initialization, reading from
 
46
      this RNG reads from the hardware? RNG on the TPM.
 
47
 
 
48
The v1.2 TPM uses only RSA, but because this key is implemented completely in
 
49
hardware it uses a different private key type, with a somewhat different API to
 
50
match the TPM's behavior.
 
51
 
 
52
.. cpp:class:: TPM_PrivateKey
 
53
 
 
54
   .. cpp:function:: TPM_PrivateKey(TPM_Context& ctx, size_t bits, const char* key_password)
 
55
 
 
56
        Create a new RSA key stored on the TPM. The bits should be either 1024
 
57
        or 2048; the TPM interface hypothetically allows larger keys but in
 
58
        practice no v1.2 TPM hardware supports them.
 
59
 
 
60
        The TPM processor is not fast, be prepared for this to take a while.
 
61
 
 
62
        The key_password is the password to the TPM key ?
 
63
 
 
64
    .. cpp:function::  std::string register_key(TPM_Storage_Type storage_type)
 
65
 
 
66
        Registers a key with the TPM. The storage_type can be either
 
67
        `TPM_Storage_Type::User` or `TPM_Storage_Type::System`. If System, the
 
68
        key is stored on the TPM itself. If User, it is stored on the local hard
 
69
        drive in a database maintained by an intermediate piece of system
 
70
        software (which actual interacts with the physical TPM on behalf of any
 
71
        number of applications calling the TPM API).
 
72
 
 
73
        The TPM has only some limited space to store private keys and may reject
 
74
        requests to store the key.
 
75
 
 
76
        In either case the key is encrypted with an RSA key which was generated
 
77
        on the TPM and which it will not allow to be exported. Thus (so goes the
 
78
        theory) without physically attacking the TPM
 
79
 
 
80
        Returns a UUID which can be passed back to constructor below.
 
81
 
 
82
    .. cpp:function::  TPM_PrivateKey(TPM_Context& ctx, const std::string& uuid, \
 
83
                                      TPM_Storage_Type storage_type)
 
84
 
 
85
        Load a registered key. The UUID was returned by the ``register_key`` function.
 
86
 
 
87
    .. cpp:function::  std::vector<uint8_t> export_blob() const
 
88
 
 
89
        Export the key as an encrypted blob. This blob can later be presented
 
90
        back to the same TPM to load the key.
 
91
 
 
92
    .. cpp:function:: TPM_PrivateKey(TPM_Context& ctx, const std::vector<uint8_t>& blob)
 
93
 
 
94
        Load a TPM key previously exported as a blob with ``export_blob``.
 
95
 
 
96
    .. cpp:function::  std::unique_ptr<Public_Key> public_key() const
 
97
 
 
98
         Return the public key associated with this TPM private key.
 
99
 
 
100
         TPM does not store public keys, nor does it support signature verification.
 
101
 
 
102
     .. cpp:function:: TSS_HKEY handle() const
 
103
 
 
104
        Returns the bare TSS key handle. Use if you need to call the raw TSS API.
 
105
 
 
106
A ``TPM_PrivateKey`` can be passed to a ``PK_Signer`` constructor and used to
 
107
sign messages just like any other key. Only PKCS #1 v1.5 signatures are supported
 
108
by the v1.2 TPM.
 
109
 
 
110
.. cpp:function:: std::vector<std::string> TPM_PrivateKey::registered_keys(TPM_Context& ctx)
 
111
 
 
112
      This static function returns the list of all keys (in URL format)
 
113
      registered with the system