libgo/go/crypto/openpgp/keys.go

   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
   5 package openpgp
   6
   7 import (
   8         "crypto"
   9         "crypto/openpgp/armor"
  10         error_ "crypto/openpgp/error"
  11         "crypto/openpgp/packet"
  12         "crypto/rsa"
  13         "io"
  14         "time"
  15 )
  16
  17 // PublicKeyType is the armor type for a PGP public key.
  18 var PublicKeyType = "PGP PUBLIC KEY BLOCK"
  19
  20 // PrivateKeyType is the armor type for a PGP private key.
  21 var 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.
  26 type Entity struct {
  27         PrimaryKey *packet.PublicKey
  28         PrivateKey *packet.PrivateKey
  29         Identities map[string]*Identity // indexed by Identity.Name
  30         Subkeys    []Subkey
  31 }
  32
  33 // An Identity represents an identity claimed by an Entity and zero or more
  34 // assertions by other entities about that claim.
  35 type Identity struct {
  36         Name          string // by convention, has the form "Full Name (comment) <email@example.com>"
  37         UserId        *packet.UserId
  38         SelfSignature *packet.Signature
  39         Signatures    []*packet.Signature
  40 }
  41
  42 // A Subkey is an additional public key in an Entity. Subkeys can be used for
  43 // encryption.
  44 type Subkey struct {
  45         PublicKey  *packet.PublicKey
  46         PrivateKey *packet.PrivateKey
  47         Sig        *packet.Signature
  48 }
  49
  50 // A Key identifies a specific public key in an Entity. This is either the
  51 // Entity's primary key or a subkey.
  52 type Key struct {
  53         Entity        *Entity
  54         PublicKey     *packet.PublicKey
  55         PrivateKey    *packet.PrivateKey
  56         SelfSignature *packet.Signature
  57 }
  58
  59 // A KeyRing provides access to public and private keys.
  60 type KeyRing interface {
  61         // KeysById returns the set of keys that have the given key id.
  62         KeysById(id uint64) []Key
  63         // DecryptionKeys returns all private keys that are valid for
  64         // decryption.
  65         DecryptionKeys() []Key
  66 }
  67
  68 // primaryIdentity returns the Identity marked as primary or the first identity
  69 // if none are so marked.
  70 func (e *Entity) primaryIdentity() *Identity {
  71         var firstIdentity *Identity
  72         for _, ident := range e.Identities {
  73                 if firstIdentity == nil {
  74                         firstIdentity = ident
  75                 }
  76                 if ident.SelfSignature.IsPrimaryId != nil && *ident.SelfSignature.IsPrimaryId {
  77                         return ident
  78                 }
  79         }
  80         return firstIdentity
  81 }
  82
  83 // encryptionKey returns the best candidate Key for encrypting a message to the
  84 // given Entity.
  85 func (e *Entity) encryptionKey() Key {
  86         candidateSubkey := -1
  87
  88         for i, subkey := range e.Subkeys {
  89                 if subkey.Sig.FlagsValid && subkey.Sig.FlagEncryptCommunications && subkey.PublicKey.PubKeyAlgo.CanEncrypt() {
  90                         candidateSubkey = i
  91                         break
  92                 }
  93         }
  94
  95         i := e.primaryIdentity()
  96
  97         if e.PrimaryKey.PubKeyAlgo.CanEncrypt() {
  98                 // If we don't have any candidate subkeys for encryption and
  99                 // the primary key doesn't have any usage metadata then we
 100                 // assume that the primary key is ok. Or, if the primary key is
 101                 // marked as ok to encrypt to, then we can obviously use it.
 102                 if candidateSubkey == -1 && !i.SelfSignature.FlagsValid || i.SelfSignature.FlagEncryptCommunications && i.SelfSignature.FlagsValid {
 103                         return Key{e, e.PrimaryKey, e.PrivateKey, i.SelfSignature}
 104                 }
 105         }
 106
 107         if candidateSubkey != -1 {
 108                 subkey := e.Subkeys[candidateSubkey]
 109                 return Key{e, subkey.PublicKey, subkey.PrivateKey, subkey.Sig}
 110         }
 111
 112         // This Entity appears to be signing only.
 113         return Key{}
 114 }
 115
 116 // signingKey return the best candidate Key for signing a message with this
 117 // Entity.
 118 func (e *Entity) signingKey() Key {
 119         candidateSubkey := -1
 120
 121         for i, subkey := range e.Subkeys {
 122                 if subkey.Sig.FlagsValid && subkey.Sig.FlagSign && subkey.PublicKey.PubKeyAlgo.CanSign() {
 123                         candidateSubkey = i
 124                         break
 125                 }
 126         }
 127
 128         i := e.primaryIdentity()
 129
 130         // If we have no candidate subkey then we assume that it's ok to sign
 131         // with the primary key.
 132         if candidateSubkey == -1 || i.SelfSignature.FlagsValid && i.SelfSignature.FlagSign {
 133                 return Key{e, e.PrimaryKey, e.PrivateKey, i.SelfSignature}
 134         }
 135
 136         subkey := e.Subkeys[candidateSubkey]
 137         return Key{e, subkey.PublicKey, subkey.PrivateKey, subkey.Sig}
 138 }
 139
 140 // An EntityList contains one or more Entities.
 141 type EntityList []*Entity
 142
 143 // KeysById returns the set of keys that have the given key id.
 144 func (el EntityList) KeysById(id uint64) (keys []Key) {
 145         for _, e := range el {
 146                 if e.PrimaryKey.KeyId == id {
 147                         var selfSig *packet.Signature
 148                         for _, ident := range e.Identities {
 149                                 if selfSig == nil {
 150                                         selfSig = ident.SelfSignature
 151                                 } else if ident.SelfSignature.IsPrimaryId != nil && *ident.SelfSignature.IsPrimaryId {
 152                                         selfSig = ident.SelfSignature
 153                                         break
 154                                 }
 155                         }
 156                         keys = append(keys, Key{e, e.PrimaryKey, e.PrivateKey, selfSig})
 157                 }
 158
 159                 for _, subKey := range e.Subkeys {
 160                         if subKey.PublicKey.KeyId == id {
 161                                 keys = append(keys, Key{e, subKey.PublicKey, subKey.PrivateKey, subKey.Sig})
 162                         }
 163                 }
 164         }
 165         return
 166 }
 167
 168 // DecryptionKeys returns all private keys that are valid for decryption.
 169 func (el EntityList) DecryptionKeys() (keys []Key) {
 170         for _, e := range el {
 171                 for _, subKey := range e.Subkeys {
 172                         if subKey.PrivateKey != nil && (!subKey.Sig.FlagsValid || subKey.Sig.FlagEncryptStorage || subKey.Sig.FlagEncryptCommunications) {
 173                                 keys = append(keys, Key{e, subKey.PublicKey, subKey.PrivateKey, subKey.Sig})
 174                         }
 175                 }
 176         }
 177         return
 178 }
 179
 180 // ReadArmoredKeyRing reads one or more public/private keys from an armor keyring file.
 181 func ReadArmoredKeyRing(r io.Reader) (EntityList, error) {
 182         block, err := armor.Decode(r)
 183         if err == io.EOF {
 184                 return nil, error_.InvalidArgumentError("no armored data found")
 185         }
 186         if err != nil {
 187                 return nil, err
 188         }
 189         if block.Type != PublicKeyType && block.Type != PrivateKeyType {
 190                 return nil, error_.InvalidArgumentError("expected public or private key block, got: " + block.Type)
 191         }
 192
 193         return ReadKeyRing(block.Body)
 194 }
 195
 196 // ReadKeyRing reads one or more public/private keys. Unsupported keys are
 197 // ignored as long as at least a single valid key is found.
 198 func ReadKeyRing(r io.Reader) (el EntityList, err error) {
 199         packets := packet.NewReader(r)
 200         var lastUnsupportedError error
 201
 202         for {
 203                 var e *Entity
 204                 e, err = readEntity(packets)
 205                 if err != nil {
 206                         if _, ok := err.(error_.UnsupportedError); ok {
 207                                 lastUnsupportedError = err
 208                                 err = readToNextPublicKey(packets)
 209                         }
 210                         if err == io.EOF {
 211                                 err = nil
 212                                 break
 213                         }
 214                         if err != nil {
 215                                 el = nil
 216                                 break
 217                         }
 218                 } else {
 219                         el = append(el, e)
 220                 }
 221         }
 222
 223         if len(el) == 0 && err == nil {
 224                 err = lastUnsupportedError
 225         }
 226         return
 227 }
 228
 229 // readToNextPublicKey reads packets until the start of the entity and leaves
 230 // the first packet of the new entity in the Reader.
 231 func readToNextPublicKey(packets *packet.Reader) (err error) {
 232         var p packet.Packet
 233         for {
 234                 p, err = packets.Next()
 235                 if err == io.EOF {
 236                         return
 237                 } else if err != nil {
 238                         if _, ok := err.(error_.UnsupportedError); ok {
 239                                 err = nil
 240                                 continue
 241                         }
 242                         return
 243                 }
 244
 245                 if pk, ok := p.(*packet.PublicKey); ok && !pk.IsSubkey {
 246                         packets.Unread(p)
 247                         return
 248                 }
 249         }
 250
 251         panic("unreachable")
 252 }
 253
 254 // readEntity reads an entity (public key, identities, subkeys etc) from the
 255 // given Reader.
 256 func readEntity(packets *packet.Reader) (*Entity, error) {
 257         e := new(Entity)
 258         e.Identities = make(map[string]*Identity)
 259
 260         p, err := packets.Next()
 261         if err != nil {
 262                 return nil, err
 263         }
 264
 265         var ok bool
 266         if e.PrimaryKey, ok = p.(*packet.PublicKey); !ok {
 267                 if e.PrivateKey, ok = p.(*packet.PrivateKey); !ok {
 268                         packets.Unread(p)
 269                         return nil, error_.StructuralError("first packet was not a public/private key")
 270                 } else {
 271                         e.PrimaryKey = &e.PrivateKey.PublicKey
 272                 }
 273         }
 274
 275         if !e.PrimaryKey.PubKeyAlgo.CanSign() {
 276                 return nil, error_.StructuralError("primary key cannot be used for signatures")
 277         }
 278
 279         var current *Identity
 280 EachPacket:
 281         for {
 282                 p, err := packets.Next()
 283                 if err == io.EOF {
 284                         break
 285                 } else if err != nil {
 286                         return nil, err
 287                 }
 288
 289                 switch pkt := p.(type) {
 290                 case *packet.UserId:
 291                         current = new(Identity)
 292                         current.Name = pkt.Id
 293                         current.UserId = pkt
 294                         e.Identities[pkt.Id] = current
 295
 296                         for {
 297                                 p, err = packets.Next()
 298                                 if err == io.EOF {
 299                                         return nil, io.ErrUnexpectedEOF
 300                                 } else if err != nil {
 301                                         return nil, err
 302                                 }
 303
 304                                 sig, ok := p.(*packet.Signature)
 305                                 if !ok {
 306                                         return nil, error_.StructuralError("user ID packet not followed by self-signature")
 307                                 }
 308
 309                                 if (sig.SigType == packet.SigTypePositiveCert || sig.SigType == packet.SigTypeGenericCert) && sig.IssuerKeyId != nil && *sig.IssuerKeyId == e.PrimaryKey.KeyId {
 310                                         if err = e.PrimaryKey.VerifyUserIdSignature(pkt.Id, sig); err != nil {
 311                                                 return nil, error_.StructuralError("user ID self-signature invalid: " + err.Error())
 312                                         }
 313                                         current.SelfSignature = sig
 314                                         break
 315                                 }
 316                                 current.Signatures = append(current.Signatures, sig)
 317                         }
 318                 case *packet.Signature:
 319                         if current == nil {
 320                                 return nil, error_.StructuralError("signature packet found before user id packet")
 321                         }
 322                         current.Signatures = append(current.Signatures, pkt)
 323                 case *packet.PrivateKey:
 324                         if pkt.IsSubkey == false {
 325                                 packets.Unread(p)
 326                                 break EachPacket
 327                         }
 328                         err = addSubkey(e, packets, &pkt.PublicKey, pkt)
 329                         if err != nil {
 330                                 return nil, err
 331                         }
 332                 case *packet.PublicKey:
 333                         if pkt.IsSubkey == false {
 334                                 packets.Unread(p)
 335                                 break EachPacket
 336                         }
 337                         err = addSubkey(e, packets, pkt, nil)
 338                         if err != nil {
 339                                 return nil, err
 340                         }
 341                 default:
 342                         // we ignore unknown packets
 343                 }
 344         }
 345
 346         if len(e.Identities) == 0 {
 347                 return nil, error_.StructuralError("entity without any identities")
 348         }
 349
 350         return e, nil
 351 }
 352
 353 func addSubkey(e *Entity, packets *packet.Reader, pub *packet.PublicKey, priv *packet.PrivateKey) error {
 354         var subKey Subkey
 355         subKey.PublicKey = pub
 356         subKey.PrivateKey = priv
 357         p, err := packets.Next()
 358         if err == io.EOF {
 359                 return io.ErrUnexpectedEOF
 360         }
 361         if err != nil {
 362                 return error_.StructuralError("subkey signature invalid: " + err.Error())
 363         }
 364         var ok bool
 365         subKey.Sig, ok = p.(*packet.Signature)
 366         if !ok {
 367                 return error_.StructuralError("subkey packet not followed by signature")
 368         }
 369         if subKey.Sig.SigType != packet.SigTypeSubkeyBinding {
 370                 return error_.StructuralError("subkey signature with wrong type")
 371         }
 372         err = e.PrimaryKey.VerifyKeySignature(subKey.PublicKey, subKey.Sig)
 373         if err != nil {
 374                 return error_.StructuralError("subkey signature invalid: " + err.Error())
 375         }
 376         e.Subkeys = append(e.Subkeys, subKey)
 377         return nil
 378 }
 379
 380 const defaultRSAKeyBits = 2048
 381
 382 // NewEntity returns an Entity that contains a fresh RSA/RSA keypair with a
 383 // single identity composed of the given full name, comment and email, any of
 384 // which may be empty but must not contain any of "()<>\x00".
 385 func NewEntity(rand io.Reader, currentTime time.Time, name, comment, email string) (*Entity, error) {
 386         uid := packet.NewUserId(name, comment, email)
 387         if uid == nil {
 388                 return nil, error_.InvalidArgumentError("user id field contained invalid characters")
 389         }
 390         signingPriv, err := rsa.GenerateKey(rand, defaultRSAKeyBits)
 391         if err != nil {
 392                 return nil, err
 393         }
 394         encryptingPriv, err := rsa.GenerateKey(rand, defaultRSAKeyBits)
 395         if err != nil {
 396                 return nil, err
 397         }
 398
 399         e := &Entity{
 400                 PrimaryKey: packet.NewRSAPublicKey(currentTime, &signingPriv.PublicKey, false /* not a subkey */ ),
 401                 PrivateKey: packet.NewRSAPrivateKey(currentTime, signingPriv, false /* not a subkey */ ),
 402                 Identities: make(map[string]*Identity),
 403         }
 404         isPrimaryId := true
 405         e.Identities[uid.Id] = &Identity{
 406                 Name:   uid.Name,
 407                 UserId: uid,
 408                 SelfSignature: &packet.Signature{
 409                         CreationTime: currentTime,
 410                         SigType:      packet.SigTypePositiveCert,
 411                         PubKeyAlgo:   packet.PubKeyAlgoRSA,
 412                         Hash:         crypto.SHA256,
 413                         IsPrimaryId:  &isPrimaryId,
 414                         FlagsValid:   true,
 415                         FlagSign:     true,
 416                         FlagCertify:  true,
 417                         IssuerKeyId:  &e.PrimaryKey.KeyId,
 418                 },
 419         }
 420
 421         e.Subkeys = make([]Subkey, 1)
 422         e.Subkeys[0] = Subkey{
 423                 PublicKey:  packet.NewRSAPublicKey(currentTime, &encryptingPriv.PublicKey, true /* is a subkey */ ),
 424                 PrivateKey: packet.NewRSAPrivateKey(currentTime, encryptingPriv, true /* is a subkey */ ),
 425                 Sig: &packet.Signature{
 426                         CreationTime:              currentTime,
 427                         SigType:                   packet.SigTypeSubkeyBinding,
 428                         PubKeyAlgo:                packet.PubKeyAlgoRSA,
 429                         Hash:                      crypto.SHA256,
 430                         FlagsValid:                true,
 431                         FlagEncryptStorage:        true,
 432                         FlagEncryptCommunications: true,
 433                         IssuerKeyId:               &e.PrimaryKey.KeyId,
 434                 },
 435         }
 436
 437         return e, nil
 438 }
 439
 440 // SerializePrivate serializes an Entity, including private key material, to
 441 // the given Writer. For now, it must only be used on an Entity returned from
 442 // NewEntity.
 443 func (e *Entity) SerializePrivate(w io.Writer) (err error) {
 444         err = e.PrivateKey.Serialize(w)
 445         if err != nil {
 446                 return
 447         }
 448         for _, ident := range e.Identities {
 449                 err = ident.UserId.Serialize(w)
 450                 if err != nil {
 451                         return
 452                 }
 453                 err = ident.SelfSignature.SignUserId(ident.UserId.Id, e.PrimaryKey, e.PrivateKey)
 454                 if err != nil {
 455                         return
 456                 }
 457                 err = ident.SelfSignature.Serialize(w)
 458                 if err != nil {
 459                         return
 460                 }
 461         }
 462         for _, subkey := range e.Subkeys {
 463                 err = subkey.PrivateKey.Serialize(w)
 464                 if err != nil {
 465                         return
 466                 }
 467                 err = subkey.Sig.SignKey(subkey.PublicKey, e.PrivateKey)
 468                 if err != nil {
 469                         return
 470                 }
 471                 err = subkey.Sig.Serialize(w)
 472                 if err != nil {
 473                         return
 474                 }
 475         }
 476         return nil
 477 }
 478
 479 // Serialize writes the public part of the given Entity to w. (No private
 480 // key material will be output).
 481 func (e *Entity) Serialize(w io.Writer) error {
 482         err := e.PrimaryKey.Serialize(w)
 483         if err != nil {
 484                 return err
 485         }
 486         for _, ident := range e.Identities {
 487                 err = ident.UserId.Serialize(w)
 488                 if err != nil {
 489                         return err
 490                 }
 491                 err = ident.SelfSignature.Serialize(w)
 492                 if err != nil {
 493                         return err
 494                 }
 495                 for _, sig := range ident.Signatures {
 496                         err = sig.Serialize(w)
 497                         if err != nil {
 498                                 return err
 499                         }
 500                 }
 501         }
 502         for _, subkey := range e.Subkeys {
 503                 err = subkey.PublicKey.Serialize(w)
 504                 if err != nil {
 505                         return err
 506                 }
 507                 err = subkey.Sig.Serialize(w)
 508                 if err != nil {
 509                         return err
 510                 }
 511         }
 512         return nil
 513 }
 514
 515 // SignIdentity adds a signature to e, from signer, attesting that identity is
 516 // associated with e. The provided identity must already be an element of
 517 // e.Identities and the private key of signer must have been decrypted if
 518 // necessary.
 519 func (e *Entity) SignIdentity(identity string, signer *Entity) error {
 520         if signer.PrivateKey == nil {
 521                 return error_.InvalidArgumentError("signing Entity must have a private key")
 522         }
 523         if signer.PrivateKey.Encrypted {
 524                 return error_.InvalidArgumentError("signing Entity's private key must be decrypted")
 525         }
 526         ident, ok := e.Identities[identity]
 527         if !ok {
 528                 return error_.InvalidArgumentError("given identity string not found in Entity")
 529         }
 530
 531         sig := &packet.Signature{
 532                 SigType:      packet.SigTypeGenericCert,
 533                 PubKeyAlgo:   signer.PrivateKey.PubKeyAlgo,
 534                 Hash:         crypto.SHA256,
 535                 CreationTime: time.Now(),
 536                 IssuerKeyId:  &signer.PrivateKey.KeyId,
 537         }
 538         if err := sig.SignKey(e.PrimaryKey, signer.PrivateKey); err != nil {
 539                 return err
 540         }
 541         ident.Signatures = append(ident.Signatures, sig)
 542         return nil
 543 }