security-description-string-for-open-named-pipe Function

Summary

Interprets an access specification and generates a Security Descriptor String.

Package

win32

Signature

security-description-string-for-open-named-pipe access-spec => result, fail-type, fail-item

Arguments

Values

Description

The function security-description-string-for-open-named-pipe interprets access-spec and generates from it a Security Descriptor String as defined by Windows. See the MSDN for documentation of "Security Descriptor String Format".

security-description-string-for-open-named-pipe has quite limited capabilities, and the string that it generates contains only the DACL part of the descriptor.

If access-spec is a keyword, then its symbol name specifies a SID (Security Identifier). This SID gets read/write permission. The SID can be either standard representation (which looks like "S-1-..") or one of the aliases. The aliases are documented in the MSDN in the page titled "SID strings" (search for SDDL_ANONYMOUS). In general they have two letters, for example :au means authenticated users. The common standard strings are documented in the MSDN page titled "Well-known SIDs" (search for SECURITY_WORLD_RID). For example, :s-1-15-11 means authentication users. Any standard strings is acceptable, not only the documented ones, provided that it specifies a valid SID. For example, you can find the SID of a user by user-name-to-sid-string, intern it in the keyword package and use this (but it is better to pass a list (:user) as described below).

If access-spec is an integer, it must be one of the integers in the WELL_KNOWN_SID_TYPE Enumeration as documented in the MSDN. For example, 17 means authenticated users. The corresponding SID gets read/write permission.

If access-spec is a string, it is returned as-is. In this case it is the responsibility of the programmer to ensure that the string is valid. Note that if this string is used in open-named-pipe-stream, open-named-pipe-stream does not inherit the access even if inherit-access-p is non-nil.

If access-spec is a list, then each element in the list must be one of:

security-description-string-for-open-named-pipe returns 3 values. When successful, result is the string and the other return values are undefined. When it fails, which can be because it is given an unrecognized SID specifier, result is nil, fail-type is a short string giving the type of the item that fails, and fail-item is the item in the list that fails when access-spec is a list.

Notes

1. When the argument is syntactically incorrect, security-description-string-for-open-named-pipe signals an error. It fails and returns nil only when a SID specifier of an acceptable type does not specify a SID.
2. Except when given a string which is returned as-is, security-description-string-for-open-named-pipe works by generating an ACE (Access Control Entry) string for each SID giving it the read and write permission, except in the case when either :disallow-write or :disallow-read is used, when it generates an ACE string denying permission. All the ACEs are then concatenated and "D:" is prepended, thus generating a Security Descriptor String containing only the DACL.
3. Experimentally, you can connect to a named pipe only if you have both read and write permission, even when opening it for only read or only write. Thus when this function is used from open-named-pipe-stream, the keywords :disallow-read etc are not very useful. They are useful only when you want to deny access for a specific SID, by using :disallow-read and :disallow-write.
4. The order of the items in the list is significant: earlier items override later items.
5. Disallowing permission, for example by using :disallow-read, is not the same as not allowing it, because in the latter case a later ACE can give the SID the permission. Disallowing prevents later ACEs from giving permission.
6. Using a string or ACE strings in the list allows the user to generate a more elaborate string than security-description-string-for-open-named-pipe knows how to generate. In this case the returned string may be invalid. When this happens from open-named-pipe-stream, open-named-pipe-stream will get a failure and signal or return an error according to errorp.

Examples

Any of these gives permissions to all authenticated users:

:AU
 17
    '(:AU)
'(17)
    '((:SID :AU))
    '((:SID "AU")
    '((:SID 17))

Also, all of the above with AU replaced by S-1-15-11 will give permission to all authenticated users.

This gives permissions to all authorized users except the user "exclude":

'((:use "exclude" :DISALLOW-READ :DISALLOW-WRITE) :AU)

See also

canonicalize-sid-string
named-pipe-stream-name
open-named-pipe-stream
sid-string-to-user-name
user-name-to-sid-string