Hallo, dies ist ein Test.

PWD: /www/data-lst1/unixsoft/unixsoft/kaempfer/.public_html

Running in File Mode
Relative path: ././../../../../../../usr/man/man3elf/elf32_sign_range.3elf
Real path: /usr/share/man/man3elf/elf32_sign_range.3elf
Zurück

'\" te
.\" Copyright (c) 1989, AT&T. All rights reserved.
.\" Copyright (c) 1998, 2021, Oracle and/or its affiliates.
.TH elf32_sign_range 3ELF "11 May 2021" "Oracle Solaris 11.4" "ELF Library Functions"
.SH NAME
elf32_sign_range, elf64_sign_range, elf32_checksum, elf64_checksum \- return a signature range, or checksum of an elf image
.SH SYNOPSIS

.LP
.nf
cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-lelf\fR [ \fIlibrary\fR ... ]
#include <libelf.h>

\fBint\fR \fBelf32_sign_range\fR(\fBElf *\fR\fIelf\fR, \fBelf_sign_range_cb_func\fR \fIcb\fR,
    \fBElf_Signrange\fR \fItype\fR, \fBvoid *\fR\fIudata\fR);
.fi

.LP
.nf
\fBint\fR \fBelf64_sign_range\fR(\fBElf *\fR\fIelf\fR, \fBelf_sign_range_cb_func\fR \fIcb\fR,
    \fBElf_Signrange\fR \fItype\fR, \fBvoid *\fR\fIudata\fR);
.fi

.LP
.nf
\fBtypedef void\fR (\fB* elf_sign_range_cb_func\fR)(\fBsize_t\fR \fIoffset\fR, \fBsize_t\fR \fIsize\fR,
    \fBvoid *\fR\fIudata\fR);
.fi

.LP
.nf
\fBlong\fR \fBelf32_checksum\fR(\fBElf *\fR\fIelf\fR);
.fi

.LP
.nf
\fBlong\fR \fBelf64_checksum\fR(\fBElf *\fR\fIelf\fR);
.fi
.SH DESCRIPTION
.sp
.LP
The \fBelf32_sign_range()\fR and \fBelf64_sign_range()\fR functions provide data ranges of the image identified by \fIelf\fR that should be processed to produce a hash of the image contents.
.sp
.LP
A hash can be used to generate a signature or checksum of the file. A signature or checksum can be used to compare different versions of a given file. A signature or checksum can also be written back to the file in a manner that does not alter the hashed value, thus facilitating easy comparisons between files.
.sp
.LP
In each case, the data range used to generate a hash can be targeted toward the type of \fBELF\fR file. When writing a signature or checksum to a file, the data included in the hash must accommodate the file being updated after the hash has been created. In addition, dynamic objects may also undergo post-processing, where non-allocatable sections are removed, added, or changed. Hence, certain items of \fBELF\fR data must be omitted from the hash calculation so that the hash value remains valid should these post-processing operations occur.
.sp
.LP
\fBelf32_sign_range()\fR and \fBelf64_sign_range()\fR are designed for \fBELF\fR files created using \fBlibelf\fR(3LIB). See NOTES.
.sp
.LP
\fBelf32_sign_range()\fR and \fBelf64_sign_range()\fR provide one or more data ranges that are appropriate to the \fBELF\fR file, and separate any \fBELF\fR data that must be omitted from the hash calculation. These data ranges are conveyed to the caller through the \fBelf_sign_range_cb_func\fR call back function. See EXAMPLES.
.sp
.LP
The data range desired is defined by the \fItype\fR.
.sp
.ne 2
.mk
.na
\fB\fBELF_SR_INTERPRET\fR\fR
.ad
.br
.sp .6
.RS 4n
The type of the \fIelf\fR file is used to determine the appropriate data ranges.
.sp
For dynamic executables and shared objects, the data range is derived from the file program header information. Effectively, the data ranges define the data associated with the memory image of the file that is created when the file is used to create an executing process.
.sp
For relocatable objects, the data range is derived from the files section header information, rather than the program header information.
.sp
Any existing \fBSHT_SUNW_SIGNATURE\fR section is omitted from the supplied data ranges. For dynamic executables and shared objects, this section is omitted as it typically is not associated with the memory image. For relocatable objects, this section is explicitly ignored.
.sp
\fBELF_SR_INTERPRET\fR is appropriate for hashing the data of a file that is significant to the files eventual use. This hash value is suitable for generating a \fBSHT_SUNW_SIGNATURE\fR section that can added to the file. A subsequent \fBELF_SR_INTERPRET\fR request of the file produces the same hash value, thus providing the foundation for cryptographic signature verification.
.sp
When processing a relocatable object, \fBELF_SR_INTERPRET\fR is equivalent to using \fBELF_SR_RELOBJ\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBELF_SR_SIGNED_INTERPRET\fR\fR
.ad
.br
.sp .6
.RS 4n
The data range is the same as \fBELF_SR_INTERPRET\fR, with the addition of any \fBSHT_SUNW_SIGNATURE\fR section data.
.sp
\fBELF_SR_SIGNED_INTERPRET\fR is appropriate for hashing the data of a file that is significant to the files eventual use, including the signature, and using the generated signature or checksum for future release management.
.RE

.sp
.ne 2
.mk
.na
\fB\fBELF_SR_RELOBJ\fR\fR
.ad
.br
.sp .6
.RS 4n
The data range is derived as if the object was interpreted as a relocatable object. The data range is derived from the files section header information, rather than the program header information. Any \fBSHT_SUNW_SIGNATURE\fR section is explicitly omitted.
.sp
\fBELF_SR_RELOBJ\fR is appropriate for hashing all the data of a file. This hash value is suitable for generating a \fBSHT_SUNW_SIGNATURE\fR section that can be added to the file. A subsequent \fBELF_SR_RELOBJ\fR request of the file produces the same hash value.
.RE

.sp
.ne 2
.mk
.na
\fB\fBELF_SR_FILE\fR\fR
.ad
.br
.sp .6
.RS 4n
The data range encompasses the data in the whole file without regard to any \fBELF\fR structures that may be present.
.sp
For all interpretation types besides \fBELF_SR_FILE\fR, data ranges are established from the \fBELF\fR data of the file. As \fBELF_SR_FILE\fR captures the whole file, any data that might exist outside the \fBELF\fR file image is captured in the data range. For example, \fBELF_SR_FILE\fR captures any data that might be concatenated to the end of an \fBELF\fR file image.
.RE

.sp
.ne 2
.mk
.na
\fB\fBELF_SR_CHECKSUM\fR\fR
.ad
.br
.sp .6
.RS 4n
The data range is similar to \fBELF_SR_RELOBJ\fR, however certain dynamic information is skipped, such as the \fBSHT_DYNAMIC\fR and \fBSHT_SUNW_ancillary\fR sections.
.sp
\fBELF_SR_CHECKSUM\fR is used by \fBld\fR(1), to update the associated dynamic information with a simple checksum when creating an \fBELF\fR file.
.RE

.sp
.LP
Data ranges are provided to the \fBelf_sign_range_cb_func\fR call back function. These ranges are identified as an \fIoffset\fR from the start of the file, and the \fIsize\fR of the number of bytes that comprise the range.
.sp
.LP
The \fIudata\fR supplied to \fBelf32_sign_range()\fR and \fBelf64_sign_range()\fR is provided to the call back. This \fIudata\fR points to a data item that coordinates the collection of a checksum or signature, and should contain a pointer to the raw file image. This exclusive image is recommended, rather than using any underlying image that might be created from \fBelf_begin\fR(3ELF). This latter image can be transformed as a result of inspecting data though \fBlibelf\fR(3LIB) routines, which can compromise the checksum computation.
.sp
.LP
The \fIudata\fR can then be used to accumulate a checksum or signature from the various data ranges. See EXAMPLES.
.sp
.LP
The \fBelf32_checksum()\fR and \fBelf64_checksum()\fR functions return a simple checksum of the image identified by \fIelf\fR. These functions use \fBelf32_sign_range()\fR and \fBelf64_sign_range()\fR respectively, with the \fBELF_SR_CHECKSUM\fR type. The checksum is typically used as the \fBSHT_DYNAMIC\fR section tag \fBDT_CHECKSUM\fR, and \fBSHT_SUNW_ancillary\fR section elements, that can be recorded in dynamic objects.
.SH RETURN VALUES
.sp
.LP
\fBelf32_sign_range()\fR and \fBelf64_sign_range()\fR return \fB1\fR on success, or \fB0\fR if the \fBELF\fR image is determined to be invalid. \fBelf32_checksum()\fR and \fBelf64_checksum()\fR return a checksum on success, or \fB0\fR if the \fBELF\fR image is determined to be invalid.
.SH EXAMPLES
.LP
\fBExample 1\fR Calculate a Simple Checksum of an \fBELF\fR File

.sp
.LP
This program demonstrates the use of the sign-range routines to obtain a simple checksum. Effectively, this program mimics the checksum functions that are implemented internally using this approach.

.sp
.in +2
.nf
#include <sys/types.h>
#include <sys/stat.h>
#include <sys/mman.h>
#include <fcntl.h>
#include <stdio.h>
#include <libelf.h>
#include <gelf.h>

typedef struct {
        char    *s_addr;
        ulong_t s_sum;
} Sum;

static void
callback(size_t offset, size_t size, void *udata)
{
        Sum     *sum = (Sum *)udata;
        char    *addr = sum->s_addr + offset;

while (size--)
                sum->s_sum += *addr++ & 0xff;
}

#define MSW(l)  (((l) >> 16) & 0x0000ffffL)
#define LSW(l)  ((l) & 0x0000ffffL)

int
main(int argc, char *argv[])
{
        char            *addr;
        int             fd;
        Elf             *elf;
        Sum             sum;
        struct stat     status;

if ((fd = open(argv[1], O_RDONLY, 0)) == \(mi1)
                return (1);

(void) elf_version(EV_CURRENT);

/* Assign an ELF descriptor to the file */
        if (((elf = elf_begin(fd, ELF_C_READ, NULL)) == NULL) ||
            (elf_kind(elf) != ELF_K_ELF))
                return (1);

/* Establish a mapping for obtaining the checksum */
        if ((fstat(fd, &status) == -1) ||
            ((addr = mmap(NULL, status.st_size, PROT_READ,
            MAP_PRIVATE, fd, 0)) == MAP_FAILED))
                return (1);

/* Initialize checksum data */
        sum.s_addr = addr;
        sum.s_sum = 0;

/* Accumulate checksum from data ranges via callback() */
        if (gelf_getclass(elf) == ELFCLASS32) {
                if (elf32_sign_range(elf, callback, ELF_SR_CHECKSUM,
                   &sum) == 0)
                        return (1);
        } else {
                if (elf64_sign_range(elf, callback, ELF_SR_CHECKSUM,
                   &sum) == 0)
                        return (1);
        }

/* Finalize checksum */
        sum.s_sum = LSW(sum.s_sum) + MSW(sum.s_sum);
        sum.s_sum = ((ushort_t)(LSW(sum.s_sum) + MSW(sum.s_sum)));

(void) printf("%s: checksum=0x%x\en", argv[1], sum.s_sum);
        return (0);
}
.fi
.in -2
.sp

.sp
.in +2
.nf
% \fBcc -m64 -o main main.c -lelf\fR
% \fBmain foo.so\fR
foo.so: checksum=0x784
% \fBelfdump -k foo.so\fR
elf checksum: 0x784
.fi
.in -2
.sp
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp
.TS
tab(
) box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPE
ATTRIBUTE VALUE
_
Interface Stability
Committed
_
MT-Level
MT-Safe
.TE
.sp
.SH SEE ALSO
.sp
.LP
\fBld\fR(1), \fBmmap\fR(2), \fBopen\fR(2), \fBstat\fR(2), \fBelf\fR(3ELF), \fBelf_begin\fR(3ELF), \fBelf_kind\fR(3ELF), \fBelf_update\fR(3ELF), \fBelf_version\fR(3ELF), \fBgelf\fR(3ELF), \fBlibelf\fR(3LIB), \fBattributes\fR(7)
.SH NOTES
.sp
.LP
A primary goal of \fBelf32_sign_range()\fR and \fBelf64_sign_range()\fR is to sign and verify an \fBELF\fR file. This model requires computing the hash of the original \fBELF\fR file using the signing functions, and updating the file to contain this hash information. The expectation is that a recomputed hash value of the new file, will match the hash value that is stored in the file.
.sp
.LP
However, \fBELF\fR provides significant flexibility in regards the layout of a file. Anticipating how the file layout might change from computing the hash to updating the file with the hash, without omitting significant amounts of \fBELF\fR metadata to compute the hash, can be hard to achieve.
.sp
.LP
To provide a signing model, and to minimize the amount of \fBELF\fR metadata that must be omitted from the hash computation, the original \fBELF\fR file should follow a \fBlibelf\fR(3LIB) format. This format is created by using \fBlibelf\fR interfaces that finalize the file layout with \fBelf_update\fR(3ELF). Attempts to sign an \fBELF\fR file that does not follow a \fBlibelf\fR format can result in computing a hash value that does \fBnot\fR match the hash value recorded in the file. To ensure a signing model can be achieved, the following steps are recommended for a signing utility.
.RS +4
.TP
.ie t \(bu
.el o
Create an intermediate \fBELF\fR file from the original \fBELF\fR file. This intermediate file should contain an empty signature section as the last section of the \fBELF\fR file, and conform to a \fBlibelf\fR(3LIB) format.

.RE
.RS +4
.TP
.ie t \(bu
.el o
Compute the hash of this intermediate file using the desired \fBElf_Signrange\fR type.

.RE
.RS +4
.TP
.ie t \(bu
.el o
Update the signature section of the intermediate file with the hash value and the \fBElf_Signrange\fR type, and finalize the file with \fBelf_update\fR(3ELF).

.RE
.RS +4
.TP
.ie t \(bu
.el o
Replace the original \fBELF\fR file with the intermediate \fBELF\fR file.

.RE
.RS +4
.TP
.ie t \(bu
.el o
The hash of the new \fBELF\fR file, created using the recorded \fBElf_Signrange\fR type, should match the hash value recorded in the file.

.RE