← Back to branch summary

~andersk/ubuntu/oneiric/openssl/spurious-reboot

« back to all changes in this revision

Viewing changes to doc/crypto/CMS_verify.pod

  • Committer: Bazaar Package Importer
  • Author(s): Colin Watson
  • Date: 2011-05-01 23:51:53 UTC
  • mfrom: (11.1.20 sid)
  • Revision ID: james.westby@ubuntu.com-20110501235153-bjcxitndquaezb68
Tags: 1.0.0d-2ubuntu1
https://launchpad.net/bugs/675566
* Resynchronise with Debian (LP: #675566).  Remaining changes:
  - debian/libssl1.0.0.postinst:
    + Display a system restart required notification bubble on libssl1.0.0
      upgrade.
    + Use a different priority for libssl1.0.0/restart-services depending
      on whether a desktop, or server dist-upgrade is being performed.
  - debian/{libssl1.0.0-udeb.dirs, control, rules}: Create
    libssl1.0.0-udeb, for the benefit of wget-udeb (no wget-udeb package
    in Debian).
  - debian/{libcrypto1.0.0-udeb.dirs, libssl1.0.0.dirs, libssl1.0.0.files,
    rules}: Move runtime libraries to /lib, for the benefit of
    wpasupplicant.
  - debian/patches/aesni.patch: Backport Intel AES-NI support, now from
    http://rt.openssl.org/Ticket/Display.html?id=2065 rather than the
    0.9.8 variant.
  - debian/patches/Bsymbolic-functions.patch: Link using
    -Bsymbolic-functions.
  - debian/patches/perlpath-quilt.patch: Don't change perl #! paths under
    .pc.
  - debian/rules:
    + Don't run 'make test' when cross-building.
    + Use host compiler when cross-building.  Patch from Neil Williams.
    + Don't build for processors no longer supported: i486, i586 (on
      i386), v8 (on sparc).
    + Fix Makefile to properly clean up libs/ dirs in clean target.
    + Replace duplicate files in the doc directory with symlinks.
* Update architectures affected by Bsymbolic-functions.patch.
* Drop debian/patches/no-sslv2.patch; Debian now adds the 'no-ssl2'
  configure option, which compiles out SSLv2 support entirely, so this is
  no longer needed.
* Drop openssl-doc in favour of the libssl-doc package introduced by
  Debian.  Add Conflicts/Replaces until the next LTS release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/crypto/CMS_verify.pod
 
1
=pod
 
2
 
 
3
=head1 NAME
 
4
 
 
5
 CMS_verify - verify a CMS SignedData structure
 
6
 
 
7
=head1 SYNOPSIS
 
8
 
 
9
 #include <openssl/cms.h>
 
10
 
 
11
 int CMS_verify(CMS_ContentInfo *cms, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, unsigned int flags);
 
12
 
 
13
 STACK_OF(X509) *CMS_get0_signers(CMS_ContentInfo *cms);
 
14
 
 
15
=head1 DESCRIPTION
 
16
 
 
17
CMS_verify() verifies a CMS SignedData structure. B<cms> is the CMS_ContentInfo
 
18
structure to verify. B<certs> is a set of certificates in which to search for
 
19
the signing certificate(s). B<store> is a trusted certificate store used for
 
20
chain verification. B<indata> is the detached content if the content is not
 
21
present in B<cms>. The content is written to B<out> if it is not NULL.
 
22
 
 
23
B<flags> is an optional set of flags, which can be used to modify the verify
 
24
operation.
 
25
 
 
26
CMS_get0_signers() retrieves the signing certificate(s) from B<cms>, it must
 
27
be called after a successful CMS_verify() operation.
 
28
 
 
29
=head1 VERIFY PROCESS
 
30
 
 
31
Normally the verify process proceeds as follows.
 
32
 
 
33
Initially some sanity checks are performed on B<cms>. The type of B<cms> must
 
34
be SignedData. There must be at least one signature on the data and if
 
35
the content is detached B<indata> cannot be B<NULL>.
 
36
 
 
37
An attempt is made to locate all the signing certificate(s), first looking in
 
38
the B<certs> parameter (if it is not NULL) and then looking in any
 
39
certificates contained in the B<cms> structure itself. If any signing
 
40
certificate cannot be located the operation fails.
 
41
 
 
42
Each signing certificate is chain verified using the B<smimesign> purpose and
 
43
the supplied trusted certificate store. Any internal certificates in the message
 
44
are used as untrusted CAs. If CRL checking is enabled in B<store> any internal
 
45
CRLs are used in addition to attempting to look them up in B<store>. If any
 
46
chain verify fails an error code is returned.
 
47
 
 
48
Finally the signed content is read (and written to B<out> is it is not NULL)
 
49
and the signature's checked.
 
50
 
 
51
If all signature's verify correctly then the function is successful.
 
52
 
 
53
Any of the following flags (ored together) can be passed in the B<flags>
 
54
parameter to change the default verify behaviour.
 
55
 
 
56
If B<CMS_NOINTERN> is set the certificates in the message itself are not
 
57
searched when locating the signing certificate(s). This means that all the
 
58
signing certificates must be in the B<certs> parameter.
 
59
 
 
60
If B<CMS_NOCRL> is set and CRL checking is enabled in B<store> then any
 
61
CRLs in the message itself are ignored.
 
62
 
 
63
If the B<CMS_TEXT> flag is set MIME headers for type B<text/plain> are deleted
 
64
from the content. If the content is not of type B<text/plain> then an error is
 
65
returned.
 
66
 
 
67
If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not
 
68
verified.
 
69
 
 
70
If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not 
 
71
verified.
 
72
 
 
73
If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked.
 
74
 
 
75
=head1 NOTES
 
76
 
 
77
One application of B<CMS_NOINTERN> is to only accept messages signed by
 
78
a small number of certificates. The acceptable certificates would be passed
 
79
in the B<certs> parameter. In this case if the signer is not one of the
 
80
certificates supplied in B<certs> then the verify will fail because the
 
81
signer cannot be found.
 
82
 
 
83
In some cases the standard techniques for looking up and validating
 
84
certificates are not appropriate: for example an application may wish to 
 
85
lookup certificates in a database or perform customised verification. This
 
86
can be achieved by setting and verifying the signers certificates manually 
 
87
using the signed data utility functions.
 
88
 
 
89
Care should be taken when modifying the default verify behaviour, for example
 
90
setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification 
 
91
and any modified content will be considered valid. This combination is however
 
92
useful if one merely wishes to write the content to B<out> and its validity
 
93
is not considered important.
 
94
 
 
95
Chain verification should arguably be performed using the signing time rather
 
96
than the current time. However since the signing time is supplied by the
 
97
signer it cannot be trusted without additional evidence (such as a trusted
 
98
timestamp).
 
99
 
 
100
=head1 RETURN VALUES
 
101
 
 
102
CMS_verify() returns 1 for a successful verification and zero if an error
 
103
occurred.
 
104
 
 
105
CMS_get0_signers() returns all signers or NULL if an error occurred.
 
106
 
 
107
The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
 
108
 
 
109
=head1 BUGS
 
110
 
 
111
The trusted certificate store is not searched for the signing certificate,
 
112
this is primarily due to the inadequacies of the current B<X509_STORE>
 
113
functionality.
 
114
 
 
115
The lack of single pass processing means that the signed content must all
 
116
be held in memory if it is not detached.
 
117
 
 
118
=head1 SEE ALSO
 
119
 
 
120
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>
 
121
 
 
122
=head1 HISTORY
 
123
 
 
124
CMS_verify() was added to OpenSSL 0.9.8
 
125
 
 
126
=cut