1// Copyright 2011 The Go Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5package openpgp 6 7import ( 8 "crypto/rsa" 9 "io" 10 "time" 11 12 "golang.org/x/crypto/openpgp/armor" 13 "golang.org/x/crypto/openpgp/errors" 14 "golang.org/x/crypto/openpgp/packet" 15) 16 17// PublicKeyType is the armor type for a PGP public key. 18var PublicKeyType = "PGP PUBLIC KEY BLOCK" 19 20// PrivateKeyType is the armor type for a PGP private key. 21var PrivateKeyType = "PGP PRIVATE KEY BLOCK" 22 23// An Entity represents the components of an OpenPGP key: a primary public key 24// (which must be a signing key), one or more identities claimed by that key, 25// and zero or more subkeys, which may be encryption keys. 26type Entity struct { 27 PrimaryKey *packet.PublicKey 28 PrivateKey *packet.PrivateKey 29 Identities map[string]*Identity // indexed by Identity.Name 30 Revocations []*packet.Signature 31 Subkeys []Subkey 32} 33 34// An Identity represents an identity claimed by an Entity and zero or more 35// assertions by other entities about that claim. 36type Identity struct { 37 Name string // by convention, has the form "Full Name (comment) <email@example.com>" 38 UserId *packet.UserId 39 SelfSignature *packet.Signature 40 Signatures []*packet.Signature 41} 42 43// A Subkey is an additional public key in an Entity. Subkeys can be used for 44// encryption. 45type Subkey struct { 46 PublicKey *packet.PublicKey 47 PrivateKey *packet.PrivateKey 48 Sig *packet.Signature 49} 50 51// A Key identifies a specific public key in an Entity. This is either the 52// Entity's primary key or a subkey. 53type Key struct { 54 Entity *Entity 55 PublicKey *packet.PublicKey 56 PrivateKey *packet.PrivateKey 57 SelfSignature *packet.Signature 58} 59 60// A KeyRing provides access to public and private keys. 61type KeyRing interface { 62 // KeysById returns the set of keys that have the given key id. 63 KeysById(id uint64) []Key 64 // KeysByIdAndUsage returns the set of keys with the given id 65 // that also meet the key usage given by requiredUsage. 66 // The requiredUsage is expressed as the bitwise-OR of 67 // packet.KeyFlag* values. 68 KeysByIdUsage(id uint64, requiredUsage byte) []Key 69 // DecryptionKeys returns all private keys that are valid for 70 // decryption. 71 DecryptionKeys() []Key 72} 73 74// primaryIdentity returns the Identity marked as primary or the first identity 75// if none are so marked. 76func (e *Entity) primaryIdentity() *Identity { 77 var firstIdentity *Identity 78 for _, ident := range e.Identities { 79 if firstIdentity == nil { 80 firstIdentity = ident 81 } 82 if ident.SelfSignature.IsPrimaryId != nil && *ident.SelfSignature.IsPrimaryId { 83 return ident 84 } 85 } 86 return firstIdentity 87} 88 89// encryptionKey returns the best candidate Key for encrypting a message to the 90// given Entity. 91func (e *Entity) encryptionKey(now time.Time) (Key, bool) { 92 candidateSubkey := -1 93 94 // Iterate the keys to find the newest key 95 var maxTime time.Time 96 for i, subkey := range e.Subkeys { 97 if subkey.Sig.FlagsValid && 98 subkey.Sig.FlagEncryptCommunications && 99 subkey.PublicKey.PubKeyAlgo.CanEncrypt() && 100 !subkey.Sig.KeyExpired(now) && 101 (maxTime.IsZero() || subkey.Sig.CreationTime.After(maxTime)) { 102 candidateSubkey = i 103 maxTime = subkey.Sig.CreationTime 104 } 105 } 106 107 if candidateSubkey != -1 { 108 subkey := e.Subkeys[candidateSubkey] 109 return Key{e, subkey.PublicKey, subkey.PrivateKey, subkey.Sig}, true 110 } 111 112 // If we don't have any candidate subkeys for encryption and 113 // the primary key doesn't have any usage metadata then we 114 // assume that the primary key is ok. Or, if the primary key is 115 // marked as ok to encrypt to, then we can obviously use it. 116 i := e.primaryIdentity() 117 if !i.SelfSignature.FlagsValid || i.SelfSignature.FlagEncryptCommunications && 118 e.PrimaryKey.PubKeyAlgo.CanEncrypt() && 119 !i.SelfSignature.KeyExpired(now) { 120 return Key{e, e.PrimaryKey, e.PrivateKey, i.SelfSignature}, true 121 } 122 123 // This Entity appears to be signing only. 124 return Key{}, false 125} 126 127// signingKey return the best candidate Key for signing a message with this 128// Entity. 129func (e *Entity) signingKey(now time.Time) (Key, bool) { 130 candidateSubkey := -1 131 132 for i, subkey := range e.Subkeys { 133 if subkey.Sig.FlagsValid && 134 subkey.Sig.FlagSign && 135 subkey.PublicKey.PubKeyAlgo.CanSign() && 136 !subkey.Sig.KeyExpired(now) { 137 candidateSubkey = i 138 break 139 } 140 } 141 142 if candidateSubkey != -1 { 143 subkey := e.Subkeys[candidateSubkey] 144 return Key{e, subkey.PublicKey, subkey.PrivateKey, subkey.Sig}, true 145 } 146 147 // If we have no candidate subkey then we assume that it's ok to sign 148 // with the primary key. 149 i := e.primaryIdentity() 150 if !i.SelfSignature.FlagsValid || i.SelfSignature.FlagSign && 151 !i.SelfSignature.KeyExpired(now) { 152 return Key{e, e.PrimaryKey, e.PrivateKey, i.SelfSignature}, true 153 } 154 155 return Key{}, false 156} 157 158// An EntityList contains one or more Entities. 159type EntityList []*Entity 160 161// KeysById returns the set of keys that have the given key id. 162func (el EntityList) KeysById(id uint64) (keys []Key) { 163 for _, e := range el { 164 if e.PrimaryKey.KeyId == id { 165 var selfSig *packet.Signature 166 for _, ident := range e.Identities { 167 if selfSig == nil { 168 selfSig = ident.SelfSignature 169 } else if ident.SelfSignature.IsPrimaryId != nil && *ident.SelfSignature.IsPrimaryId { 170 selfSig = ident.SelfSignature 171 break 172 } 173 } 174 keys = append(keys, Key{e, e.PrimaryKey, e.PrivateKey, selfSig}) 175 } 176 177 for _, subKey := range e.Subkeys { 178 if subKey.PublicKey.KeyId == id { 179 keys = append(keys, Key{e, subKey.PublicKey, subKey.PrivateKey, subKey.Sig}) 180 } 181 } 182 } 183 return 184} 185 186// KeysByIdAndUsage returns the set of keys with the given id that also meet 187// the key usage given by requiredUsage. The requiredUsage is expressed as 188// the bitwise-OR of packet.KeyFlag* values. 189func (el EntityList) KeysByIdUsage(id uint64, requiredUsage byte) (keys []Key) { 190 for _, key := range el.KeysById(id) { 191 if len(key.Entity.Revocations) > 0 { 192 continue 193 } 194 195 if key.SelfSignature.RevocationReason != nil { 196 continue 197 } 198 199 if key.SelfSignature.FlagsValid && requiredUsage != 0 { 200 var usage byte 201 if key.SelfSignature.FlagCertify { 202 usage |= packet.KeyFlagCertify 203 } 204 if key.SelfSignature.FlagSign { 205 usage |= packet.KeyFlagSign 206 } 207 if key.SelfSignature.FlagEncryptCommunications { 208 usage |= packet.KeyFlagEncryptCommunications 209 } 210 if key.SelfSignature.FlagEncryptStorage { 211 usage |= packet.KeyFlagEncryptStorage 212 } 213 if usage&requiredUsage != requiredUsage { 214 continue 215 } 216 } 217 218 keys = append(keys, key) 219 } 220 return 221} 222 223// DecryptionKeys returns all private keys that are valid for decryption. 224func (el EntityList) DecryptionKeys() (keys []Key) { 225 for _, e := range el { 226 for _, subKey := range e.Subkeys { 227 if subKey.PrivateKey != nil && (!subKey.Sig.FlagsValid || subKey.Sig.FlagEncryptStorage || subKey.Sig.FlagEncryptCommunications) { 228 keys = append(keys, Key{e, subKey.PublicKey, subKey.PrivateKey, subKey.Sig}) 229 } 230 } 231 } 232 return 233} 234 235// ReadArmoredKeyRing reads one or more public/private keys from an armor keyring file. 236func ReadArmoredKeyRing(r io.Reader) (EntityList, error) { 237 block, err := armor.Decode(r) 238 if err == io.EOF { 239 return nil, errors.InvalidArgumentError("no armored data found") 240 } 241 if err != nil { 242 return nil, err 243 } 244 if block.Type != PublicKeyType && block.Type != PrivateKeyType { 245 return nil, errors.InvalidArgumentError("expected public or private key block, got: " + block.Type) 246 } 247 248 return ReadKeyRing(block.Body) 249} 250 251// ReadKeyRing reads one or more public/private keys. Unsupported keys are 252// ignored as long as at least a single valid key is found. 253func ReadKeyRing(r io.Reader) (el EntityList, err error) { 254 packets := packet.NewReader(r) 255 var lastUnsupportedError error 256 257 for { 258 var e *Entity 259 e, err = ReadEntity(packets) 260 if err != nil { 261 // TODO: warn about skipped unsupported/unreadable keys 262 if _, ok := err.(errors.UnsupportedError); ok { 263 lastUnsupportedError = err 264 err = readToNextPublicKey(packets) 265 } else if _, ok := err.(errors.StructuralError); ok { 266 // Skip unreadable, badly-formatted keys 267 lastUnsupportedError = err 268 err = readToNextPublicKey(packets) 269 } 270 if err == io.EOF { 271 err = nil 272 break 273 } 274 if err != nil { 275 el = nil 276 break 277 } 278 } else { 279 el = append(el, e) 280 } 281 } 282 283 if len(el) == 0 && err == nil { 284 err = lastUnsupportedError 285 } 286 return 287} 288 289// readToNextPublicKey reads packets until the start of the entity and leaves 290// the first packet of the new entity in the Reader. 291func readToNextPublicKey(packets *packet.Reader) (err error) { 292 var p packet.Packet 293 for { 294 p, err = packets.Next() 295 if err == io.EOF { 296 return 297 } else if err != nil { 298 if _, ok := err.(errors.UnsupportedError); ok { 299 err = nil 300 continue 301 } 302 return 303 } 304 305 if pk, ok := p.(*packet.PublicKey); ok && !pk.IsSubkey { 306 packets.Unread(p) 307 return 308 } 309 } 310} 311 312// ReadEntity reads an entity (public key, identities, subkeys etc) from the 313// given Reader. 314func ReadEntity(packets *packet.Reader) (*Entity, error) { 315 e := new(Entity) 316 e.Identities = make(map[string]*Identity) 317 318 p, err := packets.Next() 319 if err != nil { 320 return nil, err 321 } 322 323 var ok bool 324 if e.PrimaryKey, ok = p.(*packet.PublicKey); !ok { 325 if e.PrivateKey, ok = p.(*packet.PrivateKey); !ok { 326 packets.Unread(p) 327 return nil, errors.StructuralError("first packet was not a public/private key") 328 } 329 e.PrimaryKey = &e.PrivateKey.PublicKey 330 } 331 332 if !e.PrimaryKey.PubKeyAlgo.CanSign() { 333 return nil, errors.StructuralError("primary key cannot be used for signatures") 334 } 335 336 var current *Identity 337 var revocations []*packet.Signature 338EachPacket: 339 for { 340 p, err := packets.Next() 341 if err == io.EOF { 342 break 343 } else if err != nil { 344 return nil, err 345 } 346 347 switch pkt := p.(type) { 348 case *packet.UserId: 349 // Make a new Identity object, that we might wind up throwing away. 350 // We'll only add it if we get a valid self-signature over this 351 // userID. 352 current = new(Identity) 353 current.Name = pkt.Id 354 current.UserId = pkt 355 356 for { 357 p, err = packets.Next() 358 if err == io.EOF { 359 break EachPacket 360 } else if err != nil { 361 return nil, err 362 } 363 364 sig, ok := p.(*packet.Signature) 365 if !ok { 366 packets.Unread(p) 367 continue EachPacket 368 } 369 370 if (sig.SigType == packet.SigTypePositiveCert || sig.SigType == packet.SigTypeGenericCert) && sig.IssuerKeyId != nil && *sig.IssuerKeyId == e.PrimaryKey.KeyId { 371 if err = e.PrimaryKey.VerifyUserIdSignature(pkt.Id, e.PrimaryKey, sig); err != nil { 372 return nil, errors.StructuralError("user ID self-signature invalid: " + err.Error()) 373 } 374 current.SelfSignature = sig 375 e.Identities[pkt.Id] = current 376 } else { 377 current.Signatures = append(current.Signatures, sig) 378 } 379 } 380 case *packet.Signature: 381 if pkt.SigType == packet.SigTypeKeyRevocation { 382 revocations = append(revocations, pkt) 383 } else if pkt.SigType == packet.SigTypeDirectSignature { 384 // TODO: RFC4880 5.2.1 permits signatures 385 // directly on keys (eg. to bind additional 386 // revocation keys). 387 } else if current == nil { 388 return nil, errors.StructuralError("signature packet found before user id packet") 389 } else { 390 current.Signatures = append(current.Signatures, pkt) 391 } 392 case *packet.PrivateKey: 393 if pkt.IsSubkey == false { 394 packets.Unread(p) 395 break EachPacket 396 } 397 err = addSubkey(e, packets, &pkt.PublicKey, pkt) 398 if err != nil { 399 return nil, err 400 } 401 case *packet.PublicKey: 402 if pkt.IsSubkey == false { 403 packets.Unread(p) 404 break EachPacket 405 } 406 err = addSubkey(e, packets, pkt, nil) 407 if err != nil { 408 return nil, err 409 } 410 default: 411 // we ignore unknown packets 412 } 413 } 414 415 if len(e.Identities) == 0 { 416 return nil, errors.StructuralError("entity without any identities") 417 } 418 419 for _, revocation := range revocations { 420 err = e.PrimaryKey.VerifyRevocationSignature(revocation) 421 if err == nil { 422 e.Revocations = append(e.Revocations, revocation) 423 } else { 424 // TODO: RFC 4880 5.2.3.15 defines revocation keys. 425 return nil, errors.StructuralError("revocation signature signed by alternate key") 426 } 427 } 428 429 return e, nil 430} 431 432func addSubkey(e *Entity, packets *packet.Reader, pub *packet.PublicKey, priv *packet.PrivateKey) error { 433 var subKey Subkey 434 subKey.PublicKey = pub 435 subKey.PrivateKey = priv 436 p, err := packets.Next() 437 if err == io.EOF { 438 return io.ErrUnexpectedEOF 439 } 440 if err != nil { 441 return errors.StructuralError("subkey signature invalid: " + err.Error()) 442 } 443 var ok bool 444 subKey.Sig, ok = p.(*packet.Signature) 445 if !ok { 446 return errors.StructuralError("subkey packet not followed by signature") 447 } 448 if subKey.Sig.SigType != packet.SigTypeSubkeyBinding && subKey.Sig.SigType != packet.SigTypeSubkeyRevocation { 449 return errors.StructuralError("subkey signature with wrong type") 450 } 451 err = e.PrimaryKey.VerifyKeySignature(subKey.PublicKey, subKey.Sig) 452 if err != nil { 453 return errors.StructuralError("subkey signature invalid: " + err.Error()) 454 } 455 e.Subkeys = append(e.Subkeys, subKey) 456 return nil 457} 458 459const defaultRSAKeyBits = 2048 460 461// NewEntity returns an Entity that contains a fresh RSA/RSA keypair with a 462// single identity composed of the given full name, comment and email, any of 463// which may be empty but must not contain any of "()<>\x00". 464// If config is nil, sensible defaults will be used. 465func NewEntity(name, comment, email string, config *packet.Config) (*Entity, error) { 466 currentTime := config.Now() 467 468 bits := defaultRSAKeyBits 469 if config != nil && config.RSABits != 0 { 470 bits = config.RSABits 471 } 472 473 uid := packet.NewUserId(name, comment, email) 474 if uid == nil { 475 return nil, errors.InvalidArgumentError("user id field contained invalid characters") 476 } 477 signingPriv, err := rsa.GenerateKey(config.Random(), bits) 478 if err != nil { 479 return nil, err 480 } 481 encryptingPriv, err := rsa.GenerateKey(config.Random(), bits) 482 if err != nil { 483 return nil, err 484 } 485 486 e := &Entity{ 487 PrimaryKey: packet.NewRSAPublicKey(currentTime, &signingPriv.PublicKey), 488 PrivateKey: packet.NewRSAPrivateKey(currentTime, signingPriv), 489 Identities: make(map[string]*Identity), 490 } 491 isPrimaryId := true 492 e.Identities[uid.Id] = &Identity{ 493 Name: uid.Id, 494 UserId: uid, 495 SelfSignature: &packet.Signature{ 496 CreationTime: currentTime, 497 SigType: packet.SigTypePositiveCert, 498 PubKeyAlgo: packet.PubKeyAlgoRSA, 499 Hash: config.Hash(), 500 IsPrimaryId: &isPrimaryId, 501 FlagsValid: true, 502 FlagSign: true, 503 FlagCertify: true, 504 IssuerKeyId: &e.PrimaryKey.KeyId, 505 }, 506 } 507 err = e.Identities[uid.Id].SelfSignature.SignUserId(uid.Id, e.PrimaryKey, e.PrivateKey, config) 508 if err != nil { 509 return nil, err 510 } 511 512 // If the user passes in a DefaultHash via packet.Config, 513 // set the PreferredHash for the SelfSignature. 514 if config != nil && config.DefaultHash != 0 { 515 e.Identities[uid.Id].SelfSignature.PreferredHash = []uint8{hashToHashId(config.DefaultHash)} 516 } 517 518 // Likewise for DefaultCipher. 519 if config != nil && config.DefaultCipher != 0 { 520 e.Identities[uid.Id].SelfSignature.PreferredSymmetric = []uint8{uint8(config.DefaultCipher)} 521 } 522 523 e.Subkeys = make([]Subkey, 1) 524 e.Subkeys[0] = Subkey{ 525 PublicKey: packet.NewRSAPublicKey(currentTime, &encryptingPriv.PublicKey), 526 PrivateKey: packet.NewRSAPrivateKey(currentTime, encryptingPriv), 527 Sig: &packet.Signature{ 528 CreationTime: currentTime, 529 SigType: packet.SigTypeSubkeyBinding, 530 PubKeyAlgo: packet.PubKeyAlgoRSA, 531 Hash: config.Hash(), 532 FlagsValid: true, 533 FlagEncryptStorage: true, 534 FlagEncryptCommunications: true, 535 IssuerKeyId: &e.PrimaryKey.KeyId, 536 }, 537 } 538 e.Subkeys[0].PublicKey.IsSubkey = true 539 e.Subkeys[0].PrivateKey.IsSubkey = true 540 err = e.Subkeys[0].Sig.SignKey(e.Subkeys[0].PublicKey, e.PrivateKey, config) 541 if err != nil { 542 return nil, err 543 } 544 return e, nil 545} 546 547// SerializePrivate serializes an Entity, including private key material, but 548// excluding signatures from other entities, to the given Writer. 549// Identities and subkeys are re-signed in case they changed since NewEntry. 550// If config is nil, sensible defaults will be used. 551func (e *Entity) SerializePrivate(w io.Writer, config *packet.Config) (err error) { 552 err = e.PrivateKey.Serialize(w) 553 if err != nil { 554 return 555 } 556 for _, ident := range e.Identities { 557 err = ident.UserId.Serialize(w) 558 if err != nil { 559 return 560 } 561 err = ident.SelfSignature.SignUserId(ident.UserId.Id, e.PrimaryKey, e.PrivateKey, config) 562 if err != nil { 563 return 564 } 565 err = ident.SelfSignature.Serialize(w) 566 if err != nil { 567 return 568 } 569 } 570 for _, subkey := range e.Subkeys { 571 err = subkey.PrivateKey.Serialize(w) 572 if err != nil { 573 return 574 } 575 err = subkey.Sig.SignKey(subkey.PublicKey, e.PrivateKey, config) 576 if err != nil { 577 return 578 } 579 err = subkey.Sig.Serialize(w) 580 if err != nil { 581 return 582 } 583 } 584 return nil 585} 586 587// Serialize writes the public part of the given Entity to w, including 588// signatures from other entities. No private key material will be output. 589func (e *Entity) Serialize(w io.Writer) error { 590 err := e.PrimaryKey.Serialize(w) 591 if err != nil { 592 return err 593 } 594 for _, ident := range e.Identities { 595 err = ident.UserId.Serialize(w) 596 if err != nil { 597 return err 598 } 599 err = ident.SelfSignature.Serialize(w) 600 if err != nil { 601 return err 602 } 603 for _, sig := range ident.Signatures { 604 err = sig.Serialize(w) 605 if err != nil { 606 return err 607 } 608 } 609 } 610 for _, subkey := range e.Subkeys { 611 err = subkey.PublicKey.Serialize(w) 612 if err != nil { 613 return err 614 } 615 err = subkey.Sig.Serialize(w) 616 if err != nil { 617 return err 618 } 619 } 620 return nil 621} 622 623// SignIdentity adds a signature to e, from signer, attesting that identity is 624// associated with e. The provided identity must already be an element of 625// e.Identities and the private key of signer must have been decrypted if 626// necessary. 627// If config is nil, sensible defaults will be used. 628func (e *Entity) SignIdentity(identity string, signer *Entity, config *packet.Config) error { 629 if signer.PrivateKey == nil { 630 return errors.InvalidArgumentError("signing Entity must have a private key") 631 } 632 if signer.PrivateKey.Encrypted { 633 return errors.InvalidArgumentError("signing Entity's private key must be decrypted") 634 } 635 ident, ok := e.Identities[identity] 636 if !ok { 637 return errors.InvalidArgumentError("given identity string not found in Entity") 638 } 639 640 sig := &packet.Signature{ 641 SigType: packet.SigTypeGenericCert, 642 PubKeyAlgo: signer.PrivateKey.PubKeyAlgo, 643 Hash: config.Hash(), 644 CreationTime: config.Now(), 645 IssuerKeyId: &signer.PrivateKey.KeyId, 646 } 647 if err := sig.SignUserId(identity, e.PrimaryKey, signer.PrivateKey, config); err != nil { 648 return err 649 } 650 ident.Signatures = append(ident.Signatures, sig) 651 return nil 652} 653