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.
5 // Package openpgp implements high level operations on OpenPGP messages.
6 package openpgp // import "golang.org/x/crypto/openpgp"
15 "golang.org/x/crypto/openpgp/armor"
16 "golang.org/x/crypto/openpgp/errors"
17 "golang.org/x/crypto/openpgp/packet"
20 // SignatureType is the armor type for a PGP signature.
21 var SignatureType = "PGP SIGNATURE"
23 // readArmored reads an armored block with the given type.
24 func readArmored(r io.Reader, expectedType string) (body io.Reader, err error) {
25 block, err := armor.Decode(r)
30 if block.Type != expectedType {
31 return nil, errors.InvalidArgumentError("expected '" + expectedType + "', got: " + block.Type)
34 return block.Body, nil
37 // MessageDetails contains the result of parsing an OpenPGP encrypted and/or
39 type MessageDetails struct {
40 IsEncrypted bool // true if the message was encrypted.
41 EncryptedToKeyIds []uint64 // the list of recipient key ids.
42 IsSymmetricallyEncrypted bool // true if a passphrase could have decrypted the message.
43 DecryptedWith Key // the private key used to decrypt the message, if any.
44 IsSigned bool // true if the message is signed.
45 SignedByKeyId uint64 // the key id of the signer, if any.
46 SignedBy *Key // the key of the signer, if available.
47 LiteralData *packet.LiteralData // the metadata of the contents
48 UnverifiedBody io.Reader // the contents of the message.
50 // If IsSigned is true and SignedBy is non-zero then the signature will
51 // be verified as UnverifiedBody is read. The signature cannot be
52 // checked until the whole of UnverifiedBody is read so UnverifiedBody
53 // must be consumed until EOF before the data can be trusted. Even if a
54 // message isn't signed (or the signer is unknown) the data may contain
55 // an authentication code that is only checked once UnverifiedBody has
56 // been consumed. Once EOF has been seen, the following fields are
57 // valid. (An authentication code failure is reported as a
58 // SignatureError error when reading from UnverifiedBody.)
59 SignatureError error // nil if the signature is good.
60 Signature *packet.Signature // the signature packet itself, if v4 (default)
61 SignatureV3 *packet.SignatureV3 // the signature packet if it is a v2 or v3 signature
63 decrypted io.ReadCloser
66 // A PromptFunction is used as a callback by functions that may need to decrypt
67 // a private key, or prompt for a passphrase. It is called with a list of
68 // acceptable, encrypted private keys and a boolean that indicates whether a
69 // passphrase is usable. It should either decrypt a private key or return a
70 // passphrase to try. If the decrypted private key or given passphrase isn't
71 // correct, the function will be called again, forever. Any error returned will
73 type PromptFunction func(keys []Key, symmetric bool) ([]byte, error)
75 // A keyEnvelopePair is used to store a private key with the envelope that
76 // contains a symmetric key, encrypted with that key.
77 type keyEnvelopePair struct {
79 encryptedKey *packet.EncryptedKey
82 // ReadMessage parses an OpenPGP message that may be signed and/or encrypted.
83 // The given KeyRing should contain both public keys (for signature
84 // verification) and, possibly encrypted, private keys for decrypting.
85 // If config is nil, sensible defaults will be used.
86 func ReadMessage(r io.Reader, keyring KeyRing, prompt PromptFunction, config *packet.Config) (md *MessageDetails, err error) {
89 var symKeys []*packet.SymmetricKeyEncrypted
90 var pubKeys []keyEnvelopePair
91 var se *packet.SymmetricallyEncrypted
93 packets := packet.NewReader(r)
94 md = new(MessageDetails)
97 // The message, if encrypted, starts with a number of packets
98 // containing an encrypted decryption key. The decryption key is either
99 // encrypted to a public key, or with a passphrase. This loop
100 // collects these packets.
103 p, err = packets.Next()
107 switch p := p.(type) {
108 case *packet.SymmetricKeyEncrypted:
109 // This packet contains the decryption key encrypted with a passphrase.
110 md.IsSymmetricallyEncrypted = true
111 symKeys = append(symKeys, p)
112 case *packet.EncryptedKey:
113 // This packet contains the decryption key encrypted to a public key.
114 md.EncryptedToKeyIds = append(md.EncryptedToKeyIds, p.KeyId)
116 case packet.PubKeyAlgoRSA, packet.PubKeyAlgoRSAEncryptOnly, packet.PubKeyAlgoElGamal:
123 keys = keyring.DecryptionKeys()
125 keys = keyring.KeysById(p.KeyId)
127 for _, k := range keys {
128 pubKeys = append(pubKeys, keyEnvelopePair{k, p})
130 case *packet.SymmetricallyEncrypted:
133 case *packet.Compressed, *packet.LiteralData, *packet.OnePassSignature:
134 // This message isn't encrypted.
135 if len(symKeys) != 0 || len(pubKeys) != 0 {
136 return nil, errors.StructuralError("key material not followed by encrypted message")
139 return readSignedMessage(packets, nil, keyring)
144 var decrypted io.ReadCloser
146 // Now that we have the list of encrypted keys we need to decrypt at
147 // least one of them or, if we cannot, we need to call the prompt
148 // function so that it can decrypt a key or give us a passphrase.
151 // See if any of the keys already have a private key available
152 candidates = candidates[:0]
153 candidateFingerprints := make(map[string]bool)
155 for _, pk := range pubKeys {
156 if pk.key.PrivateKey == nil {
159 if !pk.key.PrivateKey.Encrypted {
160 if len(pk.encryptedKey.Key) == 0 {
161 pk.encryptedKey.Decrypt(pk.key.PrivateKey, config)
163 if len(pk.encryptedKey.Key) == 0 {
166 decrypted, err = se.Decrypt(pk.encryptedKey.CipherFunc, pk.encryptedKey.Key)
167 if err != nil && err != errors.ErrKeyIncorrect {
170 if decrypted != nil {
171 md.DecryptedWith = pk.key
175 fpr := string(pk.key.PublicKey.Fingerprint[:])
176 if v := candidateFingerprints[fpr]; v {
179 candidates = append(candidates, pk.key)
180 candidateFingerprints[fpr] = true
184 if len(candidates) == 0 && len(symKeys) == 0 {
185 return nil, errors.ErrKeyIncorrect
189 return nil, errors.ErrKeyIncorrect
192 passphrase, err := prompt(candidates, len(symKeys) != 0)
197 // Try the symmetric passphrase first
198 if len(symKeys) != 0 && passphrase != nil {
199 for _, s := range symKeys {
200 key, cipherFunc, err := s.Decrypt(passphrase)
202 decrypted, err = se.Decrypt(cipherFunc, key)
203 if err != nil && err != errors.ErrKeyIncorrect {
206 if decrypted != nil {
215 md.decrypted = decrypted
216 if err := packets.Push(decrypted); err != nil {
219 return readSignedMessage(packets, md, keyring)
222 // readSignedMessage reads a possibly signed message if mdin is non-zero then
223 // that structure is updated and returned. Otherwise a fresh MessageDetails is
225 func readSignedMessage(packets *packet.Reader, mdin *MessageDetails, keyring KeyRing) (md *MessageDetails, err error) {
227 mdin = new(MessageDetails)
233 var wrappedHash hash.Hash
236 p, err = packets.Next()
240 switch p := p.(type) {
241 case *packet.Compressed:
242 if err := packets.Push(p.Body); err != nil {
245 case *packet.OnePassSignature:
247 return nil, errors.UnsupportedError("nested signatures")
250 h, wrappedHash, err = hashForSignature(p.Hash, p.SigType)
257 md.SignedByKeyId = p.KeyId
258 keys := keyring.KeysByIdUsage(p.KeyId, packet.KeyFlagSign)
260 md.SignedBy = &keys[0]
262 case *packet.LiteralData:
264 break FindLiteralData
268 if md.SignedBy != nil {
269 md.UnverifiedBody = &signatureCheckReader{packets, h, wrappedHash, md}
270 } else if md.decrypted != nil {
271 md.UnverifiedBody = checkReader{md}
273 md.UnverifiedBody = md.LiteralData.Body
279 // hashForSignature returns a pair of hashes that can be used to verify a
280 // signature. The signature may specify that the contents of the signed message
281 // should be preprocessed (i.e. to normalize line endings). Thus this function
282 // returns two hashes. The second should be used to hash the message itself and
283 // performs any needed preprocessing.
284 func hashForSignature(hashId crypto.Hash, sigType packet.SignatureType) (hash.Hash, hash.Hash, error) {
285 if !hashId.Available() {
286 return nil, nil, errors.UnsupportedError("hash not available: " + strconv.Itoa(int(hashId)))
291 case packet.SigTypeBinary:
293 case packet.SigTypeText:
294 return h, NewCanonicalTextHash(h), nil
297 return nil, nil, errors.UnsupportedError("unsupported signature type: " + strconv.Itoa(int(sigType)))
300 // checkReader wraps an io.Reader from a LiteralData packet. When it sees EOF
301 // it closes the ReadCloser from any SymmetricallyEncrypted packet to trigger
303 type checkReader struct {
307 func (cr checkReader) Read(buf []byte) (n int, err error) {
308 n, err = cr.md.LiteralData.Body.Read(buf)
310 mdcErr := cr.md.decrypted.Close()
318 // signatureCheckReader wraps an io.Reader from a LiteralData packet and hashes
319 // the data as it is read. When it sees an EOF from the underlying io.Reader
320 // it parses and checks a trailing Signature packet and triggers any MDC checks.
321 type signatureCheckReader struct {
322 packets *packet.Reader
323 h, wrappedHash hash.Hash
327 func (scr *signatureCheckReader) Read(buf []byte) (n int, err error) {
328 n, err = scr.md.LiteralData.Body.Read(buf)
329 scr.wrappedHash.Write(buf[:n])
332 p, scr.md.SignatureError = scr.packets.Next()
333 if scr.md.SignatureError != nil {
338 if scr.md.Signature, ok = p.(*packet.Signature); ok {
339 scr.md.SignatureError = scr.md.SignedBy.PublicKey.VerifySignature(scr.h, scr.md.Signature)
340 } else if scr.md.SignatureV3, ok = p.(*packet.SignatureV3); ok {
341 scr.md.SignatureError = scr.md.SignedBy.PublicKey.VerifySignatureV3(scr.h, scr.md.SignatureV3)
343 scr.md.SignatureError = errors.StructuralError("LiteralData not followed by Signature")
347 // The SymmetricallyEncrypted packet, if any, might have an
348 // unsigned hash of its own. In order to check this we need to
349 // close that Reader.
350 if scr.md.decrypted != nil {
351 mdcErr := scr.md.decrypted.Close()
360 // CheckDetachedSignature takes a signed file and a detached signature and
361 // returns the signer if the signature is valid. If the signer isn't known,
362 // ErrUnknownIssuer is returned.
363 func CheckDetachedSignature(keyring KeyRing, signed, signature io.Reader) (signer *Entity, err error) {
364 var issuerKeyId uint64
365 var hashFunc crypto.Hash
366 var sigType packet.SignatureType
370 packets := packet.NewReader(signature)
372 p, err = packets.Next()
374 return nil, errors.ErrUnknownIssuer
380 switch sig := p.(type) {
381 case *packet.Signature:
382 if sig.IssuerKeyId == nil {
383 return nil, errors.StructuralError("signature doesn't have an issuer")
385 issuerKeyId = *sig.IssuerKeyId
387 sigType = sig.SigType
388 case *packet.SignatureV3:
389 issuerKeyId = sig.IssuerKeyId
391 sigType = sig.SigType
393 return nil, errors.StructuralError("non signature packet found")
396 keys = keyring.KeysByIdUsage(issuerKeyId, packet.KeyFlagSign)
406 h, wrappedHash, err := hashForSignature(hashFunc, sigType)
411 if _, err := io.Copy(wrappedHash, signed); err != nil && err != io.EOF {
415 for _, key := range keys {
416 switch sig := p.(type) {
417 case *packet.Signature:
418 err = key.PublicKey.VerifySignature(h, sig)
419 case *packet.SignatureV3:
420 err = key.PublicKey.VerifySignatureV3(h, sig)
426 return key.Entity, nil
433 // CheckArmoredDetachedSignature performs the same actions as
434 // CheckDetachedSignature but expects the signature to be armored.
435 func CheckArmoredDetachedSignature(keyring KeyRing, signed, signature io.Reader) (signer *Entity, err error) {
436 body, err := readArmored(signature, SignatureType)
441 return CheckDetachedSignature(keyring, signed, body)