aboutsummaryrefslogtreecommitdiff
path: root/openssl/trunk/doc/crypto/DH_generate_parameters.pod
blob: 9081e9ea7cf9380eba53b132ac53fa586c1530ba (plain) (blame) 
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

=pod

=head1 NAME

DH_generate_parameters, DH_check - generate and check Diffie-Hellman parameters

=head1 SYNOPSIS

 #include <openssl/dh.h>

 DH *DH_generate_parameters(int prime_len, int generator,
     void (*callback)(int, int, void *), void *cb_arg);

 int DH_check(DH *dh, int *codes);

=head1 DESCRIPTION

DH_generate_parameters() generates Diffie-Hellman parameters that can
be shared among a group of users, and returns them in a newly
allocated B<DH> structure. The pseudo-random number generator must be
seeded prior to calling DH_generate_parameters().

B<prime_len> is the length in bits of the safe prime to be generated.
B<generator> is a small number E<gt> 1, typically 2 or 5. 

A callback function may be used to provide feedback about the progress
of the key generation. If B<callback> is not B<NULL>, it will be
called as described in L<BN_generate_prime(3)|BN_generate_prime(3)> while a random prime
number is generated, and when a prime has been found, B<callback(3,
0, cb_arg)> is called.

DH_check() validates Diffie-Hellman parameters. It checks that B<p> is
a safe prime, and that B<g> is a suitable generator. In the case of an
error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or
DH_NOT_SUITABLE_GENERATOR are set in B<*codes>.
DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be
checked, i.e. it does not equal 2 or 5.

=head1 RETURN VALUES

DH_generate_parameters() returns a pointer to the DH structure, or
NULL if the parameter generation fails. The error codes can be
obtained by L<ERR_get_error(3)|ERR_get_error(3)>.

DH_check() returns 1 if the check could be performed, 0 otherwise.

=head1 NOTES

DH_generate_parameters() may run for several hours before finding a
suitable prime.

The parameters generated by DH_generate_parameters() are not to be
used in signature schemes.

=head1 BUGS

If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not
a usable generator.

=head1 SEE ALSO

L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
L<DH_free(3)|DH_free(3)>

=head1 HISTORY

DH_check() is available in all versions of SSLeay and OpenSSL.
The B<cb_arg> argument to DH_generate_parameters() was added in SSLeay 0.9.0.

In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used
instead of DH_CHECK_P_NOT_SAFE_PRIME.

=cut
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-17 19:33:50 +0000
ository operator might want to do some checks to assure ;;; itself that what it's about to allow the RE to publish is not ;;; dangerous toxic waste. ;;; ;;; Protocol goals as of last discussion in Prague: ;;; ;;; 1) "Negotiate" publication point URI. This is a bit complex, in ;;; that part of the URI may come from the publication ;;; repository, parts from the RE's parent, and parts from the RE ;;; itself. Some discussion over whether we need online protocol ;;; to negotiate the publication repository's part, no firm ;;; consensus, plurality of the room was leaning towards "no", ;;; ie, the repository's portion of the URI is negotiated via the ;;; business channel and configured into the RE by the IRBE. ;;; ;;; 2) In case where parent and child are in fact sharing repository, ;;; repository operator is responsible for keeping these two users' ;;; naming schemes from coliding with each other. More precisely, ;;; the repository operator is responsible for checking to see that ;;; the parent agreed to let the child publish in a particular ;;; subtree. Fortunately, this is an easy check: the parent has to ;;; issue a cert to the child anyway, and that cert will contain a ;;; signature by the parent over the child's SIA URI, so the ;;; repository just has to check that. For purposes of this check, ;;; the parent's cert (which the repository has, by definition, ;;; since this is the nested hosting case) can serve as a trust ;;; anchor for checking the child's SIA. ;;; ;;; 3) To the extent that the repository operator wants to guard ;;; against toxic waste, it might want to check further up the ;;; resource cert chain, regardless of where the ancestors lodge. ;;; For this to work properly, the repository operator needs to ;;; agree (as part of a business negotiation, probably) with the RE ;;; on which trust anchors the repository should use to perform ;;; these checks; ultimately, this decision (as with any TA choice) ;;; is up to the relying party (in this case the repository ;;; operator), but if there's going to be a problem due to ;;; mismatched TA choices, we would really like to throw the ;;; exception during the business negotiation rather than via a ;;; runtime refusal to publish. ;;; ;;; Note that, in this publication model, any agreement that the ;;; repository makes to publish the RE's output is conditional upon ;;; the object to be published passing all of its checks. ;;; How do we construct publication URIs (which also go into some of ;;; the X.509 extensions in the resource certs)? We create CAs on the ;;; fly in response to what we learn from our parent, so it's hard to ;;; preconfigure this. This mechanism is still under discussion, the ;;; following is my version of it. ;;; ;;; At least for purposes of discussion, break the publication ;;; directory URI into three pieces: head/middle/tail/. ;;; ;;; head is a URI within the repository with which this RE publishes; ;;; this is either per-parent or per-class-per-parent, but the latter ;;; is hard to preconfigure because we only find out about classes on ;;; the fly. So, for the moment, assume it's per-parent. We're only ;;; allowed to publish stuff here because we have a business ;;; relationship with the repository, so at some level this has to be ;;; preconfigured anyway, along with the repository TA and contact ;;; URI. In theory we could negotiate a location within the ;;; repository on the fly, but let's try to keep this simple. ;;; ;;; Middle may come from this RE's parent. If the parent happens to ;;; be using the same repository as this RE is, the parent can tell us ;;; (currently via an attribute I added to the up-down protocol for ;;; this purpose) a URI under which it gives us permission to lodge. ;;; If the head URI (configured above) is not a prefix of the URI we ;;; get from the parent, we don't have permission to publish under the ;;; parent and middle is null. In essence, middle is the parent's ;;; advice on where to put this particular CA's outputs in order to ;;; get the nice hierarchical properties we want. ;;; ;;; Tail is something this RE makes up. It's per-CA, and all that ;;; really matters is that it's stable. It could be gensymed, or ;;; could be our internal name for the CA, whatever. ;;; ;;; Publication itself always requires a business signature ;;; (demonstrating that we have the right to publish in this ;;; repository at all) and may also require enough of the RPKI cert ;;; chain to demonstrate that this RE's parent has given this RE ;;; permission to publish under a particular URI. Thing that needs to ;;; be proven is that publication client A is not stepping on ;;; publication client B even when B is A's parent. ;;; Signed manifests must be supplied by the RE, as they must be ;;; signed by an EE cert issued by the CA that issues (or signs, in ;;; the case of non-cert objects) everything else in the SIA ;;; collection. This EE cert should probably just use the RFC 3779 ;;; inherit bits as an easy way of inheriting all the resources of the ;;; CA cert. So the publication operation supplies exactly one new ;;; manifest and zero or more other objects; everything in the ;;; publication PDU is published as an atomic operation, ie, if any of ;;; it can't be published, none of it is published. (publish-thing :publication-uri uri-of-thing-we-are-publishing :credential-certs (cert ....) :manifest manifest (:thing crl1 :thing-type :crl) (:thing cert1 :thing-type :cert) (:thing cert2 :thing-type :cert) ... ...) => () ;;; thing is an object (certificate, CRL, ROA) signed by the private ;;; key associated with a resource certificate held by the entity ;;; sending the (publish-thing) request. :thing-type may not be ;;; strictly necessary. ;;; ;;; credential-certs is a set of whatever resource certificates are ;;; needed to demonstrate to the repository engine that the entity ;;; requesting publication is making a legitimate publication request. ;;; Goal (2), above, requires the requestor to supply the resource ;;; certificate chain up to the parent to demonstrate that the parent ;;; has approved (signed) the requested SIA. Goal (3), above, would ;;; require supplying the cert chain back to some resource trust ;;; anchor established as part of the business relationship between ;;; requestor and repository operator.
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-17 19:33:50 +0000