1=====================
2Public Key Encryption
3=====================
4
5Unlike traditional means for public key asymmetric encryption, the nacl
6encryption systems are very high speed. The CurveCP network protocol for
7instance only uses public key encryption for all transport.
8
9Public key encryption is very simple, as is evidenced with this communication
10between Alice and Bob:
11
12.. code-block:: python
13
14    import libnacl.public
15
16    # Define a message to send
17    msg = b'You\'ve got two empty halves of coconut and you\'re bangin\' \'em together.'
18
19    # Generate the key pairs for Alice and bob, if secret keys already exist
20    # they can be passed in, otherwise new keys will be automatically generated
21    bob = libnacl.public.SecretKey()
22    alice = libnacl.public.SecretKey()
23
24    # Create the boxes, this is an object which represents the combination of the
25    # sender's secret key and the receiver's public key
26    bob_box = libnacl.public.Box(bob.sk, alice.pk)
27    alice_box = libnacl.public.Box(alice.sk, bob.pk)
28
29    # Bob's box encrypts messages for Alice
30    bob_ctxt = bob_box.encrypt(msg)
31    # Alice's box decrypts messages from Bob
32    bclear = alice_box.decrypt(bob_ctxt)
33    # Alice can send encrypted messages which only Bob can decrypt
34    alice_ctxt = alice_box.encrypt(msg)
35    aclear = bob_box.decrypt(alice_ctxt)
36
37.. note::
38
39    Every encryption routine requires a nonce. The nonce is a 24 char string
40    that must never be used twice with the same keypair. If no nonce is passed
41    in then a nonce is generated based on random data.
42    If it is desired to generate a nonce manually this can be done by passing
43    it into the encrypt method.
44
45.. _secretkey-object:
46
47SecretKey Object
48================
49
50The SecretKey object is used to manage both public and secret keys, this object
51contains a number of methods for both convenience and utility. The key data is
52also available.
53
54Keys
55----
56
57The raw public key is available as SecretKey.sk, to generate a hex encoded
58version of the key the sk_hex method is available. The same items are
59available for the public keys:
60
61.. code-block:: python
62
63    import libnacl.public
64
65    fred = libnacl.public.SecretKey()
66
67    raw_sk = fred.sk
68    hex_sk = fred.hex_sk()
69
70    raw_pk = fred.pk
71    hex_pk = fred.hex_pk()
72
73By saving only the binary keys in memory libnacl ensures that the minimal
74memory footprint is needed.
75
76.. _publickey-object:
77
78PublicKey Object
79================
80
81To manage only the public key end, a public key object exists:
82
83.. code-block:: python
84
85    import libnacl.public
86
87    tom = libnacl.public.PublicKey(tom_public_key_hex)
88
89    raw_pk = tom.pk
90    hex_pk = tom.hex_pk()
91
92Saving Keys to Disk
93===================
94
95All libnacl key objects can be safely saved to disk via the save method. This
96method changes the umask before saving the key file to ensure that the saved
97file can only be read by the user creating it and cannot be written to.
98
99.. code-block:: python
100
101    import libnacl.public
102
103    fred = libnacl.public.SecretKey()
104    fred.save('/etc/nacl/fred.key')
105