.TITLE	HASH_PASSWORD - Hash Password Using Alternate Algorithm
	.IDENT	'X-2'

;
;****************************************************************************
;*									    *
;*  COPYRIGHT © 1989 BY							    *
;*  DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS.		    *
;*  ALL RIGHTS RESERVED.						    *
;* 									    *
;*  THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED   *
;*  ONLY IN  ACCORDANCE WITH  THE  TERMS  OF  SUCH  LICENSE  AND WITH THE   *
;*  INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR  ANY  OTHER   *
;*  COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY   *
;*  OTHER PERSON.  NO TITLE TO AND OWNERSHIP OF  THE  SOFTWARE IS  HEREBY   *
;*  TRANSFERRED.							    *
;* 									    *
;*  THE INFORMATION IN THIS SOFTWARE IS  SUBJECT TO CHANGE WITHOUT NOTICE   *
;*  AND  SHOULD  NOT  BE  CONSTRUED AS  A COMMITMENT BY DIGITAL EQUIPMENT   *
;*  CORPORATION.							    *
;* 									    *
;*  DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE  OR  RELIABILITY OF ITS   *
;*  SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.		    *
;* 									    *
;*									    *
;****************************************************************************
;

;++
;
; Facility:
;
;	VMS Executive
;
; Abstract:
;
;	This module contains an alternate password hash algorithm.
;
; Envrionment:
;
;	VAX/VMS, Caller's Mode System Service
;
; Author:
;
;	Derrell D. Piper, July 1989
;
;--

	.SBTTL	Declarations
;
; Include files:
;

	.LIBRARY /SYS$LIBRARY:LIB/	; pull in the system macro library

	$DSCDEF				; descriptor offsets
	$SSDEF				; system status codes
	$SYSVECTORDEF			; system service vector offsets
	$UAFDEF				; password algorithm constants

;
; Equated symbols:
;

	PWD	= 4			; offset to password descriptor
	ALG	= 8			; offset to algorithm index
	SALT	= 12			; offset to salt value
	USER	= 16			; offset to username descriptor
	HASH	= 20			; offset to hash buffer address


	.SBTTL	$HASH_PASSWORD System Service Documentation
;++
;  
; These instructions create a SYS$HASH_PASSWORD.EXE image that contains a
; site-specific password hash algorithm.
;
; The VMS password hash algorithm is based on an algorithm described in the
; "Communications of the ACM" [Vol. 17, Num. 8; Aug 1974].  Because it is a
; one-way cipher, there is no need to keep the algorithm secret.  Therefore,
; the built-in $HASH_PASSWORD system service (part of the SECURITY.EXE loadable
; image) executes in caller's mode and is protected UR (User read only).
;
; If, however, you are adding an algorithm which must be kept secret then the
; page protection on the $HASH_PASSWORD system service should be changed to ER
; (Executive read only) and the service should execute in Executive mode.
; 
; This module can be assembled two different ways depending on whether or not
; the site-specific hash algorithm needs to be protected.
; 
; To assemble this module as a caller's mode service with UR protection:
;
;	$ MACRO HASH_PASSWORD
;
; To assemble this module as an executive mode service with ER protection:
;
;
;	$ CREATE PROTECT.MAR
;	PROTECT=1
;	$ MACRO PROTECT+HASH_PASSWORD/OBJECT=HASH_PASSWORD
;
; To link this module:
;
;	$ @SYS$EXAMPLES:HASH_PASSWORD_LNK
;
;	or
;	
;	$ LINK /NOSYSSHR/NOTRACEBACK -
;		/SHARE=SYS$HASH_PASSWORD  -
;		/MAP=SYS$HASH_PASSWORD /FULL /CROSS -
;		/SYMBOL=SYS$HASH_PASSWORD -
;		SYS$INPUT/OPTION
;		HASH_PASSWORD, -
;		SYS$LIBRARY:STARLET/INCLUDE:(SYS$DOINIT),-
;	SYS$SYSTEM:SYS.STB/SELECTIVE
;	VECTOR_TABLE=SYS$SYSTEM:SYS.STB
;	COLLECT=NONPAGED_READONLY_PSECTS/ATTRIBUTES=RESIDENT,-
;		EXEC$NONPAGED_CODE
;	COLLECT=NONPAGED_READWRITE_PSECTS/ATTRIBUTES=RESIDENT,-
;		EXEC$NONPAGED_DATA
;	COLLECT=PAGED_READONLY_PSECTS,-
;		EXEC$PAGED_CODE
;	COLLECT=PAGED_READWRITE_PSECTS,-
;		EXEC$PAGED_DATA
;	COLLECT=INITIALIZATION_PSECTS/ATTRIBUTES=INITIALIZATION_CODE,-
;		EXEC$INIT_CODE,-
;		EXEC$INIT_000,-
;		EXEC$INIT_001,-
;		EXEC$INIT_002,-
;		EXEC$INIT_PFNTBL_000,-
;		EXEC$INIT_PFNTBL_001,-
;		EXEC$INIT_PFNTBL_002,-
;		EXEC$INIT_SSTBL_000,-
;		EXEC$INIT_SSTBL_001,-
;		EXEC$INIT_SSTBL_002
;
; Loader Information:
;
;	Please refer to the V5.0 Release Notes or Introduction to VMS System
;	Services Manual Appendix C on instructions to load an
;	installation-specific system image.
;
;	The following summarize the steps involed:
;
;	1.  Copy SYS$HASH_PASSWORD.EXE images produced by the above link command
;	    to the SYS$LOADABLE_IMAGES directory.
;
;	2.  Add an entry for the SYS$HASH_PASSWORD.EXE image in the
;	    SYS$UPDATE:VMS$SYSTEM_IMAGES.IDX data file:
;
;		SYSMAN SYS_LOADABLE ADD _LOCAL_ SYS$HASH_PASSWORD.EXE -
;		    /LOAD_STEP = SYSINIT -
;		    /SEVERITY  = WARNING -
;		    /MESSAGE   = "Failure to load SYS$HASH_PASSWORD.EXE" 
;
;	3.  Invoke the SYS$UPDATE:VMS$SYSTEM_IMAGES.COM command procedure
;	    to generate a new system image data file (file name
;	    SYS$LOADABLE_IMAGES:VMS$SYSTEM_IMAGES.DATA).  During the bootstrap, 
;	    the system uses this data file to load the appropriate images. 
;
;	4.  Reboot the system, which will cause the new SYS$HASH_PASSWORD.EXE to 
;	    be loaded into the system.  Subsequent calls to the $HASH_PASSWORD
;	    system service will use this routine.
;
;--

	.SBTTL	$HASH_PASSWORD Initialization Routine

;
; HASH_PASSWORD_INIT
;
;	Reset the page protection on the $HASH_PASSWORD system service to ER.
;

	.IF DF PROTECT			; if protected, go change page protection
	DECLARE_PSECT	EXEC$INIT_CODE

INITIALIZATION_ROUTINE -
	HASH_PASSWORD_INIT

HASH_PASSWORD_INIT:
	PUSHR	#^M<R2,R3,R4,R5>	; save some registers
	MOVL	#PRT$C_ER,R0		; new page protection is ER
	MOVAB	PROTECT_END,R1		; ending VA
	SUBL2	PROTECT_START,R1	; subtract starting VA
	ASHL	#-9,R1,R1		; turn into page count
	MOVAB	PROTECT_START,R2	; starting VA
	JSB	G^EXE$SET_PAGE_PROTECTION	; go change protection
	POPR	#^M<R2,R3,R4,R5>	; restore registers
	MOVZWL	#SS$_NORMAL,R0		; set success
	RSB				; return status in R0
	.ENDC

	.SBTTL	$HASH_PASSWORD System Service
;++
; $HASH_PASSWORD
;
; Functional Description:
;
;	This routine probes the system service arguments and then either
;	calls out to the standard VMS password hash routine or executes
;	a site-specific hash algorithm.
;
; Calling sequence:
;
;	This routine should be called via a CALLS/G to SYS$HASH_PASSWORD.
;
; Input:
;
;	PWD(AP)		Address of string descriptor containing the plaintext 
;			password to be encrypted.
;
;	ALG(AP)		Unsigned byte (value) representing the encryption 
;			algorithm that should be used to encrypt the password.
;
;	SALT(AP)	Unsigned word (value) for use by the encryption algorithm.
;
;	USER(AP)	Address of string descriptor containing the username 
;			associated with the password.
;
; Output:
;
;	HASH(AP)	Address of quadword to receive the resulting hash.
;
; Routine value:
;
;	SS$_ACCVIO	input or output buffer not accessible
;	SS$_BADPARAM	algorithm is unknown or invalid
;	SS$_NORMAL	routine completed successfully
;
;--

	DECLARE_PSECT	EXEC$PAGED_CODE

PROTECT_START:						; starting address of protected code

	.IF DF PROTECT					; if protected, load as exec mode
	SYSTEM_SERVICE	HASH_PASSWORD,-
			<R2,R3,R4,R5>,-
			MODE=EXEC,-
			NARG=5
	.IFF						; else load as caller's mode
	SYSTEM_SERVICE	HASH_PASSWORD,-
			<R2,R3,R4,R5>,-
			MODE=CALLERS_MODE,-
			NARG=5
	.ENDC

	.IF DF PROTECT					; PROBE arguments

; Probe the output buffer.

	MOVL	HASH(AP),R4				; get hash buffer addr
	ASSUME	UAF$S_PWD LE 512			; will a simple PROBE work?
	IFNOWRT	#UAF$S_PWD,(R4),30$			; br if desc no good

; Probe the password buffer.

	MOVL	PWD(AP),R4				; get password desc addr
	IFNORD	#8,(R4),30$				; br if desc no good
	CLRL	R3					; use previous mode
	MOVZWL	DSC$W_LENGTH(R4),R1			; set length
	MOVL	DSC$A_POINTER(R4),R0			; set address
	JSB	G^EXE$PROBER				; probe buffer
	BLBC	R0,30$					; leave on error

; Probe the username buffer.

	MOVL	USER(AP),R4				; get password desc addr
	IFNORD	#8,(R4),30$				; br if desc no good
	MOVZWL	DSC$W_LENGTH(R4),R1			; set length
	MOVL	DSC$A_POINTER(R4),R0			; set address
	JSB	G^EXE$PROBER				; probe buffer
	BLBC	R0,30$					; leave on error

	.IFF

	MOVAL	G^EXE$SIGTORET,(FP)			; establish condition handler

	.ENDC

; The algorithm index is an unsigned byte.  Algorithm numbers 0-127 are
; reserved to DEC; customers may use numbers 128-255.
;
; UAF$C_CUST_ALGORITHM		-- first legal customer algorithm number
; UAF$C_PREFERRED_ALGORITHM	-- preferred DEC algoritm (use current)
; UAF$C_CURRENT_ALGORITHM	-- current (last legal) DEC algorithm number

	CMPB	#UAF$C_CUST_ALGORITHM,ALG(AP)		; alg in customer range?
	BLEQU	SITE_SPECIFIC				; LEQU means yes
	CMPB	#UAF$C_PREFERRED_ALGORITHM,ALG(AP)	; preferred algorithm?
	BEQL	10$					; br if so - skip next check
	CMPB	#UAF$C_CURRENT_ALGORITHM,ALG(AP)	; algorithm within DEC range?
	BLSSU	40$					; LSSU means no
10$:	JSB	G^LGI$HASH_PASSWORD			; call VMS hash routine
20$:	RET						; common exit
30$:	MOVZWL	#SS$_ACCVIO,R0				; parameter inaccessible
	BRB	20$					; leave with error
40$:	MOVZWL	#SS$_BADPARAM,R0			; algorithm is unknown
	BRB	20$					; leave with error

; Registers R0-R5 may be used by this routine, others must be saved.

SITE_SPECIFIC:

	NOP						; algorithms go here

	MOVZWL	#SS$_NORMAL,R0				; set success
	RET						; and return

PROTECT_END:						; ending address of protected code

	.END