Module Contents¶
Classes¶
Raw Python object serialization and deserialization. Object serializers are |
|
WAMP message serialization and deserialization. |
|
A WAMP message, e.g. one of the messages defined in the WAMP specification |
|
A WAMP transport is a bidirectional, full-duplex, reliable, ordered, |
|
Helper class that provides a standard way to create an ABC using |
|
Interface for WAMP sessions. |
|
Experimental authentication API. |
|
Interface to an asymmetric verification key, e.g. a WAMP-Cryptosign client or server authentication |
|
Interface to a WAMP-Cryptosign client authentication (or server verification) key. |
|
Interface to an Ethereum signing (or transaction verification) key, used for WAMP-XBR transaction |
|
Interface for key security modules, which |
|
WAMP payload codecs are used with WAMP payload transparency mode. |
- class autobahn.wamp.interfaces.IObjectSerializer[source]¶
Bases:
abc.ABC
Raw Python object serialization and deserialization. Object serializers are used by classes implementing WAMP serializers, that is instances of
autobahn.wamp.interfaces.ISerializer
.- abstract property BINARY: bool¶
Flag (read-only) to indicate if serializer requires a binary clean transport or if UTF8 transparency is sufficient.
- class autobahn.wamp.interfaces.ISerializer[source]¶
Bases:
abc.ABC
WAMP message serialization and deserialization.
- abstract property MESSAGE_TYPE_MAP: Dict[int, IMessage]¶
Mapping of WAMP message type codes to WAMP message classes.
- abstract property SERIALIZER_ID: str¶
The WAMP serialization format ID as used for WebSocket, e.g.
"json"
(or"json.batched"
) for JSON.
- abstract property RAWSOCKET_SERIALIZER_ID: int¶
The WAMP serialization format ID as used for RawSocket, e.g.
1
for JSON.
- abstract property MIME_TYPE: str¶
The WAMP serialization format MIME type, e.g.
"application/json"
for JSON.
- abstract serialize(message: IMessage) Tuple[bytes, bool] [source]¶
Serializes a WAMP message to bytes for sending over a WAMP transport.
- Parameters
message – The WAMP message to be serialized.
- Returns
A pair
(payload, is_binary)
.
- abstract unserialize(payload: bytes, is_binary: Optional[bool] = None) List[IMessage] [source]¶
Deserialize bytes from a transport and parse into WAMP messages.
- Parameters
payload – Byte string from wire.
is_binary – Type of payload. True if payload is a binary string, else the payload is UTF-8 encoded Unicode text.
- Returns
List of WAMP messages.
- class autobahn.wamp.interfaces.IMessage[source]¶
Bases:
abc.ABC
A WAMP message, e.g. one of the messages defined in the WAMP specification here.
- abstract static parse(wmsg) IMessage [source]¶
Factory method that parses a unserialized raw message (as returned byte
autobahn.interfaces.ISerializer.unserialize()
) into an instance of this class.- Returns
The parsed WAMP message.
- abstract serialize(serializer: ISerializer) bytes [source]¶
Serialize this object into a wire level bytes representation and cache the resulting bytes. If the cache already contains an entry for the given serializer, return the cached representation directly.
- Parameters
serializer – The wire level serializer to use.
- Returns
The serialized bytes.
- class autobahn.wamp.interfaces.ITransport[source]¶
Bases:
abc.ABC
A WAMP transport is a bidirectional, full-duplex, reliable, ordered, message-based channel.
- abstract property transport_details: Optional[autobahn.wamp.types.TransportDetails]¶
Return details about the transport (when the transport is open).
- abstract send(message: IMessage)[source]¶
Send a WAMP message over the transport to the peer. If the transport is not open, this raises
autobahn.wamp.exception.TransportLost
. Returns a deferred/future when the message has been processed and more messages may be sent. When send() is called while a previous deferred/future has not yet fired, the send will fail immediately.- Parameters
message – The WAMP message to send over the transport.
- abstract isOpen() bool [source]¶
Check if the transport is open for messaging.
- Returns
True
, if the transport is open.
- class autobahn.wamp.interfaces.ITransportHandler[source]¶
Bases:
abc.ABC
Helper class that provides a standard way to create an ABC using inheritance.
- abstract onOpen(transport: ITransport)[source]¶
Callback fired when transport is open. May run asynchronously. The transport is considered running and is_open() would return true, as soon as this callback has completed successfully.
- Parameters
transport – The WAMP transport.
- abstract onMessage(message: IMessage)[source]¶
Callback fired when a WAMP message was received. May run asynchronously. The callback should return or fire the returned deferred/future when it’s done processing the message. In particular, an implementation of this callback must not access the message afterwards.
- Parameters
message – The WAMP message received.
- class autobahn.wamp.interfaces.ISession[source]¶
Bases:
_ABC
Interface for WAMP sessions.
- abstract property config: autobahn.wamp.types.ComponentConfig¶
Configuration for session.
- abstract property transport: Optional[ITransport]¶
When the transport this session is attached to is currently open, this property can be read from. The property should be considered read-only. When the transport is gone, this property is set to None.
- abstract property session_details: Optional[autobahn.wamp.types.SessionDetails]¶
Return details about the session, the same as initially provided to the
ISession.onJoin()
callback on an implementation.
- abstract onUserError(fail, msg)[source]¶
This is called when we try to fire a callback, but get an exception from user code – for example, a registered publish callback or a registered method. By default, this prints the current stack-trace and then error-message to stdout.
ApplicationSession-derived objects may override this to provide logging if they prefer. The Twisted implemention does this. (See
autobahn.twisted.wamp.ApplicationSession
)- Parameters
fail (instance implementing txaio.IFailedFuture) – The failure that occurred.
msg (str) – an informative message from the library. It is suggested you log this immediately after the exception.
- abstract onConnect()[source]¶
Callback fired when the transport this session will run over has been established.
- abstract join(realm: str, authmethods: Optional[List[str]] = None, authid: Optional[str] = None, authrole: Optional[str] = None, authextra: Optional[Dict[str, Any]] = None, resumable: Optional[bool] = None, resume_session: Optional[int] = None, resume_token: Optional[str] = None)[source]¶
Attach the session to the given realm. A session is open as soon as it is attached to a realm.
- abstract onChallenge(challenge: autobahn.wamp.types.Challenge) str [source]¶
Callback fired when the peer demands authentication.
May return a Deferred/Future.
- Parameters
challenge – The authentication challenge.
- abstract onWelcome(welcome: autobahn.wamp.message.Welcome) Optional[str] [source]¶
Callback fired after the peer has successfully authenticated. If this returns anything other than None/False, the session is aborted and the return value is used as an error message.
May return a Deferred/Future.
Note
Before we let user code see the session – that is, before we fire “join” we give authentication instances a chance to abort the session. Usually this would be for “mutual authentication” scenarios. For example, WAMP-SCRAM uses this to confirm the server-signature.
- Parameters
welcome – The WELCOME message received from the server
- Returns
None, or an error message (using a fixed error URI
wamp.error.cannot_authenticate
).
- abstract onJoin(details: autobahn.wamp.types.SessionDetails)[source]¶
Callback fired when WAMP session has been established.
May return a Deferred/Future.
- Parameters
details – Session information.
- abstract leave(reason: Optional[str] = None, message: Optional[str] = None)[source]¶
Actively close this WAMP session.
- Parameters
reason – An optional URI for the closing reason. If you want to permanently log out, this should be
wamp.close.logout
.message – An optional (human-readable) closing message, intended for logging purposes.
- Returns
may return a Future/Deferred that fires when we’ve disconnected
- abstract onLeave(details: autobahn.wamp.types.CloseDetails)[source]¶
Callback fired when WAMP session has is closed
- Parameters
details – Close information for session.
- abstract set_payload_codec(payload_codec: Optional[IPayloadCodec])[source]¶
Set a payload codec on the session. To remove a previously set payload codec, set the codec to
None
.Payload codecs are used with WAMP payload transparency mode.
- Parameters
payload_codec – The payload codec that should process application payload of the given encoding.
- abstract get_payload_codec() Optional[IPayloadCodec] [source]¶
Get the current payload codec (if any) for the session.
Payload codecs are used with WAMP payload transparency mode.
- Returns
The current payload codec or
None
if no codec is active.
- abstract define(exception: Exception, error: Optional[str] = None)[source]¶
Defines an exception for a WAMP error in the context of this WAMP session.
- Parameters
exception – The exception class to define an error mapping for.
error – The URI (or URI pattern) the exception class should be mapped for. Iff the
exception
class is decorated, this must beNone
.
- abstract call(procedure: str, *args, **kwargs) Union[Any, autobahn.wamp.types.CallResult] [source]¶
Call a remote procedure.
This will return a Deferred/Future, that when resolved, provides the actual result returned by the called remote procedure.
If the result is a single positional return value, it’ll be returned “as-is”.
If the result contains multiple positional return values or keyword return values, the result is wrapped in an instance of
autobahn.wamp.types.CallResult
.If the call fails, the returned Deferred/Future will be rejected with an instance of
autobahn.wamp.exception.ApplicationError
.
If
kwargs
contains anoptions
keyword argument that is an instance ofautobahn.wamp.types.CallOptions
, this will provide specific options for the call to perform.When the Caller and Dealer implementations support canceling of calls, the call may be canceled by canceling the returned Deferred/Future.
- Parameters
procedure – The URI of the remote procedure to be called, e.g.
"com.myapp.hello"
.args – Any positional arguments for the call.
kwargs – Any keyword arguments for the call.
- Returns
A Deferred/Future for the call result.
- abstract register(endpoint: Union[Callable, Any], procedure: Optional[str] = None, options: Optional[autobahn.wamp.types.RegisterOptions] = None, prefix: Optional[str] = None, check_types: Optional[bool] = None) Union[autobahn.wamp.types.Registration, List[autobahn.wamp.types.Registration]] [source]¶
Register a procedure for remote calling.
When
endpoint
is a callable (function, method or object that implements__call__
), thenprocedure
must be provided and an instance of twisted.internet.defer.Deferred (when running on Twisted) or an instance ofasyncio.Future
(when running on asyncio) is returned.If the registration succeeds the returned Deferred/Future will resolve to an object that implements
autobahn.wamp.interfaces.IRegistration
.If the registration fails the returned Deferred/Future will reject with an instance of
autobahn.wamp.exception.ApplicationError
.
When
endpoint
is an object, then each of the object’s methods that is decorated withautobahn.wamp.register()
is automatically registered and a (single) DeferredList or Future is returned that gathers all individual underlying Deferreds/Futures.- Parameters
endpoint – The endpoint called under the procedure.
procedure – When
endpoint
is a callable, the URI (or URI pattern) of the procedure to register for. Whenendpoint
is an object, the argument is ignored (and should beNone
).options – Options for registering.
prefix – if not None, this specifies a prefix to prepend to all URIs registered for this class. So if there was an @wamp.register(‘method_foo’) on a method and prefix=’com.something.’ then a method ‘com.something.method_foo’ would ultimately be registered.
check_types – Enable automatic type checking against (Python 3.5+) type hints specified on the
endpoint
callable. Types are checked at run-time on each invocation of theendpoint
callable. When a type mismatch occurs, the error is forwarded to the callee code inonUserError
override method ofautobahn.wamp.protocol.ApplicationSession
. An error of typeautobahn.wamp.exception.TypeCheckError
is also raised and returned to the caller (via the router).
- Returns
A registration or a list of registrations (or errors)
- abstract publish(topic: str, *args, **kwargs) Optional[autobahn.wamp.types.Publication] [source]¶
Publish an event to a topic.
If
kwargs
contains anoptions
keyword argument that is an instance ofautobahn.wamp.types.PublishOptions
, this will provide specific options for the publish to perform.Note
By default, publications are non-acknowledged and the publication can fail silently, e.g. because the session is not authorized to publish to the topic.
When publication acknowledgement is requested via
options.acknowledge == True
, this function returns a Deferred/Future:If the publication succeeds the Deferred/Future will resolve to an object that implements
autobahn.wamp.interfaces.IPublication
.If the publication fails the Deferred/Future will reject with an instance of
autobahn.wamp.exception.ApplicationError
.
- Parameters
topic – The URI of the topic to publish to, e.g.
"com.myapp.mytopic1"
.args – Arbitrary application payload for the event (positional arguments).
kwargs – Arbitrary application payload for the event (keyword arguments).
- Returns
Acknowledgement for acknowledge publications - otherwise nothing.
- abstract subscribe(handler: Union[Callable, Any], topic: Optional[str] = None, options: Optional[autobahn.wamp.types.SubscribeOptions] = None, check_types: Optional[bool] = None) Union[autobahn.wamp.types.Subscription, List[autobahn.wamp.types.Subscription]] [source]¶
Subscribe to a topic for receiving events.
When
handler
is a callable (function, method or object that implements__call__
), then topic must be provided and an instance of twisted.internet.defer.Deferred (when running on Twisted) or an instance ofasyncio.Future
(when running on asyncio) is returned.If the subscription succeeds the Deferred/Future will resolve to an object that implements
autobahn.wamp.interfaces.ISubscription
.If the subscription fails the Deferred/Future will reject with an instance of
autobahn.wamp.exception.ApplicationError
.
When
handler
is an object, then each of the object’s methods that is decorated withautobahn.wamp.subscribe()
is automatically subscribed as event handlers, and a list of Deferreds/Futures is returned that each resolves or rejects as above.- Parameters
handler – The event handler to receive events.
topic – When
handler
is a callable, the URI (or URI pattern) of the topic to subscribe to. Whenhandler
is an object, this value is ignored (and should beNone
).options – Options for subscribing.
check_types – Enable automatic type checking against (Python 3.5+) type hints specified on the
endpoint
callable. Types are checked at run-time on each invocation of theendpoint
callable. When a type mismatch occurs, the error is forwarded to the subscriber code inonUserError
override method ofautobahn.wamp.protocol.ApplicationSession
.
- Returns
A single Deferred/Future or a list of such objects
- class autobahn.wamp.interfaces.IAuthenticator[source]¶
Bases:
abc.ABC
Experimental authentication API.
- abstract on_challenge(session: ISession, challenge: autobahn.wamp.types.Challenge)[source]¶
Formulate a challenge response for the given session and Challenge instance. This is sent to the server in the AUTHENTICATE message.
- abstract on_welcome(authextra: Optional[Dict[str, Any]]) Optional[str] [source]¶
This hook is called when the onWelcome/on_welcome hook is invoked in the protocol, with the ‘authextra’ dict extracted from the Welcome message. Usually this is used to verify the final message from the server (e.g. for mutual authentication).
- Returns
None if the session is successful or an error-message
- class autobahn.wamp.interfaces.IKey[source]¶
Bases:
abc.ABC
Interface to an asymmetric verification key, e.g. a WAMP-Cryptosign client or server authentication public key (with Ed25519), or a WAMP-XBR data transaction signature public key or address (with Ethereum).
The key implementation can use various methods, such as a key read from a file, database table or a key residing in a hardware device.
- abstract property security_module: Optional[ISecurityModule]¶
When this key is hosted by a security module, return a reference. If the key is freestanding (exists of its own outside any security module or key store), return
None
.- Returns
The security module of the key if the key is hosted.
- abstract property key_no: Optional[int]¶
When this key is hosted by a security module, return an identifier to refer to this key within the security module. If the key is freestanding (exists of its own outside any security module or key store), return
None
.- Returns
The identifier of this key within the security module if this key is hosted.
- abstract property key_type: str¶
Type of key and signature scheme, currently one of:
ed25519
: Ed25519, that is EdDSA signing algo with Curve25519 elliptic curve and SHA-512 hash,used with WAMP-cryptosign session authentication
eth
: Ethereum, that is ECDSA signing algo, secp256k1 elliptic curve and Keccak-256 hash,used with WAMP-XBR data and transaction signatures
- Returns
Key type, one of
ed25519
oreth
.
- abstract public_key(binary: bool = False) Union[str, bytes] [source]¶
Returns the public key part of a signing key or the (public) verification key.
- Parameters
binary – If the return type should be binary instead of hex
- Returns
The public key in hex or byte encoding.
- abstract can_sign() bool [source]¶
Check if the key can be used to sign and create new signatures, or only to verify signatures.
- Returns
True
, if the key can be used for signing.
- abstract sign(data: bytes) bytes [source]¶
Sign the given data, only available if
can_sign == True
. This method (always) runs asynchronously.- Parameters
data – The data to be signed.
- Returns
The signature, that is a future object that resolves to bytes.
- abstract recover(data: bytes, signature: bytes) bytes [source]¶
Recover the signer from the data signed, and the signature given. This method (always) runs asynchronously.
- Parameters
data – The data that was signed.
signature – The signature over the data.
- Returns
The signer public key that signed the data to create the signature given.
- class autobahn.wamp.interfaces.ICryptosignKey[source]¶
Bases:
IKey
Interface to a WAMP-Cryptosign client authentication (or server verification) key.
- abstract sign_challenge(challenge: autobahn.wamp.types.Challenge, channel_id: Optional[bytes] = None, channel_id_type: Optional[str] = None) bytes [source]¶
Sign the data from the given WAMP challenge message, and the optional TLS channel ID using this key and return a valid signature that can be used in a WAMP-cryptosign authentication handshake.
- Parameters
challenge – The WAMP challenge message as sent or received during the WAMP-cryptosign authentication handshake. This can be used by WAMP clients to compute the signature returned in the handshake, or by WAMP routers to verify the signature returned by clients, during WAMP-cryptosign client authentication.
channel_id – Optional TLS channel ID. Using this binds the WAMP session authentication to the underlying TLS channel, and thus prevents authentication-forwarding attacks.
channel_id_type – Optional TLS channel ID type, e.g.
"tls-unique"
.
- Returns
The signature, that is a future object that resolves to bytes.
- abstract verify_challenge(challenge: autobahn.wamp.types.Challenge, signature: bytes, channel_id: Optional[bytes] = None, channel_id_type: Optional[str] = None) bool [source]¶
Verify the data from the given WAMP challenge message, and the optional TLS channel ID to be signed by this key.
- Parameters
challenge – The WAMP challenge message as sent or received during the WAMP-cryptosign authentication handshake. This can be used by WAMP clients to compute the signature returned within the handshake, or by WAMP routers to verify the signature returned by clients, during WAMP-cryptosign client authentication.
signature – The signature to verify.
channel_id – Optional TLS channel ID. Using this binds the WAMP session authentication to the underlying TLS channel, and thus prevents authentication-forwarding attacks.
channel_id_type – Optional TLS channel ID type, e.g.
"tls-unique"
.
- Returns
Returns
True
if the signature over the data matches this key.
- class autobahn.wamp.interfaces.IEthereumKey[source]¶
Bases:
IKey
Interface to an Ethereum signing (or transaction verification) key, used for WAMP-XBR transaction signing (or verification).
- abstract address(binary: bool = False) Union[str, bytes] [source]¶
Returns the Ethereum (public) address of the key (which is derived from the public key).
- Parameters
binary – Return address as 160 bits (20 bytes) binary instead of the
0x
prefixed hex, check-summed address as a string.- Returns
The address in hex or byte encoding.
- abstract sign_typed_data(data: Dict[str, Any]) bytes [source]¶
Sign the given typed data according to EIP712 and create an Ethereum signature.
- Parameters
data – The data to be signed. This must follow EIP712.
- Returns
The signature, that is a future object that resolves to bytes.
- abstract verify_typed_data(data: Dict[str, Any], signature: bytes, signer_address: Union[str, bytes]) bool [source]¶
Verify the given typed data according to EIP712 to be signed by this key.
- Parameters
data – The data to be signed. This must follow EIP712.
signature – The signature to be verified.
signer_address – Address against which the signature is verified.
- Returns
Returns
True
if the signature over the data matches this key.
- class autobahn.wamp.interfaces.ISecurityModule[source]¶
Bases:
abc.ABC
Interface for key security modules, which
include filesystem and HSM backed persistent key implementations, and
provides secure key signature generation and verification with
two key types and signature schemes
The two key types and signature schemes support WAMP-cryptosign based authentication for WAMP sessions, and WAMP-XBR based signed transactions and data encryption.
References:
- abstract property is_open: bool¶
Check if the security module is currently opened. Security module operations can only be run when the module is opened.
- Returns
Flag indicating whether the security module is currently opened.
- abstract property can_lock: bool¶
Flag indicating whether this security module can be locked, e.g. by a user passphrase or PIN.
- Returns
Flag indicating whether the security module can be locked/unlocked at all.
- abstract property is_locked: bool¶
Check if this security module is currently locked.
- Returns
Flag indicating whether the security module is currently locked.
- abstract __len__() int [source]¶
Get number of key pairs currently stored within the security module.
- Returns
Current number of keys stored in security module.
- abstract __getitem__(key_no: int) Union[ICryptosignKey, IEthereumKey] [source]¶
Get a key from the security module given the key number.
- Parameters
key_no – Number of key to get.
- Returns
The key, either a
ICryptosignKey
orIEthereumKey
instance.
- abstract __setitem__(key_no: int, key: Union[ICryptosignKey, IEthereumKey]) None [source]¶
- Parameters
key_no –
key –
- Returns
- abstract create_key(key_type: str) int [source]¶
Create a new public-private asymmetric key pair, stored within the security module.
- Parameters
key_type – Type of key to generate, e.g.
"cryptosign"
or"ethereum"
.- Returns
ID of new key.
- abstract delete_key(key_no: int)[source]¶
Delete an existing key pair stored within the security module.
- Parameters
key_no – ID of key to delete.
- abstract get_random(octets: int) bytes [source]¶
Generate random bytes within the security module.
- Parameters
octets – Number of bytes (octets) to generate.
- Returns
Random bytes, generated within the security module, e.g. in a HW RNG.
- class autobahn.wamp.interfaces.IPayloadCodec[source]¶
Bases:
abc.ABC
WAMP payload codecs are used with WAMP payload transparency mode.
In payload transparency mode, application payloads are transmitted “raw”, as binary strings, without any processing at the WAMP router.
Payload transparency can be used eg for these use cases:
end-to-end encryption of application payloads (WAMP-cryptobox)
using serializers with custom user types, where the serializer and the serializer implementation has native support for serializing custom types (such as CBOR)
transmitting MQTT payloads within WAMP, when the WAMP router is providing a MQTT-WAMP bridge
- abstract encode(is_originating, uri, args=None, kwargs=None)[source]¶
Encodes application payload.
- Parameters
is_originating (bool) – Flag indicating whether the encoding is to be done from an originator (a caller or publisher).
uri (str) – The WAMP URI associated with the WAMP message for which the payload is to be encoded (eg topic or procedure).
args (list or None) – Positional application payload.
kwargs (dict or None) – Keyword-based application payload.
- Returns
The encoded application payload or None to signal no encoding should be used.
- Return type
instance of
autobahn.wamp.types.EncodedPayload
- abstract decode(is_originating, uri, encoded_payload)[source]¶
Decode application payload.
- Parameters
is_originating (bool) – Flag indicating whether the encoding is to be done from an originator (a caller or publisher).
uri (str) – The WAMP URI associated with the WAMP message for which the payload is to be encoded (eg topic or procedure).
encoded_payload (instance of
autobahn.wamp.types.EncodedPayload
) – The encoded application payload to be decoded.
- Returns
A tuple with the decoded positional and keyword-based application payload:
(uri, args, kwargs)
- Return type