time before the idle timeout applies.
Plugins can access global variables within pppd, so it is useful for
-them to #include "pppd.h" from the pppd source directory.
+them to #include "pppd.h" from the pppd source directory. Other
+header files can be included such as chap.h, mppe.h, and upap.h as
+needed per project.
Every plugin must contain a global procedure called `plugin_init'.
This procedure will get called (with no arguments) immediately after
the plugin is loaded. Every plugin should also contain a variable
called pppd_version declared as follows:
-char pppd_version[] = VERSION;
+char pppd_version[] = PPPD_VERSION;
If this declaration is included, pppd will not load the module if its
version number differs from that compiled into the plugin binary.
Plugins can affect the behaviour of pppd in at least four ways:
1. They can add extra options which pppd will then recognize. This is
- done by calling the add_options() procedure with a pointer to an
+ done by calling the ppp_add_options() procedure with a pointer to an
array of option_t structures. The last entry in the array must
have its name field set to NULL.
int (*pap_check_hook)(void);
int (*pap_passwd_hook)(char *user, char *passwd);
-int (*pap_auth_hook)(char *user, int userlen,
- char *passwd, int passlen,
- char **msgp, int *msglenp,
+int (*pap_auth_hook)(char *user, char *passwd, char **msgp,
struct wordlist **paddrs,
struct wordlist **popts);
void (*pap_logout_hook)(void);
purposes. This hook is deprecated and will be replaced by a notifier.
+int (*chap_check_hook)(void);
+int (*chap_passwd_hook)(char *user, char *passwd);
+int (*chap_verify_hook)(char *name, char *ourname, int id,
+ struct chap_digest_type *digest,
+ unsigned char *challenge, unsigned char *response,
+ char *message, int message_space)
+
+These hooks are designed to allow a plugin to replace the normal CHAP
+password processing in pppd with something different (e.g. contacting
+an external server).
+
+The chap_check_hook is called to check whether there is any possibility
+that the peer could authenticate itself to us. If it returns 1, pppd
+will ask the peer to authenticate itself. If it returns 0, pppd will
+not ask the peer to authenticate itself (but if authentication is
+required, pppd may exit, or terminate the link before network protocol
+negotiation). If it returns -1, pppd will look in the chap-secrets
+file as it would normally.
+
+The chap_passwd_hook is called to determine what password
+pppd should use in authenticating itself to the peer with CHAP. The
+user string will already be initialized, by the `user' option, the
+`name' option, or from the hostname, but can be changed if necessary.
+This hook is called only if pppd is a client, not if it is a server.
+
+MAXSECRETLEN bytes of space are available at *passwd. If this hook
+returns 0, pppd will use the value *passwd; if it returns -1, pppd
+will fail to authenticate.
+
+The chap_verify_hook is called to determine whether the peer's
+response to our CHAP challenge is valid -- it should return 1 if valid
+or 0 if not. The parameters are:
+
+* name points to a null-terminated string containing the username
+ supplied by the peer, or the remote name specified with the
+ "remotename" option.
+* ourname points to a null-terminated string containing the name of
+ the local machine (the hostname, or the name specified with the
+ "name" option).
+* id is the value of the id field from the challenge.
+* digest points to a chap_digest_type struct, which contains an
+ identifier for the type of digest in use plus function pointers for
+ functions for dealing with digests of that type.
+* challenge points to the challenge as a counted string (length byte
+ followed by the actual challenge bytes).
+* response points to the response as a counted string.
+* message points to an area of message_space bytes in which to store
+ any message that should be returned to the peer.
+
+
int (*null_auth_hook)(struct wordlist **paddrs,
struct wordlist **popts);
determine the peer's address in the usual manner.
+int (*allowed_address_hook)(u_int32_t addr)
+
+This hook is called to see if a peer is allowed to use the specified
+address. If the hook returns 1, the address is accepted. If it returns
+0, the address is rejected. If it returns -1, the address is verified
+in the normal away against the appropriate options and secrets files.
+
+
+void (*snoop_recv_hook)(unsigned char *p, int len)
+void (*snoop_send_hook)(unsigned char *p, int len)
+
+These hooks are called whenever pppd receives or sends a packet. The
+packet is in p; its length is len. This allows plugins to "snoop in"
+on the pppd conversation. The hooks may prove useful in implmenting
+L2TP.
+
+
+void (*multilink_join_hook)();
+
+This is called whenever a new link completes LCP negotiation and joins
+the bundle, if we are doing multilink.
+
+
A plugin registers itself with a notifier by declaring a procedure of
the form:
-void my_notify_proc(void *opaque, int arg);
+void (ppp_notify_fn)(void *opaque, int arg);
and then registering the procedure with the appropriate notifier with
a call of the form
- add_notifier(&interesting_notifier, my_notify_proc, opaque);
+ ppp_add_notify(ppp_notify_t, ppp_notify_fn, opaque);
+
+The ppp_notify_t is an enumerated type that describes which notifier
+to attach the function to. Example: NF_EXIT, NF_SIGNALED, NF_IP_UP
The `opaque' parameter in the add_notifier call will be passed to
my_notify_proc every time it is called. The `arg' parameter to
A notify procedure can be removed from the list for a notifier with a
call of the form
- remove_notifier(&interesting_notifier, my_notify_proc, opaque);
+ ppp_del_notify(ppp_notify_t, ppp_notify_fn, opaque);
Here is a list of the currently-implemented notifiers in pppd.
-* pidchange. This notifier is called in the parent when pppd has
+* NF_PID_CHANGE. This notifier is called in the parent when pppd has
forked and the child is continuing pppd's processing, i.e. when pppd
detaches from its controlling terminal. The argument is the pid of
the child.
-* phasechange. This is called when pppd moves from one phase of
+* NF_PHASE_CHANGE. This is called when pppd moves from one phase of
operation to another. The argument is the new phase number.
-* exitnotify. This is called just before pppd exits. The argument is
+* NF_EXIT. This is called just before pppd exits. The argument is
the status with which pppd will exit (i.e. the argument to exit()).
-* sigreceived. This is called when a signal is received, from within
+* NF_SIGNALED. This is called when a signal is received, from within
the signal handler. The argument is the signal number.
-* ip_up_notifier. This is called when IPCP has come up.
+* NF_IP_UP. This is called when IPCP has come up.
+
+* NF_IP_DOWN. This is called when IPCP goes down.
+
+* NF_IPV6_UP. This is called when IP6CP has come up.
-* ip_down_notifier. This is called when IPCP goes down.
+* NF_IPV6_DOWN. This is called when IP6CP goes down.
-* auth_up_notifier. This is called when the peer has successfully
+* NF_AUTH_UP. This is called when the peer has successfully
authenticated itself.
-* link_down_notifier. This is called when the link goes down.
+* NF_LINK_DOWN. This is called when the link goes down.
+
+* NF_FORK. Called for each time pppd exists as a new process (child).
+
+
+Regarding MPPE keys and key-material for 2.5.0 release
+
+Sometimes it is necessary for a plugin to access details related to
+the authentication process. The NF_AUTH_UP callback notifier (client only)
+allows a plugin to inspect e.g. key details after authentication has been
+completed, but before the key material is cleared from memory for security
+reasons.
+
+There are in particularly 3 functions that allow one to inspect these
+keys:
+
+* bool mppe_keys_isset()
+* int mppe_get_recv_key(unsigned char *key, int length)
+* int mppe_get_send_key(unsigned char *key, int length)
+
+The first function indicates whether or not the key material is set and
+is valid. The two latter functions will allow one to obtain a copy
+of the respective receive and send keys. The return value of these
+functions is the length of the valid key material. For security reasons,
+one should take care to clear these copies when work is complete. The
+max length of MPPE receive ands send keys are up to 32 bytes long, or
+of MPPE_MAX_KEY_SIZE length.
+
+The previous definitions of MPPE_MAX_KEY_LEN is the maximum length in
+which the Linux kernel will accept for MPPE key lengths. Plugins would
+access the MPPE keys directly via the:
+ extern u_char mppe_send_key[MPPE_MAX_KEY_LEN]
+ extern u_char mppe_recv_key[MPPE_MAX_KEY_LEN]
+variables. The 2.5.0 release prohibits the direct access of these
+variables by making them static and private in favor of using the new
+API.
-## $Id: PLUGINS,v 1.3 2001/05/21 08:34:33 paulus Exp $ ##
+## $Id: PLUGINS,v 1.8 2008/06/15 07:02:18 paulus Exp $ ##
\ No newline at end of file
projects / ppp.git / blobdiff