1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
|
Public Key Cryptography
=================================
Public key cryptography (also called asymmetric cryptography) is a collection
of techniques allowing for encryption, signatures, and key agreement.
Key Objects
----------------------------------------
Public and private keys are represented by classes ``Public_Key`` and it's
subclass ``Private_Key``. The use of inheritence here means that a
``Private_Key`` can be converted into a reference to a public key.
None of the functions on ``Public_Key`` and ``Private_Key`` itself are
particularly useful for users of the library, because 'bare' public key
operations are *very insecure*. The only purpose of these functions is to
provide a clean interface that higher level operations can be built on. So
really the only thing you need to know is that when a function takes a
reference to a ``Public_Key``, it can take any public key or private key, and
similiarly for ``Private_Key``.
Types of ``Public_Key`` include ``RSA_PublicKey``, ``DSA_PublicKey``,
``ECDSA_PublicKey``, ``ECKCDSA_PublicKey``, ``ECGDSA_PublicKey``, ``DH_PublicKey``, ``ECDH_PublicKey``,
``Curve25519_PublicKey``, ``ElGamal_PublicKey``, ``McEliece_PublicKey``, ``XMSS_PublicKey``
and ``GOST_3410_PublicKey``. There are cooresponding ``Private_Key`` classes for each of these algorithms.
.. _creating_new_private_keys:
Creating New Private Keys
----------------------------------------
Creating a new private key requires two things: a source of random numbers
(see :ref:`random_number_generators`) and some algorithm specific parameters
that define the *security level* of the resulting key. For instance, the
security level of an RSA key is (at least in part) defined by the length of
the public key modulus in bits. So to create a new RSA private key, you would
call
.. cpp:function:: RSA_PrivateKey::RSA_PrivateKey(RandomNumberGenerator& rng, size_t bits)
A constructor that creates a new random RSA private key with a modulus
of length *bits*.
Algorithms based on the discrete-logarithm problem use what is called a
*group*; a group can safely be used with many keys, and for some operations,
like key agreement, the two keys *must* use the same group. There are
currently two kinds of discrete logarithm groups supported in botan: the
integers modulo a prime, represented by :ref:`dl_group`, and elliptic curves
in GF(p), represented by :ref:`ec_group`. A rough generalization is that the
larger the group is, the more secure the algorithm is, but correspondingly the
slower the operations will be.
Given a ``DL_Group``, you can create new DSA, Diffie-Hellman and ElGamal key pairs with
.. cpp:function:: DSA_PrivateKey::DSA_PrivateKey(RandomNumberGenerator& rng, \
const DL_Group& group, const BigInt& x = 0)
.. cpp:function:: DH_PrivateKey::DH_PrivateKey(RandomNumberGenerator& rng, \
const DL_Group& group, const BigInt& x = 0)
.. cpp:function:: ElGamal_PrivateKey::ElGamal_PrivateKey(RandomNumberGenerator& rng, \
const DL_Group& group, const BigInt& x = 0)
The optional *x* parameter to each of these constructors is a private key
value. This allows you to create keys where the private key is formed by
some special technique; for instance you can use the hash of a password (see
:ref:`pbkdf` for how to do that) as a private key value. Normally, you would
leave the value as zero, letting the class generate a new random key.
Finally, given an ``EC_Group`` object, you can create a new ECDSA, ECKCDSA, ECGDSA,
ECDH, or GOST 34.10-2001 private key with
.. cpp:function:: ECDSA_PrivateKey::ECDSA_PrivateKey(RandomNumberGenerator& rng, \
const EC_Group& domain, const BigInt& x = 0)
.. cpp:function:: ECKCDSA_PrivateKey::ECKCDSA_PrivateKey(RandomNumberGenerator& rng, \
const EC_Group& domain, const BigInt& x = 0)
.. cpp:function:: ECGDSA_PrivateKey::ECGDSA_PrivateKey(RandomNumberGenerator& rng, \
const EC_Group& domain, const BigInt& x = 0)
.. cpp:function:: ECDH_PrivateKey::ECDH_PrivateKey(RandomNumberGenerator& rng, \
const EC_Group& domain, const BigInt& x = 0)
.. cpp:function:: GOST_3410_PrivateKey::GOST_3410_PrivateKey(RandomNumberGenerator& rng, \
const EC_Group& domain, const BigInt& x = 0)
.. _serializing_private_keys:
Serializing Private Keys Using PKCS #8
----------------------------------------
The standard format for serializing a private key is PKCS #8, the operations
for which are defined in ``pkcs8.h``. It supports both unencrypted and
encrypted storage.
.. cpp:function:: secure_vector<uint8_t> PKCS8::BER_encode(const Private_Key& key, \
RandomNumberGenerator& rng, const std::string& password, const std::string& pbe_algo = "")
Takes any private key object, serializes it, encrypts it using
*password*, and returns a binary structure representing the private
key.
The final (optional) argument, *pbe_algo*, specifies a particular
password based encryption (or PBE) algorithm. If you don't specify a
PBE, a sensible default will be used.
The currently supported PBE is PBES2 from PKCS5. Format is as follows:
`PBE-PKCS5v20(CIPHER,PBKDF)`. Cipher can be any block cipher with /CBC or /GCM
appended, for example "AES-128/CBC" or "Camellia-256/GCM". For best interop
with other systems, use AES in CBC mode. The PBKDF can be either the name of a
hash function (in which case PBKDF2 is used with that hash) or "Scrypt", which
causes the scrypt memory hard password hashing function to be used. Scrypt is
supported since version 2.7.0.
Use `PBE-PKCS5v20(AES-256/CBC,SHA-256)` if you want to ensure the keys can
be imported by different software packages. Use
`PBE-PKCS5v20(AES-256/GCM,Scrypt)` for best security assuming you do not
care about interop.
For ciphers you can use anything which has an OID defined for CBC or GCM mode.
Currently this includes 3DES, AES, Camellia, SM4, Serpent, and Twofish.
.. cpp:function:: std::string PKCS8::PEM_encode(const Private_Key& key, \
RandomNumberGenerator& rng, const std::string& pass, const std::string& pbe_algo = "")
This formats the key in the same manner as ``BER_encode``, but additionally
encodes it into a text format with identifying headers. Using PEM encoding
is *highly* recommended for many reasons, including compatibility with other
software, for transmission over 8-bit unclean channels, because it can be
identified by a human without special tools, and because it sometimes allows
more sane behavior of tools that process the data.
Unencrypted serialization is also supported.
.. warning::
In most situations, using unecrypted private key storage is a bad idea,
because anyone can come along and grab the private key without having to
know any passwords or other secrets. Unless you have very particular
security requirements, always use the versions that encrypt the key based on
a passphrase, described above.
.. cpp:function:: secure_vector<uint8_t> PKCS8::BER_encode(const Private_Key& key)
Serializes the private key and returns the result.
.. cpp:function:: std::string PKCS8::PEM_encode(const Private_Key& key)
Serializes the private key, base64 encodes it, and returns the
result.
Last but not least, there are some functions that will load (and
decrypt, if necessary) a PKCS #8 private key:
.. cpp:function:: Private_Key* PKCS8::load_key(DataSource& in, \
RandomNumberGenerator& rng, const User_Interface& ui)
.. cpp:function:: Private_Key* PKCS8::load_key(DataSource& in, \
RandomNumberGenerator& rng, std::string passphrase = "")
.. cpp:function:: Private_Key* PKCS8::load_key(const std::string& filename, \
RandomNumberGenerator& rng, const User_Interface& ui)
.. cpp:function:: Private_Key* PKCS8::load_key(const std::string& filename, \
RandomNumberGenerator& rng, const std::string& passphrase = "")
These functions will return an object allocated key object based on the data
from whatever source it is using (assuming, of course, the source is in fact
storing a representation of a private key, and the decryption was
successful). The encoding used (PEM or BER) need not be specified; the format
will be detected automatically. The key is allocated with ``new``, and should
be released with ``delete`` when you are done with it. The first takes a
generic ``DataSource`` that you have to create - the other is a simple wrapper
functions that take either a filename or a memory buffer and create the
appropriate ``DataSource``.
The versions taking a ``std::string`` attempt to decrypt using the password
given (if the key is encrypted; if it is not, the passphase value will be
ignored). If the passphrase does not decrypt the key, an exception will be
thrown.
The ones taking a ``User_Interface`` provide a simple callback interface which
makes handling incorrect passphrases and such a bit simpler. A
``User_Interface`` has very little to do with talking to users; it's just a
way to glue together Botan and whatever user interface you happen to be using.
.. note::
In a future version, it is likely that ``User_Interface`` will be
replaced by a simple callback using ``std::function``.
To use ``User_Interface``, derive a subclass and implement:
.. cpp:function:: std::string User_Interface::get_passphrase(const std::string& what, \
const std::string& source, UI_Result& result) const
The ``what`` argument specifies what the passphrase is needed for (for
example, PKCS #8 key loading passes ``what`` as "PKCS #8 private key"). This
lets you provide the user with some indication of *why* your application is
asking for a passphrase; feel free to pass the string through ``gettext(3)``
or moral equivalent for i18n purposes. Similarly, ``source`` specifies where
the data in question came from, if available (for example, a file name). If
the source is not available for whatever reason, then ``source`` will be an
empty string; be sure to account for this possibility.
The function returns the passphrase as the return value, and a status code
in ``result`` (either ``OK`` or ``CANCEL_ACTION``). If ``CANCEL_ACTION`` is
returned in ``result``, then the return value will be ignored, and the
caller will take whatever action is necessary (typically, throwing an
exception stating that the passphrase couldn't be determined). In the
specific case of PKCS #8 key decryption, a ``Decoding_Error`` exception will
be thrown; your UI should assume this can happen, and provide appropriate
error handling (such as putting up a dialog box informing the user of the
situation, and canceling the operation in progress).
.. _serializing_public_keys:
Serializing Public Keys
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To import and export public keys, use:
.. cpp:function:: std::vector<uint8_t> X509::BER_encode(const Public_Key& key)
.. cpp:function:: std::string X509::PEM_encode(const Public_Key& key)
.. cpp:function:: Public_Key* X509::load_key(DataSource& in)
.. cpp:function:: Public_Key* X509::load_key(const secure_vector<uint8_t>& buffer)
.. cpp:function:: Public_Key* X509::load_key(const std::string& filename)
These functions operate in the same way as the ones described in
:ref:`serializing_private_keys`, except that no encryption option is
availabe.
.. _dl_group:
DL_Group
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As described in :ref:`creating_new_private_keys`, a discrete logarithm group
can be shared among many keys, even keys created by users who do not trust
each other. However, it is necessary to trust the entity who created the
group; that is why organization like NIST use algorithms which generate groups
in a deterministic way such that creating a bogus group would require breaking
some trusted cryptographic primitive like SHA-2.
Instantiating a ``DL_Group`` simply requires calling
.. cpp:function:: DL_Group::DL_Group(const std::string& name)
The *name* parameter is a specially formatted string that consists of three
things, the type of the group ("modp" or "dsa"), the creator of the group,
and the size of the group in bits, all delimited by '/' characters.
Currently all "modp" groups included in botan are ones defined by the
Internet Engineering Task Force, so the provider is "ietf", and the strings
look like "modp/ietf/N" where N can be any of 1024, 1536, 2048, 3072,
4096, 6144, or 8192. This group type is used for Diffie-Hellman and ElGamal
algorithms.
The other type, "dsa" is used for DSA keys. They can also be used with
Diffie-Hellman and ElGamal, but this is less common. The currently available
groups are "dsa/jce/1024" and "dsa/botan/N" with N being 2048 or 3072. The
"jce" groups are the standard DSA groups used in the Java Cryptography
Extensions, while the "botan" groups were randomly generated using the
FIPS 186-3 algorithm by the library maintainers.
You can generate a new random group using
.. cpp:function:: DL_Group::DL_Group(RandomNumberGenerator& rng, \
PrimeType type, size_t pbits, size_t qbits = 0)
The *type* can be either ``Strong``, ``Prime_Subgroup``, or
``DSA_Kosherizer``. *pbits* specifies the size of the prime in
bits. If the *type* is ``Prime_Subgroup`` or ``DSA_Kosherizer``,
then *qbits* specifies the size of the subgroup.
You can serialize a ``DL_Group`` using
.. cpp:function:: secure_vector<uint8_t> DL_Group::DER_Encode(Format format)
or
.. cpp:function:: std::string DL_Group::PEM_encode(Format format)
where *format* is any of
* ``ANSI_X9_42`` (or ``DH_PARAMETERS``) for modp groups
* ``ANSI_X9_57`` (or ``DSA_PARAMETERS``) for DSA-style groups
* ``PKCS_3`` is an older format for modp groups; it should only
be used for backwards compatibility.
You can reload a serialized group using
.. cpp:function:: void DL_Group::BER_decode(DataSource& source, Format format)
.. cpp:function:: void DL_Group::PEM_decode(DataSource& source)
Code Example
"""""""""""""""""
The example below creates a new 2048 bit ``DL_Group``, prints the generated
parameters and ANSI_X9_42 encodes the created group for further usage with DH.
.. code-block:: cpp
#include <botan/dl_group.h>
#include <botan/auto_rng.h>
#include <botan/rng.h>
#include <iostream>
int main()
{
std::unique_ptr<Botan::RandomNumberGenerator> rng(new Botan::AutoSeeded_RNG);
std::unique_ptr<Botan::DL_Group> group(new Botan::DL_Group(*rng.get(), Botan::DL_Group::Strong, 2048));
std::cout << std::endl << "p: " << group->get_p();
std::cout << std::endl << "q: " << group->get_q();
std::cout << std::endl << "g: " << group->get_q();
std::cout << std::endl << "ANSI_X9_42: " << std::endl << group->PEM_encode(Botan::DL_Group::ANSI_X9_42);
return 0;
}
.. _ec_group:
EC_Group
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
An ``EC_Group`` is initialized by passing the name of the
group to be used to the constructor. These groups have
semi-standardized names like "secp256r1" and "brainpool512r1".
Key Checking
---------------------------------
Most public key algorithms have limitations or restrictions on their
parameters. For example RSA requires an odd exponent, and algorithms
based on the discrete logarithm problem need a generator > 1.
Each public key type has a function
.. cpp:function:: bool Public_Key::check_key(RandomNumberGenerator& rng, bool strong)
This function performs a number of algorithm-specific tests that the key
seems to be mathematically valid and consistent, and returns true if all of
the tests pass.
It does not have anything to do with the validity of the key for any
particular use, nor does it have anything to do with certificates that link
a key (which, after all, is just some numbers) with a user or other
entity. If *strong* is ``true``, then it does "strong" checking, which
includes expensive operations like primality checking.
As key checks are not automatically performed they must be called
manually after loading keys from untrusted sources. If a key from an untrusted source
is not checked, the implementation might be vulnerable to algorithm specific attacks.
The following example loads the Subject Public Key from the x509 certificate ``cert.pem`` and checks the
loaded key. If the key check fails a respective error is thrown.
.. code-block:: cpp
#include <botan/x509cert.h>
#include <botan/auto_rng.h>
#include <botan/rng.h>
int main()
{
Botan::X509_Certificate cert("cert.pem");
std::unique_ptr<Botan::RandomNumberGenerator> rng(new Botan::AutoSeeded_RNG);
std::unique_ptr<Botan::Public_Key> key(cert.subject_public_key());
if(!key->check_key(*rng.get(), false))
{
throw std::invalid_argument("Loaded key is invalid");
}
}
Encryption
---------------------------------
Safe public key encryption requires the use of a padding scheme which hides
the underlying mathematical properties of the algorithm. Additionally, they
will add randomness, so encrypting the same plaintext twice produces two
different ciphertexts.
The primary interface for encryption is
.. cpp:class:: PK_Encryptor
.. cpp:function:: secure_vector<uint8_t> encrypt( \
const uint8_t* in, size_t length, RandomNumberGenerator& rng) const
.. cpp:function:: secure_vector<uint8_t> encrypt( \
const std::vector<uint8_t>& in, RandomNumberGenerator& rng) const
These encrypt a message, returning the ciphertext.
.. cpp:function:: size_t maximum_input_size() const
Returns the maximum size of the message that can be processed, in
bytes. If you call :cpp:func:`PK_Encryptor::encrypt` with a value larger
than this the operation will fail with an exception.
:cpp:class:`PK_Encryptor` is only an interface - to actually encrypt you have
to create an implementation, of which there are currently three available in the
library, :cpp:class:`PK_Encryptor_EME`, :cpp:class:`DLIES_Encryptor` and
:cpp:class:`ECIES_Encryptor`. DLIES is a hybrid encryption scheme (from
IEEE 1363) that uses the DH key agreement technique in combination with a KDF, a
MAC and a symmetric encryption algorithm to perform message encryption. ECIES is
similar to DLIES, but uses ECDH for the key agreement. Normally, public key
encryption is done using algorithms which support it directly, such as RSA or
ElGamal; these use the EME class:
.. cpp:class:: PK_Encryptor_EME
.. cpp:function:: PK_Encryptor_EME(const Public_Key& key, std::string eme)
With *key* being the key you want to encrypt messages to. The padding
method to use is specified in *eme*.
The recommended values for *eme* is "EME1(SHA-1)" or "EME1(SHA-256)". If
you need compatibility with protocols using the PKCS #1 v1.5 standard,
you can also use "EME-PKCS1-v1_5".
.. cpp:class:: DLIES_Encryptor
Available in the header ``dlies.h``
.. cpp:function:: DLIES_Encryptor(const DH_PrivateKey& own_priv_key, \
RandomNumberGenerator& rng, KDF* kdf, MessageAuthenticationCode* mac, \
size_t mac_key_len = 20)
Where *kdf* is a key derivation function (see
:ref:`key_derivation_function`) and *mac* is a
MessageAuthenticationCode. The encryption is performed by XORing the
message with a stream of bytes provided by the KDF.
.. cpp:function:: DLIES_Encryptor(const DH_PrivateKey& own_priv_key, \
RandomNumberGenerator& rng, KDF* kdf, Cipher_Mode* cipher, \
size_t cipher_key_len, MessageAuthenticationCode* mac, \
size_t mac_key_len = 20)
Instead of XORing the message a block cipher can be specified.
.. cpp:class:: ECIES_Encryptor
Available in the header ``ecies.h``.
Parameters for encryption and decryption are set by the
:cpp:class:`ECIES_System_Params` class which stores the EC domain parameters,
the KDF (see :ref:`key_derivation_function`), the cipher (see
:ref:`cipher_modes`) and the MAC.
.. cpp:function:: ECIES_Encryptor(const PK_Key_Agreement_Key& private_key, \
const ECIES_System_Params& ecies_params, \
RandomNumberGenerator& rng)
Where *private_key* is the key to use for the key agreement. The system
paramters are specified in *ecies_params* and the RNG to use is passed in
*rng*.
.. cpp:function:: ECIES_Encryptor(RandomNumberGenerator& rng, \
const ECIES_System_Params& ecies_params)
Creates an ephemeral private key which is used for the key agreement.
The decryption classes are named :cpp:class:`PK_Decryptor`,
:cpp:class:`PK_Decryptor_EME`, :cpp:class:`DLIES_Decryptor` and
:cpp:class:`ECIES_Decryptor`. They are created in the exact same way, except
they take the private key, and the processing function is named ``decrypt``.
Botan implements the following encryption algorithms and padding schemes:
1. RSA
- "PKCS1v15" || "EME-PKCS1-v1_5"
- "OAEP" || "EME-OAEP" || "EME1" || "EME1(SHA-1)" || "EME1(SHA-256)"
#. DLIES
#. ECIES
#. SM2
Code Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following Code sample reads a PKCS #8 keypair from the passed location and
subsequently encrypts a fixed plaintext with the included public key, using EME1
with SHA-256. For the sake of completeness, the ciphertext is then decrypted using
the private key.
.. code-block:: cpp
#include <botan/pkcs8.h>
#include <botan/hex.h>
#include <botan/pk_keys.h>
#include <botan/pubkey.h>
#include <botan/auto_rng.h>
#include <botan/rng.h>
#include <iostream>
int main (int argc, char* argv[])
{
if(argc!=2)
return 1;
std::string plaintext("Your great-grandfather gave this watch to your granddad for good luck. Unfortunately, Dane's luck wasn't as good as his old man's.");
std::vector<uint8_t> pt(plaintext.data(),plaintext.data()+plaintext.length());
std::unique_ptr<Botan::RandomNumberGenerator> rng(new Botan::AutoSeeded_RNG);
//load keypair
std::unique_ptr<Botan::Private_Key> kp(Botan::PKCS8::load_key(argv[1],*rng.get()));
//encrypt with pk
Botan::PK_Encryptor_EME enc(*kp,*rng.get(), "EME1(SHA-256)");
std::vector<uint8_t> ct = enc.encrypt(pt,*rng.get());
//decrypt with sk
Botan::PK_Decryptor_EME dec(*kp,*rng.get(), "EME1(SHA-256)");
std::cout << std::endl << "enc: " << Botan::hex_encode(ct) << std::endl << "dec: "<< Botan::hex_encode(dec.decrypt(ct));
return 0;
}
Signatures
---------------------------------
Signature generation is performed using
.. cpp:class:: PK_Signer
.. cpp:function:: PK_Signer(const Private_Key& key, \
const std::string& emsa, \
Signature_Format format = IEEE_1363)
Constructs a new signer object for the private key *key* using the
signature format *emsa*. The key must support signature operations. In
the current version of the library, this includes RSA, DSA, ECDSA, ECKCDSA,
ECGDSA, GOST 34.10-2001. Other signature schemes may be supported in the future.
.. note::
Botan both supports non-deterministic and deterministic (as per RFC
6979) DSA and ECDSA signatures. Deterministic signatures are compatible
in the way that they can be verified with a non-deterministic implementation.
If the ``rfc6979`` module is enabled, deterministic DSA and ECDSA signatures
will be generated.
Currently available values for *emsa* include EMSA1, EMSA2, EMSA3, EMSA4,
and Raw. All of them, except Raw, take a parameter naming a message
digest function to hash the message with. The Raw encoding signs the
input directly; if the message is too big, the signing operation will
fail. Raw is not useful except in very specialized applications. Examples
are "EMSA1(SHA-1)" and "EMSA4(SHA-256)".
For RSA, use EMSA4 (also called PSS) unless you need compatibility with
software that uses the older PKCS #1 v1.5 standard, in which case use
EMSA3 (also called "EMSA-PKCS1-v1_5"). For DSA, ECDSA, ECKCDSA, ECGDSA and
GOST 34.10-2001 you should use EMSA1.
The *format* defaults to ``IEEE_1363`` which is the only available
format for RSA. For DSA, ECDSA, ECGDSA and ECKCDSA you can also use
``DER_SEQUENCE``, which will format the signature as an ASN.1
SEQUENCE value.
.. cpp:function:: void update(const uint8_t* in, size_t length)
.. cpp:function:: void update(const std::vector<uint8_t>& in)
.. cpp:function:: void update(uint8_t in)
These add more data to be included in the signature
computation. Typically, the input will be provided directly to a
hash function.
.. cpp:function:: secure_vector<uint8_t> signature(RandomNumberGenerator& rng)
Creates the signature and returns it
.. cpp:function:: secure_vector<uint8_t> sign_message( \
const uint8_t* in, size_t length, RandomNumberGenerator& rng)
.. cpp:function:: secure_vector<uint8_t> sign_message( \
const std::vector<uint8_t>& in, RandomNumberGenerator& rng)
These functions are equivalent to calling
:cpp:func:`PK_Signer::update` and then
:cpp:func:`PK_Signer::signature`. Any data previously provided
using ``update`` will be included.
Signatures are verified using
.. cpp:class:: PK_Verifier
.. cpp:function:: PK_Verifier(const Public_Key& pub_key, \
const std::string& emsa, Signature_Format format = IEEE_1363)
Construct a new verifier for signatures assicated with public
key *pub_key*. The *emsa* and *format* should be the same as
that used by the signer.
.. cpp:function:: void update(const uint8_t* in, size_t length)
.. cpp:function:: void update(const std::vector<uint8_t>& in)
.. cpp:function:: void update(uint8_t in)
Add further message data that is purportedly assocated with the
signature that will be checked.
.. cpp:function:: bool check_signature(const uint8_t* sig, size_t length)
.. cpp:function:: bool check_signature(const std::vector<uint8_t>& sig)
Check to see if *sig* is a valid signature for the message data
that was written in. Return true if so. This function clears the
internal message state, so after this call you can call
:cpp:func:`PK_Verifier::update` to start verifying another
message.
.. cpp:function:: bool verify_message(const uint8_t* msg, size_t msg_length, \
const uint8_t* sig, size_t sig_length)
.. cpp:function:: bool verify_message(const std::vector<uint8_t>& msg, \
const std::vector<uint8_t>& sig)
These are equivalent to calling :cpp:func:`PK_Verifier::update`
on *msg* and then calling :cpp:func:`PK_Verifier::check_signature`
on *sig*.
Botan implements the following signature algorithms:
1. RSA
#. DSA
#. ECDSA
#. ECGDSA
#. ECKDSA
#. GOST 34.10-2001
#. Ed25519
#. SM2
Code Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following sample program below demonstrates the generation of a new ECDSA keypair over the curve secp512r1
and a ECDSA signature using EMSA1 with SHA-256. Subsequently the computed signature is validated.
.. code-block:: cpp
#include <botan/auto_rng.h>
#include <botan/ecdsa.h>
#include <botan/ec_group.h>
#include <botan/pubkey.h>
#include <botan/hex.h>
#include <iostream>
int main()
{
Botan::AutoSeeded_RNG rng;
// Generate ECDSA keypair
Botan::ECDSA_PrivateKey key(rng, Botan::EC_Group("secp521r1"));
std::string text("This is a tasty burger!");
std::vector<uint8_t> data(text.data(),text.data()+text.length());
// sign data
Botan::PK_Signer signer(key, rng, "EMSA1(SHA-256)");
signer.update(data);
std::vector<uint8_t> signature = signer.signature(rng);
std::cout << "Signature:" << std::endl << Botan::hex_encode(signature);
// verify signature
Botan::PK_Verifier verifier(key, "EMSA1(SHA-256)");
verifier.update(data);
std::cout << std::endl << "is " << (verifier.check_signature(signature)? "valid" : "invalid");
return 0;
}
Key Agreement
---------------------------------
You can get a hold of a ``PK_Key_Agreement_Scheme`` object by calling
``get_pk_kas`` with a key that is of a type that supports key
agreement (such as a Diffie-Hellman key stored in a ``DH_PrivateKey``
object), and the name of a key derivation function. This can be "Raw",
meaning the output of the primitive itself is returned as the key, or
"KDF1(hash)" or "KDF2(hash)" where "hash" is any string you happen to
like (hopefully you like strings like "SHA-256" or "RIPEMD-160"), or
"X9.42-PRF(keywrap)", which uses the PRF specified in ANSI X9.42. It
takes the name or OID of the key wrap algorithm that will be used to
encrypt a content encryption key.
How key agreement works is that you trade public values with some
other party, and then each of you runs a computation with the other's
value and your key (this should return the same result to both
parties). This computation can be called by using
``derive_key`` with either a byte array/length pair, or a
``secure_vector<uint8_t>`` than holds the public value of the other
party. The last argument to either call is a number that specifies how
long a key you want.
Depending on the KDF you're using, you *might not* get back a key
of the size you requested. In particular "Raw" will return a number
about the size of the Diffie-Hellman modulus, and KDF1 can only return
a key that is the same size as the output of the hash. KDF2, on the
other hand, will always give you a key exactly as long as you request,
regardless of the underlying hash used with it. The key returned is a
``SymmetricKey``, ready to pass to a block cipher, MAC, or other
symmetric algorithm.
The public value that should be used can be obtained by calling
``public_data``, which exists for any key that is associated with a
key agreement algorithm. It returns a ``secure_vector<uint8_t>``.
"KDF2(SHA-256)" is by far the preferred algorithm for key derivation
in new applications. The X9.42 algorithm may be useful in some
circumstances, but unless you need X9.42 compatibility, KDF2 is easier
to use.
Botan implements the following key agreement methods:
1. ECDH over GF(p) Weierstrass curves
#. ECDH over x25519
#. DH over prime fields
#. McEliece
#. NewHope
Code Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The code below performs an unauthenticated ECDH key agreement using the secp521r elliptic curve and
applies the key derivation function KDF2(SHA-256) with 256 bit output length to the computed shared secret.
.. code-block:: cpp
#include <botan/auto_rng.h>
#include <botan/ecdh.h>
#include <botan/ec_group.h>
#include <botan/pubkey.h>
#include <botan/hex.h>
#include <iostream>
int main()
{
Botan::AutoSeeded_RNG rng;
// ec domain and
Botan::EC_Group domain("secp521r1");
std::string kdf = "KDF2(SHA-256)";
// generate ECDH keys
Botan::ECDH_PrivateKey keyA(rng, domain);
Botan::ECDH_PrivateKey keyB(rng, domain);
// Construct key agreements
Botan::PK_Key_Agreement ecdhA(keyA,rng,kdf);
Botan::PK_Key_Agreement ecdhB(keyB,rng,kdf);
// Agree on shared secret and derive symmetric key of 256 bit length
Botan::secure_vector<uint8_t> sA = ecdhA.derive_key(32,keyB.public_value()).bits_of();
Botan::secure_vector<uint8_t> sB = ecdhB.derive_key(32,keyA.public_value()).bits_of();
if(sA != sB)
return 1;
std::cout << "agreed key: " << std::endl << Botan::hex_encode(sA);
return 0;
}
McEliece
--------------------------
McEliece is a cryptographic scheme based on error correcting codes which is
thought to be resistent to quantum computers. First proposed in 1978, it is fast
and patent-free. Variants have been proposed and broken, but with suitable
parameters the original scheme remains secure. However the public keys are quite
large, which has hindered deployment in the past.
The implementation of McEliece in Botan was contributed by cryptosource GmbH. It
is based on the implementation HyMES, with the kind permission of Nicolas
Sendrier and INRIA to release a C++ adaption of their original C code under the
Botan license. It was then modified by Falko Strenzke to add side channel and
fault attack countermeasures. You can read more about the implementation at
http://www.cryptosource.de/docs/mceliece_in_botan.pdf
Encryption in the McEliece scheme consists of choosing a message block of size
`n`, encoding it in the error correcting code which is the public key, then
adding `t` bit errors. The code is created such that knowing only the public
key, decoding `t` errors is intractible, but with the additional knowledge of
the secret structure of the code a fast decoding technique exists.
The McEliece implementation in HyMES, and also in Botan, uses an optimization to
reduce the public key size, by converting the public key into a systemic code.
This means a portion of the public key is a identity matrix, and can be excluded
from the published public key. However it also means that in McEliece the
plaintext is represented directly in the ciphertext, with only a small number of
bit errors. Thus it is absolutely essential to only use McEliece with a CCA2
secure scheme.
One such scheme, KEM, is provided in Botan currently. It it a somewhat unusual
scheme in that it outputs two values, a symmetric key for use with an AEAD, and
an encrypted key. It does this by choosing a random plaintext (n - log2(n)*t
bits) using ``McEliece_PublicKey::random_plaintext_element``. Then a random
error mask is chosen and the message is coded and masked. The symmetric key is
SHA-512(plaintext || error_mask). As long as the resulting key is used with a
secure AEAD scheme (which can be used for transporting arbitrary amounts of
data), CCA2 security is provided.
In ``mcies.h`` there are functions for this combination:
.. cpp:function:: secure_vector<uint8_t> mceies_encrypt(const McEliece_PublicKey& pubkey, \
const secure_vector<uint8_t>& pt, \
uint8_t ad[], size_t ad_len, \
RandomNumberGenerator& rng, \
const std::string& aead = "AES-256/OCB")
.. cpp:function:: secure_vector<uint8_t> mceies_decrypt(const McEliece_PrivateKey& privkey, \
const secure_vector<uint8_t>& ct, \
uint8_t ad[], size_t ad_len, \
const std::string& aead = "AES-256/OCB")
For a given security level (SL) a McEliece key would use
parameters n and t, and have the cooresponding key sizes listed:
+-----+------+-----+---------------+----------------+
| SL | n | t | public key KB | private key KB |
+=====+======+=====+===============+================+
| 80 | 1632 | 33 | 59 | 140 |
+-----+------+-----+---------------+----------------+
| 107 | 2280 | 45 | 128 | 300 |
+-----+------+-----+---------------+----------------+
| 128 | 2960 | 57 | 195 | 459 |
+-----+------+-----+---------------+----------------+
| 147 | 3408 | 67 | 265 | 622 |
+-----+------+-----+---------------+----------------+
| 191 | 4624 | 95 | 516 | 1234 |
+-----+------+-----+---------------+----------------+
| 256 | 6624 | 115 | 942 | 2184 |
+-----+------+-----+---------------+----------------+
You can check the speed of McEliece with the suggested parameters above
using ``botan speed McEliece``
eXtended Merkle Signature Scheme (XMSS)
----------------------------------------
Botan implements the single tree version of the eXtended Merkle Signature
Scheme (XMSS) using Winternitz One Time Signatures+ (WOTS+). The implementation
is based on IETF Internet-Draft "XMSS: Extended Hash-Based Signatures".
XMSS uses the Botan interfaces for public key cryptography.
The following algorithms are implemented:
1. XMSS_SHA2-256_W16_H10
#. XMSS_SHA2-256_W16_H16
#. XMSS_SHA2-256_W16_H20
#. XMSS_SHA2-512_W16_H10
#. XMSS_SHA2-512_W16_H16
#. XMSS_SHA2-512_W16_H20
#. XMSS_SHAKE128_W16_H10
#. XMSS_SHAKE128_W16_H10
#. XMSS_SHAKE128_W16_H10
#. XMSS_SHAKE256_W16_H10
#. XMSS_SHAKE256_W16_H10
#. XMSS_SHAKE256_W16_H10
Code Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following code snippet shows a minimum example on how to create an XMSS
public/private key pair and how to use these keys to create and verify a signature:
.. code-block:: cpp
#include <botan/botan.h>
#include <botan/auto_rng.h>
#include <botan/xmss.h>
int main()
{
// Create a random number generator used for key generation.
Botan::AutoSeeded_RNG rng;
// create a new public/private key pair using SHA2 256 as hash
// function and a tree height of 10.
Botan::XMSS_PrivateKey private_key(
Botan::XMSS_Parameters::xmss_algorithm_t::XMSS_SHA2_256_W16_H10,
rng);
Botan::XMSS_PublicKey public_key(private_key);
// create signature operation using the private key.
std::unique_ptr<Botan::PK_Ops::Signature> sig_op =
private_key.create_signature_op(rng, "", "");
// create and sign a message using the signature operation.
Botan::secure_vector<uint8_t> msg { 0x01, 0x02, 0x03, 0x04 };
sig_op->update(msg.data(), msg.size());
Botan::secure_vector<uint8_t> sig = sig_op->sign(rng);
// create verification operation using the public key
std::unique_ptr<Botan::PK_Ops::Verification> ver_op =
public_key.create_verification_op("", "");
// verify the signature for the previously generated message.
ver_op->update(msg.data(), msg.size());
if(ver_op->is_valid_signature(sig.data(), sig.size()))
{
std::cout << "Success." << std::endl;
}
else
{
std::cout << "Error." << std::endl;
}
}
|