This routine registers authentication information with the RPC runtime. It is used by server applications.

Syntax

#include <dce/rpc.h> void rpc_server_register_auth_info( unsigned_char_t *server_princ_name, unsigned32 authn_svc, rpc_auth_key_retrieval_fn_t get_key_fn, void *arg, unsigned32 *status);

Arguments

INPUT

server_princ_name

Specifies the principal name to use for the server when authenticating remote procedure calls using the service specified by authn_svc. The content of the name and its syntax is defined by the authentication service in use.

authn_svc

Specifies the authentication service to use when the server receives a remote procedure call request. The following authentication services are supported:

• rpc_c_authn_none
  No authentication.
• rpc_c_authn_dce_secret
  DCE shared-secret key authentication.
• rpc_c_authn_dce_public
  DCE public key authentication (reserved for future use).
• rpc_c_authn_default
  DCE default authentication service.
• rpc_c_authn_winnt
  Microsoft's NTLM authentication protocol.

get_key_fn

Specifies the address of a server-provided routine that returns encryption keys. The following C definition for rpc_auth_key_retrieval_fn_t illustrates the prototype for the encryption key acquisition routine:

typedef void (*rpc_auth_key_retrieval_fn_t) ( void *arg, /* in */ unsigned_char_t *server_princ_name, /* in */ unsigned32 key_type, /* in */ unsigned32 key_ver, /* in */ void **key, /* out */ unsigned32 *status /* out */ );

The RPC runtime passes the server_princ_name parameter value specified on the call to rpc_server_register_auth_info(), as the server_princ_name parameter value, to the get_key_fn key acquisition routine. The RPC runtime automatically provides a value for the key version (key_ver) parameter. For a key_ver value of 0 (zero), the key acquisition routine must return the most recent key available. The routine returns the key in the key parameter. The key_type parameter specifies a Kerberos encryption key type. Because currently the DCE supports only DES encryption, this parameter can be ignored.

If the key acquisition routine, when called from the rpc_server_register_auth_info() routine, returns a status other than rpc_s_ok, the rpc_server_register_auth_info() routine fails and returns the error status to the calling server.

If the key acquisition routine, when called by the RPC runtime while authenticating a client remote procedure call request, returns a status other than rpc_s_ok, the request fails and the RPC runtime returns the error status to the client.

arg

Specifies an argument to pass to the get_key_fn key acquisition routine, if specified. (See the description of the get_key_fn parameter for details.)

Specify NULL for arg to use the default key table file, /krb/v5srvtab. The calling server must be root to access this file.

If arg is a key table file name, the file must have been created with the ktadd command. If the specified key table file resides in /krb5, you can supply only the file name. If the file does not reside in /krb5, you must supply the full pathname. You must prepend the file's absolute pathname with the prefix FILE:.

OUTPUT

status

Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.

The possible status codes and their meanings are as follows:

• rpc_s_ok
  Success.
• rpc_s_unknown_authn_service
  Unknown authentication service.
• rpc_s_key_func_not_allowed
  authn_svc is rpc_c_authn_default or rpc_c_authn_winnt and a non-null value was supplied for get_key_fn parameter.

Description

The rpc_server_register_auth_info() routine registers an authentication service to use for authenticating remote procedure calls to a particular server principal. A server calls this routine once for each authentication service and principal name combination that it wants to register.

The authentication service specified by a client (using the rpc_binding_set_auth_info() routine) must be one of the authentication services registered by the server. If it is not, the client's remote procedure call request fails with an rpc_s_unknown_authn_service status code.

The following table shows the RPC runtime behavior for acquiring encryption keys for each supported authentication service. Note that if authn_svc is rpc_c_authn_default, then get_key_fn must be NULL. Also note that if authn_svc is rpc_c_authn_winnt, then get_key_fn must be NULL.

RPC Key Acquisition for Authentication Services
authn_svc	get_key_fn	arg	Runtime Behavior
rpc_c_authn_default	NULL	NULL	Uses the default method of encryption key acquisition from the default key table.
rpc_c_authn_default	NULL	non-NULL	Uses the default method of encryption key acquisition from the specified key table.
rpc_c_authn_default	non-NULL	Ignored	Error returned.
rpc_c_authn_none	Ignored	Ignored	No authentication performed.
rpc_c_authn_dce_secret	NULL	NULL	Uses the default method of encryption key acquisition from the default key table.
rpc_c_authn_dce_secret	NULL	non-NULL	Uses the default method of encryption key acquisition from the specified key table.
rpc_c_authn_dce_secret	non-NULL	NULL	Uses the specified encryption key acquisition routine to obtain keys from the default key table.
rpc_c_authn_dce_secret	non-NULL	non-NULL	Uses the specified encryption key acquisition routine to obtain keys from the specified key table.
rpc_c_authn_dce_public	Ignored	Ignored	Reserved for future use.
rpc_c_authn_winnt	NULL	Ignored	Uses the default method of encryption key acquisition from the default key table.
rpc_c_authn_winnt	non-NULL	Ignored	Error returned.

Return Values

No value is returned.

See Also

• rpc_binding_set_auth_info(3rpc)

This routine returns authentication and authorization information from the binding handle for an authenticated client. It is used by server applications.

Syntax

#include <dce/rpc.h> #include <dce/id_base.h> void rpc_binding_inq_auth_client( rpc_binding_handle_t binding, rpc_authz_handle_t *privs, unsigned_char_t **server_princ_name, unsigned32 *protect_level, unsigned32 *authn_svc, unsigned32 *authz_svc, unsigned32 *status);

Arguments

INPUT

binding

Specifies the client binding handle from which to return the authentication and authorization information.

OUTPUT

privs

Returns a handle to the authorization information for the client that made the remote procedure call on binding.

The server must cast this handle to the data type specified by authn_svc and authz_svc.

If the authn_svc is rpc_c_authn_winnt the return value must be cast to an (unsigned_char_t *). When the authn_svc is rpc_c_authn_winnt the return value is the domain and username of the client that made the request. The string is in the form of \\domain_name\user_name. If the domain name is not obtainable then just the username will be returned (with no slashes).

If the authn_svc is rpc_c_authn_dce_secret, the following table shows how to cast the return value.

Casts for Authorization Information
For authz_svc value:	privs contains this data:	Use this cast:
rpc_c_authz_none	A NULL value.	None
rpc_c_authz_name	The calling client's principal name.	(unsigned_char_t *)
rpc_c_authz_dce	The calling client's privilege attribute certificate.	(sec_id_pac_t *)

Note that rpc_c_authz_none is valid only if the authn_svc parameter is rpc_c_authn_none or rpc_c_authn_winnt.

The data referenced by this parameter is read-only and should not be modified by the server. If the server wants to preserve any of the returned data, it must copy the data into server- allocated memory.

Specifying NULL prevents the routine from returning this parameter.

server_princ_name

If authz_svc is rpc_c_authn_dce_secret, this parameter returns a pointer to the server principal name specified by the client that made the remote procedure call on binding.

If authz_svc is rpc_c_authn_winnt, this parameter returns a pointer to the server principal name specified by the server when it called rpc_server_register_auth_info().

The content of the returned name and its syntax is defined by the authentication service in use. Specifying NULL prevents the routine from returning this parameter. In this case, the caller does not have to call the rpc_string_free() routine.

protect_level

Returns the protection level requested by the client that made the remote procedure call on binding. The protection level determines the degree to which authenticated communications between the client and the server are protected. Specifying NULL prevents the routine from returning this parameter.

The possible protection levels are as follows:

• rpc_c_protect_level_default
  Uses the default protection level for the specified authentication service.
• rpc_c_protect_level_none
  Performs no protection.
• rpc_c_protect_level_connect
  Performs protection only when the client establishes a relationship with the server.
• rpc_c_protect_level_call
  Performs protection only at the beginning of each remote procedure call when the server receives the request.
• rpc_c_protect_level_pkt
  Ensures that all data received is from the expected client.
• rpc_c_protect_level_pkt_integ
  Ensures and verifies that none of the data transferred between client and server has been modified.
• rpc_c_protect_level_pkt_privacy
  Performs protection as specified by all of the previous levels and also encrypt each remote procedure call argument value.

authn_svc

Returns the authentication service requested by the client that made the remote procedure call on binding. Specifying NULL prevents the routine from returning this parameter.

The possible authentication services are as follows:

• rpc_c_authn_none No authentication.
• rpc_c_authn_dce_secret
  DCE shared-secret key authentication.
• rpc_c_authn_dce_public
  DCE public key authentication (reserved for future use).
• rpc_c_authn_default
  DCE default authentication service.
• rpc_c_authn_winnt
  Microsoft's NTLM authentication protocol.

authz_svc

Returns the authorization service requested by the client that made the remote procedure call on binding. Specifying NULL prevents the routine from returning this parameter.

The possible authorization services are as follows:

• rpc_c_authz_none
  Server performs no authorization. This is valid only if the authn_svc parameter is rpc_c_authn_none.or rpc_c_authn_winnt.
• rpc_c_authz_name
  Server performs authorization based on the client principal name.
• rpc_c_authz_dce
  Server performs authorization using the client's DCE Privilege Attribute Certificate (PAC) sent to the server with each remote procedure call made with binding. Generally, access is checked against DCE Access Control Lists (ACLs).

status

Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.

The possible status codes and their meanings are as follows:

• rpc_s_ok
  Success.
• rpc_s_invalid_binding
  Invalid binding handle.
• rpc_s_wrong_kind_of_binding
  Wrong kind of binding for operation.
• rpc_s_binding_has_no_auth
  Binding has no authentication information.

Description

The rpc_binding_inq_auth_client() routine returns authentication and authorization information associated with the client identified by binding. The calling server manager routine can use the returned data for authorization purposes.

The RPC runtime allocates memory for the returned server_princ_name parameter. The server is responsible for calling the rpc_string_free() routine for the returned parameter string.

For applications in which the client side uses the IDL auto_handle or implicit_handle attribute, the server side needs to be built with the IDL explicit_handle attribute specified in the Attribute Configuration File (ACF). Using explicit_handle provides binding as the first parameter to each server manager routine.

Return Values

No value is returned.

See Also

• rpc_binding_inq_auth_info(3rpc)
• rpc_binding_set_auth_info(3rpc)
• rpc_string_free(3rpc)

This chapter provides DCL syntax and usage information for the Interface Definition Language (IDL) compiler, the NIDL-to-IDL converter (IDL/CONVERT), and the Universal Unique Identifier Generator (UUIDGEN) utility. (NIDL is the Network Interface Definition Language.)

12.0.1 IDL Compiler

This section provides DCL syntax for commands to the IDL compiler. Except where noted, IDL DCL command syntax is equivalent to the IDL universal command syntax documented in the idl(1rpc) section of the Digital DCE Application Development Reference. See the reference documentation for a complete description of the IDL universal command syntax.

NAME

• IDL --- Invokes the Interface Definition Language (IDL) compiler.

SYNOPSIS

• IDL filename [qualifier]...

QUALIFIERS

• /CLIENT_FILES [=(option[,...])]
  /NOCLIENT_FILES
  • Specify one or more of the following options:
    ALL (default)
    [NO]AUXILIARY [=filename]
    NONE
    [NO]STUB [=filename]
    This qualifier is equivalent to the -client argument in the universal syntax.

/CONVERT

• This qualifier is equivalent to the nidl_to_idl argument in the universal syntax, as explained in the nidl_to_idl(1rpc) section of the Digital DCE Application Development Reference. Use the /INCLUDE_DIRECTORY qualifier to specify a directory name that contains imported interface definition files.

/SERVER_FILES [=(option[,...])]
/NOSERVER_FILES

• Specify one or more of the following options:
  ALL (default)
  [NO]AUXILIARY [=filename]
  NONE
  [NO]STUB [=filename]
  This qualifier is equivalent to the -server argument in the universal syntax.

/INCLUDE_DIRECTORY [=directory[,...])] (default)
/NOINCLUDE_DIRECTORY

• This qualifier is equivalent to the -Idirectory and -no_def_idir arguments in the universal syntax.

/PREPROCESS
/NOPREPROCESS (default)

• This qualifier is similar to the -cpp_cmd 'c_preprocessor_command_line' and -no_cpp arguments in the universal syntax. However, /PREPROCESS does not accept a value (the compiler to handle the preprocessing), while the -cpp_cmd option does accept a value. You cannot use the /PREPROCESS qualifier to compile applications requiring the preprocessor on systems without a CC compiler. Use the C++ compiler unless the universal syntax is used.

/DEFINE [=(identifier[=definition][,...])]
/NODEFINE (default)

• This qualifier is equivalent to the -D name[=definition] argument in the universal syntax.

/UNDEFINE [=(identifier[,...])]
/NOUNDEFINE (default)

• This qualifier is equivalent to the -Uname argument in the universal syntax.

/SYNTAX_ONLY
/NOSYNTAX_ONLY (default)

• This qualifier is equivalent to the -syntax_only argument in the universal syntax.

/OPTIMIZE [={SPEED | SPACE }]
/OPTIMIZE = SPEED (default)

• This qualifier is equivalent to the -space_opt argument in the universal syntax.

/OUTPUT_DIRECTORY [=directory]
/NOOUTPUT_DIRECTORY (default)

• This qualifier is equivalent to the -out directory argument in the universal syntax.

/HEADER_FILE = filename
/HEADER_FILE=filename.H (default)

• This qualifier is equivalent to the -header header_file argument in the universal syntax.

/KEEP [=option]
/NOKEEP

• Specify one of the following options:
  ALL
  C_SOURCE
  NONE (equivalent to /NOKEEP)
  OBJECT (default)
  This qualifier is equivalent to the -keep file_types argument in the universal syntax.

/CC_COMMAND [="command-line"]
/NOCC_COMMAND
/CC_COMMAND="CC/G_FLOAT/STANDARD=NOPORTABLE" (default)

• This qualifier is equivalent to the -cc_cmd 'command_line' argument in the universal syntax.

/CC_QUALIFIERS [="command-qualifiers"]
/NOCC_QUALIFIERS (default)

• This qualifier is equivalent to the -cc_opt 'command_options' argument in the universal syntax.

/REPAIR [=(option[,...])]
/NOREPAIR

• Specify one or more of the following options:
  ALL (default)
  [NO]BOOLEAN_CONSTANTS
  [NO]EXTRA_PAD_BYTES
  [NO]MISSING_PAD_BYTES
  NONE
  This qualifier is equivalent to the -bug n and -no_bug n arguments in the universal syntax. The values [NO]MISSING_PAD_BYTES, [NO]EXTRA_PAD_BYTES, and [NO]BOOLEAN_CONSTANTS correspond to -bug 1, -bug 2, and -bug 3, respectively, in the universal syntax.

/VERIFY
/NOVERIFY (default)

• This qualifier is equivalent to the -confirm argument in the universal syntax.

/WARNINGS (default)
/NOWARNINGS

• This qualifier is equivalent to the -no_warn argument in the universal syntax.

/LOG
/NOLOG (default)

• This qualifier is equivalent to the -v argument in the universal syntax.

/LANGUAGE [={CC | FORTRAN}]
/LANGUAGE=CC (default)
/LANGUAGE=CXX

• This qualifier is equivalent to the -lang argument in the universal syntax.

/STANDARD [={[NO]PORTABLE | DCE_V10 | DEC_V10 | EXTENDED}]
/STANDARD=PORTABLE (default)

• This qualifier is equivalent to the -standard [standard_type] argument in the universal syntax. This universal syntax argument is documented in the section that describes IDL compiler enhancements in the Digital DCE for OpenVMS VAX and OpenVMS Alpha Product Guide.

/DIAGNOSTICS [=filename]
/NODIAGNOSTICS (default)

• This qualifier requests that a diagnostic file listing the errors reported by a compilation be generated for LSE. If you do not specify a filename, the compiler uses the basename of the IDL file and appends the .DIA extension to it.

/ENTRY_POINT_VECTOR [=(option[,...])]
/NOENTRY_POINT_VECTOR
/ENTRY_POINT_VECTOR=(NOCLIENT, MANAGER) (default)

• Specify one or more of the following options:
  ALL
  [NO]CLIENT
  [NO]MANAGER
  NONE
  This qualifier provides a function similar to those of the -cepv and -no_mepv arguments in the universal syntax.
  The /ENTRY_POINT_VECTOR command qualifier controls generation of the client and manager entry point vectors through the keywords CLIENT and MANAGER. In the universal command syntax, two separate idl options (-cepv and -no_mepv) control generation of the client and manager entry point vectors.
  The following example generates both client and manager entry point vectors using the universal command syntax:
  $ idl fpe_server.idl -cepv
  The equivalent DCL command is as follows:
  $ idl fpe_server.idl /ENTRY_POINT_VECTOR=(CLIENT,MANAGER)
  If one or more options are specified, the DCL syntax requires you to specify all required options. Options that are not listed are not enabled.

/TRACE [=(option\italic)[,...])]
/NOTRACE (default)

• Specify one or more of the following options:
  [NO]LOG_MANAGER
  EVENTS=({ALL|CALLS|CONTEXT_HANDLES|ERRORS|NONE |MISCELLANEOUS}[,...])
  This qualifier is equivalent to the -trace value argument in the universal syntax, which is documented in the Digital DCE for OpenVMS VAX and OpenVMS Alpha Product Guide.

/VERSION
/NOVERSION (default)

• This qualifier is equivalent to the -version argument in the universal syntax.