pub struct SslStream<S> { /* private fields */ }
Expand description
A TLS session over a stream.
Implementations§
source§impl<S: Read + Write> SslStream<S>
impl<S: Read + Write> SslStream<S>
sourcepub fn new(ssl: Ssl, stream: S) -> Result<Self, ErrorStack>
pub fn new(ssl: Ssl, stream: S) -> Result<Self, ErrorStack>
Creates a new SslStream
.
This function performs no IO; the stream will not have performed any part of the handshake
with the peer. If the Ssl
was configured with SslRef::set_connect_state
or
SslRef::set_accept_state
, the handshake can be performed automatically during the first
call to read or write. Otherwise the connect
and accept
methods can be used to
explicitly perform the handshake.
This corresponds to SSL_set_bio
.
Examples found in repository?
3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581
pub unsafe fn from_raw_parts(ssl: *mut ffi::SSL, stream: S) -> Self {
let ssl = Ssl::from_ptr(ssl);
Self::new(ssl, stream).unwrap()
}
/// Read application data transmitted by a client before handshake completion.
///
/// Useful for reducing latency, but vulnerable to replay attacks. Call
/// [`SslRef::set_accept_state`] first.
///
/// Returns `Ok(0)` if all early data has been read.
///
/// Requires OpenSSL 1.1.1 or LibreSSL 3.4.0 or newer.
#[corresponds(SSL_read_early_data)]
#[cfg(any(ossl111, libressl340))]
pub fn read_early_data(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
let mut read = 0;
let ret = unsafe {
ffi::SSL_read_early_data(
self.ssl.as_ptr(),
buf.as_ptr() as *mut c_void,
buf.len(),
&mut read,
)
};
match ret {
ffi::SSL_READ_EARLY_DATA_ERROR => Err(self.make_error(ret)),
ffi::SSL_READ_EARLY_DATA_SUCCESS => Ok(read),
ffi::SSL_READ_EARLY_DATA_FINISH => Ok(0),
_ => unreachable!(),
}
}
/// Send data to the server without blocking on handshake completion.
///
/// Useful for reducing latency, but vulnerable to replay attacks. Call
/// [`SslRef::set_connect_state`] first.
///
/// Requires OpenSSL 1.1.1 or LibreSSL 3.4.0 or newer.
#[corresponds(SSL_write_early_data)]
#[cfg(any(ossl111, libressl340))]
pub fn write_early_data(&mut self, buf: &[u8]) -> Result<usize, Error> {
let mut written = 0;
let ret = unsafe {
ffi::SSL_write_early_data(
self.ssl.as_ptr(),
buf.as_ptr() as *const c_void,
buf.len(),
&mut written,
)
};
if ret > 0 {
Ok(written)
} else {
Err(self.make_error(ret))
}
}
/// Initiates a client-side TLS handshake.
///
/// # Warning
///
/// OpenSSL's default configuration is insecure. It is highly recommended to use
/// `SslConnector` rather than `Ssl` directly, as it manages that configuration.
#[corresponds(SSL_connect)]
pub fn connect(&mut self) -> Result<(), Error> {
let ret = unsafe { ffi::SSL_connect(self.ssl.as_ptr()) };
if ret > 0 {
Ok(())
} else {
Err(self.make_error(ret))
}
}
/// Initiates a server-side TLS handshake.
///
/// # Warning
///
/// OpenSSL's default configuration is insecure. It is highly recommended to use
/// `SslAcceptor` rather than `Ssl` directly, as it manages that configuration.
#[corresponds(SSL_accept)]
pub fn accept(&mut self) -> Result<(), Error> {
let ret = unsafe { ffi::SSL_accept(self.ssl.as_ptr()) };
if ret > 0 {
Ok(())
} else {
Err(self.make_error(ret))
}
}
/// Initiates the handshake.
///
/// This will fail if `set_accept_state` or `set_connect_state` was not called first.
#[corresponds(SSL_do_handshake)]
pub fn do_handshake(&mut self) -> Result<(), Error> {
let ret = unsafe { ffi::SSL_do_handshake(self.ssl.as_ptr()) };
if ret > 0 {
Ok(())
} else {
Err(self.make_error(ret))
}
}
/// Perform a stateless server-side handshake.
///
/// Requires that cookie generation and verification callbacks were
/// set on the SSL context.
///
/// Returns `Ok(true)` if a complete ClientHello containing a valid cookie
/// was read, in which case the handshake should be continued via
/// `accept`. If a HelloRetryRequest containing a fresh cookie was
/// transmitted, `Ok(false)` is returned instead. If the handshake cannot
/// proceed at all, `Err` is returned.
#[corresponds(SSL_stateless)]
#[cfg(ossl111)]
pub fn stateless(&mut self) -> Result<bool, ErrorStack> {
match unsafe { ffi::SSL_stateless(self.ssl.as_ptr()) } {
1 => Ok(true),
0 => Ok(false),
-1 => Err(ErrorStack::get()),
_ => unreachable!(),
}
}
/// Like `read`, but returns an `ssl::Error` rather than an `io::Error`.
///
/// It is particularly useful with a non-blocking socket, where the error value will identify if
/// OpenSSL is waiting on read or write readiness.
#[corresponds(SSL_read)]
pub fn ssl_read(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
// The interpretation of the return code here is a little odd with a
// zero-length write. OpenSSL will likely correctly report back to us
// that it read zero bytes, but zero is also the sentinel for "error".
// To avoid that confusion short-circuit that logic and return quickly
// if `buf` has a length of zero.
if buf.is_empty() {
return Ok(0);
}
let ret = self.ssl.read(buf);
if ret > 0 {
Ok(ret as usize)
} else {
Err(self.make_error(ret))
}
}
/// Like `write`, but returns an `ssl::Error` rather than an `io::Error`.
///
/// It is particularly useful with a non-blocking socket, where the error value will identify if
/// OpenSSL is waiting on read or write readiness.
#[corresponds(SSL_write)]
pub fn ssl_write(&mut self, buf: &[u8]) -> Result<usize, Error> {
// See above for why we short-circuit on zero-length buffers
if buf.is_empty() {
return Ok(0);
}
let ret = self.ssl.write(buf);
if ret > 0 {
Ok(ret as usize)
} else {
Err(self.make_error(ret))
}
}
/// Reads data from the stream, without removing it from the queue.
#[corresponds(SSL_peek)]
pub fn ssl_peek(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
// See above for why we short-circuit on zero-length buffers
if buf.is_empty() {
return Ok(0);
}
let ret = self.ssl.peek(buf);
if ret > 0 {
Ok(ret as usize)
} else {
Err(self.make_error(ret))
}
}
/// Shuts down the session.
///
/// The shutdown process consists of two steps. The first step sends a close notify message to
/// the peer, after which `ShutdownResult::Sent` is returned. The second step awaits the receipt
/// of a close notify message from the peer, after which `ShutdownResult::Received` is returned.
///
/// While the connection may be closed after the first step, it is recommended to fully shut the
/// session down. In particular, it must be fully shut down if the connection is to be used for
/// further communication in the future.
#[corresponds(SSL_shutdown)]
pub fn shutdown(&mut self) -> Result<ShutdownResult, Error> {
match unsafe { ffi::SSL_shutdown(self.ssl.as_ptr()) } {
0 => Ok(ShutdownResult::Sent),
1 => Ok(ShutdownResult::Received),
n => Err(self.make_error(n)),
}
}
/// Returns the session's shutdown state.
#[corresponds(SSL_get_shutdown)]
pub fn get_shutdown(&mut self) -> ShutdownState {
unsafe {
let bits = ffi::SSL_get_shutdown(self.ssl.as_ptr());
ShutdownState { bits }
}
}
/// Sets the session's shutdown state.
///
/// This can be used to tell OpenSSL that the session should be cached even if a full two-way
/// shutdown was not completed.
#[corresponds(SSL_set_shutdown)]
pub fn set_shutdown(&mut self, state: ShutdownState) {
unsafe { ffi::SSL_set_shutdown(self.ssl.as_ptr(), state.bits()) }
}
}
impl<S> SslStream<S> {
fn make_error(&mut self, ret: c_int) -> Error {
self.check_panic();
let code = self.ssl.get_error(ret);
let cause = match code {
ErrorCode::SSL => Some(InnerError::Ssl(ErrorStack::get())),
ErrorCode::SYSCALL => {
let errs = ErrorStack::get();
if errs.errors().is_empty() {
self.get_bio_error().map(InnerError::Io)
} else {
Some(InnerError::Ssl(errs))
}
}
ErrorCode::ZERO_RETURN => None,
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
self.get_bio_error().map(InnerError::Io)
}
_ => None,
};
Error { code, cause }
}
fn check_panic(&mut self) {
if let Some(err) = unsafe { bio::take_panic::<S>(self.ssl.get_raw_rbio()) } {
resume_unwind(err)
}
}
fn get_bio_error(&mut self) -> Option<io::Error> {
unsafe { bio::take_error::<S>(self.ssl.get_raw_rbio()) }
}
/// Returns a shared reference to the underlying stream.
pub fn get_ref(&self) -> &S {
unsafe {
let bio = self.ssl.get_raw_rbio();
bio::get_ref(bio)
}
}
/// Returns a mutable reference to the underlying stream.
///
/// # Warning
///
/// It is inadvisable to read from or write to the underlying stream as it
/// will most likely corrupt the SSL session.
pub fn get_mut(&mut self) -> &mut S {
unsafe {
let bio = self.ssl.get_raw_rbio();
bio::get_mut(bio)
}
}
/// Returns a shared reference to the `Ssl` object associated with this stream.
pub fn ssl(&self) -> &SslRef {
&self.ssl
}
}
impl<S: Read + Write> Read for SslStream<S> {
fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
loop {
match self.ssl_read(buf) {
Ok(n) => return Ok(n),
Err(ref e) if e.code() == ErrorCode::ZERO_RETURN => return Ok(0),
Err(ref e) if e.code() == ErrorCode::SYSCALL && e.io_error().is_none() => {
return Ok(0);
}
Err(ref e) if e.code() == ErrorCode::WANT_READ && e.io_error().is_none() => {}
Err(e) => {
return Err(e
.into_io_error()
.unwrap_or_else(|e| io::Error::new(io::ErrorKind::Other, e)));
}
}
}
}
}
impl<S: Read + Write> Write for SslStream<S> {
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
loop {
match self.ssl_write(buf) {
Ok(n) => return Ok(n),
Err(ref e) if e.code() == ErrorCode::WANT_READ && e.io_error().is_none() => {}
Err(e) => {
return Err(e
.into_io_error()
.unwrap_or_else(|e| io::Error::new(io::ErrorKind::Other, e)));
}
}
}
}
fn flush(&mut self) -> io::Result<()> {
self.get_mut().flush()
}
}
/// A partially constructed `SslStream`, useful for unusual handshakes.
#[deprecated(
since = "0.10.32",
note = "use the methods directly on Ssl/SslStream instead"
)]
pub struct SslStreamBuilder<S> {
inner: SslStream<S>,
}
#[allow(deprecated)]
impl<S> SslStreamBuilder<S>
where
S: Read + Write,
{
/// Begin creating an `SslStream` atop `stream`
pub fn new(ssl: Ssl, stream: S) -> Self {
Self {
inner: SslStream::new(ssl, stream).unwrap(),
}
}
sourcepub unsafe fn from_raw_parts(ssl: *mut SSL, stream: S) -> Self
👎Deprecated since 0.10.32: use Ssl::from_ptr and SslStream::new instead
pub unsafe fn from_raw_parts(ssl: *mut SSL, stream: S) -> Self
Constructs an SslStream
from a pointer to the underlying OpenSSL SSL
struct.
This is useful if the handshake has already been completed elsewhere.
Safety
The caller must ensure the pointer is valid.
sourcepub fn read_early_data(&mut self, buf: &mut [u8]) -> Result<usize, Error>
pub fn read_early_data(&mut self, buf: &mut [u8]) -> Result<usize, Error>
Read application data transmitted by a client before handshake completion.
Useful for reducing latency, but vulnerable to replay attacks. Call
SslRef::set_accept_state
first.
Returns Ok(0)
if all early data has been read.
Requires OpenSSL 1.1.1 or LibreSSL 3.4.0 or newer.
This corresponds to SSL_read_early_data
.
sourcepub fn write_early_data(&mut self, buf: &[u8]) -> Result<usize, Error>
pub fn write_early_data(&mut self, buf: &[u8]) -> Result<usize, Error>
Send data to the server without blocking on handshake completion.
Useful for reducing latency, but vulnerable to replay attacks. Call
SslRef::set_connect_state
first.
Requires OpenSSL 1.1.1 or LibreSSL 3.4.0 or newer.
This corresponds to SSL_write_early_data
.
sourcepub fn connect(&mut self) -> Result<(), Error>
pub fn connect(&mut self) -> Result<(), Error>
Initiates a client-side TLS handshake.
Warning
OpenSSL’s default configuration is insecure. It is highly recommended to use
SslConnector
rather than Ssl
directly, as it manages that configuration.
This corresponds to SSL_connect
.
Examples found in repository?
3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642
pub fn connect(mut self) -> Result<SslStream<S>, HandshakeError<S>> {
match self.inner.connect() {
Ok(()) => Ok(self.inner),
Err(error) => match error.code() {
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
Err(HandshakeError::WouldBlock(MidHandshakeSslStream {
stream: self.inner,
error,
}))
}
_ => Err(HandshakeError::Failure(MidHandshakeSslStream {
stream: self.inner,
error,
})),
},
}
}
sourcepub fn accept(&mut self) -> Result<(), Error>
pub fn accept(&mut self) -> Result<(), Error>
Initiates a server-side TLS handshake.
Warning
OpenSSL’s default configuration is insecure. It is highly recommended to use
SslAcceptor
rather than Ssl
directly, as it manages that configuration.
This corresponds to SSL_accept
.
Examples found in repository?
3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661
pub fn accept(mut self) -> Result<SslStream<S>, HandshakeError<S>> {
match self.inner.accept() {
Ok(()) => Ok(self.inner),
Err(error) => match error.code() {
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
Err(HandshakeError::WouldBlock(MidHandshakeSslStream {
stream: self.inner,
error,
}))
}
_ => Err(HandshakeError::Failure(MidHandshakeSslStream {
stream: self.inner,
error,
})),
},
}
}
sourcepub fn do_handshake(&mut self) -> Result<(), Error>
pub fn do_handshake(&mut self) -> Result<(), Error>
Initiates the handshake.
This will fail if set_accept_state
or set_connect_state
was not called first.
This corresponds to SSL_do_handshake
.
Examples found in repository?
3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686
pub fn handshake(mut self) -> Result<SslStream<S>, HandshakeError<S>> {
match self.stream.do_handshake() {
Ok(()) => Ok(self.stream),
Err(error) => {
self.error = error;
match self.error.code() {
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
Err(HandshakeError::WouldBlock(self))
}
_ => Err(HandshakeError::Failure(self)),
}
}
}
}
}
/// A TLS session over a stream.
pub struct SslStream<S> {
ssl: ManuallyDrop<Ssl>,
method: ManuallyDrop<BioMethod>,
_p: PhantomData<S>,
}
impl<S> Drop for SslStream<S> {
fn drop(&mut self) {
// ssl holds a reference to method internally so it has to drop first
unsafe {
ManuallyDrop::drop(&mut self.ssl);
ManuallyDrop::drop(&mut self.method);
}
}
}
impl<S> fmt::Debug for SslStream<S>
where
S: fmt::Debug,
{
fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt.debug_struct("SslStream")
.field("stream", &self.get_ref())
.field("ssl", &self.ssl())
.finish()
}
}
impl<S: Read + Write> SslStream<S> {
/// Creates a new `SslStream`.
///
/// This function performs no IO; the stream will not have performed any part of the handshake
/// with the peer. If the `Ssl` was configured with [`SslRef::set_connect_state`] or
/// [`SslRef::set_accept_state`], the handshake can be performed automatically during the first
/// call to read or write. Otherwise the `connect` and `accept` methods can be used to
/// explicitly perform the handshake.
#[corresponds(SSL_set_bio)]
pub fn new(ssl: Ssl, stream: S) -> Result<Self, ErrorStack> {
let (bio, method) = bio::new(stream)?;
unsafe {
ffi::SSL_set_bio(ssl.as_ptr(), bio, bio);
}
Ok(SslStream {
ssl: ManuallyDrop::new(ssl),
method: ManuallyDrop::new(method),
_p: PhantomData,
})
}
/// Constructs an `SslStream` from a pointer to the underlying OpenSSL `SSL` struct.
///
/// This is useful if the handshake has already been completed elsewhere.
///
/// # Safety
///
/// The caller must ensure the pointer is valid.
#[deprecated(
since = "0.10.32",
note = "use Ssl::from_ptr and SslStream::new instead"
)]
pub unsafe fn from_raw_parts(ssl: *mut ffi::SSL, stream: S) -> Self {
let ssl = Ssl::from_ptr(ssl);
Self::new(ssl, stream).unwrap()
}
/// Read application data transmitted by a client before handshake completion.
///
/// Useful for reducing latency, but vulnerable to replay attacks. Call
/// [`SslRef::set_accept_state`] first.
///
/// Returns `Ok(0)` if all early data has been read.
///
/// Requires OpenSSL 1.1.1 or LibreSSL 3.4.0 or newer.
#[corresponds(SSL_read_early_data)]
#[cfg(any(ossl111, libressl340))]
pub fn read_early_data(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
let mut read = 0;
let ret = unsafe {
ffi::SSL_read_early_data(
self.ssl.as_ptr(),
buf.as_ptr() as *mut c_void,
buf.len(),
&mut read,
)
};
match ret {
ffi::SSL_READ_EARLY_DATA_ERROR => Err(self.make_error(ret)),
ffi::SSL_READ_EARLY_DATA_SUCCESS => Ok(read),
ffi::SSL_READ_EARLY_DATA_FINISH => Ok(0),
_ => unreachable!(),
}
}
/// Send data to the server without blocking on handshake completion.
///
/// Useful for reducing latency, but vulnerable to replay attacks. Call
/// [`SslRef::set_connect_state`] first.
///
/// Requires OpenSSL 1.1.1 or LibreSSL 3.4.0 or newer.
#[corresponds(SSL_write_early_data)]
#[cfg(any(ossl111, libressl340))]
pub fn write_early_data(&mut self, buf: &[u8]) -> Result<usize, Error> {
let mut written = 0;
let ret = unsafe {
ffi::SSL_write_early_data(
self.ssl.as_ptr(),
buf.as_ptr() as *const c_void,
buf.len(),
&mut written,
)
};
if ret > 0 {
Ok(written)
} else {
Err(self.make_error(ret))
}
}
/// Initiates a client-side TLS handshake.
///
/// # Warning
///
/// OpenSSL's default configuration is insecure. It is highly recommended to use
/// `SslConnector` rather than `Ssl` directly, as it manages that configuration.
#[corresponds(SSL_connect)]
pub fn connect(&mut self) -> Result<(), Error> {
let ret = unsafe { ffi::SSL_connect(self.ssl.as_ptr()) };
if ret > 0 {
Ok(())
} else {
Err(self.make_error(ret))
}
}
/// Initiates a server-side TLS handshake.
///
/// # Warning
///
/// OpenSSL's default configuration is insecure. It is highly recommended to use
/// `SslAcceptor` rather than `Ssl` directly, as it manages that configuration.
#[corresponds(SSL_accept)]
pub fn accept(&mut self) -> Result<(), Error> {
let ret = unsafe { ffi::SSL_accept(self.ssl.as_ptr()) };
if ret > 0 {
Ok(())
} else {
Err(self.make_error(ret))
}
}
/// Initiates the handshake.
///
/// This will fail if `set_accept_state` or `set_connect_state` was not called first.
#[corresponds(SSL_do_handshake)]
pub fn do_handshake(&mut self) -> Result<(), Error> {
let ret = unsafe { ffi::SSL_do_handshake(self.ssl.as_ptr()) };
if ret > 0 {
Ok(())
} else {
Err(self.make_error(ret))
}
}
/// Perform a stateless server-side handshake.
///
/// Requires that cookie generation and verification callbacks were
/// set on the SSL context.
///
/// Returns `Ok(true)` if a complete ClientHello containing a valid cookie
/// was read, in which case the handshake should be continued via
/// `accept`. If a HelloRetryRequest containing a fresh cookie was
/// transmitted, `Ok(false)` is returned instead. If the handshake cannot
/// proceed at all, `Err` is returned.
#[corresponds(SSL_stateless)]
#[cfg(ossl111)]
pub fn stateless(&mut self) -> Result<bool, ErrorStack> {
match unsafe { ffi::SSL_stateless(self.ssl.as_ptr()) } {
1 => Ok(true),
0 => Ok(false),
-1 => Err(ErrorStack::get()),
_ => unreachable!(),
}
}
/// Like `read`, but returns an `ssl::Error` rather than an `io::Error`.
///
/// It is particularly useful with a non-blocking socket, where the error value will identify if
/// OpenSSL is waiting on read or write readiness.
#[corresponds(SSL_read)]
pub fn ssl_read(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
// The interpretation of the return code here is a little odd with a
// zero-length write. OpenSSL will likely correctly report back to us
// that it read zero bytes, but zero is also the sentinel for "error".
// To avoid that confusion short-circuit that logic and return quickly
// if `buf` has a length of zero.
if buf.is_empty() {
return Ok(0);
}
let ret = self.ssl.read(buf);
if ret > 0 {
Ok(ret as usize)
} else {
Err(self.make_error(ret))
}
}
/// Like `write`, but returns an `ssl::Error` rather than an `io::Error`.
///
/// It is particularly useful with a non-blocking socket, where the error value will identify if
/// OpenSSL is waiting on read or write readiness.
#[corresponds(SSL_write)]
pub fn ssl_write(&mut self, buf: &[u8]) -> Result<usize, Error> {
// See above for why we short-circuit on zero-length buffers
if buf.is_empty() {
return Ok(0);
}
let ret = self.ssl.write(buf);
if ret > 0 {
Ok(ret as usize)
} else {
Err(self.make_error(ret))
}
}
/// Reads data from the stream, without removing it from the queue.
#[corresponds(SSL_peek)]
pub fn ssl_peek(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
// See above for why we short-circuit on zero-length buffers
if buf.is_empty() {
return Ok(0);
}
let ret = self.ssl.peek(buf);
if ret > 0 {
Ok(ret as usize)
} else {
Err(self.make_error(ret))
}
}
/// Shuts down the session.
///
/// The shutdown process consists of two steps. The first step sends a close notify message to
/// the peer, after which `ShutdownResult::Sent` is returned. The second step awaits the receipt
/// of a close notify message from the peer, after which `ShutdownResult::Received` is returned.
///
/// While the connection may be closed after the first step, it is recommended to fully shut the
/// session down. In particular, it must be fully shut down if the connection is to be used for
/// further communication in the future.
#[corresponds(SSL_shutdown)]
pub fn shutdown(&mut self) -> Result<ShutdownResult, Error> {
match unsafe { ffi::SSL_shutdown(self.ssl.as_ptr()) } {
0 => Ok(ShutdownResult::Sent),
1 => Ok(ShutdownResult::Received),
n => Err(self.make_error(n)),
}
}
/// Returns the session's shutdown state.
#[corresponds(SSL_get_shutdown)]
pub fn get_shutdown(&mut self) -> ShutdownState {
unsafe {
let bits = ffi::SSL_get_shutdown(self.ssl.as_ptr());
ShutdownState { bits }
}
}
/// Sets the session's shutdown state.
///
/// This can be used to tell OpenSSL that the session should be cached even if a full two-way
/// shutdown was not completed.
#[corresponds(SSL_set_shutdown)]
pub fn set_shutdown(&mut self, state: ShutdownState) {
unsafe { ffi::SSL_set_shutdown(self.ssl.as_ptr(), state.bits()) }
}
}
impl<S> SslStream<S> {
fn make_error(&mut self, ret: c_int) -> Error {
self.check_panic();
let code = self.ssl.get_error(ret);
let cause = match code {
ErrorCode::SSL => Some(InnerError::Ssl(ErrorStack::get())),
ErrorCode::SYSCALL => {
let errs = ErrorStack::get();
if errs.errors().is_empty() {
self.get_bio_error().map(InnerError::Io)
} else {
Some(InnerError::Ssl(errs))
}
}
ErrorCode::ZERO_RETURN => None,
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
self.get_bio_error().map(InnerError::Io)
}
_ => None,
};
Error { code, cause }
}
fn check_panic(&mut self) {
if let Some(err) = unsafe { bio::take_panic::<S>(self.ssl.get_raw_rbio()) } {
resume_unwind(err)
}
}
fn get_bio_error(&mut self) -> Option<io::Error> {
unsafe { bio::take_error::<S>(self.ssl.get_raw_rbio()) }
}
/// Returns a shared reference to the underlying stream.
pub fn get_ref(&self) -> &S {
unsafe {
let bio = self.ssl.get_raw_rbio();
bio::get_ref(bio)
}
}
/// Returns a mutable reference to the underlying stream.
///
/// # Warning
///
/// It is inadvisable to read from or write to the underlying stream as it
/// will most likely corrupt the SSL session.
pub fn get_mut(&mut self) -> &mut S {
unsafe {
let bio = self.ssl.get_raw_rbio();
bio::get_mut(bio)
}
}
/// Returns a shared reference to the `Ssl` object associated with this stream.
pub fn ssl(&self) -> &SslRef {
&self.ssl
}
}
impl<S: Read + Write> Read for SslStream<S> {
fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
loop {
match self.ssl_read(buf) {
Ok(n) => return Ok(n),
Err(ref e) if e.code() == ErrorCode::ZERO_RETURN => return Ok(0),
Err(ref e) if e.code() == ErrorCode::SYSCALL && e.io_error().is_none() => {
return Ok(0);
}
Err(ref e) if e.code() == ErrorCode::WANT_READ && e.io_error().is_none() => {}
Err(e) => {
return Err(e
.into_io_error()
.unwrap_or_else(|e| io::Error::new(io::ErrorKind::Other, e)));
}
}
}
}
}
impl<S: Read + Write> Write for SslStream<S> {
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
loop {
match self.ssl_write(buf) {
Ok(n) => return Ok(n),
Err(ref e) if e.code() == ErrorCode::WANT_READ && e.io_error().is_none() => {}
Err(e) => {
return Err(e
.into_io_error()
.unwrap_or_else(|e| io::Error::new(io::ErrorKind::Other, e)));
}
}
}
}
fn flush(&mut self) -> io::Result<()> {
self.get_mut().flush()
}
}
/// A partially constructed `SslStream`, useful for unusual handshakes.
#[deprecated(
since = "0.10.32",
note = "use the methods directly on Ssl/SslStream instead"
)]
pub struct SslStreamBuilder<S> {
inner: SslStream<S>,
}
#[allow(deprecated)]
impl<S> SslStreamBuilder<S>
where
S: Read + Write,
{
/// Begin creating an `SslStream` atop `stream`
pub fn new(ssl: Ssl, stream: S) -> Self {
Self {
inner: SslStream::new(ssl, stream).unwrap(),
}
}
/// Perform a stateless server-side handshake
///
/// Requires that cookie generation and verification callbacks were
/// set on the SSL context.
///
/// Returns `Ok(true)` if a complete ClientHello containing a valid cookie
/// was read, in which case the handshake should be continued via
/// `accept`. If a HelloRetryRequest containing a fresh cookie was
/// transmitted, `Ok(false)` is returned instead. If the handshake cannot
/// proceed at all, `Err` is returned.
///
/// This corresponds to [`SSL_stateless`]
///
/// [`SSL_stateless`]: https://www.openssl.org/docs/manmaster/man3/SSL_stateless.html
#[cfg(ossl111)]
pub fn stateless(&mut self) -> Result<bool, ErrorStack> {
match unsafe { ffi::SSL_stateless(self.inner.ssl.as_ptr()) } {
1 => Ok(true),
0 => Ok(false),
-1 => Err(ErrorStack::get()),
_ => unreachable!(),
}
}
/// Configure as an outgoing stream from a client.
///
/// This corresponds to [`SSL_set_connect_state`].
///
/// [`SSL_set_connect_state`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_connect_state.html
pub fn set_connect_state(&mut self) {
unsafe { ffi::SSL_set_connect_state(self.inner.ssl.as_ptr()) }
}
/// Configure as an incoming stream to a server.
///
/// This corresponds to [`SSL_set_accept_state`].
///
/// [`SSL_set_accept_state`]: https://www.openssl.org/docs/manmaster/man3/SSL_set_accept_state.html
pub fn set_accept_state(&mut self) {
unsafe { ffi::SSL_set_accept_state(self.inner.ssl.as_ptr()) }
}
/// See `Ssl::connect`
pub fn connect(mut self) -> Result<SslStream<S>, HandshakeError<S>> {
match self.inner.connect() {
Ok(()) => Ok(self.inner),
Err(error) => match error.code() {
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
Err(HandshakeError::WouldBlock(MidHandshakeSslStream {
stream: self.inner,
error,
}))
}
_ => Err(HandshakeError::Failure(MidHandshakeSslStream {
stream: self.inner,
error,
})),
},
}
}
/// See `Ssl::accept`
pub fn accept(mut self) -> Result<SslStream<S>, HandshakeError<S>> {
match self.inner.accept() {
Ok(()) => Ok(self.inner),
Err(error) => match error.code() {
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
Err(HandshakeError::WouldBlock(MidHandshakeSslStream {
stream: self.inner,
error,
}))
}
_ => Err(HandshakeError::Failure(MidHandshakeSslStream {
stream: self.inner,
error,
})),
},
}
}
/// Initiates the handshake.
///
/// This will fail if `set_accept_state` or `set_connect_state` was not called first.
///
/// This corresponds to [`SSL_do_handshake`].
///
/// [`SSL_do_handshake`]: https://www.openssl.org/docs/manmaster/man3/SSL_do_handshake.html
pub fn handshake(mut self) -> Result<SslStream<S>, HandshakeError<S>> {
match self.inner.do_handshake() {
Ok(()) => Ok(self.inner),
Err(error) => match error.code() {
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
Err(HandshakeError::WouldBlock(MidHandshakeSslStream {
stream: self.inner,
error,
}))
}
_ => Err(HandshakeError::Failure(MidHandshakeSslStream {
stream: self.inner,
error,
})),
},
}
}
sourcepub fn stateless(&mut self) -> Result<bool, ErrorStack>
pub fn stateless(&mut self) -> Result<bool, ErrorStack>
Perform a stateless server-side handshake.
Requires that cookie generation and verification callbacks were set on the SSL context.
Returns Ok(true)
if a complete ClientHello containing a valid cookie
was read, in which case the handshake should be continued via
accept
. If a HelloRetryRequest containing a fresh cookie was
transmitted, Ok(false)
is returned instead. If the handshake cannot
proceed at all, Err
is returned.
This corresponds to SSL_stateless
.
sourcepub fn ssl_read(&mut self, buf: &mut [u8]) -> Result<usize, Error>
pub fn ssl_read(&mut self, buf: &mut [u8]) -> Result<usize, Error>
Like read
, but returns an ssl::Error
rather than an io::Error
.
It is particularly useful with a non-blocking socket, where the error value will identify if OpenSSL is waiting on read or write readiness.
This corresponds to SSL_read
.
Examples found in repository?
3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539
fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
loop {
match self.ssl_read(buf) {
Ok(n) => return Ok(n),
Err(ref e) if e.code() == ErrorCode::ZERO_RETURN => return Ok(0),
Err(ref e) if e.code() == ErrorCode::SYSCALL && e.io_error().is_none() => {
return Ok(0);
}
Err(ref e) if e.code() == ErrorCode::WANT_READ && e.io_error().is_none() => {}
Err(e) => {
return Err(e
.into_io_error()
.unwrap_or_else(|e| io::Error::new(io::ErrorKind::Other, e)));
}
}
}
}
sourcepub fn ssl_write(&mut self, buf: &[u8]) -> Result<usize, Error>
pub fn ssl_write(&mut self, buf: &[u8]) -> Result<usize, Error>
Like write
, but returns an ssl::Error
rather than an io::Error
.
It is particularly useful with a non-blocking socket, where the error value will identify if OpenSSL is waiting on read or write readiness.
This corresponds to SSL_write
.
Examples found in repository?
3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
loop {
match self.ssl_write(buf) {
Ok(n) => return Ok(n),
Err(ref e) if e.code() == ErrorCode::WANT_READ && e.io_error().is_none() => {}
Err(e) => {
return Err(e
.into_io_error()
.unwrap_or_else(|e| io::Error::new(io::ErrorKind::Other, e)));
}
}
}
}
sourcepub fn ssl_peek(&mut self, buf: &mut [u8]) -> Result<usize, Error>
pub fn ssl_peek(&mut self, buf: &mut [u8]) -> Result<usize, Error>
Reads data from the stream, without removing it from the queue.
This corresponds to SSL_peek
.
sourcepub fn shutdown(&mut self) -> Result<ShutdownResult, Error>
pub fn shutdown(&mut self) -> Result<ShutdownResult, Error>
Shuts down the session.
The shutdown process consists of two steps. The first step sends a close notify message to
the peer, after which ShutdownResult::Sent
is returned. The second step awaits the receipt
of a close notify message from the peer, after which ShutdownResult::Received
is returned.
While the connection may be closed after the first step, it is recommended to fully shut the session down. In particular, it must be fully shut down if the connection is to be used for further communication in the future.
This corresponds to SSL_shutdown
.
sourcepub fn get_shutdown(&mut self) -> ShutdownState
pub fn get_shutdown(&mut self) -> ShutdownState
Returns the session’s shutdown state.
This corresponds to SSL_get_shutdown
.
sourcepub fn set_shutdown(&mut self, state: ShutdownState)
pub fn set_shutdown(&mut self, state: ShutdownState)
Sets the session’s shutdown state.
This can be used to tell OpenSSL that the session should be cached even if a full two-way shutdown was not completed.
This corresponds to SSL_set_shutdown
.
source§impl<S> SslStream<S>
impl<S> SslStream<S>
sourcepub fn get_ref(&self) -> &S
pub fn get_ref(&self) -> &S
Returns a shared reference to the underlying stream.
Examples found in repository?
3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204
pub fn get_ref(&self) -> &S {
self.stream.get_ref()
}
/// Returns a mutable reference to the inner stream.
pub fn get_mut(&mut self) -> &mut S {
self.stream.get_mut()
}
/// Returns a shared reference to the `Ssl` of the stream.
pub fn ssl(&self) -> &SslRef {
self.stream.ssl()
}
/// Returns the underlying error which interrupted this handshake.
pub fn error(&self) -> &Error {
&self.error
}
/// Consumes `self`, returning its error.
pub fn into_error(self) -> Error {
self.error
}
}
impl<S> MidHandshakeSslStream<S>
where
S: Read + Write,
{
/// Restarts the handshake process.
///
/// This corresponds to [`SSL_do_handshake`].
///
/// [`SSL_do_handshake`]: https://www.openssl.org/docs/manmaster/man3/SSL_do_handshake.html
pub fn handshake(mut self) -> Result<SslStream<S>, HandshakeError<S>> {
match self.stream.do_handshake() {
Ok(()) => Ok(self.stream),
Err(error) => {
self.error = error;
match self.error.code() {
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
Err(HandshakeError::WouldBlock(self))
}
_ => Err(HandshakeError::Failure(self)),
}
}
}
}
}
/// A TLS session over a stream.
pub struct SslStream<S> {
ssl: ManuallyDrop<Ssl>,
method: ManuallyDrop<BioMethod>,
_p: PhantomData<S>,
}
impl<S> Drop for SslStream<S> {
fn drop(&mut self) {
// ssl holds a reference to method internally so it has to drop first
unsafe {
ManuallyDrop::drop(&mut self.ssl);
ManuallyDrop::drop(&mut self.method);
}
}
}
impl<S> fmt::Debug for SslStream<S>
where
S: fmt::Debug,
{
fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt.debug_struct("SslStream")
.field("stream", &self.get_ref())
.field("ssl", &self.ssl())
.finish()
}
sourcepub fn get_mut(&mut self) -> &mut S
pub fn get_mut(&mut self) -> &mut S
Returns a mutable reference to the underlying stream.
Warning
It is inadvisable to read from or write to the underlying stream as it will most likely corrupt the SSL session.
Examples found in repository?
3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559
pub fn get_mut(&mut self) -> &mut S {
self.stream.get_mut()
}
/// Returns a shared reference to the `Ssl` of the stream.
pub fn ssl(&self) -> &SslRef {
self.stream.ssl()
}
/// Returns the underlying error which interrupted this handshake.
pub fn error(&self) -> &Error {
&self.error
}
/// Consumes `self`, returning its error.
pub fn into_error(self) -> Error {
self.error
}
}
impl<S> MidHandshakeSslStream<S>
where
S: Read + Write,
{
/// Restarts the handshake process.
///
/// This corresponds to [`SSL_do_handshake`].
///
/// [`SSL_do_handshake`]: https://www.openssl.org/docs/manmaster/man3/SSL_do_handshake.html
pub fn handshake(mut self) -> Result<SslStream<S>, HandshakeError<S>> {
match self.stream.do_handshake() {
Ok(()) => Ok(self.stream),
Err(error) => {
self.error = error;
match self.error.code() {
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
Err(HandshakeError::WouldBlock(self))
}
_ => Err(HandshakeError::Failure(self)),
}
}
}
}
}
/// A TLS session over a stream.
pub struct SslStream<S> {
ssl: ManuallyDrop<Ssl>,
method: ManuallyDrop<BioMethod>,
_p: PhantomData<S>,
}
impl<S> Drop for SslStream<S> {
fn drop(&mut self) {
// ssl holds a reference to method internally so it has to drop first
unsafe {
ManuallyDrop::drop(&mut self.ssl);
ManuallyDrop::drop(&mut self.method);
}
}
}
impl<S> fmt::Debug for SslStream<S>
where
S: fmt::Debug,
{
fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt.debug_struct("SslStream")
.field("stream", &self.get_ref())
.field("ssl", &self.ssl())
.finish()
}
}
impl<S: Read + Write> SslStream<S> {
/// Creates a new `SslStream`.
///
/// This function performs no IO; the stream will not have performed any part of the handshake
/// with the peer. If the `Ssl` was configured with [`SslRef::set_connect_state`] or
/// [`SslRef::set_accept_state`], the handshake can be performed automatically during the first
/// call to read or write. Otherwise the `connect` and `accept` methods can be used to
/// explicitly perform the handshake.
#[corresponds(SSL_set_bio)]
pub fn new(ssl: Ssl, stream: S) -> Result<Self, ErrorStack> {
let (bio, method) = bio::new(stream)?;
unsafe {
ffi::SSL_set_bio(ssl.as_ptr(), bio, bio);
}
Ok(SslStream {
ssl: ManuallyDrop::new(ssl),
method: ManuallyDrop::new(method),
_p: PhantomData,
})
}
/// Constructs an `SslStream` from a pointer to the underlying OpenSSL `SSL` struct.
///
/// This is useful if the handshake has already been completed elsewhere.
///
/// # Safety
///
/// The caller must ensure the pointer is valid.
#[deprecated(
since = "0.10.32",
note = "use Ssl::from_ptr and SslStream::new instead"
)]
pub unsafe fn from_raw_parts(ssl: *mut ffi::SSL, stream: S) -> Self {
let ssl = Ssl::from_ptr(ssl);
Self::new(ssl, stream).unwrap()
}
/// Read application data transmitted by a client before handshake completion.
///
/// Useful for reducing latency, but vulnerable to replay attacks. Call
/// [`SslRef::set_accept_state`] first.
///
/// Returns `Ok(0)` if all early data has been read.
///
/// Requires OpenSSL 1.1.1 or LibreSSL 3.4.0 or newer.
#[corresponds(SSL_read_early_data)]
#[cfg(any(ossl111, libressl340))]
pub fn read_early_data(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
let mut read = 0;
let ret = unsafe {
ffi::SSL_read_early_data(
self.ssl.as_ptr(),
buf.as_ptr() as *mut c_void,
buf.len(),
&mut read,
)
};
match ret {
ffi::SSL_READ_EARLY_DATA_ERROR => Err(self.make_error(ret)),
ffi::SSL_READ_EARLY_DATA_SUCCESS => Ok(read),
ffi::SSL_READ_EARLY_DATA_FINISH => Ok(0),
_ => unreachable!(),
}
}
/// Send data to the server without blocking on handshake completion.
///
/// Useful for reducing latency, but vulnerable to replay attacks. Call
/// [`SslRef::set_connect_state`] first.
///
/// Requires OpenSSL 1.1.1 or LibreSSL 3.4.0 or newer.
#[corresponds(SSL_write_early_data)]
#[cfg(any(ossl111, libressl340))]
pub fn write_early_data(&mut self, buf: &[u8]) -> Result<usize, Error> {
let mut written = 0;
let ret = unsafe {
ffi::SSL_write_early_data(
self.ssl.as_ptr(),
buf.as_ptr() as *const c_void,
buf.len(),
&mut written,
)
};
if ret > 0 {
Ok(written)
} else {
Err(self.make_error(ret))
}
}
/// Initiates a client-side TLS handshake.
///
/// # Warning
///
/// OpenSSL's default configuration is insecure. It is highly recommended to use
/// `SslConnector` rather than `Ssl` directly, as it manages that configuration.
#[corresponds(SSL_connect)]
pub fn connect(&mut self) -> Result<(), Error> {
let ret = unsafe { ffi::SSL_connect(self.ssl.as_ptr()) };
if ret > 0 {
Ok(())
} else {
Err(self.make_error(ret))
}
}
/// Initiates a server-side TLS handshake.
///
/// # Warning
///
/// OpenSSL's default configuration is insecure. It is highly recommended to use
/// `SslAcceptor` rather than `Ssl` directly, as it manages that configuration.
#[corresponds(SSL_accept)]
pub fn accept(&mut self) -> Result<(), Error> {
let ret = unsafe { ffi::SSL_accept(self.ssl.as_ptr()) };
if ret > 0 {
Ok(())
} else {
Err(self.make_error(ret))
}
}
/// Initiates the handshake.
///
/// This will fail if `set_accept_state` or `set_connect_state` was not called first.
#[corresponds(SSL_do_handshake)]
pub fn do_handshake(&mut self) -> Result<(), Error> {
let ret = unsafe { ffi::SSL_do_handshake(self.ssl.as_ptr()) };
if ret > 0 {
Ok(())
} else {
Err(self.make_error(ret))
}
}
/// Perform a stateless server-side handshake.
///
/// Requires that cookie generation and verification callbacks were
/// set on the SSL context.
///
/// Returns `Ok(true)` if a complete ClientHello containing a valid cookie
/// was read, in which case the handshake should be continued via
/// `accept`. If a HelloRetryRequest containing a fresh cookie was
/// transmitted, `Ok(false)` is returned instead. If the handshake cannot
/// proceed at all, `Err` is returned.
#[corresponds(SSL_stateless)]
#[cfg(ossl111)]
pub fn stateless(&mut self) -> Result<bool, ErrorStack> {
match unsafe { ffi::SSL_stateless(self.ssl.as_ptr()) } {
1 => Ok(true),
0 => Ok(false),
-1 => Err(ErrorStack::get()),
_ => unreachable!(),
}
}
/// Like `read`, but returns an `ssl::Error` rather than an `io::Error`.
///
/// It is particularly useful with a non-blocking socket, where the error value will identify if
/// OpenSSL is waiting on read or write readiness.
#[corresponds(SSL_read)]
pub fn ssl_read(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
// The interpretation of the return code here is a little odd with a
// zero-length write. OpenSSL will likely correctly report back to us
// that it read zero bytes, but zero is also the sentinel for "error".
// To avoid that confusion short-circuit that logic and return quickly
// if `buf` has a length of zero.
if buf.is_empty() {
return Ok(0);
}
let ret = self.ssl.read(buf);
if ret > 0 {
Ok(ret as usize)
} else {
Err(self.make_error(ret))
}
}
/// Like `write`, but returns an `ssl::Error` rather than an `io::Error`.
///
/// It is particularly useful with a non-blocking socket, where the error value will identify if
/// OpenSSL is waiting on read or write readiness.
#[corresponds(SSL_write)]
pub fn ssl_write(&mut self, buf: &[u8]) -> Result<usize, Error> {
// See above for why we short-circuit on zero-length buffers
if buf.is_empty() {
return Ok(0);
}
let ret = self.ssl.write(buf);
if ret > 0 {
Ok(ret as usize)
} else {
Err(self.make_error(ret))
}
}
/// Reads data from the stream, without removing it from the queue.
#[corresponds(SSL_peek)]
pub fn ssl_peek(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
// See above for why we short-circuit on zero-length buffers
if buf.is_empty() {
return Ok(0);
}
let ret = self.ssl.peek(buf);
if ret > 0 {
Ok(ret as usize)
} else {
Err(self.make_error(ret))
}
}
/// Shuts down the session.
///
/// The shutdown process consists of two steps. The first step sends a close notify message to
/// the peer, after which `ShutdownResult::Sent` is returned. The second step awaits the receipt
/// of a close notify message from the peer, after which `ShutdownResult::Received` is returned.
///
/// While the connection may be closed after the first step, it is recommended to fully shut the
/// session down. In particular, it must be fully shut down if the connection is to be used for
/// further communication in the future.
#[corresponds(SSL_shutdown)]
pub fn shutdown(&mut self) -> Result<ShutdownResult, Error> {
match unsafe { ffi::SSL_shutdown(self.ssl.as_ptr()) } {
0 => Ok(ShutdownResult::Sent),
1 => Ok(ShutdownResult::Received),
n => Err(self.make_error(n)),
}
}
/// Returns the session's shutdown state.
#[corresponds(SSL_get_shutdown)]
pub fn get_shutdown(&mut self) -> ShutdownState {
unsafe {
let bits = ffi::SSL_get_shutdown(self.ssl.as_ptr());
ShutdownState { bits }
}
}
/// Sets the session's shutdown state.
///
/// This can be used to tell OpenSSL that the session should be cached even if a full two-way
/// shutdown was not completed.
#[corresponds(SSL_set_shutdown)]
pub fn set_shutdown(&mut self, state: ShutdownState) {
unsafe { ffi::SSL_set_shutdown(self.ssl.as_ptr(), state.bits()) }
}
}
impl<S> SslStream<S> {
fn make_error(&mut self, ret: c_int) -> Error {
self.check_panic();
let code = self.ssl.get_error(ret);
let cause = match code {
ErrorCode::SSL => Some(InnerError::Ssl(ErrorStack::get())),
ErrorCode::SYSCALL => {
let errs = ErrorStack::get();
if errs.errors().is_empty() {
self.get_bio_error().map(InnerError::Io)
} else {
Some(InnerError::Ssl(errs))
}
}
ErrorCode::ZERO_RETURN => None,
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
self.get_bio_error().map(InnerError::Io)
}
_ => None,
};
Error { code, cause }
}
fn check_panic(&mut self) {
if let Some(err) = unsafe { bio::take_panic::<S>(self.ssl.get_raw_rbio()) } {
resume_unwind(err)
}
}
fn get_bio_error(&mut self) -> Option<io::Error> {
unsafe { bio::take_error::<S>(self.ssl.get_raw_rbio()) }
}
/// Returns a shared reference to the underlying stream.
pub fn get_ref(&self) -> &S {
unsafe {
let bio = self.ssl.get_raw_rbio();
bio::get_ref(bio)
}
}
/// Returns a mutable reference to the underlying stream.
///
/// # Warning
///
/// It is inadvisable to read from or write to the underlying stream as it
/// will most likely corrupt the SSL session.
pub fn get_mut(&mut self) -> &mut S {
unsafe {
let bio = self.ssl.get_raw_rbio();
bio::get_mut(bio)
}
}
/// Returns a shared reference to the `Ssl` object associated with this stream.
pub fn ssl(&self) -> &SslRef {
&self.ssl
}
}
impl<S: Read + Write> Read for SslStream<S> {
fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
loop {
match self.ssl_read(buf) {
Ok(n) => return Ok(n),
Err(ref e) if e.code() == ErrorCode::ZERO_RETURN => return Ok(0),
Err(ref e) if e.code() == ErrorCode::SYSCALL && e.io_error().is_none() => {
return Ok(0);
}
Err(ref e) if e.code() == ErrorCode::WANT_READ && e.io_error().is_none() => {}
Err(e) => {
return Err(e
.into_io_error()
.unwrap_or_else(|e| io::Error::new(io::ErrorKind::Other, e)));
}
}
}
}
}
impl<S: Read + Write> Write for SslStream<S> {
fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
loop {
match self.ssl_write(buf) {
Ok(n) => return Ok(n),
Err(ref e) if e.code() == ErrorCode::WANT_READ && e.io_error().is_none() => {}
Err(e) => {
return Err(e
.into_io_error()
.unwrap_or_else(|e| io::Error::new(io::ErrorKind::Other, e)));
}
}
}
}
fn flush(&mut self) -> io::Result<()> {
self.get_mut().flush()
}
sourcepub fn ssl(&self) -> &SslRef
pub fn ssl(&self) -> &SslRef
Returns a shared reference to the Ssl
object associated with this stream.
Examples found in repository?
3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204
pub fn ssl(&self) -> &SslRef {
self.stream.ssl()
}
/// Returns the underlying error which interrupted this handshake.
pub fn error(&self) -> &Error {
&self.error
}
/// Consumes `self`, returning its error.
pub fn into_error(self) -> Error {
self.error
}
}
impl<S> MidHandshakeSslStream<S>
where
S: Read + Write,
{
/// Restarts the handshake process.
///
/// This corresponds to [`SSL_do_handshake`].
///
/// [`SSL_do_handshake`]: https://www.openssl.org/docs/manmaster/man3/SSL_do_handshake.html
pub fn handshake(mut self) -> Result<SslStream<S>, HandshakeError<S>> {
match self.stream.do_handshake() {
Ok(()) => Ok(self.stream),
Err(error) => {
self.error = error;
match self.error.code() {
ErrorCode::WANT_READ | ErrorCode::WANT_WRITE => {
Err(HandshakeError::WouldBlock(self))
}
_ => Err(HandshakeError::Failure(self)),
}
}
}
}
}
/// A TLS session over a stream.
pub struct SslStream<S> {
ssl: ManuallyDrop<Ssl>,
method: ManuallyDrop<BioMethod>,
_p: PhantomData<S>,
}
impl<S> Drop for SslStream<S> {
fn drop(&mut self) {
// ssl holds a reference to method internally so it has to drop first
unsafe {
ManuallyDrop::drop(&mut self.ssl);
ManuallyDrop::drop(&mut self.method);
}
}
}
impl<S> fmt::Debug for SslStream<S>
where
S: fmt::Debug,
{
fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt.debug_struct("SslStream")
.field("stream", &self.get_ref())
.field("ssl", &self.ssl())
.finish()
}
Trait Implementations§
source§impl<S: Read + Write> Read for SslStream<S>
impl<S: Read + Write> Read for SslStream<S>
source§fn read(&mut self, buf: &mut [u8]) -> Result<usize>
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
1.36.0 · source§fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
read
, except that it reads into a slice of buffers. Read moresource§fn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)1.0.0 · source§fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
buf
. Read more1.0.0 · source§fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
buf
. Read more1.6.0 · source§fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
buf
. Read moresource§fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)source§fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)cursor
. Read more1.0.0 · source§fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
Read
. Read moresource§impl<S: Read + Write> Write for SslStream<S>
impl<S: Read + Write> Write for SslStream<S>
source§fn write(&mut self, buf: &[u8]) -> Result<usize>
fn write(&mut self, buf: &[u8]) -> Result<usize>
source§fn flush(&mut self) -> Result<()>
fn flush(&mut self) -> Result<()>
source§fn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)1.0.0 · source§fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
source§fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)