-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdraft-koch-openpgp-2015-rfc4880bis-02.txt
7336 lines (4810 loc) · 283 KB
/
draft-koch-openpgp-2015-rfc4880bis-02.txt
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
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Network Working Group W. Koch
Internet-Draft GnuPG e.V.
Obsoletes: 4880, 5581, 6637 (if approved) B. Carlson
Intended status: Standards Track
Expires: 1 December 2023 R.H. Tse
Ribose
D.A. Atkins
D.K. Gillmor
30 May 2023
OpenPGP Message Format
draft-koch-openpgp-2015-rfc4880bis-02
Abstract
This document specifies the message formats used in OpenPGP. OpenPGP
provides encryption with public-key or symmetric cryptographic
algorithms, digital signatures, compression and key management.
This document is maintained in order to publish all necessary
information needed to develop interoperable applications based on the
OpenPGP format. It is not a step-by-step cookbook for writing an
application. It describes only the format and methods needed to
read, check, generate, and write conforming packets crossing any
network. It does not deal with storage and implementation questions.
It does, however, discuss implementation issues necessary to avoid
security flaws.
This document obsoletes: RFC 4880 (OpenPGP), RFC 5581 (Camellia in
OpenPGP) and RFC 6637 (Elliptic Curves in OpenPGP).
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
Koch, et al. Expires 1 December 2023 [Page 1]
Internet-Draft OpenPGP Message Format May 2023
This Internet-Draft will expire on 1 December 2023.
Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2. General functions . . . . . . . . . . . . . . . . . . . . . . 6
2.1. Confidentiality via Encryption . . . . . . . . . . . . . 6
2.2. Authentication via Digital Signature . . . . . . . . . . 7
2.3. Compression . . . . . . . . . . . . . . . . . . . . . . . 8
2.4. Conversion to Radix-64 . . . . . . . . . . . . . . . . . 8
2.5. Signature-Only Applications . . . . . . . . . . . . . . . 8
3. Data Element Formats . . . . . . . . . . . . . . . . . . . . 8
3.1. Scalar Numbers . . . . . . . . . . . . . . . . . . . . . 9
3.2. Multiprecision Integers . . . . . . . . . . . . . . . . . 9
3.3. Key IDs . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.4. Text . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.5. Time Fields . . . . . . . . . . . . . . . . . . . . . . . 10
3.6. Keyrings . . . . . . . . . . . . . . . . . . . . . . . . 10
3.7. String-to-Key (S2K) Specifiers . . . . . . . . . . . . . 10
3.7.1. String-to-Key (S2K) Specifier Types . . . . . . . . . 10
3.7.2. String-to-Key Usage . . . . . . . . . . . . . . . . . 12
4. Packet Syntax . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2. Packet Headers . . . . . . . . . . . . . . . . . . . . . 14
4.2.1. Old Format Packet Lengths . . . . . . . . . . . . . . 15
4.2.2. New Format Packet Lengths . . . . . . . . . . . . . . 15
4.2.3. Packet Length Examples . . . . . . . . . . . . . . . 17
4.3. Packet Tags . . . . . . . . . . . . . . . . . . . . . . . 17
5. Packet Types . . . . . . . . . . . . . . . . . . . . . . . . 18
5.1. Public-Key Encrypted Session Key Packets (Tag 1) . . . . 18
5.2. Signature Packet (Tag 2) . . . . . . . . . . . . . . . . 20
5.2.1. Signature Types . . . . . . . . . . . . . . . . . . . 20
5.2.2. Version 3 Signature Packet Format . . . . . . . . . . 23
Koch, et al. Expires 1 December 2023 [Page 2]
Internet-Draft OpenPGP Message Format May 2023
5.2.3. Version 4 and 5 Signature Packet Formats . . . . . . 25
5.2.4. Computing Signatures . . . . . . . . . . . . . . . . 47
5.3. Symmetric-Key Encrypted Session Key Packets (Tag 3) . . . 50
5.4. One-Pass Signature Packets (Tag 4) . . . . . . . . . . . 51
5.5. Key Material Packet . . . . . . . . . . . . . . . . . . . 52
5.5.1. Key Packet Variants . . . . . . . . . . . . . . . . . 52
5.5.2. Public-Key Packet Formats . . . . . . . . . . . . . . 53
5.5.3. Secret-Key Packet Formats . . . . . . . . . . . . . . 54
5.6. Algorithm-specific Parts of Keys . . . . . . . . . . . . 57
5.6.1. Algorithm-Specific Part for RSA Keys . . . . . . . . 57
5.6.2. Algorithm-Specific Part for DSA Keys . . . . . . . . 57
5.6.3. Algorithm-Specific Part for Elgamal Keys . . . . . . 58
5.6.4. Algorithm-Specific Part for ECDSA Keys . . . . . . . 58
5.6.5. Algorithm-Specific Part for EdDSA Keys . . . . . . . 58
5.6.6. Algorithm-Specific Part for ECDH Keys . . . . . . . . 59
5.7. Compressed Data Packet (Tag 8) . . . . . . . . . . . . . 60
5.8. Symmetrically Encrypted Data Packet (Tag 9) . . . . . . . 60
5.9. Marker Packet (Obsolete Literal Packet) (Tag 10) . . . . 61
5.10. Literal Data Packet (Tag 11) . . . . . . . . . . . . . . 62
5.11. Trust Packet (Tag 12) . . . . . . . . . . . . . . . . . . 63
5.12. User ID Packet (Tag 13) . . . . . . . . . . . . . . . . . 63
5.13. User Attribute Packet (Tag 17) . . . . . . . . . . . . . 63
5.13.1. The Image Attribute Subpacket . . . . . . . . . . . 64
5.13.2. User ID Attribute Subpacket . . . . . . . . . . . . 65
5.14. Sym. Encrypted Integrity Protected Data Packet (Tag
18) . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.15. Modification Detection Code Packet (Tag 19) . . . . . . . 68
5.16. OCB Encrypted Data Packet (Tag 20) . . . . . . . . . . . 69
5.16.1. EAX Mode . . . . . . . . . . . . . . . . . . . . . . 70
5.16.2. OCB Mode . . . . . . . . . . . . . . . . . . . . . . 71
6. Radix-64 Conversions . . . . . . . . . . . . . . . . . . . . 71
6.1. An Implementation of the CRC-24 in "C" . . . . . . . . . 72
6.2. Forming ASCII Armor . . . . . . . . . . . . . . . . . . . 72
6.3. Encoding Binary in Radix-64 . . . . . . . . . . . . . . . 75
6.4. Decoding Radix-64 . . . . . . . . . . . . . . . . . . . . 76
6.5. Examples of Radix-64 . . . . . . . . . . . . . . . . . . 77
6.6. Example of an ASCII Armored Message . . . . . . . . . . . 77
7. Cleartext Signature Framework . . . . . . . . . . . . . . . . 78
7.1. Dash-Escaped Text . . . . . . . . . . . . . . . . . . . . 78
8. Regular Expressions . . . . . . . . . . . . . . . . . . . . . 79
9. Constants . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.1. Public-Key Algorithms . . . . . . . . . . . . . . . . . . 80
9.2. ECC Curve OID . . . . . . . . . . . . . . . . . . . . . . 81
9.3. Symmetric-Key Algorithms . . . . . . . . . . . . . . . . 83
9.4. Compression Algorithms . . . . . . . . . . . . . . . . . 84
9.5. Hash Algorithms . . . . . . . . . . . . . . . . . . . . . 84
9.6. Encryption Modes . . . . . . . . . . . . . . . . . . . . 85
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 86
Koch, et al. Expires 1 December 2023 [Page 3]
Internet-Draft OpenPGP Message Format May 2023
10.1. New String-to-Key Specifier Types . . . . . . . . . . . 86
10.2. New Packets . . . . . . . . . . . . . . . . . . . . . . 86
10.2.1. User Attribute Types . . . . . . . . . . . . . . . . 86
10.2.2. Image Format Subpacket Types . . . . . . . . . . . . 87
10.2.3. New Signature Subpackets . . . . . . . . . . . . . . 87
10.2.4. New Packet Versions . . . . . . . . . . . . . . . . 90
10.3. New Algorithms . . . . . . . . . . . . . . . . . . . . . 90
10.3.1. Public-Key Algorithms . . . . . . . . . . . . . . . 90
10.3.2. Symmetric-Key Algorithms . . . . . . . . . . . . . . 91
10.3.3. Hash Algorithms . . . . . . . . . . . . . . . . . . 91
10.3.4. Compression Algorithms . . . . . . . . . . . . . . . 92
11. Packet Composition . . . . . . . . . . . . . . . . . . . . . 92
11.1. Transferable Public Keys . . . . . . . . . . . . . . . . 92
11.2. Transferable Secret Keys . . . . . . . . . . . . . . . . 94
11.3. OpenPGP Messages . . . . . . . . . . . . . . . . . . . . 94
11.4. Detached Signatures . . . . . . . . . . . . . . . . . . 95
12. Enhanced Key Formats . . . . . . . . . . . . . . . . . . . . 95
12.1. Key Structures . . . . . . . . . . . . . . . . . . . . . 95
12.2. Key IDs and Fingerprints . . . . . . . . . . . . . . . . 97
13. Elliptic Curve Cryptography . . . . . . . . . . . . . . . . . 98
13.1. Supported ECC Curves . . . . . . . . . . . . . . . . . . 99
13.2. ECDSA and ECDH Conversion Primitives . . . . . . . . . . 99
13.3. EdDSA Point Format . . . . . . . . . . . . . . . . . . . 100
13.4. Key Derivation Function . . . . . . . . . . . . . . . . 100
13.5. ECDH Algorithm . . . . . . . . . . . . . . . . . . . . . 101
13.5.1. ECDH Parameters . . . . . . . . . . . . . . . . . . 103
14. Notes on Algorithms . . . . . . . . . . . . . . . . . . . . . 104
14.1. PKCS#1 Encoding in OpenPGP . . . . . . . . . . . . . . . 104
14.1.1. EME-PKCS1-v1_5-ENCODE . . . . . . . . . . . . . . . 104
14.1.2. EME-PKCS1-v1_5-DECODE . . . . . . . . . . . . . . . 105
14.1.3. EMSA-PKCS1-v1_5 . . . . . . . . . . . . . . . . . . 106
14.2. Symmetric Algorithm Preferences . . . . . . . . . . . . 107
14.3. Other Algorithm Preferences . . . . . . . . . . . . . . 108
14.3.1. Compression Preferences . . . . . . . . . . . . . . 108
14.3.2. Hash Algorithm Preferences . . . . . . . . . . . . . 109
14.4. Plaintext . . . . . . . . . . . . . . . . . . . . . . . 109
14.5. RSA . . . . . . . . . . . . . . . . . . . . . . . . . . 109
14.6. DSA . . . . . . . . . . . . . . . . . . . . . . . . . . 110
14.7. Elgamal . . . . . . . . . . . . . . . . . . . . . . . . 110
14.8. EdDSA . . . . . . . . . . . . . . . . . . . . . . . . . 110
14.9. Reserved Algorithm Numbers . . . . . . . . . . . . . . . 111
14.10. OpenPGP CFB Mode . . . . . . . . . . . . . . . . . . . . 111
14.11. Private or Experimental Parameters . . . . . . . . . . . 112
14.12. Meta-Considerations for Expansion . . . . . . . . . . . 113
15. Security Considerations . . . . . . . . . . . . . . . . . . . 113
16. Compatibility Profiles . . . . . . . . . . . . . . . . . . . 118
16.1. OpenPGP ECC Profile . . . . . . . . . . . . . . . . . . 118
17. Implementation Nits . . . . . . . . . . . . . . . . . . . . . 119
Koch, et al. Expires 1 December 2023 [Page 4]
Internet-Draft OpenPGP Message Format May 2023
18. References . . . . . . . . . . . . . . . . . . . . . . . . . 120
18.1. Normative References . . . . . . . . . . . . . . . . . . 120
18.2. Informative References . . . . . . . . . . . . . . . . . 123
Appendix A. Test vectors . . . . . . . . . . . . . . . . . . . . 124
A.1. Sample EdDSA key . . . . . . . . . . . . . . . . . . . . 125
A.2. Sample EdDSA signature . . . . . . . . . . . . . . . . . 125
A.3. Sample OCB encryption and decryption . . . . . . . . . . 126
A.3.1. Sample Parameters . . . . . . . . . . . . . . . . . . 126
A.3.2. Sample symmetric-key encrypted session key packet
(v5) . . . . . . . . . . . . . . . . . . . . . . . . 126
A.3.3. Starting OCB decryption of CEK . . . . . . . . . . . 127
A.3.4. Sample OCB Encrypted Data packet . . . . . . . . . . 127
A.3.5. Decryption of data . . . . . . . . . . . . . . . . . 128
A.3.6. Complete OCB encrypted packet sequence . . . . . . . 128
Appendix B. ECC Point compression flag bytes . . . . . . . . . . 129
Appendix C. Changes since RFC-4880 . . . . . . . . . . . . . . . 129
Appendix D. The principal authors of RFC-4880 . . . . . . . . . 130
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 131
1. Introduction
This document provides information on the message-exchange packet
formats used by OpenPGP to provide encryption, decryption, signing,
and key management functions. It is a revision of RFC 4880, "OpenPGP
Message Format", which is a revision of RFC 2440, which itself
replaces RFC 1991, "PGP Message Exchange Formats" [RFC1991] [RFC2440]
[RFC4880].
This document obsoletes: RFC 4880 (OpenPGP), RFC 5581 (Camellia
cipher) and RFC 6637 (ECC for OpenPGP).
1.1. Terms
* OpenPGP - This is a term for security software that uses PGP 5 as
a basis, formalized in this document.
* PGP - Pretty Good Privacy. PGP is a family of software systems
developed by Philip R. Zimmermann from which OpenPGP is based.
* PGP 2 - This version of PGP has many variants; where necessary a
more detailed version number is used here. PGP 2 uses only RSA,
MD5, and IDEA for its cryptographic transforms. An informational
RFC, RFC 1991, was written describing this version of PGP.
* PGP 5 - This version of PGP is formerly known as "PGP 3" in the
community. It has new formats and corrects a number of problems
in the PGP 2 design. It is referred to here as PGP 5 because that
software was the first release of the "PGP 3" code base.
Koch, et al. Expires 1 December 2023 [Page 5]
Internet-Draft OpenPGP Message Format May 2023
* GnuPG - GNU Privacy Guard, also called GPG, is the leading Open
Source implementation of OpenPGP and has been developed along with
the OpenPGP standard since 1997.
* RNP - Ribose Network PGP is a newer OpenPGP implemention and
prominently used by the mail client Thunderbird.
"PGP" is a trademark of CA, INC. The use of this, or any other,
marks is solely for identification purposes. The term "OpenPGP"
refers to the protocol described in this and related documents.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
The key words "PRIVATE USE", "EXPERT REVIEW", "SPECIFICATION
REQUIRED", "RFC REQUIRED", and "IETF REVIEW" that appear in this
document when used to describe namespace allocation are to be
interpreted as described in [RFC8126].
2. General functions
OpenPGP provides data integrity services for messages and data files
by using these core technologies:
* digital signatures
* encryption
* compression
* Radix-64 conversion
In addition, OpenPGP provides key management and certificate
services, but many of these are beyond the scope of this document.
2.1. Confidentiality via Encryption
OpenPGP combines symmetric-key encryption and public-key encryption
to provide confidentiality. When made confidential, first the object
is encrypted using a symmetric encryption algorithm. Each symmetric
key is used only once, for a single object. A new "session key" is
generated as a random number for each object (sometimes referred to
as a session). Since it is used only once, the session key is bound
to the message and transmitted with it. To protect the key, it is
encrypted with the receiver's public key. The sequence is as
follows:
Koch, et al. Expires 1 December 2023 [Page 6]
Internet-Draft OpenPGP Message Format May 2023
1. The sender creates a message.
2. The sending OpenPGP generates a random number to be used as a
session key for this message only.
3. The session key is encrypted using each recipient's public key.
These "encrypted session keys" start the message.
4. The sending OpenPGP encrypts the message using the session key,
which forms the remainder of the message. Note that the message
is also usually compressed.
5. The receiving OpenPGP decrypts the session key using the
recipient's private key.
6. The receiving OpenPGP decrypts the message using the session key.
If the message was compressed, it will be decompressed.
With symmetric-key encryption, an object may be encrypted with a
symmetric key derived from a passphrase (or other shared secret), or
a two-stage mechanism similar to the public-key method described
above in which a session key is itself encrypted with a symmetric
algorithm keyed from a shared secret.
Both digital signature and confidentiality services may be applied to
the same message. First, a signature is generated for the message
and attached to the message. Then the message plus signature is
encrypted using a symmetric session key. Finally, the session key is
encrypted using public-key encryption and prefixed to the encrypted
block.
2.2. Authentication via Digital Signature
The digital signature uses a hash code or message digest algorithm,
and a public-key signature algorithm. The sequence is as follows:
1. The sender creates a message.
2. The sending software generates a hash code of the message.
3. The sending software generates a signature from the hash code
using the sender's private key.
4. The binary signature is attached to the message.
5. The receiving software keeps a copy of the message signature.
Koch, et al. Expires 1 December 2023 [Page 7]
Internet-Draft OpenPGP Message Format May 2023
6. The receiving software generates a new hash code for the received
message and verifies it using the message's signature. If the
verification is successful, the message is accepted as authentic.
2.3. Compression
OpenPGP implementations SHOULD compress the message after applying
the signature but before encryption.
If an implementation does not implement compression, its authors
should be aware that most OpenPGP messages in the world are
compressed. Thus, it may even be wise for a space-constrained
implementation to implement decompression, but not compression.
Furthermore, compression has the added side effect that some types of
attacks can be thwarted by the fact that slightly altered, compressed
data rarely uncompresses without severe errors. This is hardly
rigorous, but it is operationally useful. These attacks can be
rigorously prevented by implementing and using Modification Detection
Codes as described in sections following.
2.4. Conversion to Radix-64
OpenPGP's underlying native representation for encrypted messages,
signature certificates, and keys is a stream of arbitrary octets.
Some systems only permit the use of blocks consisting of seven-bit,
printable text. For transporting OpenPGP's native raw binary octets
through channels that are not safe to raw binary data, a printable
encoding of these binary octets is needed. OpenPGP provides the
service of converting the raw 8-bit binary octet stream to a stream
of printable ASCII characters, called Radix-64 encoding or ASCII
Armor.
Implementations SHOULD provide Radix-64 conversions.
2.5. Signature-Only Applications
OpenPGP is designed for applications that use both encryption and
signatures, but there are a number of problems that are solved by a
signature-only implementation. Although this specification requires
both encryption and signatures, it is reasonable for there to be
subset implementations that are non-conformant only in that they omit
encryption.
3. Data Element Formats
This section describes the data elements used by OpenPGP.
Koch, et al. Expires 1 December 2023 [Page 8]
Internet-Draft OpenPGP Message Format May 2023
3.1. Scalar Numbers
Scalar numbers are unsigned and are always stored in big-endian
format. Using n[k] to refer to the kth octet being interpreted, the
value of a two-octet scalar is ((n[0] << 8) + n[1]). The value of a
four-octet scalar is ((n[0] << 24) + (n[1] << 16) + (n[2] << 8) +
n[3]).
3.2. Multiprecision Integers
Multiprecision integers (also called MPIs) are unsigned integers used
to hold large integers such as the ones used in cryptographic
calculations.
An MPI consists of two pieces: a two-octet scalar that is the length
of the MPI in bits followed by a string of octets that contain the
actual integer.
These octets form a big-endian number; a big-endian number can be
made into an MPI by prefixing it with the appropriate length.
Examples:
(all numbers are in hexadecimal)
The string of octets [00 01 01] forms an MPI with the value 1. The
string [00 09 01 FF] forms an MPI with the value of 511.
Additional rules:
The size of an MPI is ((MPI.length + 7) / 8) + 2 octets.
The length field of an MPI describes the length starting from its
most significant non-zero bit. Thus, the MPI [00 02 01] is not
formed correctly. It should be [00 01 01].
Unused bits of an MPI MUST be zero.
Also note that when an MPI is encrypted, the length refers to the
plaintext MPI. It may be ill-formed in its ciphertext.
3.3. Key IDs
A Key ID is an eight-octet scalar that identifies a key.
Implementations SHOULD NOT assume that Key IDs are unique. The
section "Enhanced Key Formats" below describes how Key IDs are
formed.
Koch, et al. Expires 1 December 2023 [Page 9]
Internet-Draft OpenPGP Message Format May 2023
3.4. Text
Unless otherwise specified, the character set for text is the UTF-8
[RFC3629] encoding of Unicode [ISO10646].
3.5. Time Fields
A time field is an unsigned four-octet number containing the number
of seconds elapsed since midnight, 1 January 1970 UTC.
3.6. Keyrings
A keyring is a collection of one or more keys in a file or database.
Traditionally, a keyring is simply a sequential list of keys, but may
be any suitable database. It is beyond the scope of this standard to
discuss the details of keyrings or other databases.
3.7. String-to-Key (S2K) Specifiers
String-to-key (S2K) specifiers are used to convert passphrase strings
into symmetric-key encryption/decryption keys. They are used in two
places, currently: to encrypt the secret part of private keys in the
private keyring, and to convert passphrases to encryption keys for
symmetrically encrypted messages.
3.7.1. String-to-Key (S2K) Specifier Types
There are three types of S2K specifiers currently supported, and some
reserved values:
+============+==========================+
| ID | S2K Type |
+============+==========================+
| 0 | Simple S2K |
+------------+--------------------------+
| 1 | Salted S2K |
+------------+--------------------------+
| 2 | Reserved value |
+------------+--------------------------+
| 3 | Iterated and Salted S2K |
+------------+--------------------------+
| 100 to 110 | Private/Experimental S2K |
+------------+--------------------------+
Table 1
These are described in the following Sections.
Koch, et al. Expires 1 December 2023 [Page 10]
Internet-Draft OpenPGP Message Format May 2023
3.7.1.1. Simple S2K
This directly hashes the string to produce the key data. See below
for how this hashing is done.
Octet 0: 0x00
Octet 1: hash algorithm
Simple S2K hashes the passphrase to produce the session key. The
manner in which this is done depends on the size of the session key
(which will depend on the cipher used) and the size of the hash
algorithm's output. If the hash size is greater than the session key
size, the high-order (leftmost) octets of the hash are used as the
key.
If the hash size is less than the key size, multiple instances of the
hash context are created -- enough to produce the required key data.
These instances are preloaded with 0, 1, 2, ... octets of zeros (that
is to say, the first instance has no preloading, the second gets
preloaded with 1 octet of zero, the third is preloaded with two
octets of zeros, and so forth).
As the data is hashed, it is given independently to each hash
context. Since the contexts have been initialized differently, they
will each produce different hash output. Once the passphrase is
hashed, the output data from the multiple hashes is concatenated,
first hash leftmost, to produce the key data, with any excess octets
on the right discarded.
3.7.1.2. Salted S2K
This includes a "salt" value in the S2K specifier -- some arbitrary
data -- that gets hashed along with the passphrase string, to help
prevent dictionary attacks.
Octet 0: 0x01
Octet 1: hash algorithm
Octets 2-9: 8-octet salt value
Salted S2K is exactly like Simple S2K, except that the input to the
hash function(s) consists of the 8 octets of salt from the S2K
specifier, followed by the passphrase.
Koch, et al. Expires 1 December 2023 [Page 11]
Internet-Draft OpenPGP Message Format May 2023
3.7.1.3. Iterated and Salted S2K
This includes both a salt and an octet count. The salt is combined
with the passphrase and the resulting value is hashed repeatedly.
This further increases the amount of work an attacker must do to try
dictionary attacks.
Octet 0: 0x03
Octet 1: hash algorithm
Octets 2-9: 8-octet salt value
Octet 10: count, a one-octet, coded value
The count is coded into a one-octet number using the following
formula:
#define EXPBIAS 6
count = ((Int32)16 + (c & 15)) << ((c >> 4) + EXPBIAS);
The above formula is in C, where "Int32" is a type for a 32-bit
integer, and the variable "c" is the coded count, Octet 10.
Iterated-Salted S2K hashes the passphrase and salt data multiple
times. The total number of octets to be hashed is specified in the
encoded count in the S2K specifier. Note that the resulting count
value is an octet count of how many octets will be hashed, not an
iteration count.
Initially, one or more hash contexts are set up as with the other S2K
algorithms, depending on how many octets of key data are needed.
Then the salt, followed by the passphrase data, is repeatedly hashed
until the number of octets specified by the octet count has been
hashed. The one exception is that if the octet count is less than
the size of the salt plus passphrase, the full salt plus passphrase
will be hashed even though that is greater than the octet count.
After the hashing is done, the data is unloaded from the hash
context(s) as with the other S2K algorithms.
3.7.2. String-to-Key Usage
Implementations SHOULD use salted or iterated-and-salted S2K
specifiers, as simple S2K specifiers are more vulnerable to
dictionary attacks.
Koch, et al. Expires 1 December 2023 [Page 12]
Internet-Draft OpenPGP Message Format May 2023
3.7.2.1. Secret-Key Encryption
An S2K specifier can be stored in the secret keyring to specify how
to convert the passphrase to a key that unlocks the secret data.
Older versions of PGP just stored a cipher algorithm octet preceding
the secret data or a zero to indicate that the secret data was
unencrypted. The MD5 hash function was always used to convert the
passphrase to a key for the specified cipher algorithm.
For compatibility, when an S2K specifier is used, the special value
253, 254, or 255 is stored in the position where the hash algorithm
octet would have been in the old data structure. This is then
followed immediately by a one-octet algorithm identifier, and then by
the S2K specifier as encoded above.
Therefore, preceding the secret data there will be one of these
possibilities:
0: secret data is unencrypted (no passphrase)
255, 254, or 253: followed by algorithm octet and S2K specifier
Cipher alg: use Simple S2K algorithm using MD5 hash
This last possibility, the cipher algorithm number with an implicit
use of MD5 and IDEA, is provided for backward compatibility; it MAY
be understood, but SHOULD NOT be generated, and is deprecated.
These are followed by an Initial Vector of the same length as the
block size of the cipher for the decryption of the secret values, if
they are encrypted, and then the secret-key values themselves.
3.7.2.2. Symmetric-Key Message Encryption
OpenPGP can create a Symmetric-key Encrypted Session Key (ESK) packet
at the front of a message. This is used to allow S2K specifiers to
be used for the passphrase conversion or to create messages with a
mix of symmetric-key ESKs and public-key ESKs. This allows a message
to be decrypted either with a passphrase or a public-key pair.
PGP 2 always used IDEA with Simple string-to-key conversion when
encrypting a message with a symmetric algorithm. This is deprecated,
but MAY be used for backward-compatibility.
4. Packet Syntax
This section describes the packets used by OpenPGP.
Koch, et al. Expires 1 December 2023 [Page 13]
Internet-Draft OpenPGP Message Format May 2023
4.1. Overview
An OpenPGP message is constructed from a number of records that are
traditionally called packets. A packet is a chunk of data that has a
tag specifying its meaning. An OpenPGP message, keyring,
certificate, and so forth consists of a number of packets. Some of
those packets may contain other OpenPGP packets (for example, a
compressed data packet, when uncompressed, contains OpenPGP packets).
Each packet consists of a packet header, followed by the packet body.
The packet header is of variable length.
4.2. Packet Headers
The first octet of the packet header is called the "Packet Tag". It
determines the format of the header and denotes the packet contents.
The remainder of the packet header is the length of the packet.
Note that the most significant bit is the leftmost bit, called bit 7.
A mask for this bit is 0x80 in hexadecimal.
+---------------+
PTag |7 6 5 4 3 2 1 0|
+---------------+
Bit 7 -- Always one
Bit 6 -- New packet format if set
PGP 2.6.x only uses old format packets. Thus, software that
interoperates with those versions of PGP must only use old format
packets. If interoperability is not an issue, the new packet format
is RECOMMENDED. Note that old format packets have four bits of
packet tags, and new format packets have six; some features cannot be
used and still be backward-compatible.
Also note that packets with a tag greater than or equal to 16 MUST
use new format packets. The old format packets can only express tags
less than or equal to 15.
Old format packets contain:
Bits 5-2 -- packet tag
Bits 1-0 -- length-type
New format packets contain:
Bits 5-0 -- packet tag
Koch, et al. Expires 1 December 2023 [Page 14]
Internet-Draft OpenPGP Message Format May 2023
4.2.1. Old Format Packet Lengths
The meaning of the length-type in old format packets is:
0 The packet has a one-octet length. The header is 2 octets long.
1 The packet has a two-octet length. The header is 3 octets long.
2 The packet has a four-octet length. The header is 5 octets long.
3 The packet is of indeterminate length. The header is 1 octet
long, and the implementation must determine how long the packet
is. If the packet is in a file, this means that the packet
extends until the end of the file. In general, an implementation
SHOULD NOT use indeterminate-length packets except where the end
of the data will be clear from the context, and even then it is
better to use a definite length, or a new format header. The new
format headers described below have a mechanism for precisely
encoding data of indeterminate length.
4.2.2. New Format Packet Lengths
New format packets have four possible ways of encoding length:
1. A one-octet Body Length header encodes packet lengths of up to
191 octets.
2. A two-octet Body Length header encodes packet lengths of 192 to
8383 octets.
3. A five-octet Body Length header encodes packet lengths of up to
4,294,967,295 (0xFFFFFFFF) octets in length. (This actually
encodes a four-octet scalar number.)
4. When the length of the packet body is not known in advance by the
issuer, Partial Body Length headers encode a packet of
indeterminate length, effectively making it a stream.
4.2.2.1. One-Octet Lengths
A one-octet Body Length header encodes a length of 0 to 191 octets.
This type of length header is recognized because the one octet value
is less than 192. The body length is equal to:
bodyLen = 1st_octet;
Koch, et al. Expires 1 December 2023 [Page 15]
Internet-Draft OpenPGP Message Format May 2023
4.2.2.2. Two-Octet Lengths
A two-octet Body Length header encodes a length of 192 to 8383
octets. It is recognized because its first octet is in the range 192
to 223. The body length is equal to:
bodyLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192
4.2.2.3. Five-Octet Lengths
A five-octet Body Length header consists of a single octet holding
the value 255, followed by a four-octet scalar. The body length is
equal to:
bodyLen = (2nd_octet << 24) | (3rd_octet << 16) |
(4th_octet << 8) | 5th_octet
This basic set of one, two, and five-octet lengths is also used
internally to some packets.
4.2.2.4. Partial Body Lengths
A Partial Body Length header is one octet long and encodes the length
of only part of the data packet. This length is a power of 2, from 1
to 1,073,741,824 (2 to the 30th power). It is recognized by its one
octet value that is greater than or equal to 224, and less than 255.
The Partial Body Length is equal to:
partialBodyLen = 1 << (1st_octet & 0x1F);
Each Partial Body Length header is followed by a portion of the
packet body data. The Partial Body Length header specifies this
portion's length. Another length header (one octet, two-octet, five-
octet, or partial) follows that portion. The last length header in
the packet MUST NOT be a Partial Body Length header. Partial Body
Length headers may only be used for the non-final parts of the
packet.
Note also that the last Body Length header can be a zero-length
header.
An implementation MAY use Partial Body Lengths for data packets, be
they literal, compressed, or encrypted. The first partial length
MUST be at least 512 octets long. Partial Body Lengths MUST NOT be
used for any other packet types.
Koch, et al. Expires 1 December 2023 [Page 16]
Internet-Draft OpenPGP Message Format May 2023
4.2.3. Packet Length Examples
These examples show ways that new format packets might encode the
packet lengths.
A packet with length 100 may have its length encoded in one octet:
0x64. This is followed by 100 octets of data.
A packet with length 1723 may have its length encoded in two octets:
0xC5, 0xFB. This header is followed by the 1723 octets of data.
A packet with length 100000 may have its length encoded in five
octets: 0xFF, 0x00, 0x01, 0x86, 0xA0.
It might also be encoded in the following octet stream: 0xEF, first
32768 octets of data; 0xE1, next two octets of data; 0xE0, next one
octet of data; 0xF0, next 65536 octets of data; 0xC5, 0xDD, last 1693
octets of data. This is just one possible encoding, and many
variations are possible on the size of the Partial Body Length
headers, as long as a regular Body Length header encodes the last
portion of the data.
Please note that in all of these explanations, the total length of
the packet is the length of the header(s) plus the length of the
body.
4.3. Packet Tags
The packet tag denotes what type of packet the body holds. Note that
old format headers can only have tags less than 16, whereas new
format headers can have tags as great as 63. The defined tags (in
decimal) are as follows:
+==========+====================================================+
| Tag | Packet Type |
+==========+====================================================+
| 0 | Reserved - a packet tag MUST NOT have this value |
+----------+----------------------------------------------------+
| 1 | Public-Key Encrypted Session Key Packet |
+----------+----------------------------------------------------+
| 2 | Signature Packet |
+----------+----------------------------------------------------+
| 3 | Symmetric-Key Encrypted Session Key Packet |
+----------+----------------------------------------------------+
| 4 | One-Pass Signature Packet |
+----------+----------------------------------------------------+
| 5 | Secret-Key Packet |
+----------+----------------------------------------------------+
Koch, et al. Expires 1 December 2023 [Page 17]
Internet-Draft OpenPGP Message Format May 2023
| 6 | Public-Key Packet |
+----------+----------------------------------------------------+
| 7 | Secret-Subkey Packet |
+----------+----------------------------------------------------+
| 8 | Compressed Data Packet |
+----------+----------------------------------------------------+
| 9 | Symmetrically Encrypted Data Packet |
+----------+----------------------------------------------------+
| 10 | Marker Packet |
+----------+----------------------------------------------------+
| 11 | Literal Data Packet |
+----------+----------------------------------------------------+
| 12 | Trust Packet |
+----------+----------------------------------------------------+
| 13 | User ID Packet |
+----------+----------------------------------------------------+
| 14 | Public-Subkey Packet |
+----------+----------------------------------------------------+
| 17 | User Attribute Packet |
+----------+----------------------------------------------------+
| 18 | Sym. Encrypted and Integrity Protected Data Packet |
+----------+----------------------------------------------------+
| 19 | Modification Detection Code Packet |
+----------+----------------------------------------------------+
| 20 | OCB Encrypted Data Packet |
+----------+----------------------------------------------------+
| 21 | Reserved |
+----------+----------------------------------------------------+
| 26 | Reserved (CMS Encrypted Session Key Packet) |
+----------+----------------------------------------------------+
| 60 to 63 | Private or Experimental Values |
+----------+----------------------------------------------------+
Table 2
5. Packet Types
5.1. Public-Key Encrypted Session Key Packets (Tag 1)
A Public-Key Encrypted Session Key packet holds the session key used
to encrypt a message. Zero or more Public-Key Encrypted Session Key
packets and/or Symmetric-Key Encrypted Session Key packets may
precede a Symmetrically Encrypted Data Packet, which holds an
encrypted message. The message is encrypted with the session key,