channel.h File Reference

Secure channel abstraction. More...

#include <stdint.h>
#include <ipxe/crypto.h>
#include <ipxe/x509.h>
#include <ipxe/sha256.h>

Go to the source code of this file.

Data Structures
struct	secure_channel_properties
	Secure channel properties. More...
struct	secure_pipe
	A secure channel transmit or receive pipe. More...
struct	secure_channel
	A secure channel. More...
struct	secure_preshared_identity
	A pre-shared bound peer identity. More...
struct	secure_channel_operations
	Secure channel operations. More...

Macros
#define	channel_ephemeral_algorithm   sha256_algorithm
	Ephemeral master secret digest algorithm.

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
static void	channel_init (struct secure_channel *channel, struct secure_channel_operations *op)
	Initialise secure channel.
static int	channel_is_established (struct secure_channel *channel)
	Check if secure channel has been established.
static void	channel_clear_preshared (struct secure_preshared_identity *psid)
	Clear pre-shared bound peer identity.
void	channel_ephemeral (struct secure_channel *channel, const void *info, size_t info_len, void *out, size_t len)
	Generate ephemeral secret.
void	channel_ephemeral_label (struct secure_channel *channel, const char *label, void *out, size_t len)
	Generate labelled ephemeral secret.
void	channel_unkey (struct secure_channel *channel)
	Clear shared secret.
int	channel_key_share (struct secure_channel *channel, struct exchange_algorithm *exchange, void *public)
	Share public key.
int	channel_key_agree (struct secure_channel *channel, struct exchange_algorithm *exchange, const void *partner)
	Agree shared secret.
int	channel_bind_verify (struct secure_channel *channel, struct x509_certificate *identity, struct pubkey_algorithm *pubkey, struct digest_algorithm *digest, const void *value, const struct asn1_cursor *signature)
	Bind peer identity via ephemeral public key signature verification.
int	channel_bind_encrypt (struct secure_channel *channel, struct x509_certificate *identity, struct exchange_algorithm *exchange, struct pubkey_algorithm *pubkey, struct asn1_builder *ciphertext)
	Bind peer identity via shared secret encryption.
int	channel_save (struct secure_channel *channel, struct secure_preshared_identity *psid)
	Save a pre-shared key.
int	channel_load (struct secure_channel *channel, struct secure_preshared_identity *psid)
	Load a pre-shared key.
int	channel_confirm (struct secure_channel *channel, const void *auth, size_t len)
	Confirm peer identity.
int	channel_establish (struct secure_channel *channel, const char *name, struct x509_root *root)
	Establish channel as trusted for application data.
int	channel_set_cipher (struct secure_channel *channel, struct secure_pipe *pipe, struct cipher_algorithm *cipher, const void *key, size_t len)
	Set cipher algorithm and key.
int	channel_open (struct secure_channel *channel)
	Open secure channel.
void	channel_reopen (struct secure_channel *channel)
	Reopen secure channel.
void	channel_close (struct secure_channel *channel)
	Close secure channel.

Variables
struct cipher_algorithm	channel_dead_cipher
	Dead cipher.

Detailed Description

Secure channel abstraction.

Definition in file channel.h.

Macro Definition Documentation

channel_ephemeral_algorithm

#define channel_ephemeral_algorithm   sha256_algorithm

Ephemeral master secret digest algorithm.

Definition at line 19 of file channel.h.

Referenced by channel_ephemeral(), and channel_ephemeral_init().

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

channel_init()

void channel_init ( struct secure_channel * channel, struct secure_channel_operations * op )

inlinestatic

Initialise secure channel.

Parameters

channel	Secure channel
op	Channel operations

Definition at line 256 of file channel.h.

                                                                         {
 
        channel->op = op;
        channel->tx.cipher = &channel_dead_cipher;
        channel->rx.cipher = &channel_dead_cipher;
}

References channel, channel_dead_cipher, and op.

Referenced by add_tls().

channel_is_established()

int channel_is_established ( struct secure_channel * channel )

inlinestatic

Check if secure channel has been established.

Parameters

channel

Secure channel

Return values

is_established

Channel has been established

Definition at line 271 of file channel.h.

                                                          {
 
        return ( channel->props.established != NULL );
}

References channel, and NULL.

Referenced by tls_channel_save(), and tls_ready().

channel_clear_preshared()

void channel_clear_preshared ( struct secure_preshared_identity * psid )

inlinestatic

Clear pre-shared bound peer identity.

Parameters

psid	Pre-shared identity

Definition at line 282 of file channel.h.

                                                                   {
 
        x509_put ( psid->bound );
        psid->bound = NULL;
}

References secure_preshared_identity::bound, NULL, and x509_put().

Referenced by channel_save(), and free_tls_session().

channel_ephemeral()

void channel_ephemeral ( struct secure_channel * channel, const void * info, size_t info_len, void * out, size_t len )

extern

Generate ephemeral secret.

Parameters

channel	Secure channel
info	Additional information
info_len	Length of additional information
out	Ephemeral secret to fill in
len	Length of ephemeral secret

Definition at line 195 of file channel.c.

                                                                  {
        struct digest_algorithm *digest = &channel_ephemeral_algorithm;
 
        /* Additional info should always be provided */
        assert ( info != NULL );
        assert ( info_len > 0 );
 
        /* Generate from ephemeral master secret and additional information */
        hkdf_expand ( digest, channel->ephemeral, info, info_len, out, len );
}

References assert, channel, channel_ephemeral_algorithm, hkdf_expand(), info, info_len, len, NULL, and out.

Referenced by channel_ephemeral_label(), and tls_send_record().

channel_ephemeral_label()

void channel_ephemeral_label ( struct secure_channel * channel, const char * label, void * out, size_t len )

extern

Generate labelled ephemeral secret.

Parameters

channel	Secure channel
label	Additional information string
out	Ephemeral secret to fill in
len	Length of ephemeral secret

Definition at line 215 of file channel.c.

                                                                          {
 
        /* Generate from ephemeral master secret and label */
        channel_ephemeral ( channel, label, strlen ( label ), out, len );
        DBGC2 ( channel, "CHANNEL %p ephemeral \"%s\":\n", channel, label );
        DBGC2_HDA ( channel, 0, out, len );
}

References channel, channel_ephemeral(), DBGC2, DBGC2_HDA, len, out, and strlen().

Referenced by channel_ephemeral_replace(), channel_key_private(), tls_nonce(), and tls_session().

channel_unkey()

void channel_unkey ( struct secure_channel * channel )

extern

Clear shared secret.

Parameters

channel

Secure channel

Definition at line 273 of file channel.c.

                                                      {
 
        /* Key binding is defined only for the current shared secret,
         * and so any existing bound peer identity must be cleared.
         */
        channel_unbind ( channel );
 
        /* Clear shared key */
        channel->props.keyed = 0;
 
        /* Reset the key schedule */
        channel->op->reset ( channel );
}

References channel, and channel_unbind().

Referenced by channel_bind_encrypt(), channel_close(), channel_key(), channel_load(), channel_open(), channel_reopen(), and tls_clear_digest().

channel_key_share()

int channel_key_share ( struct secure_channel * channel, struct exchange_algorithm * exchange, void * public )

extern

Share public key.

Parameters

channel	Secure channel
exchange	Key exchange algorithm
public	Public key to fill in

Return values

rc	Return status code

Definition at line 320 of file channel.c.

                                                                            {
        size_t privsize = exchange->privsize;
        size_t pubsize = exchange->pubsize;
        uint8_t private[privsize];
        int rc;
 
        /* (Re)generate private key */
        channel_key_private ( channel, exchange, private );
 
        /* Generate public key */
        if ( ( rc = exchange_share ( exchange, private, public ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not share \"%s\": %s\n",
                       channel, exchange->name, strerror ( rc ) );
                goto err_share;
        }
 
        /* Show public key (for debugging) */
        DBGC2 ( channel, "CHANNEL %p sharing \"%s\":\n",
                channel, exchange->name );
        DBGC2_HDA ( channel, 0, public, pubsize );
 
 err_share:
        /* Erase private key */
        memset ( private, 0, sizeof ( private ) );
        return rc;
}

References channel, channel_key_private(), DBGC, DBGC2, DBGC2_HDA, exchange_share(), memset(), exchange_algorithm::name, exchange_algorithm::privsize, exchange_algorithm::pubsize, rc, and strerror().

Referenced by tls_key_share().

channel_key_agree()

int channel_key_agree ( struct secure_channel * channel, struct exchange_algorithm * exchange, const void * partner )

extern

Agree shared secret.

Parameters

channel	Secure channel
exchange	Key exchange algorithm
partner	Partner public key

Return values

rc	Return status code

Definition at line 424 of file channel.c.

                                              {
        size_t sharedsize = exchange->sharedsize;
        size_t pubsize = exchange->pubsize;
        void *tmp;
        int rc;
 
        /* Show partner public key (for debugging) */
        DBGC2 ( channel, "CHANNEL %p partner \"%s\":\n",
                channel, exchange->name );
        DBGC2_HDA ( channel, 0, partner, pubsize );
 
        /* Allocate space for shared secret (may be too large for stack) */
        tmp = zalloc ( sharedsize );
        if ( ! tmp ) {
                rc = -ENOMEM;
                goto err_alloc;
        }
 
        /* Generate and apply shared secret */
        if ( ( rc = channel_key ( channel, exchange, partner, tmp ) ) != 0 )
                goto err_key;
 
 err_key:
        /* Erase shared secret */
        zfree ( tmp );
 err_alloc:
        return rc;
}

References channel, channel_key(), DBGC2, DBGC2_HDA, ENOMEM, exchange_algorithm::name, partner, exchange_algorithm::pubsize, rc, exchange_algorithm::sharedsize, tmp, zalloc(), and zfree().

Referenced by tls_key_agree().

channel_bind_verify()

int channel_bind_verify ( struct secure_channel * channel, struct x509_certificate * identity, struct pubkey_algorithm * pubkey, struct digest_algorithm * digest, const void * value, const struct asn1_cursor * signature )

extern

Bind peer identity via ephemeral public key signature verification.

Parameters

channel	Secure channel
identity	Identity to be bound
pubkey	Public-key algorithm
digest	Digest algorithm
value	Digest value (must cover peer's ephemeral public key)
signature	Signature

Return values

rc	Return status code

The peer may delegate authority to the shared secret by signing a digest that covers at least its own ephemeral public key (e.g. the Diffie-Hellman parameters provided in a ServerKeyExchange record) and a challenge nonce (e.g. the TLS client random bytes).

The consumer asserts to the secure channel that the digest covers at least the peer's ephemeral public key and a nonce. The digest may cover arbitrary additional information (e.g. the entire transcript hash as signed by a CertificateVerify record).

This assertion is an unverifiable promise made by the consumer: there is no way for the secure channel itself to determine what is covered by the digest.

Definition at line 611 of file channel.c.

                                                                {
        const struct asn1_cursor *key = &identity->subject.public_key.raw;
        int rc;
 
        /* Verify signature */
        if ( ( rc = pubkey_verify ( pubkey, key, digest, value,
                                    signature ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not verify binding: %s\n",
                       channel, strerror ( rc ) );
                return rc;
        }
 
        /* Bind to the identity that signed the shared secret */
        if ( ( rc = channel_bind ( channel, identity ) ) != 0 )
                return rc;
 
        return 0;
}

References channel, channel_bind(), DBGC, key, pubkey_verify(), x509_subject::public_key, x509_public_key::raw, rc, signature, strerror(), x509_certificate::subject, and value.

Referenced by tls_new_server_key_exchange().

channel_bind_encrypt()

int channel_bind_encrypt ( struct secure_channel * channel, struct x509_certificate * identity, struct exchange_algorithm * exchange, struct pubkey_algorithm * pubkey, struct asn1_builder * ciphertext )

extern

Bind peer identity via shared secret encryption.

Parameters

channel	Secure channel
identity	Identity to be bound
exchange	Key exchange algorithm
pubkey	Public-key algorithm
ciphertext	Encrypted shared secret

Return values

rc	Return status code

The local endpoint may delegate authority to the shared secret by encrypting a unilaterally chosen shared secret (e.g. a classic TLS static RSA pre-master secret).

Definition at line 648 of file channel.c.

                                                             {
        const struct asn1_cursor *key = &identity->subject.public_key.raw;
        size_t sharedsize = exchange->sharedsize;
        struct asn1_cursor plaintext;
        void *tmp;
        int rc;
 
        /* Allocate space for shared secret (may be too large for stack) */
        tmp = zalloc ( sharedsize );
        if ( ! tmp ) {
                rc = -ENOMEM;
                goto err_alloc;
        }
        plaintext.data = tmp;
        plaintext.len = sharedsize;
 
        /* Generate unencrypted shared secret */
        if ( ( rc = channel_key_transport ( channel, exchange, tmp ) ) != 0 )
                goto err_transport;
 
        /* Encrypt shared secret */
        if ( ( rc = pubkey_encrypt ( pubkey, key, &plaintext,
                                     ciphertext ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not encrypt \"%s\": %s\n",
                       channel, exchange->name, strerror ( rc ) );
                goto err_encrypt;
        }
 
        /* Bind to the identity that can decrypt the shared secret */
        if ( ( rc = channel_bind ( channel, identity ) ) != 0 )
                goto err_bind;
 
 err_bind:
 err_encrypt:
 err_transport:
        /* Clear the generated shared secret on any error */
        if ( rc != 0 )
                channel_unkey ( channel );
        /* Erase unencrypted shared secret */
        zfree ( tmp );
 err_alloc:
        return rc;
}

References channel, channel_bind(), channel_key_transport(), channel_unkey(), asn1_cursor::data, DBGC, ENOMEM, key, asn1_cursor::len, exchange_algorithm::name, pubkey_encrypt(), x509_subject::public_key, x509_public_key::raw, rc, exchange_algorithm::sharedsize, strerror(), x509_certificate::subject, tmp, zalloc(), and zfree().

Referenced by tls_key_encrypt().

channel_save()

int channel_save ( struct secure_channel * channel, struct secure_preshared_identity * psid )

extern

Save a pre-shared key.

Parameters

channel	Secure channel
psid	Pre-shared bound peer identity

Return values

rc	Return status code

Definition at line 738 of file channel.c.

                                                            {
        struct x509_certificate *identity;
        int rc;
 
        /* Clear any existing pre-shared bound peer identity */
        channel_clear_preshared ( psid );
 
        /* Fail if there is no bound peer identity to save */
        identity = channel->props.bound;
        if ( ! identity ) {
                DBGC ( channel, "CHANNEL %p cannot create pre-shared key "
                       "for unbound peer\n", channel );
                return -EPROTO_NOT_BOUND;
        }
 
        /* Fail if consumer does not support pre-shared keys */
        if ( ! channel->op->save ) {
                DBGC ( channel, "CHANNEL %p does not support pre-shared "
                       "keys\n", channel );
                return -ENOTSUP;
        }
 
        /* Save pre-shared key */
        if ( ( rc = channel->op->save ( channel, psid ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not save pre-shared "
                       "key: %s\n", channel, strerror ( rc ) );
                return rc;
        }
 
        /* Record pre-shared bound peer identity */
        psid->bound = x509_get ( identity );
        DBGC ( channel, "CHANNEL %p key material saved for \"%s\"\n",
               channel, x509_name ( identity ) );
 
        return 0;
}

References secure_preshared_identity::bound, channel, channel_clear_preshared(), DBGC, ENOTSUP, EPROTO_NOT_BOUND, rc, strerror(), x509_get(), and x509_name().

Referenced by tls_save().

channel_load()

int channel_load ( struct secure_channel * channel, struct secure_preshared_identity * psid )

extern

Load a pre-shared key.

Parameters

channel	Secure channel
psid	Pre-shared bound peer identity

Return values

rc	Return status code

Definition at line 783 of file channel.c.

                                                            {
        struct x509_certificate *identity;
        int rc;
 
        /* Clear any existing shared secret */
        channel_unkey ( channel );
 
        /* Fail if there is no bound peer identity to resume */
        identity = psid->bound;
        if ( ! identity ) {
                DBGC ( channel, "CHANNEL %p cannot resume from empty "
                       "pre-shared key\n", channel );
                rc = -EPROTO_NOT_BOUND;
                goto err_empty;
        }
 
        /* Fail if consumer does not support pre-shared keys */
        if ( ! channel->op->load ) {
                DBGC ( channel, "CHANNEL %p does not support pre-shared "
                       "keys\n", channel );
                rc = -ENOTSUP;
                goto err_unsupported;
        }
 
        /* Load pre-shared key */
        if ( ( rc = channel->op->load ( channel, psid ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p could not load pre-shared key: "
                       "%s\n", channel, strerror ( rc ) );
                goto err_load;
        }
 
        /* Channel now possesses a shared secret */
        channel->props.keyed = 1;
        DBGC ( channel, "CHANNEL %p key material obtained from pre-shared "
               "key\n", channel );
 
        /* Bind to the identity that was bound to the pre-shared key */
        if ( ( rc = channel_bind ( channel, identity ) ) != 0 )
                goto err_bind;
 
        return 0;
 
 err_bind:
 err_load:
 err_unsupported:
 err_empty:
        channel_unkey ( channel );
        return rc;
}

References secure_preshared_identity::bound, channel, channel_bind(), channel_unkey(), DBGC, ENOTSUP, EPROTO_NOT_BOUND, rc, and strerror().

Referenced by tls_resume().

channel_confirm()

int channel_confirm ( struct secure_channel * channel, const void * auth, size_t len )

extern

Confirm peer identity.

Parameters

channel	Secure channel
auth	Authenticator value
len	Length of authenticator value

Return values

rc	Return status code

The consumer asserts to the secure channel that the authenticator value was received after the receive pipe was transitioned to a cipher capable of providing confidentiality.

This assertion is an unverifiable promise made by the consumer: there is no way for the secure channel itself to determine when the authenticator value was received.

Definition at line 896 of file channel.c.

                                                     {
        struct x509_certificate *identity;
        int rc;
 
        /* Clear any existing confirmed peer identity */
        channel_unconfirm ( channel );
 
        /* Fail if there is no bound peer identity to authenticate */
        identity = channel->props.bound;
        if ( ! identity ) {
                DBGC ( channel, "CHANNEL %p cannot authenticate unbound "
                       "peer\n", channel );
                return -EPROTO_NOT_BOUND;
        }
 
        /* Sanity check: binding is not possible without keying */
        assert ( channel->props.keyed );
 
        /* Require key confirmation over a confidential channel */
        if ( ! channel->rx.cipher->confidential ) {
                DBGC ( channel, "CHANNEL %p cannot confirm key with a "
                       "non-confidential cipher\n", channel );
                return -EPERM_NOT_CONFIDENTIAL;
        }
 
        /* Verify authentication data */
        if ( ( rc = channel->op->verify ( channel, auth, len ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p failed to authenticate: %s\n",
                       channel, strerror ( rc ) );
                return rc;
        }
 
        /* Record bound peer identity as confirmed peer identity */
        channel->props.confirmed = x509_get ( identity );
        DBGC ( channel, "CHANNEL %p key material confirmed for \"%s\"\n",
               channel, x509_name ( identity ) );
 
        return 0;
}

References assert, channel, channel_unconfirm(), DBGC, EPERM_NOT_CONFIDENTIAL, EPROTO_NOT_BOUND, len, rc, strerror(), x509_get(), and x509_name().

Referenced by tls_new_finished().

channel_establish()

int channel_establish ( struct secure_channel * channel, const char * name, struct x509_root * root )

extern

Establish channel as trusted for application data.

Parameters

channel	Secure channel
name	Required peer identity name
root	Root certificate list, or NULL to use default

Return values

rc	Return status code

Definition at line 986 of file channel.c.

                                                 {
        struct x509_certificate *identity;
        int rc;
 
        /* Clear any existing established peer identity */
        channel_unestablish ( channel );
 
        /* Fail if there is no confirmed peer identity to establish */
        identity = channel->props.confirmed;
        if ( ! identity ) {
                DBGC ( channel, "CHANNEL %p cannot establish unconfirmed "
                       "peer\n", channel );
                return -EPROTO_NOT_CONFIRMED;
        }
 
        /* Sanity check: confirmation is not possible without binding */
        assert ( channel->props.bound == identity );
        assert ( channel->props.keyed );
 
        /* Fail if ciphers are still operating in plaintext mode */
        if ( ! ( channel->tx.cipher->confidential &&
                 channel->rx.cipher->confidential ) ) {
                DBGC ( channel, "CHANNEL %p cannot establish channel with a "
                       "non-confidential cipher\n", channel );
                return -EPERM_NOT_CONFIDENTIAL;
        }
 
        /* Fail if confirmed peer identity name is incorrect */
        if ( ( rc = x509_check_name ( identity, name ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p identity \"%s\" does not match "
                       "\"%s\": %s\n", channel, x509_name ( identity ),
                       name, strerror ( rc ) );
                return rc;
        }
 
        /* Fail if confirmed peer identity has not been validated */
        if ( ! x509_is_valid ( identity, root ) ) {
                DBGC ( channel, "CHANNEL %p identity \"%s\" has not been "
                       "validated\n", channel, x509_name ( identity ) );
                return -EPERM_NOT_VALID;
        }
 
        /* Record confirmed peer identity as established peer identity */
        channel->props.established = x509_get ( identity );
        DBGC ( channel, "CHANNEL %p established for \"%s\"\n",
               channel, x509_name ( identity ) );
 
        return 0;
}

References assert, channel, channel_unestablish(), DBGC, EPERM_NOT_CONFIDENTIAL, EPERM_NOT_VALID, EPROTO_NOT_CONFIRMED, name, rc, root, strerror(), x509_check_name(), x509_get(), x509_is_valid(), and x509_name().

Referenced by tls_establish().

channel_set_cipher()

int channel_set_cipher ( struct secure_channel * channel, struct secure_pipe * pipe, struct cipher_algorithm * cipher, const void * key, size_t len )

extern

Set cipher algorithm and key.

Parameters

channel	Secure channel
pipe	Secure channel pipe
cipher	Cipher algorithm
key	Key
len	Length of key

Return values

rc	Return status code

The consumer asserts to the secure channel that the key is ultimately derived from the shared secret that was previously provided to the consumer by the secure channel, i.e. that possession of the cipher key implies possession of the shared secret.

This assertion is an unverifiable promise made by the consumer: we can check that a shared secret exists, but there is no way for the secure channel itself to determine how the cipher key is derived.

Definition at line 1136 of file channel.c.

                                                       {
        int rc;
 
        /* Zero and free any existing cipher context */
        channel_clear_cipher ( pipe );
 
        /* Fail if there is no shared secret from which a key could derive */
        if ( ! channel->props.keyed ) {
                DBGC ( channel, "CHANNEL %p refusing to use definitely "
                       "non-derived shared secret\n", channel );
                rc = -EPROTO_NOT_KEYED;
                goto err_keyed;
        }
 
        /* Refuse to explicitly set a non-confidential cipher */
        if ( ! cipher->confidential ) {
                DBGC ( channel, "CHANNEL %p %s refusing to use "
                       "non-confidential cipher \"%s\"\n", channel,
                       channel_pipe_name ( channel, pipe ), cipher->name );
                rc = -EPERM_NOT_CONFIDENTIAL;
                goto err_confidential;
        }
        pipe->cipher = cipher;
 
        /* Allocate new context */
        pipe->ctx = zalloc ( cipher->ctxsize );
        if ( ! pipe->ctx ) {
                rc = -ENOMEM;
                goto err_alloc;
        }
 
        /* Set cipher key */
        if ( ( rc = cipher_setkey ( cipher, pipe->ctx, key, len ) ) != 0 ) {
                DBGC ( channel, "CHANNEL %p %s could not set \"%s\" key: %s\n",
                       channel, channel_pipe_name ( channel, pipe ),
                       cipher->name, strerror ( rc ) );
                goto err_setkey;
        }
 
        DBGC ( channel, "CHANNEL %p %s using \"%s\" with %zd-bit key\n",
               channel, channel_pipe_name ( channel, pipe ),
               cipher->name, ( 8 * len ) );
        return 0;
 
 err_setkey:
 err_alloc:
 err_confidential:
 err_keyed:
        channel_clear_cipher ( pipe );
        return rc;
}

References channel, channel_clear_cipher(), channel_pipe_name(), secure_pipe::cipher, cipher_setkey(), cipher_algorithm::confidential, secure_pipe::ctx, cipher_algorithm::ctxsize, DBGC, ENOMEM, EPERM_NOT_CONFIDENTIAL, EPROTO_NOT_KEYED, key, len, cipher_algorithm::name, rc, strerror(), and zalloc().

Referenced by tls_change_cipher().

channel_open()

int channel_open ( struct secure_channel * channel )

extern

Open secure channel.

Parameters

channel

Secure channel

Return values

rc	Return status code

Definition at line 1205 of file channel.c.

                                                    {
        int rc;
 
        /* Sanity checks */
        assert ( channel != NULL );
        assert ( channel->op != NULL );
        assert ( channel->op->reset != NULL );
        assert ( channel->op->apply != NULL );
        assert ( channel->op->verify != NULL );
 
        /* Clear security properties (which should already be clear) */
        assert ( channel->props.keyed == 0 );
        assert ( channel->props.bound == NULL );
        assert ( channel->props.confirmed == NULL );
        assert ( channel->props.established == NULL );
        channel_unkey ( channel );
        assert ( channel->props.keyed == 0 );
        assert ( channel->props.bound == NULL );
        assert ( channel->props.confirmed == NULL );
        assert ( channel->props.established == NULL );
 
        /* Reset ciphers (which should already have no contexts) */
        assert ( channel->tx.ctx == NULL );
        assert ( channel->rx.ctx == NULL );
        channel_clear_cipher ( &channel->tx );
        channel_clear_cipher ( &channel->rx );
        assert ( channel->tx.ctx == NULL );
        assert ( channel->rx.ctx == NULL );
 
        /* Initialise ephemeral master secret */
        if ( ( rc = channel_ephemeral_init ( channel ) ) != 0 )
                return rc;
 
        /* Enable initial plaintext ciphers */
        channel->tx.cipher = &cipher_null;
        channel->rx.cipher = &cipher_null;
 
        DBGC ( channel, "CHANNEL %p opened\n", channel );
        return 0;
}

References assert, channel, channel_clear_cipher(), channel_ephemeral_init(), channel_unkey(), cipher_null, DBGC, NULL, and rc.

Referenced by add_tls().

channel_reopen()

void channel_reopen ( struct secure_channel * channel )

extern

Reopen secure channel.

Parameters

channel

Secure channel

The channel will be returned to a freshly opened state (including a new ephemeral master secret), but with any existing cipher state retained. All security properties will be cleared.

This allows a new secure channel to be established with either or both of the transmit and receive pipes having already transitioned to a cipher capable of providing confidentiality.

The consumer may choose to reopen a fully established channel while leaving the cipher keys intact (as is done in TLS renegotiation), in which case it may choose to treat the channel as remaining established (to the old peer identity) at least until the point that the cipher keys are next changed (and possibly further, depending upon the protocol design). The secure channel itself does not attempt to model any such choice by the consumer: reopening will clear all security properties including the established peer identity.

Definition at line 1269 of file channel.c.

                                                       {
 
        /* Clear security properties */
        channel_unkey ( channel );
        assert ( channel->props.keyed == 0 );
        assert ( channel->props.bound == NULL );
        assert ( channel->props.confirmed == NULL );
        assert ( channel->props.established == NULL );
 
        /* Replace ephemeral master secret
         *
         * We choose to replace rather than reinitialise the ephemeral
         * master secret so that this function may be used from code
         * paths that cannot allow for failure (such as when closing
         * the channel).
         */
        channel_ephemeral_replace ( channel );
 
        DBGC ( channel, "CHANNEL %p reopened\n", channel );
}

References assert, channel, channel_ephemeral_replace(), channel_unkey(), DBGC, and NULL.

Referenced by tls_restart().

channel_close()

void channel_close ( struct secure_channel * channel )

extern

Close secure channel.

Parameters

channel

Secure channel

All secret values held by the secure channel will be destroyed, including the ephemeral master secret.

This function may safely be called on a channel that has already been closed.

Definition at line 1301 of file channel.c.

                                                      {
 
        /* Clear security properties */
        channel_unkey ( channel );
        assert ( channel->props.keyed == 0 );
        assert ( channel->props.bound == NULL );
        assert ( channel->props.confirmed == NULL );
        assert ( channel->props.established == NULL );
 
        /* Reset ciphers */
        channel_clear_cipher ( &channel->tx );
        channel_clear_cipher ( &channel->rx );
        assert ( channel->tx.ctx == NULL );
        assert ( channel->rx.ctx == NULL );
 
        /* Replace ephemeral master secret
         *
         * We choose to replace rather than zero the ephemeral master
         * secret.  For any channel that has been successfully opened,
         * this ensures that an erroneous reuse of the channel after
         * it has been closed cannot lead to the use of predictable
         * ephemeral secrets (derived from an all-zero value), or to
         * reuse of its previous ephemeral secrets.
         */
        channel_ephemeral_replace ( channel );
 
        DBGC ( channel, "CHANNEL %p closed\n", channel );
}

References assert, channel, channel_clear_cipher(), channel_ephemeral_replace(), channel_unkey(), DBGC, and NULL.

Referenced by add_tls(), and tls_close().

Variable Documentation

channel_dead_cipher

struct cipher_algorithm channel_dead_cipher

extern

Dead cipher.

We activate this cipher (rather than the null cipher) upon any cipher-related failure, to guard against code paths that may fail to check for cipher errors.

Definition at line 1073 of file channel.c.

                                            {
        .name = "dead",
        .ctxsize = 0,
        .blocksize = 1,
        .alignsize = 1,
        .authsize = 0,
        .confidential = 0,
        .setkey = cipher_null_setkey,
        .setiv = cipher_null_setiv,
        .encrypt = channel_dead_crypt,
        .decrypt = channel_dead_crypt,
        .auth = cipher_null_auth,
};

Referenced by channel_clear_cipher(), and channel_init().