Attachment #126591 for bug #170341

View | Details | Raw Unified | Return to bug 170341
Collapse All | Expand All




that the structure can not be deallocated until the reference is released.
.PP
However, a structural reference provides no guarantee that the \s-1ENGINE\s0 is
initialised and able to use any of its cryptographic
implementations. Indeed it's quite possible that most ENGINEs will not
initialise at all in typical environments, as ENGINEs are typically used to
support specialised hardware. To use an \s-1ENGINE\s0's functionality, you need a

implicitly contains a structural reference as well \- however to avoid
difficult-to-find programming bugs, it is recommended to treat the two
kinds of reference independently. If you have a functional reference to an
\&\s-1ENGINE\s0, you have a guarantee that the \s-1ENGINE\s0 has been initialised and is ready to
perform cryptographic operations, and will remain initialised
until after you have released your reference.
.PP
\&\fIStructural references\fR

.PP
Here we'll assume we want to load and register all \s-1ENGINE\s0 implementations
bundled with OpenSSL, such that for any cryptographic algorithm required by
OpenSSL \- if there is an \s-1ENGINE\s0 that implements it and can be initialised,
it should be used. The following code illustrates how this can work;
.PP
.Vb 4

Return to bug 170341

Lines 321-327 Link Here

(-)/tmp/engine.3 (-4 / +4 lines)
321	that the structure can not be deallocated until the reference is released.	321	that the structure can not be deallocated until the reference is released.
322	.PP	322	.PP
323	However, a structural reference provides no guarantee that the \s-1ENGINE\s0 is	323	However, a structural reference provides no guarantee that the \s-1ENGINE\s0 is
324	initiliased and able to use any of its cryptographic	324	initialised and able to use any of its cryptographic
325	implementations. Indeed it's quite possible that most ENGINEs will not	325	implementations. Indeed it's quite possible that most ENGINEs will not
326	initialise at all in typical environments, as ENGINEs are typically used to	326	initialise at all in typical environments, as ENGINEs are typically used to
327	support specialised hardware. To use an \s-1ENGINE\s0's functionality, you need a	327	support specialised hardware. To use an \s-1ENGINE\s0's functionality, you need a
Lines 330-337 Link Here
330	implicitly contains a structural reference as well \- however to avoid	330	implicitly contains a structural reference as well \- however to avoid
331	difficult-to-find programming bugs, it is recommended to treat the two	331	difficult-to-find programming bugs, it is recommended to treat the two
332	kinds of reference independently. If you have a functional reference to an	332	kinds of reference independently. If you have a functional reference to an
333	\&\s-1ENGINE\s0, you have a guarantee that the \s-1ENGINE\s0 has been initialised ready to	333	\&\s-1ENGINE\s0, you have a guarantee that the \s-1ENGINE\s0 has been initialised and is ready to
334	perform cryptographic operations and will remain uninitialised	334	perform cryptographic operations, and will remain initialised
335	until after you have released your reference.	335	until after you have released your reference.
336	.PP	336	.PP
337	\&\fIStructural references\fR	337	\&\fIStructural references\fR
Lines 534-540 Link Here
534	.PP	534	.PP
535	Here we'll assume we want to load and register all \s-1ENGINE\s0 implementations	535	Here we'll assume we want to load and register all \s-1ENGINE\s0 implementations
536	bundled with OpenSSL, such that for any cryptographic algorithm required by	536	bundled with OpenSSL, such that for any cryptographic algorithm required by
537	OpenSSL \- if there is an \s-1ENGINE\s0 that implements it and can be initialise,	537	OpenSSL \- if there is an \s-1ENGINE\s0 that implements it and can be initialised,
538	it should be used. The following code illustrates how this can work;	538	it should be used. The following code illustrates how this can work;
539	.PP	539	.PP
540	.Vb 4	540	.Vb 4